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:
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.
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.
Step 1: Initialize new hardhat project
In the first step, we are establishing a basic solidity development setup.
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.
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).
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.
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.
./scripts/fundVerifier.ts
import { ethers } from "hardhat";
// PullVerifier contract address on ETH Sepolia
const PullVerifierAddress = "0xBd0AFEE88B7FcEE6139467700D6f40F13FEDa739";
async function main() {
// Use default hardhat signer to fund the PullConsumer contract
const [funder] = await ethers.getSigners();
// 0.0003 is the exact cost for 10 updates on eth_seoplia
const depositAmount = ethers.parseEther("0.0003");
// Send funding transaction
const tx = await funder.sendTransaction({
to: PullVerifierAddress ,
value: depositAmount
});
await tx.wait();
console.log(`sent ${depositAmount} to PullVerifier, tx: ${tx.hash}`);
}
main()
.then(() => process.exit(0))
.catch(error => {
console.error(error);
process.exit(1);
});
Change the PullConsumerAddress to the address you got from deployment and execute the script to fund the deployed PullConsumer contract.
yarn hardhat run ./scripts/fundVerifier.ts --network eth_sepolia
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.
yarn add --dev @entangle-labs/udf-sdk
Copy the script below to the scripts/fetchAndVerify.ts file.
Don't forget to change the PullVerifierAddress to your contract address.
scripts/fetchAndVerify.ts
import { ethers } from "hardhat";
import {
PullVerifier,
} from "../typechain-types";
import { UdfSdk } from '@entangle-labs/udf-sdk';
// PullVerifier contract address on ETH Sepolia
const PullVerifierAddress = "0xBd0AFEE88B7FcEE6139467700D6f40F13FEDa739";
async function main() {
// Fetch the update data from finalized-data-snap
const sdk = new UdfSdk();
const updateData = await sdk.getCallData(["BTC/USD"]);
const feedKey = ethers.encodeBytes32String("BTC/USD");
// Bind PullVerifier contract on the network
const verifier = await ethers.getContractAt(
"PullVerifier",
PullVerifierAddress
);
// Send verify transaction
let tx = await verifier.VerifyPAYG(
updateData,feedKey
);
await tx.wait();
console.log("sent tx:", tx.hash);
let price = await verifier.latestPrice();
let timestamp = await verifier.latestTimestamp();
console.log("price:", price );
console.log("timestamp:", timestamp );
}
main()
.then(() => process.exit(0))
.catch(error => {
console.error(error);
process.exit(1);
});
Now let’s execute the script using the command below.
yarn hardhat run ./scripts/fetchAndVerify.ts --network eth_sepolia
Expected Result
sent tx: 0xb66fb4112b7fdf72211c2238b9b0a609a8321e2694ddad9b69ec7dcc953fdb18
price: 76683771643884818373141n
timestamp: 1744027087n
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.
cast run 0xb66fb4112b7fdf72211c2238b9b0a609a8321e2694ddad9b69ec7dcc953fdb18 -r https://eth-sepolia.public.blastapi.io
