Setup and Configuration

Configure the Push Oracle SDK for deploying and managing continuous data feed oracle networks on Cardano.

Installation

git clone https://github.com/Charli3-Official/charli3-push-oracle-sdk.git
cd charli3-push-oracle-sdk
poetry install
poetry shell

Configuration File Structure

Push Oracle operations use YAML configuration files. Two main configuration files are used:

1. oracle_deploy.yml - For initial oracle deployment
2. oracle-owner-actions.yml - For ongoing oracle management

Deployment Configuration (oracle_deploy.yml)

Create oracle_deploy.yml for oracle deployment:

# Network Configuration
network: "testnet"  # Options: TESTNET, MAINNET
 
# Wallet Configuration (choose one method)
MNEMONIC_24: "your twenty four word recovery phrase here"
 
# Blockchain Connectivity
chain_query:
  # Option 1: Blockfrost
  blockfrost:
    api_url: "https://cardano-preprod.blockfrost.io/api"
    project_id: "preprodXXXXXXXXXXXX"
  
  # Option 2: Ogmios + Kupo
  ogmios:
    ws_url: "ws://localhost:1337"
    kupo_url: "http://localhost:1442"
 
# Oracle Deployment Parameters
script_start_slot: 27893300  # Current blockchain slot + buffer
 
# Token Configuration
c3_token_hash: "436941ead56c61dbf9b92b5f566f7d5b9cac08f8c957f28f0bd60d4b"
c3_token_name: "C3"
initial_c3_amount: 1000000000  # Initial C3 tokens to fund oracle (1000 C3)
 
# Optional: Exchange Rate Oracle (for dynamic fees)
exchange_rate_token_name: "Rate"  # Optional
exchange_rate_token_hash: "c6f192a236596e2bbaac5900d67e9700dec7c77d9da626c98e0ab2ac"  # Optional
 
# Oracle Settings
oracle_settings:
  # Node Operators (verification key hashes in hex format)
  os_node_list:
    - "c36a4d3ef399163ce61f92008d5191556e3c3c5c111b50764c1e4"
    - "d1707e481671d473ee5a8d561aaac4a1f4e8c937ce61e5d11fc0611f"
    - "3318ad8f0c743a674831d69e4c61c0d805eda695b0f20a4ff0edebc5"
  
  # Node Update Requirements
  os_updated_nodes: 6000          # Minimum nodes required (percentage in basis points, 6000 = 60%)
  os_updated_node_time: 1800000   # Node update validity window (ms, 1800000 = 30 min)
  
  # Aggregation Parameters
  os_aggregate_time: 1800000      # Minimum time between aggregations (ms, 1800000 = 30 min)
  os_aggregate_change: 200        # Minimum price change to trigger aggregation (basis points, 200 = 2%)
  os_aggregate_valid_range: 600000  # Aggregation validity window (ms, 600000 = 10 min)
  
  # Economic Parameters
  os_minimum_deposit: 1000000000  # Minimum C3 deposit required (lovelace)
  
  # Fee Structure (in C3 tokens or lovelace)
  os_node_fee_price:
    node_fee: 10        # Fee per node per update
    aggregate_fee: 20   # Fee for aggregation
    platform_fee: 10    # Platform fee per aggregation
  
  # Consensus Parameters
  os_iqr_multiplier: 2   # IQR fence multiplier for outlier detection (2 = 2.0x)
  os_divergence: 1500    # Maximum divergence allowed (basis points, 1500 = 15%)
  
  # Platform Governance
  os_platform:
    pmultisig_pkhs:
      - "1a550d57572584e1add125b5712f709ac3b9828ad86581a4759022ba"
    pmultisig_threshold: 1  # Number of signatures required

Oracle Owner Configuration (oracle-owner-actions.yml)

Create oracle-owner-actions.yml for management operations:

# Wallet Configuration (choose one method)
MNEMONIC_24: "your twenty four word recovery phrase here"
 
# OR use signing key files (for multisig)
payment_sk: "payment.skey"
payment_vk: "payment.vkey"
stake_vk: "stake.vkey"
 
# Network
network: "testnet"
 
# Blockchain Connectivity
chain_query:
  blockfrost:
    api_url: "https://cardano-preprod.blockfrost.io/api"
    project_id: "preprodXXXXXXXXXXXX"
  ogmios:
    ws_url: "ws://localhost:1337"
    kupo_url: "http://localhost:1442"
 
# Oracle Information
oracle_owner:
  oracle_addr: "addr_test1wp6kt5etqmudy6pwhdp8g97ydt47w9znthu7ws9ar0rmptgkn2qzy"
  minting_nft_hash: "1f2d9f081287bc0b89ca08c088e3fa20a7719b8b954e4993539fde17"
  c3_token_hash: "436941ead56c61dbf9b92b5f566f7d5b9cac08f8c957f28f0bd60d4b"
  c3_token_name: "C3"
  script_start_slot: 28585322
  
  # Optional: Reference Script for reduced tx fees
  reference_script_input: "tx_hash#output_index"  # Format: "abc123...#0"
  
  # Platform Governance
  oracle_platform:
    multisig_pkhs:
      - "1a550d57572584e1add125b5712f709ac3b9828ad86581a4759022ba"
    multisig_threshold: 1

