Switchboard On-Demand Schemas

Feed request schemas for Switchboard on-demand oracles.

Overview

This crate provides schema definitions and utilities for working with Switchboard on-demand oracle feed requests. It supports both V1 (legacy) and V2 feed request formats, enabling developers to create, serialize, deserialize, and validate oracle feed requests.

Features

• Dual Version Support: Handle both V1 and V2 feed request formats
• Feed ID Generation: Deterministic feed ID calculation for both versions
• Checksum Validation: Multi-feed and single-feed checksum generation
• Protobuf Integration: Seamless integration with switchboard-protos
• Caching: Built-in caching for deserialized jobs and feed IDs
• Type Safety: Strongly-typed Rust structs with serde support

Installation

Add this to your Cargo.toml:

[dependencies]
sb-on-demand-schemas = "0.1.0"

Usage

Working with V2 Feed Requests

use sb_on_demand_schemas::{FeedRequestV2, FeedRequest};
use switchboard_protos::oracle_job::OracleFeed;

// Create a V2 feed request from base64-encoded protobuf
let feed_request = FeedRequestV2::new(feed_proto_b64);

// Deserialize the feed
let feed: OracleFeed = feed_request.deserialize()?;

// Get the feed ID
let feed_id = feed_request.feed_id()?;

// Convert to generic FeedRequest
let generic_request: FeedRequest = feed_request.into();

Working with V1 Feed Requests

use sb_on_demand_schemas::FeedRequestV1;
use solana_sdk::pubkey::Pubkey;

// Create a V1 feed request
let feed_request = FeedRequestV1::new(
    id,
    jobs_b64_encoded,
    max_variance,
    min_responses,
);

// Deserialize jobs
let jobs = feed_request.deserialize_jobs()?;

// Get feed ID (requires queue pubkey for V1)
let queue = Pubkey::new_unique();
let feed_id = feed_request.feed_id(&queue)?;

// Generate checksum
let checksum = feed_request.single_checksum(
    &queue,
    value,
    hash,
    Some(timestamp),
)?;

Generic FeedRequest API

use sb_on_demand_schemas::FeedRequest;

// The FeedRequest enum handles both V1 and V2
match feed_request {
    FeedRequest::V1(v1) => {
        // Handle V1-specific logic
    }
    FeedRequest::V2(v2) => {
        // Handle V2-specific logic
    }
}

// Or use the unified API
let id = feed_request.id();
let jobs = feed_request.deserialize_jobs()?;
let min_responses = feed_request.min_job_responses();
let max_range = feed_request.max_range_pct();

Multi-Feed Checksum Generation

use sb_on_demand_schemas::FeedRequest;

// V2 multi-feed checksum
let checksum = FeedRequest::multi_checksum(
    &queue_key,
    &feed_requests,
    &values,
    &signed_slothash,
    Some(timestamp),
)?;

Creating Test Feeds

use sb_on_demand_schemas::{create_btc_v2_feed, encode_feed_to_base64};

// Create a BTC price feed for testing
let feed = create_btc_v2_feed()?;

// Encode to base64
let feed_b64 = encode_feed_to_base64(&feed);

// Use in a feed request
let feed_request = FeedRequestV2::new(feed_b64);

Feed Request Versions

V1 (Legacy)

V1 feed requests use a list of base64-encoded jobs with variance and minimum response parameters:

• jobs_b64_encoded: Vector of base64-encoded protobuf jobs
• max_variance: Maximum allowed variance between job responses
• min_responses: Minimum number of successful job responses required
• Feed ID calculated using queue pubkey + job hashes

V2 (Current)

V2 feed requests use a single base64-encoded OracleFeed protobuf:

• feed_proto_b64: Base64-encoded OracleFeed protobuf
• Includes all configuration within the feed structure
• Feed ID calculated from the feed protobuf hash
• Supports min_oracle_samples for multi-oracle aggregation

Checksum Generation

Both versions support checksum generation for feed validation:

• Single Feed Checksum: Validates a single feed update
• Multi Feed Checksum: Validates multiple feed updates atomically
• Checksums include feed ID, value, variance, and timestamp

Performance Optimizations

• Caching: Deserialized jobs and feed IDs are cached using Arc<RwLock<Option<T>>>
• Lazy Deserialization: Jobs and feeds are only deserialized when needed
• Pre-allocated Buffers: Multi-checksum generation pre-allocates buffers to avoid reallocations

Building from Source

# Clone the repository
git clone https://github.com/switchboard-xyz/sbv3
cd sbv3/rust/sb-on-demand-schemas

# Build the crate
cargo build

# Run tests
cargo test

# Check for linting issues
cargo clippy

# Format code
cargo fmt

Dependencies

• switchboard-protos: Protobuf definitions for oracle jobs
• switchboard-on-demand: On-demand oracle client library
• solana-sdk: Solana SDK for pubkey and hashing
• prost: Protocol Buffer implementation
• serde: Serialization framework
• sha2: SHA-256 hashing
• anyhow: Error handling

Examples

See the tests module in src/lib.rs for comprehensive examples of:

• Creating V2 feeds
• Encoding/decoding feed requests
• Feed ID generation
• Checksum validation
• Version conversion

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License.

Resources

• Switchboard Documentation
• Main Repository
• API Documentation
• Discord Community

Support

For questions and support:

• Join our Discord
• Check our documentation
• Open an issue on GitHub