Setup and Configuration

Configure the Pull Oracle Platform SDK for deploying and managing on-demand oracle networks.

Installation

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

Configuration Parameters

Network Settings

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

Wallet Configuration

Option 1: Mnemonic (24 words)

wallet:
  mnemonic: "word1 word2 ... word24"

Option 2: Signing Key File

wallet:
  signing_key_file: "path/to/payment.skey"

Multisig Configuration

Multisig enables shared governance of platform operations:

Parameter	Description	Required	Default
`threshold`	Minimum signatures required	No	`1`
`parties`	List of verification key hashes (hex)	No	`[]`

multisig:
  threshold: 2  # Must be ≤ number of parties
  parties:
    - "ad1f6e3..."  # Hex VKH (NOT bech32 addr_vkh1...)
    - "7b9c2d4..."

Getting verification key hashes:

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

Important:

Parties must be specified as hex-encoded verification key hashes
Do NOT use bech32 format (addr_vkh1...)
If threshold = 1, multisig operations work like single-signature
All governance operations require multisig authorization when threshold > 1

Node Configuration

Parameter	Description	Format	Required
`feed_vkh`	List of node feed verification key hashes	Hex strings	Yes
`required_signatures`	Minimum node signatures for valid aggregation	Integer	Yes

nodes:
  feed_vkh:
    - "007df380aef26e44739db3f4fe67d8137446e630dab3df16d9fbddc5"
    - "b296714efefe2d991bb7eb002b48b024d1a152691c6fe9e0f76511c5"
  required_signatures: 2  # Must be ≤ number of nodes

Key format:

Node keys are hex-encoded verification key hashes
NOT bech32 format (no ed25519_pk1 prefix)
Each node typically manages their own keys via charli3 generate-node-keys

Token Configuration

Parameter	Description	Required	Format
`platform_auth_policy`	Platform authorization NFT policy ID	Yes	Hex
`reward_token_policy`	Custom reward token policy	No	Hex
`reward_token_name`	Custom reward token name	No	Hex
`rate_token_policy`	Rate token policy	No	Hex
`rate_token_name`	Rate token name	No	Hex

Note: If reward/rate tokens are not specified, ADA is used by default.

Fee Configuration

Parameter	Description	Value (lovelace)	Example Value
`node_fee`	Fee per node per aggregation	Integer	`2000000` (2 ADA)
`platform_fee`	Platform fee per aggregation	Integer	`1000000` (1 ADA)

Total cost per aggregation:

Total = (node_fee × participating_nodes) + platform_fee + tx_fee

Consensus & Outlier Detection

Parameter	Description	Typical Value	Notes
`iqr_multiplier`	IQR fence multiplier for outlier detection	`150`	150 = 1.5x IQR

Lower values mean stricter outlier filtering. The value represents the multiplier × 100 (e.g., 150 = 1.5).

Timing Parameters

Parameter	Description	Value (ms)	Example
`pause_period`	Duration before oracle can be removed after pause	Integer	`3600000` (1 hour)
`reward_dismissing_period`	Time before unclaimed rewards can be dismissed	Integer	`7200000` (2 hours)
`aggregation_liveness`	Validity window for aggregations	Integer	`3600000` (1 hour)
`time_uncertainty_aggregation`	Max transaction validity for aggregation txs	Integer	`120000` (2 min)
`time_uncertainty_platform`	Max transaction validity for platform txs	Integer	`180000` (3 min)
`utxo_size_safety_buffer`	Minimum ADA per UTXO	Integer	`5000000` (5 ADA)

Constraints:

reward_dismissing_period must be > pause_period
All values in milliseconds

UTXO Scaling

Parameter	Description	Min Value	Example
`reward_count`	Number of RewardAccount UTXOs to create	1	`1-5`
`aggstate_count`	Number of AggState UTXOs to create	1	`1-5`

reward_count: 3    # Creates 3 RewardAccount UTXOs
aggstate_count: 3  # Creates 3 AggState UTXOs

Understanding UTXO pairs:

Each RewardAccount UTXO can handle rewards for one concurrent transaction
Each AggState UTXO can hold one aggregation state
More UTXOs = higher parallel throughput but higher locked ADA
Can be scaled up or down after deployment

Cost impact:

Locked ADA ≈ (reward_count + aggstate_count) × utxo_size_safety_buffer

