Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Data Streams - Update #1869

Merged
merged 12 commits into from
Apr 23, 2024
Merged

Data Streams - Update #1869

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
f2dda47
DS Update
khadni Apr 10, 2024
5bf9591
DS Update
khadni Apr 10, 2024
882ea63
Update src/features/chainlink-automation/common/StreamsLookupInterfac…
khadni Apr 10, 2024
fa1acec
Merge branch 'main' into data-streams-update
khadni Apr 10, 2024
46baf17
Merge branch 'main' into data-streams-update
khadni Apr 10, 2024
dc4b918
Merge branch 'main' into data-streams-update
khadni Apr 15, 2024
54ebaea
Report schema note
khadni Apr 15, 2024
4a2b15b
Merge branch 'main' into data-streams-update
dwightjl Apr 23, 2024
53198cf
Update RRD Preview URL
dwightjl Apr 23, 2024
6bf1224
Update notes
khadni Apr 23, 2024
2b034d5
Update diagrams
khadni Apr 23, 2024
9701fa5
Merge branch 'main' into data-streams-update
khadni Apr 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion public/samples/DataStreams/LogEmitter.sol
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: GPL-3.0

pragma solidity >=0.8.19;
pragma solidity 0.8.19;

contract LogEmitter {
event Log(address indexed msgSender);
Expand Down
43 changes: 25 additions & 18 deletions public/samples/DataStreams/StreamsUpkeep.sol
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,14 @@ import {IERC20} from "@chainlink/contracts/src/v0.8/vendor/openzeppelin-solidity

// Custom interfaces for IVerifierProxy and IFeeManager
interface IVerifierProxy {
/**
* @notice Verifies that the data encoded has been signed.
* correctly by routing to the correct verifier, and bills the user if applicable.
* @param payload The encoded data to be verified, including the signed
* report.
* @param parameterPayload Fee metadata for billing. For the current implementation this is just the abi-encoded fee token ERC-20 address.
* @return verifierResponse The encoded report from the verifier.
*/
function verify(
bytes calldata payload,
bytes calldata parameterPayload
Expand All @@ -24,6 +32,18 @@ interface IVerifierProxy {
}

interface IFeeManager {
/**
* @notice Calculates the fee and reward associated with verifying a report, including discounts for subscribers.
* This function assesses the fee and reward for report verification, applying a discount for recognized subscriber addresses.
* @param subscriber The address attempting to verify the report. A discount is applied if this address
* is recognized as a subscriber.
* @param unverifiedReport The report data awaiting verification. The content of this report is used to
* determine the base fee and reward, before considering subscriber discounts.
* @param quoteAddress The payment token address used for quoting fees and rewards.
* @return fee The fee assessed for verifying the report, with subscriber discounts applied where applicable.
* @return reward The reward allocated to the caller for successfully verifying the report.
* @return totalDiscount The total discount amount deducted from the fee for subscribers.
*/
function getFeeAndReward(
address subscriber,
bytes memory unverifiedReport,
Expand All @@ -38,17 +58,7 @@ interface IFeeManager {
}

contract StreamsUpkeep is ILogAutomation, StreamsLookupCompatibleInterface {
struct BasicReport {
bytes32 feedId; // The feed ID the report has data for
uint32 validFromTimestamp; // Earliest timestamp for which price is applicable
uint32 observationsTimestamp; // Latest timestamp for which price is applicable
uint192 nativeFee; // Base cost to validate a transaction using the report, denominated in the chain’s native token (WETH/ETH)
uint192 linkFee; // Base cost to validate a transaction using the report, denominated in LINK
uint32 expiresAt; // Latest timestamp where the report can be verified onchain
int192 price; // DON consensus median price, carried to 8 decimal places
}

struct PremiumReport {
struct Report {
bytes32 feedId; // The feed ID the report has data for
uint32 validFromTimestamp; // Earliest timestamp for which price is applicable
uint32 observationsTimestamp; // Latest timestamp for which price is applicable
Expand All @@ -73,10 +83,10 @@ contract StreamsUpkeep is ILogAutomation, StreamsLookupCompatibleInterface {
string public constant DATASTREAMS_QUERYLABEL = "timestamp";
int192 public last_retrieved_price;

// This example reads the ID for the basic ETH/USD price report on Arbitrum Sepolia.
// This example reads the ID for the ETH/USD report on Arbitrum Sepolia.
// Find a complete list of IDs at https://docs.chain.link/data-streams/stream-ids
string[] public feedIds = [
"0x00027bbaff688c906a3e20a34fe951715d1018d262a5b66e38eda027a674cd1b"
"0x000359843a543ee2fe414dc14c7e7920ef10f4372990b79d6361cdc0dd1ba782"
];

constructor(address _verifier) {
Expand Down Expand Up @@ -162,11 +172,8 @@ contract StreamsUpkeep is ILogAutomation, StreamsLookupCompatibleInterface {
abi.encode(feeTokenAddress)
);

// Decode verified report data into BasicReport struct
BasicReport memory verifiedReport = abi.decode(
verifiedReportData,
(BasicReport)
);
// Decode verified report data into a Report struct
Report memory verifiedReport = abi.decode(verifiedReportData, (Report));

// Log price from report
emit PriceUpdate(verifiedReport.price);
Expand Down
19 changes: 3 additions & 16 deletions public/samples/DataStreams/StreamsUpkeepRegistrar.sol
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,17 +85,7 @@ contract StreamsUpkeepRegistrar is
LinkTokenInterface public immutable i_link;
AutomationRegistrarInterface public immutable i_registrar;

struct BasicReport {
bytes32 feedId; // The feed ID the report has data for
uint32 validFromTimestamp; // Earliest timestamp for which price is applicable
uint32 observationsTimestamp; // Latest timestamp for which price is applicable
uint192 nativeFee; // Base cost to validate a transaction using the report, denominated in the chain’s native token (WETH/ETH)
uint192 linkFee; // Base cost to validate a transaction using the report, denominated in LINK
uint32 expiresAt; // Latest timestamp where the report can be verified onchain
int192 price; // DON consensus median price, carried to 8 decimal places
}

struct PremiumReport {
struct Report {
bytes32 feedId; // The feed ID the report has data for
uint32 validFromTimestamp; // Earliest timestamp for which price is applicable
uint32 observationsTimestamp; // Latest timestamp for which price is applicable
Expand Down Expand Up @@ -233,11 +223,8 @@ contract StreamsUpkeepRegistrar is
abi.encode(feeTokenAddress)
);

// Decode verified report data into BasicReport struct
BasicReport memory verifiedReport = abi.decode(
verifiedReportData,
(BasicReport)
);
// Decode verified report data into a Report struct
Report memory verifiedReport = abi.decode(verifiedReportData, (Report));

// Log price from report
emit PriceUpdate(verifiedReport.price);
Expand Down
4 changes: 2 additions & 2 deletions src/content/data-streams/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,8 +46,8 @@ Chainlink Data Streams supports fee payments in LINK and in alternative assets,

Chainlink Data Streams has the following core components:

- **A Chainlink Decentralized Oracle Network (DON):** This DON operates similarly to the DONs that power [Chainlink Data Feeds](/data-feeds), but the key difference is that it signs and delivers reports to the Chainlink Data Engine rather than delivering answers onchain directly. This allows the Data Streams DON to deliver reports more frequently for time-sensitive applications. Nodes in the DON retrieve data from many different data providers, reach a concensus about the median price of an asset, sign a report including that data, and deliver the report to the Chainlink Data Engine.
- **The Chainlink Data Engine:** The Data Engine stores the signed reports and delivers them to Chainlink Automation when it is requested.
- **A Chainlink Decentralized Oracle Network (DON):** This DON operates similarly to the DONs that power [Chainlink Data Feeds](/data-feeds), but the key difference is that it signs and delivers reports to the Data Streams Aggregation Network rather than delivering answers onchain directly. This allows the Data Streams DON to deliver reports more frequently for time-sensitive applications. Nodes in the DON retrieve data from many different data providers, reach a concensus about the median price of an asset, sign a report including that data, and deliver the report to the Data Streams Aggregation Network.
- **The Data Streams Aggregation Network:** The Data Streams Aggregation Network stores the signed reports and delivers them to Chainlink Automation when it is requested.
- **The Chainlink Verifier Contract:** This contract verifies the signature from the DON to cryptographically guarantee that the report has not been altered from the time that the DON reached concensus to the point where you use the data in your application.

<ClickToZoom src="/images/data-streams/data-streams-architecture.webp" />
Expand Down
37 changes: 13 additions & 24 deletions src/content/data-streams/reference/report-schema.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,27 +15,16 @@ import { Aside } from "@components"
integrating Chainlink Data Streams with your applications.
</Aside>

Data Streams can deliver a broad array of information in each report. The values you can expect in each report depend on the schema for the Stream ID that you select. You can find the schema for each ID on the [Stream IDs](/data-streams/stream-ids) page.

## Basic schema

Streams with the `Basic` schema have the following values specifically applicable to market pricing data:

| Value | Type | Description |
| ----------------------- | --------- | ----------------------------------------------------------------------------- |
| `feedID` | `bytes32` | The unique identifier for the stream |
| `validFromTimestamp` | `uint32` | The earliest timestamp during which the price is valid |
| `observationsTimestamp` | `uint32` | The latest timestamp during which the price is valid |
| `nativeFee` | `uint192` | The cost to verify this report when paying with the blockchain's native token |
| `linkFee` | `uint192` | The cost to verify this report when paying with LINK |
| `expiresAt` | `uint32` | The expiration date of this report |
| `price` | `int192` | The DON's consensus median price for this report carried to 8 decimal places |

## Premium schema

The `Premium` schema includes all values from the `Basic` schema, and also includes `bid` and `ask` values:

| Value | Type | Description |
| ----- | -------- | ------------------------------------------------------------------------------- |
| `bid` | `int192` | The simulated price impact of a buy order up to the X% depth of liquidity usage |
| `ask` | `int192` | Simulated price impact of a sell order up to the X% depth of liquidity usage |
Data Streams feeds have the following values specifically applicable to market pricing data. They adhere to the schema outlined below:

| Value | Type | Description |
| ----------------------- | --------- | ------------------------------------------------------------------------------------- |
| `feedID` | `bytes32` | The unique identifier for the Data Streams feed |
| `validFromTimestamp` | `uint32` | The earliest timestamp during which the price is valid |
| `observationsTimestamp` | `uint32` | The latest timestamp during which the price is valid |
| `nativeFee` | `uint192` | The cost to verify this report onchain when paying with the blockchain's native token |
| `linkFee` | `uint192` | The cost to verify this report onchain when paying with LINK |
| `expiresAt` | `uint32` | The expiration date of this report |
| `price` | `int192` | The DON's consensus median price for this report carried to 18 decimal places |
| `bid` | `int192` | The simulated price impact of a buy order up to the X% depth of liquidity usage |
| `ask` | `int192` | Simulated price impact of a sell order up to the X% depth of liquidity usage |
28 changes: 14 additions & 14 deletions src/features/chainlink-automation/common/StreamsLookupInterface.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,13 @@ Automation network will use this revert to trigger fetching of the specified rep

#### Parameters

| Variable Name | Type | Description | Permissible Values |
| -------------- | ---------- | ----------------------------------------------------------------------- | ------------------------------------------------------- |
| `feedParamKey` | `String` | Specify the feed identifiers that will be provided | `"feedIDs"` |
| `feeds` | `String[]` | String list of feed identifiers | e.g. `["feedID1","feedID2",..]` with a maximum of 5 IDs |
| `timeParamKey` | `String` | Specify query type | `"timestamp"` |
| `time` | `uint256` | Specify query value | `block.timestamp` |
| `extraData` | `bytes` | Any extra data user wants to receive in callback, alongside API bytes[] | log data |
| Variable Name | Type | Description | Permissible Values |
| -------------- | ---------- | ----------------------------------------------------------------------- | --------------------------------------------------------------- |
| `feedParamKey` | `String` | Specify the feed identifiers that will be provided | `"feedIDs"` |
| `feeds` | `String[]` | String list of feed identifiers | e.g. `["feedID1","feedID2",..]` with a maximum of 5 IDs |
| `timeParamKey` | `String` | Specify query type | `"timestamp"` |
| `time` | `uint256` | Specify query value | e.g. `log.timestamp` from the returned Log struct in `checkLog` |
| `extraData` | `bytes` | Any extra data user wants to receive in callback, alongside API bytes[] | e.gc. log data |
khadni marked this conversation as resolved.
Show resolved Hide resolved

#### Outputs

Expand All @@ -28,7 +28,7 @@ The fetched signed reports will be provided to the user in [`checkCallback`](#ch
| Variable Name | Type | Description | Usage examples |
| ------------- | --------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `values` | `bytes[]` | List of signed reports fetched from API | List of signed reports `values[0], values[1]…` ordered to match order in feeds |
| `extraData` | `bytes` | Bytes data sent as part of original MercuryLookup revert error | e.g. can send log data if you want to decode to use |
| `extraData` | `bytes` | Bytes data sent as part of original StreamsLookup revert error | e.g. can send log data if you want to decode to use |

### checkCallback function

Expand All @@ -38,15 +38,15 @@ This is a `view` function that will be simulated offchain to receive the signed

| Variable Name | Type | Description | Permissible Values |
| ------------- | --------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `values` | `bytes[]` | List of signed reports fetched from API | List of signed reports `values[0], values[1]…` ordered to match order in feeds |
| `extraData` | `bytes` | Bytes data sent as part of original MercuryLookup revert error | e.g. can send log data if you want to decode to use |
| `values` | `bytes[]` | List of signed reports fetched from Data Streams API | List of signed reports `values[0], values[1]…` ordered to match order in feeds |
| `extraData` | `bytes` | Bytes data sent as part of original StreamsLookup revert error | e.g. can send log data if you want to decode to use |

#### Outputs

| Variable Name | Type | Description | Permissible Values |
| -------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| `performData` | `bytes` | Data encoded in the `oracleCallback` function that will be used to execute function onchain, e.g. encode signed reports and log data if need be | `bytes` |
| `upkeepNeeded` | `boolean` | When set to `true` this will trigger the `performUpkeep` function to be executed onchain | `true` of `false` |
| Variable Name | Type | Description | Permissible Values |
| -------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| `performData` | `bytes` | Encoded data that will be used to execute the `performUpkeep` function onchain. E.g. encoded signed reports and log data if need be | `bytes` |
| `upkeepNeeded` | `boolean` | When set to `true`, this will trigger the `performUpkeep` function to be executed onchain | `true` of `false` |

### checkErrorHandler function

Expand Down
6 changes: 3 additions & 3 deletions src/features/chainlink-automation/common/iLogAutomation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,6 @@ This function contains the code that will be executed onchain to finalize the tr

#### Parameters

| Variable Name | Type | Description | Permissible Values |
| ------------- | ------- | ----------------------------------------------------------------------------------------- | ------------------ |
| `performData` | `bytes` | Data encoded in the `checkLog` function that will be used to execute the function onchain | bytes |
| Variable Name | Type | Description | Permissible Values |
| ------------- | ------- | ---------------------------------------------------------------------------------------------- | ------------------ |
| `performData` | `bytes` | Data encoded in the `checkCallback` function that will be used to execute the function onchain | bytes |
Loading
Loading