Platform Operations

Ongoing management operations for Pull Oracle networks including governance actions, node management, and reward collection.

Governance Operations

All governance operations require multisig authorization when threshold > 1.

Update Oracle Settings

Modify oracle parameters after deployment.

Command:

charli3 oracle update-settings --config oracle-config.yaml

Interactive prompts guide you through updating:

Aggregation liveness period
Transaction validity windows
IQR fence multiplier
Required node signature count

Multisig workflow:

# Party 1: Build transaction
charli3 oracle update-settings --config party1-config.yaml
# Output: tx_oracle_update_settings.json
 
# Parties 2-N: Add signatures
charli3 oracle sign-tx \
  --config party2-config.yaml \
  --tx-file tx_oracle_update_settings.json
 
# Final party: Submit when threshold is met
charli3 oracle submit-tx \
  --config partyN-config.yaml \
  --tx-file tx_oracle_update_settings.json

Add Nodes

Add new node operators to the oracle network.

Update configuration with new nodes:

nodes:
  feed_vkh:
    - "007df380aef26e44739db3f4fe67d8137446e630dab3df16d9fbddc5"  # Existing
    - "b296714efefe2d991bb7eb002b48b024d1a152691c6fe9e0f76511c5"  # Existing
    - "018ab1dd5f33ca2e0ae6ccb694ea379d841bf5f4d2d5756452a2117d"  # New
  required_signatures: 2

Command:

charli3 oracle add-nodes --config oracle-config.yaml

The SDK:

Compares config nodes with on-chain nodes
Identifies new nodes to add
Shows changes for confirmation
Builds add-nodes transaction

Multisig workflow:

# Party 1: Build
charli3 oracle add-nodes --config party1-config.yaml
# Output: tx_oracle_add_nodes.json
 
# Additional parties: Sign and submit
charli3 oracle sign-tx --config party2-config.yaml --tx-file tx_oracle_add_nodes.json
charli3 oracle submit-tx --config partyN-config.yaml --tx-file tx_oracle_add_nodes.json

Remove Nodes

Remove node operators from the oracle network.

Update configuration (remove node entries):

nodes:
  feed_vkh:
    - "007df380aef26e44739db3f4fe67d8137446e630dab3df16d9fbddc5"  # Keep
    - "b296714efefe2d991bb7eb002b48b024d1a152691c6fe9e0f76511c5"  # Keep
    # Removed: - "018ab1dd5f33ca2e0ae6ccb694ea379d841bf5f4d2d5756452a2117d"
  required_signatures: 2

Command:

charli3 oracle del-nodes --config oracle-config.yaml

The SDK:

Identifies removed nodes
Checks for accumulated rewards
Sends rewards to operators before removal
Shows changes for confirmation

Multisig workflow:

# Party 1: Build
charli3 oracle del-nodes --config party1-config.yaml
# Output: tx_oracle_delete_nodes.json
 
# Additional parties: Sign and submit

UTXO Scaling Operations

Adjust oracle throughput by scaling the number of parallel UTXOs.

Scale Up

Increase capacity for more concurrent requests.

Command:

charli3 oracle scale-up \
  --config oracle-config.yaml \
  --reward-accounts 2 \
  --aggstates 2

This creates:

2 additional RewardAccount UTXOs
2 additional AggState UTXOs

Parameters:

Parameter	Description	Required
`--reward-accounts`	Number of RewardAccount UTXOs to add	No (default: 0)
`--aggstates`	Number of AggState UTXOs to add	No (default: 0)

When to scale up:

High request volume causing UTXO conflicts
Need for better throughput
Expanding to new use cases

Cost: ~5 ADA per UTXO × total UTXOs added

Multisig workflow:

# Party 1: Build
charli3 oracle scale-up --config party1-config.yaml \
  --reward-accounts 2 --aggstates 2
# Output: tx_oracle_scale_up.json
 
# Additional parties: Sign and submit

Scale Down

Decrease capacity and recover locked ADA.

Command:

charli3 oracle scale-down \
  --config oracle-config.yaml \
  --reward-accounts 2 \
  --aggstates 2

Important: Only empty UTXOs can be removed:

Empty RewardAccount UTXOs (no pending rewards)
Expired or unused AggState UTXOs

The SDK validates eligibility before building the transaction.

When to scale down:

Reduced request volume
Want to recover locked ADA
Consolidating oracle infrastructure

Multisig workflow:

# Party 1: Build
charli3 oracle scale-down --config party1-config.yaml \
  --reward-accounts 1 --aggstates 1
# Output: tx_oracle_scale_down.json
 
# Additional parties: Sign and submit

Oracle Lifecycle Management

Pause Oracle

Temporarily halt aggregation operations while preserving state.

Use cases:

Maintenance or upgrades
Node operator changes
Emergency situations

Command:

charli3 oracle pause --config oracle-config.yaml

Effects:

Stops new aggregation requests
Existing rewards remain claimable
Node operators can finalize pending work

Multisig workflow:

# Party 1: Build
charli3 oracle pause --config party1-config.yaml
# Output: tx_oracle_pause.json
 