Configuration Parameters Reference

Network Settings

Note: You must provide either Blockfrost OR Ogmios+Kupo configuration.

Wallet Configuration

Option 1: Mnemonic (24 words)

• Simple setup for single-signature operations
• Automatically derives payment and stake keys
• Derivation path: m/1852'/1815'/0'/0/0 (payment), m/1852'/1815'/0'/2/0 (stake)

Option 2: Signing Key Files

• Required for multisig operations
• Supports multiple signers
• Requires separate payment.skey, payment.vkey, and stake.vkey files

Script Start Slot

The script_start_slot is crucial for creating unique NFT policy IDs:

# Get current slot from blockchain
cardano-cli query tip --testnet-magic 1
 
# Add buffer (e.g., +1000 slots for deployment time)
script_start_slot = current_slot + 1000

Important: This slot must be in the future when the transaction is built.

Token Configuration

Payment Token: The oracle uses C3 tokens to pay node operators and collect platform fees.

Exchange Rate Token (Optional): If specified, enables dynamic fee calculation based on C3/ADA exchange rate.

Node Configuration

Node List Format:

• Each entry is a verification key hash (VKH) in hex format
• NOT bech32 format (no addr_vkh1 prefix)
• Obtain from: cardano-cli address key-hash --payment-verification-key-file node.vkey

Updated Nodes Percentage:

• Expressed in basis points (10000 = 100%)
• Example: 6000 = 60% of nodes must update before aggregation
• Must be ≤ 10000

Aggregation Parameters

Aggregation Logic: An aggregation can occur when EITHER:

1. os_aggregate_time has elapsed since last aggregation, OR
2. Price changed by ≥ os_aggregate_change since last aggregation

Valid Range: Maximum time allowed for aggregation transaction to be submitted after being built.

Fee Configuration

Fee Calculation:

Total per aggregation = (node_fee × participating_nodes) + aggregate_fee + platform_fee

Dynamic Fees (with exchange rate oracle):

• Fees are scaled by the C3/ADA rate
• scaled_fee = fee × rate / 1000000
• Ensures consistent value regardless of C3 price

Consensus & Outlier Detection

IQR Outlier Detection:

• Uses interquartile range (IQR) to identify outliers
• Lower values = stricter filtering
• Formula: outlier if value < Q1 - (k × IQR) OR value > Q3 + (k × IQR)
• os_iqr_multiplier is the k value

Divergence Check:

• Filters values diverging too much from median
• divergence = |value - median| / median × 10000
• Values with divergence > os_divergence are excluded

Platform Governance (Multisig)

Multisig Configuration:

• Each party’s verification key hash (hex format)
• Threshold must be ≤ number of parties
• If threshold = 1, behaves like single-signature
• All governance operations require threshold signatures

Getting VKHs:

# From verification key file
cardano-cli address key-hash --payment-verification-key-file party1.vkey
 
# From address
cardano-cli address info --address addr1...

Economic Parameters

Minimum Deposit: Ensures oracle has sufficient funds to pay node operators and platform fees.

Reference Script

Benefits:

• Reduces transaction size (validators referenced, not included)
• Lower transaction fees
• One-time cost (~66 ADA locked)

Format: <transaction_hash>#<output_index>

Example: abc123def456...789#0

Validation Rules

The SDK validates configuration before operations:

Timing Constraints:

• All time values must be positive integers
• Values in milliseconds

Percentage Constraints:

• os_updated_nodes must be ≤ 10000 (100%)
• os_aggregate_change must be ≤ 10000 (100%)
• os_divergence must be ≤ 10000 (100%)

Node Constraints:

• os_node_list must have no duplicates
• At least 1 node required
• All VKHs must be valid hex format

Multisig Constraints:

• pmultisig_threshold must be ≤ len(pmultisig_pkhs)
• pmultisig_threshold must be ≥ 1

Economic Constraints:

• os_minimum_deposit must be > 0
• All fees must be ≥ 0

Common Issues

“Invalid node verification key hash format”

• Cause: VKH in wrong format (bech32 instead of hex)
• Solution: Use hex format from cardano-cli address key-hash

“Threshold exceeds number of parties”

• Cause: pmultisig_threshold > len(pmultisig_pkhs)
• Solution: Reduce threshold or add more parties

“Percentage exceeds 10000”

• Cause: Basis point values > 10000 (100%)
• Solution: Check os_updated_nodes, os_aggregate_change, os_divergence

“Script start slot in the past”

• Cause: script_start_slot ≤ current blockchain slot
• Solution: Set to current slot + buffer (e.g., +1000)

“Duplicate nodes in os_node_list”

• Cause: Same VKH listed multiple times
• Solution: Remove duplicate entries

“Insufficient C3 tokens”

• Cause: Wallet doesn’t have initial_c3_amount C3 tokens
• Solution: Mint C3 tokens first or reduce initial_c3_amount

“Invalid mnemonic”

• Cause: Mnemonic not 24 words or invalid checksum
• Solution: Verify mnemonic is correct 24-word phrase

“Chain query context not available”

• Cause: Neither Blockfrost nor Ogmios+Kupo configured
• Solution: Add either blockfrost or ogmios configuration

Next Steps

• Deployment Guide - Deploy your oracle