OraclesProductsOn-Demand Pull OracleInfrastructure

Infrastructure

This article reviews Charli3’s ODV (On-Demand Validation) oracle contracts and its integration with the Cardano blockchain features, including inline datums, reference UTXOs, and reference scripts.

First, we will examine the ODV oracle contracts, including their UTXOs, datums, tokens, and NFTs, as well as the mechanism that incentivizes individuals towards active participation in data acquisition. Then, we will look at how the oracle components work together to provide accurate, decentralized, and trustworthy data on demand.

Oracle Contract’s UTXOs

In the ODV oracle contract, several essential UTXOs work together to provide on-demand data:

  1. Oracle Settings UTXO: Contains the configuration details of the oracle contract, including authorized nodes, consensus parameters, and reward settings. This configuration allows for customizing feed generation requirements and other features. It acts as a single point of truth for oracle settings.

  2. Aggregation State UTXO: Houses the aggregated data from all node operators (the oracle feed value). It acts as the primary data source that can be referenced by DApp contracts, containing the median value calculated from all participating nodes.

  3. Reward Transport UTXO: Facilitates the transfer of oracle fee value from end user to Reward Account UTXO. Oracle platform creates multiple reward transport UTXOs when deploying an oracle, ensuring that users can send ODV aggregation transactions in parallel. Number of Reward Transport UTXOs equals to the number of Aggregation State UTXOs at all times during oracle network existence.

  4. Reward Account UTXO: Records the earned rewards for each node participating in the oracle network. It maintains the reward distribution state and allows nodes to collect their accumulated rewards.

  5. Reference Script UTXO: Houses the contract’s script, facilitating its reuse and reducing transaction costs.

Figure 1.Figure 1. The ODV Oracle contract creates multiple UTXOs at its initiation stage.

Oracle Settings UTXO

The Oracle Settings UTXO encapsulates the contract settings, including parameters such as authorized nodes, consensus rules, payment rewards, and platform signatories. It contains the Oracle Settings NFT and serves as the authoritative configuration for the entire ODV system.

Figure 2.Figure 2. The Oracle Settings UTXO’s datum and values.

Aggregation State UTXO

The Aggregation State UTXO contains the oracle feed value (median of all node values) that is consumed by DApp contracts. The platform creates multiple Aggregation State UTXOs when deploying a new oracle to enable parallel transactions during one slot.

Figure 3.Figure 3. The Aggregation State UTXO’s datum and values.

Reward Transport UTXO

The Reward Transport UTXO contains a message with individual oracle feed values from all nodes. It is consumed in the aggregation transaction and later used for reward calculation.

Figure 4.Figure 4. The Reward Transport UTXO’s datum and values.

Reward Account UTXO

The Reward Account UTXO maintains distinct records for each node’s earned reward. It accumulates rewards from multiple transactions and allows nodes to claim their rewards.

Figure 5.Figure 5. The Reward Account UTXO’s datum and values.

Reference Script UTXO

To minimize user fees and prevent blockchain bloat, scripts can be stored separately in the blockchain. Rather than including the complete script in each contract transaction, a spending transaction can reference the script’s location and utilize it for validation when spending a UTXO. This approach eliminates the need to duplicate the script in every transaction, leading to more efficient and streamlined transactions.

Usage Flow

When a DApp requests a value from an ODV oracle, this chain of events happens in a two-round communication process:

First Round: Feed Value Collection

  1. The DApp client sends a request to all oracle nodes for their feed values.

  2. Each oracle node independently:

    • Fetches the current value from multiple sources
    • Aggregates these sources to calculate its feed value
    • Creates a signed message containing the feed value, timestamp, and the oracle NFT’s policy ID
    • Returns this signed message to the DApp client

  3. The DApp client collects all the individual signed messages from the nodes.

Second Round: Transaction Signing

  1. The DApp client constructs an aggregation transaction that:

    • Consumes one of the available oracle reward transport and aggregation state UTXO pairs
    • Contains the calculated the median value from all node feeds messages
    • Outputs the new reward transport and aggregation state UTXOs

  2. The DApp client sends this transaction to all oracle nodes for signing.

  3. Each node verifies the transaction contents and returns its signature.

  4. The DApp client collects all node signatures, combines them with the transaction (Figure 6), and submits the fully signed transaction to the blockchain.

Figure 6.Figure 6. The Aggregate transaction takes in oracle UTXOs, user input and calculates a new Aggregate State UTXO’s datum through the consensus algorithm

As evident from the above diagram user wallet input (possibly paid as a subscription if wallet allows it) or DApp treasury input should pay Oracle fees, as well as the transaction fee.