# Additional parties: Sign and submit

Resume Oracle

Resume normal operations after pause.

Command:

charli3 oracle resume --config oracle-config.yaml

Effects:

Enables new aggregation requests
Oracle returns to normal operation

Multisig workflow:

# Party 1: Build
charli3 oracle resume --config party1-config.yaml
# Output: tx_oracle_resume.json
 
# Additional parties: Sign and submit

Remove Oracle

Permanently remove the oracle and cleanup all resources.

Prerequisites:

Oracle must be paused first
Pause period must have elapsed (from timing.pause_period config)
All parties should collect rewards before removal

Command:

charli3 oracle remove --config oracle-config.yaml

Effects:

Burns all oracle NFTs (CoreSettings, AggState, RewardAccount)
Recovers locked ADA
Oracle becomes permanently non-functional

Warning: This operation is irreversible.

Multisig workflow:

# Party 1: Build
charli3 oracle remove --config party1-config.yaml
# Output: tx_oracle_remove.json
 
# Additional parties: Sign and submit

Reward Operations

Platform Collect

Collect accumulated platform fees from reward accounts.

Command:

charli3 oracle platform-collect --config oracle-config.yaml

The SDK:

Queries all RewardAccount UTXOs
Calculates total platform fees available
Builds collection transaction

Note: Platform collection typically doesn’t require multisig (direct operation by platform wallet).

Node Collect

Node operators collect their accumulated rewards.

Command (run by node operator):

charli3 oracle node-collect --config node-config.yaml

The SDK:

Identifies node’s accumulated rewards across all RewardAccount UTXOs
Prompts for withdrawal address
Builds collection transaction
Node operator signs and submits

Requirements:

Node operator’s wallet must match their registered feed VKH
Node must have accumulated rewards

Dismiss Rewards

Dismiss unclaimed rewards after the dismissal period has elapsed.

Command:

charli3 oracle dismiss-rewards --config oracle-config.yaml

Prerequisites:

Rewards must be older than reward_dismissing_period
Typically used for cleanup of abandoned rewards

Transaction Management

Sign Transaction

Add your signature to a pending multisig transaction.

Command:

charli3 oracle sign-tx \
  --config your-config.yaml \
  --tx-file tx_oracle_<operation>.json

The command:

Validates you haven’t already signed
Adds your signature to the transaction
Updates the transaction file
Shows signature progress

Example output:

Signature added successfully
Progress: 2 of 3 signatures collected
Remaining: 1 signature required

Submit Transaction

Submit a fully-signed multisig transaction.

Command:

charli3 oracle submit-tx \
  --config your-config.yaml \
  --tx-file tx_oracle_<operation>.json

Validation:

Checks threshold is met
Validates all signatures
Submits to blockchain
Monitors confirmation

Important: Transaction will fail if:

Insufficient signatures (< threshold)
Any signature is invalid
Transaction expired (validity window passed)

Best Practices

Multisig Coordination

Establish communication - Set up secure channel for coordination
Version control configs - Ensure all parties use identical configuration
Document signing order - Who builds, who signs, who submits
Test on testnet first - Validate operations before mainnet
Backup transaction files - Store signed transactions before submission

Security

Protect signing keys - Use hardware wallets for mainnet operations
Verify transaction contents - Always inspect before signing
Separate wallets - Different wallets for platform and personal funds
Regular audits - Periodically review access controls
Incident response plan - Prepare for key compromise scenarios

Operations

Monitor oracle health - Regular health checks and UTXO status
Keep configs synchronized - All parties maintain same configuration
Document changes - Log all parameter updates and governance actions
Plan maintenance windows - Schedule updates during low-activity periods
Have rollback procedures - Document recovery steps for failures

Troubleshooting

“Platform auth UTxO not found”

Verify platform auth NFT policy ID in config matches actual policy
Check platform address has the NFT using Blockfrost/Kupo
Ensure you’re querying correct network (preprod vs mainnet)

“Insufficient signatures for multisig”

Check signature count: cat tx_file.json | jq '.signed_by | length'
Ensure all required parties have signed exactly once
Verify threshold matches configuration
Confirm no duplicate signatures

“Cannot scale down - UTXOs not empty”

Wait for pending aggregations to complete
Use platform-collect to clear platform fees
Notify node operators to collect their rewards with node-collect
Check AggState UTXOs are expired or unused

“Transaction validation failed”

Common causes:

Datum mismatch - On-chain datum doesn’t match expected format
Missing required signatures - Multisig threshold not met
Timing constraints violated - Transaction validity window expired
Wrong redeemer - Incorrect redeemer type for operation

Solution:

Review transaction: cardano-cli transaction view --tx-file <file>
Check logs for specific validation error
Verify all prerequisites are met (e.g., pause period elapsed)
Rebuild transaction if necessary

“Node VKH not found in oracle”

Verify node’s feed VKH matches configuration
Check node was added via add-nodes operation
Query oracle state to see registered nodes

“Reward collection failed”

Verify node has accumulated rewards
Check wallet matches node’s registered VKH
Ensure RewardAccount UTXOs are accessible

Deployment Guide Setup & Configuration