Oracles Operation

Understand Charli3's Oracles: Learn about the architecture and mechanism for generating reliable data.

This article assumes familiarity with the (E)UTXO model. It reviews Charli3's oracle contracts and it's integration with the Vasil Hard Fork features, including inline datums, reference UTXOs, and reference scripts.

First, we will examine one of the most basic oracle contracts, including its UTXOs, inline datums, tokens, and NFTs, as well as the mechanism that incentivizes individuals towards active participation in data acquisition. Then, we will look at a more advanced oracle contract that uses multiple trusted data sources and examine how it's UTXOs work together to provide accurate, decentralized, and trustworthy data.

Oracle Contract's UTXOs

The simplest oracle contract is comprised of four essential UTXOs:

• The Node UTXO, which is responsible for transporting external blockchain data.

• The Aggregate UTXO, which houses the contract's configurations and Charli3 Oracle Tokens (C3).

• The Feed UTXO, which serves as a repository for the consolidated and processed data obtained from all the Node UTXOs.

• The Reference Script UTXO, which store the contract's script.

Figure 1. The simplest Oracle contract creates four UTXOs at its initiation stage.

Node UTXO

Let's concentrate on the Node UTXO for now. Upon executing the start oracle transaction, the inline datum will only contain information about the wallet that is authorized to update it. The individual, or entity, that holds the wallet access, can modify the information stored in the datum. As shown in Figure 2, the Update-node transaction updates data A to B.

Figure 2. The Update-node transaction modify the UTXO's inline datum.

It's important to note that the Node-NFT is a unique identifier within the UTXO value. Each oracle contract UTXO holds a unique identifier that distinguishes it from other outputs that may be located at the same script address.

Aggregate UTXO

The inline data in the Aggregate UTXOs holds the protocols, referred to as Oracle Settings, that dictate how and when information from the Node UTXOs is processed. For example, the contract may require nodes to provide updated data on a daily, hourly, or even minute-by-minute basis.

The values of the UTXOs are comprised of an Aggregate-NFT and a specified amount of C3 tokens. The C3 tokens serve as a form of fiduciary value for Node UTXOs owners who consistently and precisely update the UTXOs' information. The algorithm responsible for determining the recipients of this reward is known as the consensus algorithm.

Figure 3. The Aggregate UTXO's datum and values.

Feed UTXO

The Feed UTXO stores the information generated by the consensus algorithm in its datum. This information can be accessed by other contracts simultaneously using Vasil's read-only UTXO feature for Oracles PlutusV2, without encountering any race conditions.

Figure 4: The Feed UTXO's datum and values; initially, the datum is empty.

Reference Script UTXO

To reduce user fees and prevent bloating of the blockchain, scripts can be stored in the blockchain using a reference input and an inline Datum. Instead of including the entire script each time it's used in a transaction, a spending transaction can refer to the script's location and reuse it for validation when spending a UTXO. This eliminates the need to carry the script's contents within the transaction.

Consensus algorithm with a single Node UTXO

By executing the Aggregate transaction on our simple oracle example, the contract takes in a unique Node UTXO, and the consensus algorithm reflects its information in the Feed UTXO. The Node UTXO that provides information is rewarded with a predefined amount of C3 tokens.

The Feed UTXO's datum now includes the final oracle information, also known as the oracle feed. Please refer to Figure 5 for a visual representation. Third-party contracts can access this by searching for the UTXO that contains the Feed's NFT, referred to as "Feed NFT" in Figure 5.

Although this example contract only involves copying and pasting information from the node to the feed, it effectively demonstrates the collaborative functionality of each UTXO.

Note: To ensure decentralization and security, Charli3 does not provide contracts with a single source of data. This sub-section introduces readers to the Aggregate transaction for educational purposes only.

Figure 5. The Aggregate transaction takes in all oracle UTXOs and calculates a new Feed datum using the consensus algorithm

Consensus algorithm with multiples Node UTXOs

For contracts that involve multiple Node UTXOs, also know as Node Pool; such as the exchange rate between two assets, the consensus algorithm calculates the final feed by taking the median value of all node's exchange rates. The nodes whose input values don't exceed the MAD and DIV percentages defined in the Oracle Settings are rewarded.

Specialized functions will be used to achieve the highest precision and accuracy for data types that cannot be calculated with the median formula.

The consensus algorithm's final feed, or oracle feed, is stored in the datum of the Feed UTXO. As previously mentioned, third-party contracts can access the oracle feed by locating the correct NFT at the contract address, see Figure 5.

Oracle Settings

The Oracle Settings store variables that can be adjusted to fit the feed's focus and target audience needs, including:

1. List of associated wallets, ID authorized to update each Node's UTXOs.

2. The minimum percentages of Node's datums needed in the Aggregate transaction.

3. A timeframe that determines the freshness of Node's datum information.