Oracle fees include:

  1. Payment for the nodes, who behave according to the oracle consensus, i.e. they are not detected as outliers after IQR algorithm run on their individual feed inputs. End user should pay for all of the nodes participating in the oracle network anyway, these nodes are defined inside Oracle Settings datum.
  2. Payment for platform, that maintains oracle network in operational state. Platform will take a small base fee, plus any rewards that were given to outliers, and any tips added to the ODV aggregation transaction.

Transaction fees include:

  1. Regular ada fee for the ODV aggregate transaction.
  2. Subsidies for the future transaction fee during reward consensus transaction (see next section for more information). These subsides are equal to the ODV aggregate transaction fee, effectively doubling the estimated transaction fee for ODV aggregate.

Post-Transaction Processing

This step is not done by the user or the DApp, instead it is done by a node operator on the back-end server. In theory anyone could do this transaction, but node operator server app has a background task that automates the process.

As you noticed on Figure 6 - Reward Transport UTXO empty input turns into full output, which includes all individual node feeds mapping: from node feed verification key to node feed value. Reward Transport output value includes the NFT and C3 oracle fee tokens that were paid for this particular ODV aggregation. At the ODV aggregation transaction smart contract validates only median, timestamps, and oracle fee transfer. Next step is to run outlier detection mechanism and distribute reward into the Reward Account UTXO. This transaction does reward-calculation/reward-consensus and you can see it on Figure 7. Only non-outlier nodes get their corresponding reward entry increased during the datum accumulator update, while the C3 tokens reward value is taken from the transport UTXO into the account UTXO.

Figure 7.Figure 7. Rewards are moved from Reward Transport UTXO and transferred to the Reward Account UTXO after each consensus transaction, and can be claimed by participants anytime.

As you can see from the diagram while reward transport UTXO is emptied and could be consumed with subsequent ODV aggregation, reward account UTXO can be consumed by nodes and escrowed rewards transferred to the eligible parties.

Consensus Algorithm

For ODV oracles employing multiple nodes, nodes multisig is checked, while the consensus algorithm determines the final feed by computing the median value of all nodes’ exchange rates. Nodes with input values not flagged as outliers during the consensus phase are rewarded.

Outlier Consensus Algorithm: IQR + Divergency from Median

The Pull Oracle uses a hybrid outlier detection algorithm to ensure reliable consensus among submitted data points (“feeds”) from different nodes. This mechanism balances robustness (resisting manipulation or bad data) and adaptability (still functioning with small sample sizes).

Core Concept: Interquartile Range (IQR)

The interquartile range (IQR) is a common statistical method used to detect outliers. It measures the range between the 25th percentile (Q1) and the 75th percentile (Q3) of a sorted data set:

IQR = Q3 - Q1

Using the IQR, we can define a “fence” for acceptable values:

Lower Fence = Q1 - (multiplier × IQR)
Upper Fence = Q3 + (multiplier × IQR)

Any values outside this range are considered outliers.

The algorithm typically uses a multiplier like 1.5 (150%) as the default, following Tukey’s method.

IQR Limitations

  • Minimum required data: At least 4 values (1 per quartile) are needed for IQR to compute.

  • Recommended: At least 20 points (5 per quartile) for reliable outlier detection.

  • Degenerate cases: If the 25th and 75th percentiles are equal, the IQR becomes zero, making outlier fences collapse to a single value—this disables the method.

Fallback: Divergency from the Median (percentage divergency - PD)

If the data set is too small or lacks spread (i.e., IQR = 0), the algorithm falls back to a divergency-based filter:

Lower Fence = Median - (factor × Median)
Upper Fence = Median + (factor × Median)

This fallback uses a relative range around the median with a configurable divergency factor (e.g., ±3%).

Combined Logic

Here’s how the consensus function chooses the filtering method:

  1. If there’s only 1 data point: accept it (no outlier check needed).

  2. If there are fewer than 4 values: use divergency from median.

  3. If IQR is computable but equals zero: fallback to divergency.

  4. Otherwise: use IQR-based outlier detection.

This approach allows the oracle to:

  • Maintain strong outlier rejection with large, well-distributed samples.
  • Still operate on minimal data, e.g. during early epochs or network partitions.
  • Avoid false positives caused by zero-IQR edge cases.
  • Imposing penalties on adversarial outliers enhances the network’s reliability and accuracy. But usually being flagged as an outlier means that something is wrong with node operator server setup, e.g. it’s using paid CEX API and the API key is expired, so it returns zero feed.

Oracle Configuration

