Skip to Content
DocumentationRadixPull Oracle Flow

Pull Oracle Flow

The Morpher Oracle on Radix uses a pull-based approach where data is requested on-demand rather than pushed to the blockchain at regular intervals. This page explains the detailed flow of data from request to on-chain verification.

Data Flow Diagram

Step-by-Step Process

1. User Initiates Request

  • A user interacts with the DApp frontend (e.g., wants to buy a Gumball)
  • The frontend needs current price data to create the transaction

2. DApp Backend Creates Signed Request

  • The DApp backend prepares a request with:
    • Market ID (e.g., “GATEIO:XRD_USDT”)
    • Public key (BLS12-381) - this must match the key stored in the NFT
    • NFT ID (subscription identifier) - proves the DApp has paid for Oracle access
  • The backend signs this request with its private key to prove authenticity

3. Oracle Backend Verification

  • The Oracle backend receives the signed request
  • It verifies the signature is valid (signed by the claimed public key)
  • It checks that the NFT ID exists and is active
  • It confirms the public key in the request matches the one stored in the NFT
  • This multi-step verification ensures only paid subscribers can access the Oracle

4. Oracle Data Preparation and Signing

  • The Oracle backend retrieves the latest price data for the requested market
  • It adds important metadata:
    • Market ID (e.g., “GATEIO:XRD_USDT”)
    • Price value (e.g., 0.05 USD per XRD)
    • Nonce (unique identifier)
    • Data timestamp (when the price was recorded)
    • Oracle timestamp (when the data was signed)
    • Market status timestamp (when market status was last checked)
    • Market status (open/closed)
  • The Oracle signs this complete data package with its private key

5. Data Return to Frontend

  • The signed price data is returned to the DApp backend
  • The DApp backend forwards this data to the frontend
  • No modifications are made to the signed data to preserve its integrity

6. Transaction Creation

  • The frontend constructs a transaction manifest that includes:
    • The signed price data (exactly as received from the Oracle)
    • Instructions to call the Oracle component for verification
    • Instructions for the smart contract to use the verified data
    • For example, in the Gumball demo, instructions to mint a Gumball token

7. On-Chain Verification and Execution

  • The user approves and submits the transaction with the signed price data
  • The smart contract calls the Oracle component to verify the data
  • The Oracle component verifies:
    • The signature is valid (signed by the Oracle)
    • The data is fresh (recent timestamps)
    • The market status is appropriate
  • The Oracle component returns a verified PriceMessage to the smart contract
  • The smart contract can apply additional checks:
    • Maximum age of price data
    • Price thresholds or limits
  • If all checks pass, the transaction executes using the verified price data

Code Example: Request Signing

Here’s how a DApp backend would sign a request to the Oracle:

import { bytesToHex } from "@noble/curves/abstract/utils";
import { bls12_381 as bls } from '@noble/curves/bls12-381';
 
// Use custom DST for BLS signatures
const htfEthereum = { DST: 'BLS_SIG_BLS12381G2_XMD:SHA-256_SSWU_RO_POP_' };
 
export function getPublicKey(privateKey) {
    return Array.from(
        bls.getPublicKey(privateKey), 
        byte => byte.toString(16).padStart(2, '0')
    ).join('');
}
 
export function oracleRequestMsgToString(msg: OracleRequestMessage) {
    return `${msg.marketId}##${msg.publicKeyBLS}##${msg.nftId}`;
}
 
export async function getSignatureOracleRequest(marketId: string): Promise<OracleRequestMessage> {
    const nftId = process.env.ORACLE_NFT_ID; // Your NFT ID
    const pk = process.env.PK_DAPP; // Your private key from secure storage
    
    // Create the request message
    let oracleRequestMsg: OracleRequestMessage = {
        marketId,
        publicKeyBLS: getPublicKey(pk),
        nftId,
        signature: ""
    };
    
    // Convert message to string format for signing
    const msgString = oracleRequestMsgToString(oracleRequestMsg);
    const msgHex = Buffer.from(msgString, 'utf8').toString('hex');
    
    // Sign the message
    let signature = bytesToHex(await bls.sign(msgHex, pk, htfEthereum));
    oracleRequestMsg.signature = signature;
    
    return oracleRequestMsg;
}

Benefits of the Pull Oracle Approach

  1. On-Demand Data: Data is only fetched when needed, reducing unnecessary blockchain transactions
  2. Data Freshness: Each request gets the latest available data
  3. Reduced Costs: No continuous updates means lower overall costs
  4. Flexibility: DApps can request data for specific markets as needed
  5. Verifiability: All data includes signatures that can be verified on-chain

In the next section, we’ll explore the Integration Guide for implementing the Morpher Oracle in your DApp.

Oracle ArchitectureTimestamp Validation