search

EVM Smart Contracts

In the Pull model, consumers include verification data about the most recent update directly in their transaction. This data is fetched from the oracle and verified within the same transaction before being used.

This scheme comes with the following properties:

  1. Consumers always use the latest update in their transaction, so the price used in the transaction is as close to real time as protocol update frequency.

  2. The cost for maintaining update relevance on-chain relies on end-consumers. This allows the oracle protocol to have much larger set of assets.

This guide will help developers who want to use Pull model (PAYG) within their contracts. It uses Hardhat for contract compilation, although similar methods apply with other frameworks.

hashtag
Step 1: Initialize new hardhat project

In the first step, we are establishing a basic solidity development setup.

yarn init -y
# yarn initialization flow
yarn add --dev hardhat
yarn hardhat init
# Hardhat initialization flow (select TypeScript project)

hashtag
Step 2: Write a contract that verifies an update in the transaction

Now create a new PullVerifier contract, which utilizes the pullMarketplace.verifyWithFee function to verify the update information provided through calldata. The update contains oracle votes along with their signatures.

Once the PullVerifier contract verifies the update against these inputs, it returns the verified value to the caller contract. If the verification fails (e.g., due to mismatched data, invalid signatures, or other inconsistencies) the contract reverts the entire transaction, ensuring that only valid data is accepted.

./contractrs/PullVerifier.sol
// SPDX-License-Identifier: BSL1.1
pragma solidity ^0.8.20;

interface IPullMarketplace  {
        struct PriceUpdate {
        uint256 price;
        uint256 timestamp;
    }
    function verifyWithFee(
        bytes calldata updateData,
        bytes32 feedKey
    ) external payable returns (PriceUpdate memory);
    function getUpdateFee(uint256 nUpdates) external view returns (uint256);
    
}
contract PullVerifier {
    IPullMarketplace public pullMarketplace;
    uint public latestPrice;
    uint public latestTimestamp;
    constructor(address _pullMarketplace){
        pullMarketplace = IPullMarketplace(_pullMarketplace);
    }
    // @notice function that verifies feed from provided update PAYG through PullMarketplace and stores update data
    function VerifyPAYG(bytes calldata updateData, bytes32 feedKey) external{
	  // Calculate required fee
        uint256 fee = pullMarketplace.getUpdateFee(1);
	// Verify the update
        IPullMarketplace.PriceUpdate memory priceUpdate = pullMarketplace.verifyWithFee{value: fee}(updateData, feedKey);
	// store update data
        latestPrice = priceUpdate.price;
        latestTimestamp = priceUpdate.timestamp;
    }
   

    // @notice deposit native tokens for fee coverage
   receive() payable external {}

}

Now that we have a contract, let's write a hardhat ignition script to deploy it.

hashtag
Step 3: Deploy the contract

circle-info

To deploy your contract on testnet, you'll need ETH eth_sepolia testnet tokens. You can obtain funds from public faucets (Option 1arrow-up-right, Option 2arrow-up-right, Option 3arrow-up-right, Option 4arrow-up-right, Option 5arrow-up-right).

Now let's modify the hardhat configuration file to add the eth_sepolia network.

Now we can deploy the PullVerifier contract by running the command below.

chevron-rightExpected Resulthashtag

hashtag
Step 4: Understanding update format and Finalized Data API

At this point, the PullConsumer contract is ready to verify updates that we send it. But before doing that, let's quickly go through the update format and the data that it expects.

As an example, let’s imagine you need BTC/USD price in your contract. First, we need to fetch the latest update from the Finalized Data backend service. This service constantly synchronizes its state with oracle's state and provides oracle data via convenient APIs (REST, WebSocket).

chevron-rightExpected Resulthashtag

This response provides all necessary details to verify the BTC/USD update, specifically:

  • feeds: An array containing parsed update data for requested feeds.

  • votes: Publisher's latest votes on the specific feed. This aggregated array of votes is necessary to obtain agreed-upon value on-chain.

    • Value: The data that Publisher observed.

    • Timestamp: Timestamp at which the Publisher observed that data.

    • Publisher: Publisher's public key.

    • Signature: ECDSA signature for the observed value. This signature represents commitment from publisher that this data is what he observed.

This data enables executing the transaction on the PullVerifier contract. To begin, fetch the latest update from the Finalized Data API for the BTC/USD price.

hashtag
Step 5: Send a transaction with the update data

Now that we understand the Finalized Data API, we can create scripts to demonstrate update verification.

First of all, we need to fund the PullVerifier contract, so it will be able to pay the verification fee. Copy the following code to the scripts/fundVerifier.ts file.

Change the PullConsumerAddress to the address you got from deployment and execute the script to fund the deployed PullConsumer contract.

Now we will need to create a script that retrieves an update from the API, parses the response, encodes it to EVM calldata, and sends a transaction to verify the update. The contract can then validate the update and incorporate the verified price into its on-chain logic.

First, add the UDF SDK library. We will use it to fetch the update using the REST API and encode it for on-chain usage.

Copy the script below to the scripts/fetchAndVerify.ts file.

circle-info

Don't forget to change the PullVerifierAddress to your contract address.

Now let’s execute the script using the command below.

chevron-rightExpected Resulthashtag

You can use cast to examine the transaction call trace and logs. The emitted event shows the latest update that we verified.

Note that gas usage may vary depending on the result and the version of the library in use.

chevron-rightExpected Resulthashtag
PreviousFetch Data via Pull Model (PAYG)NextSolana Smart Contracts

Last updated