Setup and Configuration

Configure the Charli3 Oracle Data Verification (ODV) Client SDK for consuming oracle data from Pull Oracle networks.

Installation

git clone https://github.com/Charli3-Official/charli3-pull-oracle-client.git
cd charli3-pull-oracle-client
poetry install
poetry shell
charli3 --help

Configuration Parameters

Network Settings

Configure blockchain connectivity using either Blockfrost or Ogmios/Kupo:

Parameter	Description	Values
`network`	Cardano network	`mainnet`, `preprod`, `preview`
`blockfrost.project_id`	Blockfrost API key	From blockfrost.io
`ogmios_url`	Ogmios WebSocket URL	`ws://host:port`
`kupo_url`	Kupo HTTP URL	`http://host:port`

Blockfrost Configuration:

network:
  network: "preprod"
  blockfrost:
    project_id: "preprodXXXXXXXXXXXX"

Ogmios/Kupo Configuration:

network:
  network: "preprod"
  ogmios_kupo:
    ogmios_url: "ws://localhost:1337"
    kupo_url: "http://localhost:1442"

Wallet Configuration

The wallet is used to sign and submit aggregation transactions.

Option 1: Mnemonic Phrase

wallet:
  mnemonic: "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
  network: "preprod"  # Must match network.network

Option 2: Signing Key File

wallet:
  payment_skey_path: "payment.skey"
  payment_vkey_path: "payment.vkey"
  stake_vkey_path: "stake.vkey"
  network: "preprod"

Important:

Wallet must have sufficient ADA for transaction fees (~2-5 ADA recommended)
Network in wallet config must match network.network

Oracle Configuration

Parameter	Description	Format	Required
`policy_id`	Oracle NFT policy ID	56-char hex	Yes
`oracle_address`	Oracle script address	Bech32 address	Yes
`odv_validity_length`	Transaction validity window	Milliseconds	Yes

policy_id: "b00f27e5c2284f87b29c2b877dd341e3f0c3d06e1e0b02bb9c458f13"
oracle_address: "addr_test1wpgjxstaqc8am88c89zd72j5rw065ex8l5j7ln4pzngxt8qr4tzdj"
odv_validity_length: 120000  # 2 minutes

Getting oracle parameters:

policy_id: Provided by oracle deployer
oracle_address: Oracle script address on-chain
odv_validity_length: Must be ≤ oracle’s time_uncertainty_aggregation parameter

Node Configuration

Configure oracle node endpoints for collecting feed data:

nodes:
  - root_url: "https://oracle-node-1.testnet.charli3.io"
    pub_key: "bd72e960d6237031290e8b4189ea7c6c305ef907d4881729db60e3f3b7c4af5b"
  - root_url: "https://oracle-node-2.testnet.charli3.io"
    pub_key: "7437e43e7e88c5642569f112f0e22b17c2fae155007254506dd0090dd9312568"
  - root_url: "https://oracle-node-3.testnet.charli3.io"
    pub_key: "76502e17aba981ecbf09fd5b41bc1b6a3f5a0a85bb47c07300b906a347969702"

Parameter	Description	Format
`root_url`	Node HTTP endpoint	HTTPS URL
`pub_key`	Node’s verification key	64-char hex

Important:

Node public keys must match keys registered in oracle deployment
At least required_signatures nodes must be available for valid aggregation
URLs must be accessible from your environment

Reference Script Configuration

Reference scripts reduce transaction sizes and fees:

reference_script:
  # Option 1: Specify address (SDK searches for script at address)
  address: "addr_test1wqag3rt979nep9g2wtdwu8mr4gz6m4kjdpp37wx8pnh8dqq9pqw0r"
  
  # Option 2: Specify exact UTxO reference (more efficient)
  utxo_reference:
    transaction_id: "4606793120f127744d2b2f3bcc265a9a91eea8693f6eee2f48287738edededed"
    output_index: 1

Recommendations:

Use utxo_reference for better performance (avoids UTxO search)
If reference script changes, update configuration
Reference script should contain oracle validator

Token Configuration (Optional)

Configure custom reward tokens if oracle uses tokens other than ADA:

tokens:
  reward_token_policy: "a0028f350aaabe0545fdcb56b039bfb08e4bb4d8c4d7c3c7d481c235"
  reward_token_name: "484f534b59"  # Hex-encoded token name

Parameter	Description	Format
`reward_token_policy`	Reward token policy ID	56-char hex
`reward_token_name`	Reward token name	Hex string

Note: If not specified, the SDK assumes ADA rewards.

Configuration File Structure

Create config.yaml:

# Network Configuration
network:
  network: "preprod"  # Options: mainnet, preprod, preview
  
  # Option 1: Blockfrost
  blockfrost:
    project_id: "preprodXXXXXXXXXXXX"
  
  # Option 2: Ogmios + Kupo
  # ogmios_kupo:
  #   ogmios_url: "ws://127.0.0.1:1337"
  #   kupo_url: "http://127.0.0.1:1442"
 
# Wallet Configuration
wallet:
  mnemonic: "$WALLET_MNEMONIC"  # Environment variable reference
  network: "preprod"
 
# Oracle Configuration
policy_id: "b00f27e5c2284f87b29c2b877dd341e3f0c3d06e1e0b02bb9c458f13"
oracle_address: "addr_test1wpgjxstaqc8am88c89zd72j5rw065ex8l5j7ln4pzngxt8qr4tzdj"
odv_validity_length: 120000  # Must be <= oracle's time_uncertainty_aggregation
 
# Node Configuration
nodes:
  - root_url: "https://oracle-node-1.testnet.charli3.io"
    pub_key: "bd72e960d6237031290e8b4189ea7c6c305ef907d4881729db60e3f3b7c4af5b"
  - root_url: "https://oracle-node-2.testnet.charli3.io"
    pub_key: "7437e43e7e88c5642569f112f0e22b17c2fae155007254506dd0090dd9312568"
  - root_url: "https://oracle-node-3.testnet.charli3.io"
    pub_key: "76502e17aba981ecbf09fd5b41bc1b6a3f5a0a85bb47c07300b906a347969702"
 
# Reference Script Configuration
reference_script:
  address: "addr_test1wqag3rt979nep9g2wtdwu8mr4gz6m4kjdpp37wx8pnh8dqq9pqw0r"
  utxo_reference:
    transaction_id: "4606793120f127744d2b2f3bcc265a9a91eea8693f6eee2f48287738edededed"
    output_index: 1
 
# Token Configuration (optional - defaults to ADA)
tokens:
  reward_token_policy: ""
  reward_token_name: ""

Environment Variables

The configuration supports environment variable substitution using $VAR_NAME syntax:

wallet:
  mnemonic: "$WALLET_MNEMONIC"
 
network:
  blockfrost:
    project_id: "$BLOCKFROST_PROJECT_ID"

Set environment variables:

export WALLET_MNEMONIC="abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
export BLOCKFROST_PROJECT_ID="preprodXXXXXXXXXXXX"

Validate Configuration

Before using the SDK, validate your configuration:

charli3 validate-config --config config.yaml

Expected output:

Configuration Validation

Setting               Value                                      Status
Network               preprod                                    Valid
Oracle Address        addr_test1wp...                           Valid
Policy ID             b00f27e5c228...                           Valid
Validity Length       120000ms                                   Valid
Nodes Count           3                                          Valid

✓ Configuration is valid

Node Endpoints:
    1. https://oracle-node-1.testnet.charli3.io
    2. https://oracle-node-2.testnet.charli3.io
    3. https://oracle-node-3.testnet.charli3.io

Common Issues

Issue: No valid network configuration provided

Solution: Ensure either blockfrost or ogmios_kupo section is present and complete

Issue: Wallet config must contain either a mnemonic or all key file paths

Solution: Provide either mnemonic OR all three key file paths (payment_skey, payment_vkey, stake_vkey)

Issue: Network mismatch between network and wallet config

Solution: Ensure network.network matches wallet.network

Issue: Reference script UTxO not found

Solution:
1. Verify UTxO exists on-chain
2. Check transaction ID and output index are correct
3. Use correct address to let SDK search for script

Issue: No UTxOs found at script address

Solution:
1. Verify oracle is deployed at oracle_address
2. Check oracle hasn’t been removed
3. Ensure policy_id matches oracle deployment

Issue: Validity window length exceeds oracle configuration

Solution: Reduce odv_validity_length to be ≤ oracle’s time_uncertainty_aggregation

Issue: Environment variable not found

Solution: Set required environment variables before running commands:

export WALLET_MNEMONIC="your mnemonic here"
charli3 validate-config --config config.yaml

Issue: Connection refused to node endpoint

Solution:
1. Verify node URLs are accessible
2. Check firewall/network restrictions
3. Ensure nodes are online and running

Security Best Practices

1. Protect your mnemonic:

Never commit mnemonics to version control
Use environment variables: mnemonic: "$WALLET_MNEMONIC"
Use read-only file permissions: chmod 600 config.yaml

2. Use dedicated wallet:

Don’t use your main wallet for oracle operations
Keep only necessary ADA for transaction fees
Monitor wallet for unexpected transactions

3. Verify oracle parameters:

Always validate policy_id and oracle_address with oracle deployer
Verify node public keys match registered nodes
Check oracle is from trusted source

Next Steps

Usage Guide - Learn how to use the ODV Client SDK

Platform Operations Usage Guide