Oracle configuration is immutable smart contract validator argument, which cannot be changed even by the oracle platform. It contains essential security parameters, that need to be immutable for the correct and fair oracle network functioning. These include:

  1. platform auth nft - platform is authorized by providing its input with specific NFT inside the transaction.
  2. pause period length - pause period is when oracle can no longer do aggregations, but rewards can still be calculated. Before oracle is removed platform need to start a pause period for nodes to safely collect all their rewards. When pause period ends and the oracle can be removed any left out rewards would be at the control of the platform.
  3. reward dismissing period length - after this period uncalculated rewards inside Reward Transport UTXO can be dismissed with DismissRewards redeemer. Calculated rewards inside the Reward Account UTXO will never be dismissed.
  4. fee token - oracle fees are paid using this asset, if it’s not set then ada is used.
  5. reward escrow script hash - when oracle platform removes nodes it will do a final token reward payout to this address, ada rewards are paid to nodes payment address, so escrow script field can be empty ("").

Oracle Settings

The oracle settings store adjustable variables that cater to the ODV Network focus and target audience requirements, including:

  1. nodes - list of authorized nodes with their verification key hashes for participating in the oracle network
  2. threshold - percentage of nodes needed to generate a valid oracle feed
  3. configuration of oracle fees - how much each non-outlier node will receive, as well as the platform fee
  4. aggregation liveness period - aggregation is considered live, i.e. usable by dapps during this period
  5. tx validity interval length - time error acceptable by validator during ODV aggregation, and during performing platform governance actions
  6. iqr fence multiplier - see interquartile range (IQR) and Tukey fences methods for outlier detection, typical value for this parameter is 1.5 in case of normal distribution
  7. median divergency factor - in case IQR is not applicable (equals zero) median is multiplied by this factor to then produce a fence for filtering out outliers; typical value for this parameter is 2.5% for stablecoins and 30% for everything else
  8. UTXO size safety buffer - should be equal to a minimum ada amount held at maximum expected oracle UTXO size, so that users won’t pay for datum size increase
  9. pause period timestamp - if oracle is in pause state, then this field will have a pause start timestamp value

Exception Handling

Node Downtime

ODV oracles are configurable to function with a minimum number of available nodes. The oracle settings allow for specifying the minimum number of signatures required to submit an aggregation transaction.

Outlier Detection

Cheating attempts within the system, such as providing false node information, are deterred by the consensus algorithm. The IQR and PD methods identify and exclude outliers from rewards, ensuring only accurate data providers are compensated.

The platform operators have the capability to remove underperforming nodes by updating the oracle settings, maintaining the quality of the feed output. Similarly, they can add new nodes to enhance the overall participation in the oracle network.

On-Chain Code

The Charli3 on-chain contract code ensures security by securely storing token reward information (C3) and NFTs within the validator argument. This information is immutable, ensuring that participants in the network cannot be subjected to cheating or manipulation.

The entire Charli3 mechanism is executed in the on-chain code, making the entire process transparent. Rewards, configurations and other parameters are visible to the general public.

Reward System

The reward mechanism in ODV oracles is designed to compensate all network participants for their active involvement in providing accurate data. Rewards are calculated and distributed during the consensus phase, with outliers receiving reduced or no rewards.

In an ODV oracle, rewards are accumulated in the Reward Account UTXO and can be claimed by nodes at their convenience.

Off-chain Code

The off-chain component of the ODV oracle system consists of:

  1. Node Operator Backend: Responsible for aggregating data from various sources, signing and validating transactions.

  2. DApp Client Interface: Enables making requests to the oracle network, handles the collection of signed messages and transaction construction and submission.

Thanks to its reliance on Pycardano, the off-chain core seamlessly integrates with other components within the Charli3 Ecosystem. Recognizing the inherent costs and limitations associated with on-chain operations, Charli3’s off-chain core is meticulously designed to optimize cost efficiency.

Platform Operators Transactions

The platform operators have the ability to perform several transactions:

  1. Update-Oracle-Settings: Modify the oracle settings, including adding or removing nodes, adjusting consensus parameters, and changing reward structures.

  2. Add-Transport-UTXOs: Create additional Reward Transport and Aggregation State UTXOs to handle increased transaction volume.

  3. Platform-Collect: Collect the platform rewards from the Reward Account UTXO.

  4. Oracle-Remove: Remove the oracle by collecting and consuming all contract UTXOs, including associated NFTs, ADAs, and C3 tokens.

Multi-Signature Validation

Changes in the ODV network use a multi-signature validation, needing approval from multiple parties. This ensures decentralized control over critical oracle settings.

Node Operator Transactions

  1. Calculate-Rewards: Node operator runs a server background task to accumulate rewards from Reward Transport UTXOs into the Reward Account UTXO.
  2. Node-Collect: Node operator can withdraw their accumulated rewards from the Reward Account UTXO.
SummaryOff-chain