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..755fc97cfd5 --- /dev/null +++ b/src/content/data-streams/concepts/calculated-streams.mdx @@ -0,0 +1,156 @@ +--- +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 Crypto streams": "/data-streams/crypto-streams", + "Find the list of available RWA streams": "/data-streams/rwa-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 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 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 && (