Merge branch 'main' into llms-full-text

Author: gfletcher-cll

public/samples/DataStreams/ClientReportsVerifier.sol

@@ -1,9 +1,7 @@
 // SPDX-License-Identifier: MIT
-
 pragma solidity 0.8.19;
 
 import {Common} from "@chainlink/contracts/src/v0.8/llo-feeds/libraries/Common.sol";
-import {IRewardManager} from "@chainlink/contracts/src/v0.8/llo-feeds/v0.3.0/interfaces/IRewardManager.sol";
 import {IVerifierFeeManager} from "@chainlink/contracts/src/v0.8/llo-feeds/v0.3.0/interfaces/IVerifierFeeManager.sol";
 import {IERC20} from "@chainlink/contracts/src/v0.8/vendor/openzeppelin-solidity/v4.8.3/contracts/token/ERC20/IERC20.sol";
 import {SafeERC20} from "@chainlink/contracts/src/v0.8/vendor/openzeppelin-solidity/v4.8.3/contracts/token/ERC20/utils/SafeERC20.sol";
@@ -13,27 +11,37 @@ using SafeERC20 for IERC20;
 /**
  * THIS IS AN EXAMPLE CONTRACT THAT USES UN-AUDITED CODE FOR DEMONSTRATION PURPOSES.
  * DO NOT USE THIS CODE IN PRODUCTION.
+ *
+ *  This contract can verify Chainlink Data Streams reports onchain and pay
+ *  the verification fee in LINK (when required).
+ *
+ * - If `VerifierProxy.s_feeManager()` returns a non-zero address, the network
+ *   expects you to interact with that FeeManager for every verification call:
+ *   quote fees, approve the RewardManager, then call `verify()`.
+ *
+ * - If `s_feeManager()` returns the zero address, no FeeManager contract has
+ *   been deployed on that chain. In that case there is nothing to quote or pay
+ *   onchain, so the contract skips the fee logic entirely.
+ *
+ *  The `if (address(feeManager) != address(0))` check below chooses the
+ *  correct path automatically, making the same bytecode usable on any chain.
  */
 
-// Custom interfaces for IVerifierProxy and IFeeManager
+// ────────────────────────────────────────────────────────────────────────────
+//  Interfaces
+// ────────────────────────────────────────────────────────────────────────────
+
 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. In the current implementation, this consists of the abi-encoded address of the ERC-20 token used for fees.
-     * @return verifierResponse The encoded report from the verifier.
+     * @notice Route a report to the correct verifier and (optionally) bill fees.
+     * @param payload           Full report payload (header + signed report).
+     * @param parameterPayload  ABI-encoded fee metadata.
      */
     function verify(
         bytes calldata payload,
         bytes calldata parameterPayload
     ) external payable returns (bytes memory verifierResponse);
 
