Oracle Node Setup

Status: Oracle nodes are planned for v1.2, alongside the $SNAP NFT launch and cross-chain bridge deployment. The specifications below describe the intended design.

Oracle nodes are responsible for attesting to cross-chain bridge state on the Citrate network. They monitor bridge contracts on connected chains (Ethereum, etc.), verify deposit and withdrawal events, and submit attestations that allow the Citrate bridge to release funds. Running an oracle requires holding a $SNAP NFT, which serves as your license to participate in the oracle network.

$SNAP NFT Requirement

To operate an oracle node, you must hold a $SNAP (Staked Node Attestation Pass) NFT in the wallet connected to your node. $SNAP NFTs are ERC-6551 token-bound accounts that grant specific network privileges, including oracle participation rights.

Check if your wallet holds a $SNAP NFT:

citrate-cli snap check --address 0xYOUR_ORACLE_ADDRESS --rpc https://rpc.cnidarian.cloud

View your $SNAP details:

citrate-cli snap info --token-id YOUR_SNAP_TOKEN_ID --rpc https://rpc.cnidarian.cloud

$SNAP NFTs come in three rarity tiers, each granting different attestation weight:

Tier	Attestation Weight	Minimum Stake	Fee Share
Common	1x	5,000 SALT	Base rate
Rare	3x	15,000 SALT	2x base rate
Legendary	10x	50,000 SALT	5x base rate

Higher rarity $SNAP NFTs earn proportionally more fees and have greater influence on bridge consensus decisions. See the $SNAP NFTs page for detailed information on acquiring and managing your NFT.

Installation and Configuration

Oracle nodes run a specialized daemon (citrate-oracle) alongside the standard Citrate client. We recommend using a dedicated RPC provider like Alchemy or Infura for your connected chain endpoints rather than relying on public RPCs, which can be unreliable under load.

Install the oracle daemon:

curl -L https://releases.cnidarian.cloud/citrate-oracle/latest | bash

Initialize oracle configuration:

citrate-oracle init --snap-token-id YOUR_SNAP_TOKEN_ID

Configure the oracle in ~/.citrate/oracle.toml:

[oracle]
snap_token_id = "YOUR_SNAP_TOKEN_ID"
attestation_key = "~/.citrate/keys/oracle_attestation.key"
poll_interval_seconds = 5
 
# Citrate network connection
[citrate]
rpc_url = "http://localhost:8545"    # Local citrated RPC
bridge_contract = "0xBRIDGE_CONTRACT_ADDRESS"
 
# Connected chains to monitor
[[chains]]
name = "ethereum"
chain_id = 1
rpc_url = "https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY"
bridge_contract = "0xETH_BRIDGE_CONTRACT"
confirmations_required = 12          # Wait for 12 ETH blocks before attesting
 
[[chains]]
name = "arbitrum"
chain_id = 42161
rpc_url = "https://arb-mainnet.g.alchemy.com/v2/YOUR_KEY"
bridge_contract = "0xARB_BRIDGE_CONTRACT"
confirmations_required = 1

Generate your attestation key:

citrate-oracle keygen --output ~/.citrate/keys/oracle_attestation.key

Attestation Duties

Oracle nodes perform two primary duties:

1. Deposit Attestation: When a user deposits tokens on a connected chain (e.g., ETH on Ethereum), your oracle monitors the bridge contract, waits for the required confirmations, and submits an attestation to the Citrate bridge contract confirming the deposit.

2. Withdrawal Verification: When a user requests a withdrawal from Citrate to a connected chain, your oracle verifies the withdrawal request is valid and co-signs the release transaction.

The attestation process:

User deposits ETH on Ethereum bridge
    → Oracle monitors Ethereum for deposit events
    → Oracle waits for N block confirmations
    → Oracle creates attestation (deposit_hash, amount, recipient, chain_id)
    → Oracle signs attestation with attestation key
    → Oracle submits attestation to Citrate bridge contract
    → When quorum of oracles attest, bridge mints wrapped tokens on Citrate

A quorum of oracle attestations (weighted by $SNAP tier) is required before any bridge action is executed. The current quorum threshold is 67% of total attestation weight.

Fee Collection

Oracle nodes earn fees from every bridge transaction they attest to. Fees are collected in SALT and accumulate in your $SNAP NFT's token-bound account.

Check accumulated oracle fees:

citrate-cli oracle fees --snap-token-id YOUR_SNAP_TOKEN_ID --rpc https://rpc.cnidarian.cloud

Claim accumulated fees:

citrate-cli oracle claim-fees --snap-token-id YOUR_SNAP_TOKEN_ID --rpc https://rpc.cnidarian.cloud --private-key $PRIVATE_KEY

Fee distribution per bridge transaction:

Recipient	Share
Attesting oracles (weighted by $SNAP tier)	70%
Protocol treasury	20%
Bridge liquidity providers	10%

Uptime Requirements

Oracle uptime is critical for bridge security. The network tracks oracle availability and penalizes nodes that fail to meet minimum uptime requirements.

Metric	Requirement	Penalty
Uptime	>99% per epoch (24 hours)	Fee reduction for the epoch
Attestation participation	>95% of eligible events	Warning, then fee reduction
Latency	Attestation within 30 seconds of quorum eligibility	Reduced attestation weight
Extended downtime	>4 hours continuous	Temporary suspension from oracle set

Monitor your oracle health:

Check oracle status and uptime:

citrate-oracle status

View attestation history:

citrate-oracle history --count 50

Check latency to connected chains:

citrate-oracle ping-chains

I'd strongly suggest setting up automated alerts for oracle downtime events -- even brief outages affect your fee earnings and can trigger penalties if they cause you to miss attestation duties.