Documentation

PixelOracle is a zero-knowledge oracle infrastructure built on Solana. It provides privacy-preserving data verification for DeFi protocols, DAO governance systems, gaming applications, and any on-chain program that needs reliable external data without exposing query metadata. The protocol uses Groth16 zero-knowledge proofs to ensure that oracle responses are mathematically verifiable while keeping query inputs private.

To integrate PixelOracle, you need three things: a Solana RPC connection, an API key from the developer portal, and the @pxoracl/sdk npm package. The minimum viable integration is five lines of code. Install the package, initialize the client, and call oracle.query with your target asset and data type. The SDK handles commitment generation, network routing, proof verification, and result parsing internally.

API keys are available in five tiers based on $PXCL staking. The free tier provides 100 queries per day with basic verification. Higher tiers unlock ZK proof generation, cross-chain queries, batch operations, and dedicated node access. See the Fee Structure section below for complete tier details.

PixelOracle operates as a five-layer stack built on Solana. Layer 0 is the Solana runtime itself, providing sub-second finality for oracle transactions. Layer 1 is Light Protocol ZK Compression, which stores oracle proofs in compressed PDAs at roughly 1/1000th the cost of standard Solana accounts. Layer 2 is the Anchor oracle program, an on-chain program that manages the query lifecycle, stores verification keys, and executes proof verification. Layer 3 is the cross-chain bridge adapter layer, containing protocol-specific adapters for Ethereum, BSC, and other EVM-compatible chains. Layer 4 is the privacy-preserving query engine, which implements ZK circuits ensuring that query inputs remain private while outputs are publicly verifiable.

The oracle network consists of multiple independent nodes that aggregate data from external sources, reach consensus on results, and submit signed attestations to the on-chain program. A query is considered verified when at least 2/3 of active nodes agree on the result. Each node runs the same aggregation logic but fetches data independently, reducing the risk of single-source manipulation. Node operators are required to stake $PXCL tokens as collateral, and nodes that submit incorrect data are subject to slashing.

The proving system uses Groth16 on the BN254 elliptic curve. The circuit takes query parameters and the oracle result as private inputs and outputs a commitment hash as the public signal. The trusted setup was performed via a 128-participant MPC ceremony, and the resulting verification key is stored immutably in the Anchor program. Proof generation runs client-side in the SDK and takes 300-500 milliseconds depending on circuit complexity.

Every oracle query follows a six-step lifecycle. First, the client creates a SHA-256 commitment hash over the query parameters and a random nonce. This commitment is submitted to the oracle network without revealing the actual query parameters. Second, the commitment is broadcast to all active oracle nodes. Third, nodes independently aggregate data from external sources and reach consensus on the result using a 2/3 threshold voting protocol. Fourth, a Groth16 zero-knowledge proof is generated over the result, binding the oracle output to the original commitment without revealing the inputs. Fifth, the proof and result are stored in a Light Protocol compressed PDA on Solana. Sixth, the client receives the verified response containing the value, proof hash, risk score, and verification status.

The entire lifecycle completes in under two seconds for single-chain queries. Cross-chain queries add the bridge latency of the source chain (12-15 seconds for Ethereum, 3-5 seconds for BSC). The SDK exposes hooks for each lifecycle stage via event emitters, allowing you to track query progress in real-time. Failed queries are automatically retried up to three times with exponential backoff before returning an error.

PixelOracle uses Light Protocol ZK Compression to store oracle proofs and results on Solana at a fraction of the cost of standard accounts. Traditional Solana accounts require rent-exempt balances of approximately 0.002 SOL per account. With ZK Compression, the same data is stored in a Merkle state tree where only the tree root lives on-chain. Individual proof records are stored as leaves in the tree, with inclusion proofs provided via 26-hash Merkle paths. This reduces per-proof storage cost to approximately 0.000002 SOL, a savings of roughly 1000x.

Each state tree has a depth of 26, supporting up to 67 million leaf entries. When a tree fills up, a new tree is created automatically. The SDK handles tree selection and Merkle path construction transparently. Reading compressed data requires an RPC provider that supports the Light Protocol indexer API. Most major Solana RPC providers include this support. When compression is enabled, all oracle.query results, oracle.getProof history lookups, and oracle.verify operations read from the compressed state tree instead of standard accounts.

The compression layer also enables efficient historical queries. Because Merkle trees are append-only, historical proof records are preserved indefinitely without incurring ongoing rent costs. The oracle.getProof method queries the compressed state tree directly, supporting pagination, time-range filters, and circuit-level filtering. This makes PixelOracle practical for applications that need to store and retrieve millions of oracle proofs over the lifetime of a protocol.

Cross-chain queries allow you to fetch and verify data from Ethereum, BSC, and other EVM-compatible chains while settling on Solana. Each source chain requires its own RPC endpoint configured in the PxOracle constructor. The SDK ships with built-in bridge adapters for Ethereum and BSC. Additional adapters for Polygon, Arbitrum, and Avalanche are under development.

When you call oracle.crossChain, the adapter fetches the requested data from the source chain and generates a Merkle Patricia Trie storage proof against the source block header. This storage proof is a cryptographic guarantee that the data existed in the source chain state at a specific block height. The proof is then bridged to Solana, where the oracle program verifies it against a trusted block hash relay. No trusted bridge operator is required because verification is purely mathematical.

The confirmations parameter controls how many blocks must pass on the source chain before the data is considered final. For Ethereum, 12 confirmations (approximately 2.5 minutes) provides strong finality. For BSC, 15 confirmations (approximately 45 seconds) is recommended. Lower confirmation counts reduce latency but increase the risk of reorg invalidation. The SDK will reject cross-chain results where the source block has been reorged out of the canonical chain.

The PixelOracle REST API provides direct access to oracle queries, proof verification, query status polling, cross-chain verification, and protocol statistics. All endpoints except /api/v1/stats require a Bearer token in the Authorization header. The base URL for all requests is https://api.pixeloracle.io. Rate limits are determined by your API key tier.

Oracle query fees are paid in $PXCL tokens. 50% of all query fees are used to buy back and permanently burn $PXCL, creating a deflationary pressure that scales with protocol usage. The remaining 50% is distributed between oracle node operators (30%) and the protocol treasury (20%).

Per-query costs vary by operation type. Standard single-chain queries with proof generation cost 0.5 $PXCL. Cross-chain queries cost 2.0 $PXCL due to bridge adapter overhead. Batch queries receive a 20% discount per asset after the first. Verification-only calls (oracle.verify) cost 0.1 $PXCL. Subscriptions are billed per update at the same rate as single queries. All fees are deducted from the staked balance, so you do not need to approve individual transactions.

The SDK uses a typed error hierarchy rooted at PxOracleError. All errors include a machine-readable code, a human-readable message, and a timestamp. Network errors (PxOracleNetworkError) include the failing endpoint URL and HTTP status code. Validation errors (PxOracleValidationError) include the offending field name and constraint description. Proof errors (PxOracleProofError) include the circuit identifier and failure reason. Rate limit errors (PxOracleRateLimitError) include a retryAfter value in seconds.

The SDK does not retry validation errors or rate limit errors. Network errors and proof errors are retried up to three times with exponential backoff (1s, 2s, 4s). You can override the retry behavior by passing a custom retryPolicy to the PxOracle constructor. Setting maxRetries to 0 disables retries entirely. The onRetry callback fires before each retry attempt, giving you the opportunity to log or abort.