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 latency.
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 UDF Pull model (with subscription) 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 PullVerifierSub contract, which utilizes the pullMarketplace.verifyAsSubscriber function to verify the update information provided through calldata. The update contains oracle votes along with their signatures.
This contract should already be in subscription so it can have access for verification. The subscription can be purchased from the marketplace and the consumer contract needs to be added as an authorized address for the subscription.
Once the PullVerifierSub contract verifies the update against these inputs, it stores them on-chain, to later be accessed. 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/PullVerifierSub.sol
// SPDX-License-Identifier: BSL1.1
pragma solidity ^0.8.20;
interface IPullMarketplace {
struct PriceUpdate {
uint256 price;
uint256 timestamp;
}
function verifyAsSubscriber(
bytes calldata updateData,
bytes32 feedKey
)
external
returns (PriceUpdate memory);
}
contract PullVerifierSub {
IPullMarketplace public pullMarketplace;
uint public latestPrice;
uint public latestTimestamp;
constructor(address _pullMarketplace){
pullMarketplace = IPullMarketplace(_pullMarketplace);
}
// @notice function that verifies feed as subscriber from provided update through UDFOracle and stores update data
function verify(bytes calldata updateData, bytes32 feedKey) external{
IPullMarketplace.PriceUpdate memory priceUpdate = pullMarketplace.verifyAsSubscriber(updateData,feedKey);
latestPrice = priceUpdate.price;
latestTimestamp = priceUpdate.timestamp;
}
}
Next, create an ignition script to help with deployment of the new PullVerifierSub contract.
Now we should add the deployed PullVerifierSub contract as an allowed address to our subscription, so that it can verify Pull updates.
Step 5: Execute transaction
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
To validate that we have our price, we will write an example backend script that send transaction to execute PullVerifierSub.verifyAsSubscriber. Let's create separate directory scripts and our new script verifyAsSub.ts to do just that.
mkdir scripts && touch ./scripts/verifyAsSub.ts
Change the PullVerifierAddress to the address you got from deployment and execute the script.
./scripts/verifyAsSub.ts
import {
PullVerifierSub,
} from "../typechain-types";
import { ethers } from "hardhat";
import { UdfSdk } from '@entangle-labs/udf-sdk';
// PullVerifierSub address we got from the deployment
const PullVerifierAddress = "0x7c0ad1Bb6c6dD48CA70C190B400aD56DeF61F43C";
async function main() {
const pullVerifier = await ethers.getContractAt(
"PullVerifierSub",
PullVerifierAddress
) as PullVerifierSub;
// 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");
let tx = await pullVerifier.verify(updateData,feedKey);
await tx.wait();
console.log("sent PullVerifierSub.verify tx", tx.hash);
let price = await pullVerifier.latestPrice();
let timestamp = await pullVerifier.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 run the script using the command below to ensure it's working.
yarn hardhat run ./scripts/verifyAsSub.ts --network eth_sepolia
Expected Results
sent PullVerifierSub.verify tx 0x7d202c67c1d3f04606743a406979eb4dd4a435be37eb0490c502895c28ecc0ec
price: 84087090417798546633122n
timestamp: 1743492361n
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 0x7d202c67c1d3f04606743a406979eb4dd4a435be37eb0490c502895c28ecc0ec -r https://ethereum-sepolia-rpc.publicnode.com
To deploy your contract on testnet, you'll need ETH eth_sepolia testnet tokens. You can obtain funds from public faucets (, , , , ).
To do that, go to the BTC/USD and select Pull Mode. Then add the address of the deployed PullVerifierSub contract under "Which addresses can read the contract?" and click Subscribe.