4. An Aggregation transaction frequency period.

5. A percentage change in the feed data.

6. The amount of C3 tokens paid to each node operator for participating in the consensus algorithm.

7. A measure of the average deviation of the Node's datum information from the median (MAD).

8. Percentage divergence between each Node's datum and the MAD (DIV).

Settings 4 and 5 determine the execution of the Aggregate transaction: 4 by a fixed frequency and 5 by exceeding a percentage change in the consensus algorithm value.

Exception handling

Node Downtime

For cases where some UTXO Nodes do not update their information regularly, Oracle Setting number 3 will evaluate and discard inactive Nodes. Setting number 2 lets the oracle owner specify the minimum percentage of Nodes that must have recent information to trigger an Aggregate transaction. For instance, if the oracle contract starts with 10 Node UTXOs, the owner can set the requirement to at least 50% of them having active information.

Charli3's oracles and nodes are spread out globally to ensure non-stop data access. The Charli3 team also has monitoring systems in place for each node and feed, which send notifications immediately in the face of any eventuality.

Outlier Detection

Attempts at cheating the system by providing false node information can be thwarted by two mechanisms. First, submitting an Update node transaction to the Cardano blockchain requires a fee, disincentivizing false submissions. Second, oracle settings 7 and 8 enable setting a threshold for outliers and selecting values closest to the median. As a result, only a select number of nodes, for example, 5 out of 10, may receive a reward in C3 tokens, incentivizing accurate information.

The owner of the oracle contract can eliminate underperforming Node UTXOs by executing the transaction "Del-nodes". This is a transaction that only the contract owner can execute to ensure the quality of the contract's output.

On-Chain Code

The Charli3 on-chain contract code securely identifies the contract owner by storing their wallet ID along with token reward information (C3) and NFTs generated during the oracle contract start transaction. These details are kept in an Oracle data type, which serves as the validator's argument, to prevent any unauthorized tampering by external parties.

A valid argument for a contract validator could be:

Validator's argument

oracle :: Oracle
oracle =  Oracle
      { oracleCreator = PaymentPubKeyHash
            "1a550d5f572584e1add125b5712f709ac3b9828ad86581a475902ffa"
      , oracleNFT =
          AssetClass
            ( "e36cd9189099d7bedae87e8702e86e38122a62141743e1a64a5349ff"
            , "OracleFeed")
      , aggStateNFT =
          AssetClass
            ( "e36cd9189099d7bedae87e8702e86e38122a62141743e1a64a5349ff"
            , "AggState")
      , feeToken =
          AssetClass
            ( "436941ead56c61dbf9b92b5f566f7d5b9cac08f8c957f28f0bd60d4a"
            , "C3")
      , nodeToken =
          AssetClass
            ( "e36cd9189099d7bedae87e8702e86e38122a62141743e1a64a5349ff"
            , "NodeFeed")
      }

Note that the validator argument stores the token name and minting policy for NFTs and tokens, including NFTs for the feed UTXO (OracleNFT) and Aggregate UTXO (aggStateNFT), as well as N tokens for various Node UTXOs (nodeToken).

Let's take a look to the signature of the contract's validator:

Validator signature

mkOracleValidator :: Oracle -> OracleDatum -> OracleRedeemer -> BDScriptContext -> Bool

After reviewing the Oracle and Datum types, we've created different Redeemers types for various off-chain operations, which are outlined below.

Off-chain Code

Oracle owner transactions

The creator of the oracle can perform the following operations, which have been implemented as off-chain code in both Haskell and Python contract versions:

1. Aggregate: Execute the Aggregate transaction.

2. Add-funds: The Aggregate UTXO is consumed to produce a new one increasing the C3 tokens amount.

3. Edit-Oracle-Settings: Edit the Aggregate UTXO's datums by changing the oracle setting values.

4. Add-Node: Generate new Node UTXOs by receiving a list of wallet IDs and minting additional Node tokens to be distributed to the new UTXOs.

5. Del-Node: Eliminate Node UTXOs by burning the Node tokens belonging to the specified wallet IDs.

6. Oracle-close: The contract UTXOs, along with all associated NFTs, ADAs, and C3 tokens, are collected and consumed. In cases where Node UTXOs hold C3 tokens, the tokens are paid to their corresponding node wallet operators. This operation marks the end of the contract since no usable UTXOs are created.

Node operator transactions

1. Update-node: The node operator can modify data in the Node UTXO through the Update-node transaction, but not the wallet ID or NFT information.

2. Node-collect: The owner operating the Node UTXO can withdraw the C3 tokens received as rewards to his personal wallet.

3. Aggregate: Execute the Aggregate transaction.

4. Update-and-Aggregate: This transaction combines the Update-node and Aggregate transactions to reduce slot time when the required percentage of UTXOs is reached to perform an Aggregate transaction.