-    /**
-     * @notice Verifies multiple reports in bulk, ensuring that each is signed correctly, routes them to the appropriate verifier, and handles billing for the verification process.
-     * @param payloads An array of encoded data to be verified, where each entry includes the signed report.
-     * @param parameterPayload Fee metadata for billing. In the current implementation, this consists of the abi-encoded address of the ERC-20 token used for fees.
-     * @return verifiedReports An array of encoded reports returned from the verifier.
-     */
     function verifyBulk(
         bytes[] calldata payloads,
         bytes calldata parameterPayload
@@ -44,14 +52,7 @@ 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.
+     * @return fee, reward, totalDiscount
      */
     function getFeeAndReward(
         address subscriber,
@@ -66,179 +67,160 @@ interface IFeeManager {
     function i_rewardManager() external view returns (address);
 }
 
+// ────────────────────────────────────────────────────────────────────────────
+//  Contract
+// ────────────────────────────────────────────────────────────────────────────
+
 /**
  * @dev This contract implements functionality to verify Data Streams reports from
- * the Streams Direct API or WebSocket connection, with payment in LINK tokens.
+ * the Data Streams API, with payment in LINK tokens.
  */
 contract ClientReportsVerifier {
-    error NothingToWithdraw(); // Thrown when a withdrawal attempt is made but the contract holds no tokens of the specified type.
-    error NotOwner(address caller); // Thrown when a caller tries to execute a function that is restricted to the contract's owner.
-    error InvalidReportVersion(uint16 version); // Thrown when an unsupported report version is provided to verifyReport.
+    // ----------------- Errors -----------------
+    error NothingToWithdraw();
+    error NotOwner(address caller);
+    error InvalidReportVersion(uint16 version);
 
+    // ----------------- Report schemas -----------------
+    // More info: https://docs.chain.link/data-streams/reference/report-schema
     /**
-     * @dev Represents a data report from a Data Streams stream for v3 schema (crypto streams).
-     * The `price`, `bid`, and `ask` values are carried to either 8 or 18 decimal places, depending on the stream.
-     * For more information, see https://docs.chain.link/data-streams/crypto-streams and https://docs.chain.link/data-streams/reference/report-schema
+     * @dev Data Streams report schema v3 (crypto streams).
+     *      Prices, bids and asks use 8 or 18 decimals depending on the stream.
      */
     struct ReportV3 {
-        bytes32 feedId; // The stream 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 (e.g., 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 (8 or 18 decimals).
-        int192 bid; // Simulated price impact of a buy order up to the X% depth of liquidity utilisation (8 or 18 decimals).
-        int192 ask; // Simulated price impact of a sell order up to the X% depth of liquidity utilisation (8 or 18 decimals).
+        bytes32 feedId;
+        uint32 validFromTimestamp;
+        uint32 observationsTimestamp;
+        uint192 nativeFee;
+        uint192 linkFee;
+        uint32 expiresAt;
+        int192 price;
+        int192 bid;
+        int192 ask;
     }
 
     /**
-     * @dev Represents a data report from a Data Streams stream for v4 schema (RWA stream).
-     * The `price` value is carried to either 8 or 18 decimal places, depending on the stream.
-     * The `marketStatus` indicates whether the market is currently open. Possible values: `0` (`Unknown`), `1` (`Closed`), `2` (`Open`).
-     * For more information, see https://docs.chain.link/data-streams/rwa-streams and https://docs.chain.link/data-streams/reference/report-schema-v4
+     * @dev Data Streams report schema v4 (RWA streams).
      */
     struct ReportV4 {
-        bytes32 feedId; // The stream 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 (e.g., 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 benchmark price (8 or 18 decimals).
-        uint32 marketStatus; // The DON's consensus on whether the market is currently open.
+        bytes32 feedId;
+        uint32 validFromTimestamp;
+        uint32 observationsTimestamp;
+        uint192 nativeFee;
+        uint192 linkFee;
+        uint32 expiresAt;
+        int192 price;
+        uint32 marketStatus;
     }
 
-    IVerifierProxy public s_verifierProxy; // The VerifierProxy contract used for report verification.
+    // ----------------- Storage -----------------
+    IVerifierProxy public immutable i_verifierProxy;
+    address private immutable i_owner;
 
-    address private s_owner; // The owner of the contract.
-    int192 public lastDecodedPrice; // Stores the last decoded price from a verified report.
+    int192 public lastDecodedPrice;
 
-    event DecodedPrice(int192 price); // Event emitted when a report is successfully verified and decoded.
+    // ----------------- Events -----------------
+    event DecodedPrice(int192 price);
 
+    // ----------------- Constructor / modifier -----------------
     /**
-     * @param _verifierProxy The address of the VerifierProxy contract.
-     * You can find these addresses on https://docs.chain.link/data-streams/crypto-streams.
+     * @param _verifierProxy Address of the VerifierProxy on the target network.
+     *        Addresses: https://docs.chain.link/data-streams/crypto-streams
      */
     constructor(address _verifierProxy) {
-        s_owner = msg.sender;
-        s_verifierProxy = IVerifierProxy(_verifierProxy);
+        i_owner = msg.sender;
+        i_verifierProxy = IVerifierProxy(_verifierProxy);
     }
 
-    /// @notice Checks if the caller is the owner of the contract.
     modifier onlyOwner() {
-        if (msg.sender != s_owner) revert NotOwner(msg.sender);
+        if (msg.sender != i_owner) revert NotOwner(msg.sender);
         _;
     }
 
+    // ----------------- Public API -----------------
+
     /**
-     * @notice Verifies an unverified data report and processes its contents, supporting both v3 and v4 report schemas.
-     * @dev Performs the following steps:
-     * - Decodes the unverified report to extract the report data.
-     * - Extracts the report version by reading the first two bytes of the report data.
-     *   - The first two bytes correspond to the schema version encoded in the stream ID.
-     *   - Schema version `0x0003` corresponds to report version 3 (for Crypto assets).
-     *   - Schema version `0x0004` corresponds to report version 4 (for Real World Assets).
-     * - Validates that the report version is either 3 or 4; reverts with `InvalidReportVersion` otherwise.
-     * - Retrieves the fee manager and reward manager contracts.
-     * - Calculates the fee required for report verification using the fee manager.
-     * - Approves the reward manager to spend the calculated fee amount.
-     * - Verifies the report via the VerifierProxy contract.
-     * - Decodes the verified report data into the appropriate report struct (`ReportV3` or `ReportV4`) based on the report version.
-     * - Emits a `DecodedPrice` event with the price extracted from the verified report.
-     * - Updates the `lastDecodedPrice` state variable with the price from the verified report.
-     * @param unverifiedReport The encoded report data to be verified, including the signed report and metadata.
-     * @custom:reverts InvalidReportVersion(uint8 version) Thrown when an unsupported report version is provided.
+     * @notice Verify a Data Streams report (schema v3 or v4).
+     *
+     * @dev Steps:
+     *  1. Decode the unverified report to get `reportData`.
+     *  2. Read the first two bytes → schema version (`0x0003` or `0x0004`).
+     *     - Revert if the version is unsupported.
+     *  3. Fee handling:
+     *     - Query `s_feeManager()` on the proxy.
+     *       – Non-zero → quote the fee, approve the RewardManager,
+     *         ABI-encode the fee token address for `verify()`.
+     *       – Zero     → no FeeManager; skip quoting/approval and pass `""`.
+     *  4. Call `VerifierProxy.verify()`.
+     *  5. Decode the verified report into the correct struct and emit the price.
+     *
+     *  @param unverifiedReport Full payload returned by Streams Direct.
+     *  @custom:reverts InvalidReportVersion when schema ≠ v3/v4.
      */
     function verifyReport(bytes memory unverifiedReport) external {
-        // Retrieve fee manager and reward manager
-        IFeeManager feeManager = IFeeManager(
-            address(s_verifierProxy.s_feeManager())
-        );
-
-        IRewardManager rewardManager = IRewardManager(
-            address(feeManager.i_rewardManager())
-        );
-
-        // Decode unverified report to extract report data
+        // ─── 1. & 2. Extract reportData and schema version ──
         (, bytes memory reportData) = abi.decode(
             unverifiedReport,
             (bytes32[3], bytes)
         );
 
-        // Extract report version from reportData
         uint16 reportVersion = (uint16(uint8(reportData[0])) << 8) |
             uint16(uint8(reportData[1]));
+        if (reportVersion != 3 && reportVersion != 4)
+            revert InvalidReportVersion(reportVersion);
 
-        // Validate report version
-        if (reportVersion != 3 && reportVersion != 4) {
-            revert InvalidReportVersion(uint8(reportVersion));
-        }
+        // ─── 3. Fee handling ──
+        IFeeManager feeManager = IFeeManager(
+            address(i_verifierProxy.s_feeManager())
+        );
 
-        // Set the fee token address (LINK in this case)
-        address feeTokenAddress = feeManager.i_linkAddress();
+        bytes memory parameterPayload;
+        if (address(feeManager) != address(0)) {
+            // FeeManager exists — always quote & approve
+            address feeToken = feeManager.i_linkAddress();
 
-        // Calculate the fee required for report verification
-        (Common.Asset memory fee, , ) = feeManager.getFeeAndReward(
-            address(this),
-            reportData,
-            feeTokenAddress
-        );
+            (Common.Asset memory fee, , ) = feeManager.getFeeAndReward(
+                address(this),
+                reportData,
+                feeToken
+            );
 
-        // Approve rewardManager to spend this contract's balance in fees
-        IERC20(feeTokenAddress).approve(address(rewardManager), fee.amount);
+            IERC20(feeToken).approve(feeManager.i_rewardManager(), fee.amount);
+            parameterPayload = abi.encode(feeToken);
+        } else {
+            // No FeeManager deployed on this chain
+            parameterPayload = bytes("");
+        }
 
-        // Verify the report through the VerifierProxy
-        bytes memory verifiedReportData = s_verifierProxy.verify(
+        // ─── 4. Verify through the proxy ──
+        bytes memory verified = i_verifierProxy.verify(
             unverifiedReport,
-            abi.encode(feeTokenAddress)
+            parameterPayload
         );
 
-        // Decode verified report data into the appropriate Report struct based on reportVersion
+        // ─── 5. Decode & store price ──
         if (reportVersion == 3) {
-            // v3 report schema
-            ReportV3 memory verifiedReport = abi.decode(
-                verifiedReportData,
-                (ReportV3)
-            );
-
-            // Log price from the verified report
-            emit DecodedPrice(verifiedReport.price);
-
-            // Store the price from the report
-            lastDecodedPrice = verifiedReport.price;
-        } else if (reportVersion == 4) {
-            // v4 report schema
-            ReportV4 memory verifiedReport = abi.decode(
-                verifiedReportData,
-                (ReportV4)
-            );
-
-            // Log price from the verified report
-            emit DecodedPrice(verifiedReport.price);
-
-            // Store the price from the report
-            lastDecodedPrice = verifiedReport.price;
+            int192 price = abi.decode(verified, (ReportV3)).price;
+            lastDecodedPrice = price;
+            emit DecodedPrice(price);
+        } else {
+            int192 price = abi.decode(verified, (ReportV4)).price;
+            lastDecodedPrice = price;
+            emit DecodedPrice(price);
         }
     }
 
     /**
-     * @notice Withdraws all tokens of a specific ERC20 token type to a beneficiary address.
-     * @dev Utilizes SafeERC20's safeTransfer for secure token transfer. Reverts if the contract's balance of the specified token is zero.
-     * @param _beneficiary Address to which the tokens will be sent. Must not be the zero address.
-     * @param _token Address of the ERC20 token to be withdrawn. Must be a valid ERC20 token contract.
+     * @notice Withdraw all balance of an ERC-20 token held by this contract.
+     * @param _beneficiary Address that receives the tokens.
+     * @param _token       ERC-20 token address.
      */
     function withdrawToken(
         address _beneficiary,
         address _token
-    ) public onlyOwner {
-        // Retrieve the balance of this contract for the specified token
+    ) external onlyOwner {
         uint256 amount = IERC20(_token).balanceOf(address(this));
-
-        // Revert if there is nothing to withdraw
         if (amount == 0) revert NothingToWithdraw();
-
-        // Transfer the tokens to the beneficiary
         IERC20(_token).safeTransfer(_beneficiary, amount);
     }
 }

src/content/data-feeds/aptos/index.mdx

@@ -124,7 +124,11 @@ You now have a funded testnet account on Aptos.
      aptos config show-profiles --profile=default
      ```
 
-   - The `data_feeds` address is the Chainlink Data Feeds contract address on Aptos testnet (`0xf1099f135ddddad1c065203431be328a408b0ca452ada70374ce26bd2b32fdd3`).
+   - The `data_feeds` address is the `ChainlinkDataFeeds` package address on Aptos testnet ([`0xf1099f135ddddad1c065203431be328a408b0ca452ada70374ce26bd2b32fdd3`](https://explorer.aptoslabs.com/object/0xf1099f135ddddad1c065203431be328a408b0ca452ada70374ce26bd2b32fdd3/modules/packages/ChainlinkDataFeeds?network=testnet)).
+
+   - The `platform` address is the `ChainlinkPlatform` package address on Aptos testnet ([`0x516e771e1b4a903afe74c27d057c65849ecc1383782f6642d7ff21425f4f9c99`](https://explorer.aptoslabs.com/object/0x516e771e1b4a903afe74c27d057c65849ecc1383782f6642d7ff21425f4f9c99/modules/packages/ChainlinkPlatform?network=testnet)).
+
+   **Note**: You can find the mainnet addresses in the [Feeds Addresses](/data-feeds/price-feeds/addresses?page=1&testnetPage=1&network=aptos) page.
 
 1. Run the following command to download the compiled bytecode for the `ChainlinkPlatform` and `ChainlinkDataFeeds` packages: