diff --git a/public/images/data-streams/calculated-streams-diagram.png b/public/images/data-streams/calculated-streams-diagram.png new file mode 100644 index 00000000000..64b02149cde Binary files /dev/null and b/public/images/data-streams/calculated-streams-diagram.png differ diff --git a/reports/llms-report.json b/reports/llms-report.json index 0ed858d2f18..f4febe6a04e 100644 --- a/reports/llms-report.json +++ b/reports/llms-report.json @@ -1,5 +1,5 @@ { - "startedAt": "2025-12-10T23:13:13.756Z", + "startedAt": "2025-12-11T00:13:00.625Z", "siteBase": "https://docs.chain.link", "sections": [ { @@ -39,16 +39,16 @@ "pagesProcessed": 37, "outputPath": "src/content/data-feeds/llms-full.txt", "bytes": 302816, - "prevBytes": 302589, - "deltaBytes": 227 + "prevBytes": 302816, + "deltaBytes": 0 }, { "section": "data-streams", - "pagesProcessed": 55, + "pagesProcessed": 56, "outputPath": "src/content/data-streams/llms-full.txt", - "bytes": 477063, + "bytes": 484871, "prevBytes": 477063, - "deltaBytes": 0 + "deltaBytes": 7808 }, { "section": "dta-technical-standard", @@ -123,5 +123,5 @@ "deltaBytes": 0 } ], - "finishedAt": "2025-12-10T23:13:17.715Z" + "finishedAt": "2025-12-11T00:13:04.595Z" } diff --git a/src/config/sidebar.ts b/src/config/sidebar.ts index c70e3d9195a..81423c3f0ff 100644 --- a/src/config/sidebar.ts +++ b/src/config/sidebar.ts @@ -944,6 +944,10 @@ export const SIDEBAR: Partial> = { title: "Best Practices", url: "data-streams/concepts/best-practices", }, + { + title: "Calculated Streams", + url: "data-streams/concepts/calculated-streams", + }, { title: "Liquidity-Weighted Bid and Ask prices", url: "data-streams/concepts/liquidity-weighted-prices", diff --git a/src/content/data-streams/concepts/calculated-streams.mdx b/src/content/data-streams/concepts/calculated-streams.mdx new file mode 100644 index 00000000000..0e079382d4c --- /dev/null +++ b/src/content/data-streams/concepts/calculated-streams.mdx @@ -0,0 +1,186 @@ +--- +section: dataStreams +date: "Last Modified" +title: "Calculated Streams" +metadata: + title: "Chainlink Calculated Streams | Derived Data Stream Values" + description: "Learn about Calculated Streams in Chainlink Data Streams - streams whose values are derived from multiple underlying inputs using predefined expressions." + keywords: + [ + "Calculated Streams", + "Data Streams", + "Derived Values", + "Index Pricing", + "Collateral Values", + "Tokenized Assets", + "Stream Calculations", + ] +whatsnext: + { + "Find the list of available Exchange Rate streams": "/data-streams/exchange-rate-streams", + "Learn about Data Streams architecture": "/data-streams/architecture", + "Data Streams Best Practices": "/data-streams/concepts/best-practices", + } +--- + +import { Aside, ClickToZoom } from "@components" + +Calculated streams are Chainlink data streams whose values are derived by applying arithmetic expressions to multiple underlying inputs. + +All Data Streams use a [Decentralized Oracle Network (DON)](/data-streams/architecture) where nodes reach consensus and publish signed reports. Traditional Data Streams aggregate market data from multiple independent providers, ensuring no single data source can compromise the stream's integrity. + +Instead of aggregating only raw market data, calculated streams compute derived values using predefined formulas applied to various inputs, including existing data streams, onchain state, and offchain APIs. Some inputs are decentralized aggregates (for example, crypto price streams from multiple independent providers), while others may come from a single protocol or API (for example, a specific vault contract or yield provider). Because a calculated stream depends on all of these inputs, you should evaluate their dependencies and failure modes carefully before using it in a value-securing application. + + + +## Why use calculated streams? + +- **Simpler integrations**: Consume one stream instead of implementing calculation logic in your contracts or backend +- **Canonical formulas**: All integrators use the same formula and inputs, ensuring consistency across protocols +- **Managed infrastructure**: Chainlink handles RPC calls, API integrations, and the calculation pipeline + +## How to identify calculated streams + +Calculated streams are marked with a Calculated badge in the Data Streams feed list. + +## How calculated streams work + +Calculated streams leverage existing Data Streams infrastructure. Data providers feed market data into the DON, which produces base streams. The DON then uses these base streams—along with onchain state and offchain APIs—as inputs to calculate derived values. + + + +### Architecture flow + +1. **Data collection**: The DON retrieves inputs specific to each calculated stream, which may include: + - Existing Data Streams (market prices from multiple independent data providers) + - Onchain state via RPC calls (vault balances, token supplies, contract data) + - Offchain data via APIs (yield rates, interest components, external reference data) +2. **Calculation**: The DON applies the predefined formula to combine the inputs +3. **Consensus and signing**: Nodes reach consensus on the calculated value and sign the report +4. **Publication**: Calculated streams are published through the Data Streams Aggregation Network + +### Input sources + +The inputs for a calculated stream depend on what it's computing. A stream might use: + +#### Existing Data Streams + +Market prices already aggregated from multiple independent sources (3+ providers). Example: using individual crypto asset prices as inputs for an index calculation. + +#### Onchain state + +Protocol-specific data read via RPC, such as vault balances, token supplies, or smart contract state. May come from a single protocol's contracts. + +#### Offchain APIs + +External data from specific trusted providers, such as yield rates or reference values. May come from a single API endpoint. + +### Calculation and output + +The DON executes the predefined formula (weighted averages, ratios, sums, etc.) using the latest available inputs. The calculated value is packaged into a signed report with standard metadata (timestamps, fees) and published through the Data Streams Aggregation Network. You consume these reports using the same REST APIs, WebSocket connections, and onchain verification as traditional streams. + +## Example: Tokenized yield product + +A calculated stream for a tokenized yield-bearing vault might combine: + +- **Vault balance (onchain)**: Total assets in the vault contract +- **Token supply (onchain)**: Circulating supply of vault shares +- **Accrued yield (offchain)**: Interest from an external API + +**Formula:** `(vault balance + accrued yield) / token supply` + +**Result**: a price per share that reflects the vault's total value including pending yield. + +Without this stream, protocols accepting the vault token as collateral would need to query the vault contract, fetch accrued interest from the yield provider's API, perform the calculation themselves, and keep this logic synchronized across all integrators. A calculated stream helps ensure integrators apply the same pricing logic and update together when the underlying formula or yield source changes. + +## Key differences from standard streams + +While calculated streams use the same infrastructure and delivery mechanisms as standard streams, they have distinct behaviors you should understand before integrating. For mitigation strategies, see [Risks and mitigation](#risks-and-mitigation). + +### Report availability + +Standard streams aggregate data from multiple independent providers, so they remain available as long as enough providers are reporting. Calculated streams depend on **all** of their inputs being available. If any required input becomes unavailable or returns errors, the calculated **stream stops producing reports until all inputs recover**. This prevents potentially incorrect values from being published. + +### Input reliability + +Standard streams source data exclusively from decentralized aggregates of multiple independent data providers. Calculated streams may include a mix of: + +- **Decentralized aggregates**: Existing Data Streams with multiple independent sources (similar reliability to standard streams) +- **Single-source inputs**: Specific protocol contracts or APIs where availability depends on a single system + +Single-source inputs carry higher risk. If that source experiences downtime, report production halts entirely until it recovers. Review the input sources for any calculated stream you plan to use. + +### Timing characteristics + +Standard streams reflect a single aggregated market price at a point in time. Calculated streams combine multiple inputs that may update at different frequencies and reflect slightly different timestamps. The calculated value is an approximation based on the latest available data from each input, not a single-block atomic snapshot. + +During rapid changes (large deposits, withdrawals, or sharp market moves), you may observe temporary differences between the calculated stream value and values from other sources like block explorers or protocol dashboards. These differences typically resolve as all inputs update to reflect the new state. + +--- + +## Risks and mitigation + +Calculated streams inherit risks from their underlying inputs and introduce additional considerations. Use these strategies to mitigate potential issues. + +### Handling report gaps + +Because calculated streams stop producing reports when any input fails, your application must handle gaps in report availability. + +#### Mitigation + +- Design your protocol to handle report gaps gracefully (pause operations, use last-known values with appropriate staleness checks, or implement fallbacks based on your risk tolerance) +- Implement staleness checks to detect when reports stop arriving and trigger appropriate protocol responses +- Set alerts for report gaps to detect input source issues early + +### Single-source input reliability + +Single-source inputs (specific APIs or contracts) may have lower availability than decentralized aggregates. + +#### Mitigation + +- Understand your input sources and assess the reliability of each, particularly single-source APIs or contracts +- For critical applications, consider independently monitoring the availability of single-source inputs +- Define acceptable downtime thresholds and corresponding protocol responses + +### Timing discrepancies + +Temporary differences between the calculated stream and other data sources are expected during rapid changes. + +#### Mitigation + +- Implement max deviation checks against expected ranges +- Use time-weighted averages or circuit breakers for extreme moves +- Monitor trends over time rather than reacting to individual updates +- Compare calculated values against market references when available (e.g., spot prices for index tokens) + + + +--- + +## Best practices + +### Protocol design + +- Set deviation limits to cap price changes per update or time window +- Define fallback behavior if the stream stops updating or jumps beyond thresholds +- Test your protocol's behavior during report gaps before deploying to production + +### Monitoring + +- Set alerts for report gaps to detect when no new reports arrive within your expected update frequency +- Track the calculated stream value over time to establish normal behavior patterns +- Monitor key inputs independently when feasible (vault balances, token supplies, API availability) to identify which input may be causing issues +- Alert on movements outside your expected range diff --git a/src/content/data-streams/llms-full.txt b/src/content/data-streams/llms-full.txt index 2ed3dd881c8..7033917a8be 100644 --- a/src/content/data-streams/llms-full.txt +++ b/src/content/data-streams/llms-full.txt @@ -408,6 +408,135 @@ For broader guidance around market hours and event handling, refer to the [Marke --- +# Calculated Streams +Source: https://docs.chain.link/data-streams/concepts/calculated-streams + +Calculated streams are Chainlink data streams whose values are derived by applying arithmetic expressions to multiple underlying inputs. + +All Data Streams use a [Decentralized Oracle Network (DON)](/data-streams/architecture) where nodes reach consensus and publish signed reports. Traditional Data Streams aggregate market data from multiple independent providers, ensuring no single data source can compromise the stream's integrity. + +Instead of aggregating only raw market data, calculated streams compute derived values using predefined formulas applied to various inputs, including existing data streams, onchain state, and offchain APIs. Some inputs are decentralized aggregates (for example, crypto price streams from multiple independent providers), while others may come from a single protocol or API (for example, a specific vault contract or yield provider). Because a calculated stream depends on all of these inputs, you should evaluate their dependencies and failure modes carefully before using it in a value-securing application. + + + +## Why use calculated streams? + +- **Simpler integrations**: Consume one stream instead of implementing calculation logic in your contracts or backend +- **Canonical formulas**: All integrators use the same formula and inputs, ensuring consistency across protocols +- **Managed infrastructure**: Chainlink handles RPC calls, API integrations, and the calculation pipeline + +## How to identify calculated streams + +Calculated streams are marked with a Calculated badge in the documentation. + +## How calculated streams work + +Calculated streams leverage existing Data Streams infrastructure. Data providers feed market data into the DON, which produces base streams. The DON then uses these base streams—along with onchain state and offchain APIs—as inputs to calculate derived values. + +### Architecture flow + +1. **Data collection**: The DON retrieves inputs specific to each calculated stream, which may include: + - Existing Data Streams (market prices from multiple independent data providers) + - Onchain state via RPC calls (vault balances, token supplies, contract data) + - Offchain data via APIs (yield rates, interest components, external reference data) +2. **Calculation**: The DON applies the predefined formula to combine the inputs +3. **Consensus and signing**: Nodes reach consensus on the calculated value and sign the report +4. **Publication**: Calculated streams are published through the Data Streams Aggregation Network + +### Input sources + +The inputs for a calculated stream depend on what it's computing. A stream might use: + +#### Existing Data Streams + +Market prices already aggregated from multiple independent sources (3+ providers). Example: using individual crypto asset prices as inputs for an index calculation. + +#### Onchain state + +Protocol-specific data read via RPC, such as vault balances, token supplies, or smart contract state. May come from a single protocol's contracts. + +#### Offchain APIs + +External data from specific trusted providers, such as yield rates or reference values. May come from a single API endpoint. + +### Calculation and output + +The DON executes the predefined formula (weighted averages, ratios, sums, etc.) using the latest available inputs. The calculated value is packaged into a signed report with standard metadata (timestamps, fees) and published through the Data Streams Aggregation Network. You consume these reports using the same REST APIs, WebSocket connections, and onchain verification as traditional streams. + +*** + +## Risks and mitigation + +Calculated streams inherit risks from their underlying inputs and introduce additional considerations due to combining multiple data sources. + +### Multiple dependencies + +If a required input becomes unavailable or unreliable, the calculated stream might stop updating or cease to reflect current conditions. Integrators should not assume any specific fallback behavior and must design their protocols to handle this scenario explicitly. + +#### Mitigation + +- Design your protocol to handle missing data gracefully (pause operations, use last-known values, or implement fallbacks based on your risk tolerance) + +### Timing and synchronization + +Inputs update at different frequencies and are read via separate calls, so they may reflect slightly different block heights or timestamps. The calculated value is an approximation based on the latest available data from each input, not a single-block atomic snapshot. + +Users should expect small, transient differences between the calculated stream value and values observed on block explorers, vault dashboards, or DEX charts—especially during rapid changes such as large deposits, withdrawals, or sharp market moves. This does not necessarily indicate an issue with the stream, but is a natural consequence of combining multiple inputs with different update cadences. + +#### Mitigation + +- Implement max deviation checks against expected ranges +- Use time-weighted averages or circuit breakers for extreme moves +- Monitor trends over time rather than reacting to individual updates + + + +*** + +## Example: Tokenized yield product + +A calculated stream for a tokenized yield-bearing vault might combine: + +- **Vault balance (onchain)**: Total assets in the vault contract +- **Token supply (onchain)**: Circulating supply of vault shares +- **Accrued yield (offchain)**: Interest from an external API + +**Formula:** `(vault balance + accrued yield) / token supply` + +**Result**: a price per share that reflects the vault's total value including pending yield. + +Without this stream, protocols accepting the vault token as collateral would need to query the vault contract, fetch accrued interest from the yield provider's API, perform the calculation themselves, and keep this logic synchronized across all integrators. A calculated stream helps ensure integrators apply the same pricing logic and update together when the underlying formula or yield source changes. + +## Best practices + +### Protocol design + +- Set deviation limits to cap price changes per update or time window +- Compare calculated values against market references when available (e.g., spot prices for index tokens) +- Define fallback behavior if the stream stops updating or jumps beyond thresholds + +### Monitoring + +- Track the calculated stream value over time to establish normal behavior +- Monitor key inputs independently when feasible (vault balances, token supplies) to cross-check outputs +- Alert on update gaps or movements outside your safe range + +### Handling updates + +- Subscribe to Chainlink release notes for formula changes +- Test new streams or updated configurations in staging + +--- + # DEX State Price Streams Source: https://docs.chain.link/data-streams/concepts/dex-state-price-streams diff --git a/src/features/feeds/components/Tables.tsx b/src/features/feeds/components/Tables.tsx index a32e992f987..bb74e761f11 100644 --- a/src/features/feeds/components/Tables.tsx +++ b/src/features/feeds/components/Tables.tsx @@ -846,6 +846,13 @@ export const StreamsTr = ({ metadata, isMainnet }) => { // Determine if stream is deprecating const isDeprecating = !!metadata.docs?.shutdownDate + // Temporary calculated stream detection until proper metadata tagging is implemented + // TODO: Replace with metadata.docs.isCalculated or similar once available + const isCalculatedStream = + metadata.docs?.productTypeCode === "ExRate" && + metadata.docs?.attributeType === "ExchangeRate" && + metadata.docs?.assetClass === "Tokenized Debt" + return ( @@ -860,6 +867,16 @@ export const StreamsTr = ({ metadata, isMainnet }) => { DEX State Price )} + {isCalculatedStream && ( + + Calculated + + )} {metadata.docs.shutdownDate && (