Deployment Options

Parameter	Description	Default	Notes
`use_aiken`	Use Aiken compiler for parameter application	`false`	Requires Aiken installed
`blueprint_path`	Path to Plutus blueprint file	`./artifacts/plutus.json`	Relative to working directory
`create_reference`	Create reference script during deployment	`true`	Costs ~64 ADA

Configuration File Structure

Pull Oracle operations use YAML configuration files. Create oracle-config.yaml:

# Network Configuration
network:
  network: "preprod"  # Options: mainnet, preprod, preview
 
  # Blockchain Connectivity (choose one)
  blockfrost:
    project_id: "preprodXXXXXXXXXXXX"
    base_url: "https://cardano-preprod.blockfrost.io/api/v0"
 
  # OR
  ogmios_kupo:
    ogmios_url: "ws://localhost:1337"
    kupo_url: "http://localhost:1442"
 
# Wallet Configuration
wallet:
  mnemonic: "your twelve or twenty four word recovery phrase..."
  # OR
  # signing_key_file: "payment.skey"
 
# Multisig Configuration (Optional - default threshold = 1)
multisig:
  threshold: 2  # Minimum signatures required
  parties:
    - "ad1f6e3..." #  Verification key hash for each party (hex format)
    - "7b9c2d4..."
    - "f3a8e5c..."  # Optional additional parties
 
# Token Configuration
tokens:
  platform_auth_policy: "..."  # Set after minting platform NFT
  reward_token_policy: "..."   # Reward token policy ID (optional)
  reward_token_name: "..."     # Reward token name in hex (optional)
  rate_token_policy: "..."     # Rate token policy ID (optional)
  rate_token_name: "..."       # Rate token name in hex (optional)
 
# Node Operators
nodes:
  feed_vkh:  # Feed verification key hashes (hex format, NOT bech32)
    - "007df380aef26e44739db3f4fe67d8137446e630dab3df16d9fbddc5"
    - "b296714efefe2d991bb7eb002b48b024d1a152691c6fe9e0f76511c5"
    - "018ab1dd5f33ca2e0ae6ccb694ea379d841bf5f4d2d5756452a2117d"
  required_signatures: 2  # Minimum node signatures required for aggregation
 
# Fee Configuration (in lovelace)
fees:
  node_fee: 2000000      # 2 ADA per node per request
  platform_fee: 1000000  # 1 ADA platform fee per request
 
# Timing Parameters (in milliseconds)
timing:
  pause_period: 3600000                    # 1 hour
  reward_dismissing_period: 7200000        # 2 hours (must be > pause_period)
  aggregation_liveness: 3600000            # 1 hour
  time_uncertainty_aggregation: 120000     # 2 minutes
  time_uncertainty_platform: 180000        # 3 minutes
  iqr_multiplier: 150                      # IQR outlier detection (150 = 1.5x)
  utxo_size_safety_buffer: 5000000         # 5 ADA minimum per UTXO
 
# UTXO Scaling (creates matching pairs of AggState + RewardAccount)
reward_count: 3       # Creates 3 RewardAccount UTXOs
aggstate_count: 3     # Creates 3 AggState UTXOs
 
# Deployment Options
use_aiken: true
blueprint_path: "./artifacts/plutus.json"
create_reference: true

Common Issues

Issue: reward_dismissing_period must be greater than pause_period

Solution: Ensure reward_dismissing_period > pause_period in timing config

Issue: Invalid node verification key hash format

Solution: Keys must be hex-encoded, not bech32 (no ed25519_pk1 or addr_vkh1 prefix)

Issue: Threshold exceeds number of parties

Solution: Ensure threshold ≤ len(parties) in multisig config

Issue: Required signatures exceeds number of nodes

Solution: Ensure required_signatures ≤ len(feed_vkh) in nodes config

Issue: Insufficient wallet funds

Solution: Ensure wallet has enough ADA:
- Reference script: ~64 ADA
- UTXO pairs: ~(reward_count + aggstate_count) × 5 ADA
- Transaction fees: ~5-10 ADA
- Total for deployment: typically 100-150 ADA

Issue: Platform auth NFT not found

Solution: First mint the platform auth NFT with charli3 platform token mint

Next Steps

Deployment Guide - Deploy your oracle

Get Started Deployment Guide