Class Gateway

Gateway - Interface to Switchboard Oracle Network

The Gateway class provides methods to interact with Switchboard's oracle network, allowing you to fetch signatures, quotes, and randomness from oracle operators.

Variable Overrides

Many methods support variableOverrides which allow you to inject custom values into oracle job execution. This is particularly useful for:

  • API Keys: Securely pass API credentials without hardcoding in job definitions
  • Environment Config: Switch between dev/staging/prod endpoints dynamically
  • Custom Parameters: Override any variable defined in your oracle jobs

How Variable Overrides Work

When you provide variableOverrides, the gateway will:

  1. Parse the oracle job definitions
  2. Replace any matching variable references with your provided values
  3. Execute the jobs with the overridden values
  4. Return signed oracle responses

Example Usage

// Your oracle job might reference ${API_KEY} and ${NETWORK}
const overrides = {
  "API_KEY": "your-secret-key",
  "NETWORK": "mainnet"
};

const response = await gateway.fetchSignatures({
  recentHash: slothash,
  encodedJobs: [jobBase64],
  numSignatures: 3,
  variableOverrides: overrides
});

Best Practices

  1. Security: Never hardcode sensitive API keys in jobs - use overrides
  2. Environment Management: Use overrides to switch between dev/staging/prod
  3. Flexibility: Design jobs with variables for maximum reusability
  4. Validation: Ensure all required variables are provided in overrides
  5. Documentation: Document expected variables in your job definitions

Gateway

Constructors

constructor

Properties

gatewayUrl

Methods

[toPrimitive] endpoint fetchAttestation fetchAttestationQuote fetchBridgingMessage fetchQuote fetchRandomnessReveal fetchSignaturesConsensus ping toString

Constructors

constructor

  • new Gateway(gatewayUrlOrInstance: string | Gateway): Gateway

    Constructs a Gateway instance

    Parameters

    • gatewayUrlOrInstance: string | Gateway

      The URL of the switchboard gateway, or another Gateway instance to clone

    Returns Gateway

    Example

    // Create from URL string
    const gateway1 = new Gateway("https://gateway.switchboard.xyz");

    // Clone from another Gateway instance
    const gateway2 = new Gateway(gateway1);

Properties

ReadonlygatewayUrl

gatewayUrl: string

Methods

[toPrimitive]

  • "[toPrimitive]"(hint: string): null | string

    Parameters

    • hint: string

    Returns null | string

endpoint

fetchAttestation

  • fetchAttestation(
        params: {
            oracle_ed25519_enclave_signer: string;
            oracle_pubkey: string;
            oracle_reward_wallet: string;
            oracle_secp256k1_enclave_signer: string;
            quote: string;
            recentHash: string;
            timestamp: number;
        },
    ): Promise<AttestEnclaveResponse>

    Fetches signatures from the gateway. REST API endpoint: /api/v1/gateway_attest_enclave

    Parameters

    • params: {
          oracle_ed25519_enclave_signer: string;
          oracle_pubkey: string;
          oracle_reward_wallet: string;
          oracle_secp256k1_enclave_signer: string;
          quote: string;
          recentHash: string;
          timestamp: number;
      }

    Returns Promise<AttestEnclaveResponse>

    A promise that resolves to the attestation response.

    Throws

    if the request fails.

fetchAttestationQuote

  • fetchAttestationQuote(
        params: {
            blockhash: string;
            get_for_guardian: boolean;
            get_for_oracle: boolean;
        },
    ): Promise<FetchQuoteResponse[]>

    Fetches an attestation quote from the gateway.

    REST API endpoint: /api/v1/gateway_fetch_quote

    Parameters

    • params: { blockhash: string; get_for_guardian: boolean; get_for_oracle: boolean }

    Returns Promise<FetchQuoteResponse[]>

    A promise that resolves to the quote response.

    Throws

    if the request fails.

fetchBridgingMessage

  • fetchBridgingMessage(
        params: { chainHash: string; oraclePubkey: string; queuePubkey: string },
    ): Promise<BridgeEnclaveResponse>

    Sends a request to the gateway bridge enclave.

    REST API endpoint: /api/v1/gateway_bridge_enclave

    Parameters

    • params: { chainHash: string; oraclePubkey: string; queuePubkey: string }

    Returns Promise<BridgeEnclaveResponse>

    A promise that resolves to the response.

    Throws

    if the request fails.

fetchQuote

  • fetchQuote(
        crossbar: CrossbarClient,
        feedHashes: string[],
        numSignatures?: number,
        variableOverrides?: Record<string, string>,
    ): Promise<FetchSignaturesConsensusResponse>

    Fetches oracle quote data from the gateway

    This method retrieves signed price quotes from oracle operators through the gateway interface. It's the primary method for fetching oracle data using the modern quote terminology.

    Protocol Details

    • Uses Ed25519 signature scheme for efficient verification
    • Supports both protobuf and legacy job specifications
    • Implements consensus mechanism across multiple oracles
    • Returns structured response with oracle metadata

    Response Structure

    The returned response contains:

    • oracle_responses: Array of signed oracle data
    • recent_hash: Recent Solana block hash for replay protection
    • slot: Recent slot number for temporal validation

    Parameters

    • crossbar: CrossbarClient

      Crossbar client for data routing and feed resolution

    • feedHashes: string[]

      Array of feed hashes to fetch (hex strings, max 16)

    • numSignatures: number = 1

      Number of oracle signatures required (default: 1, max based on queue config)

    • OptionalvariableOverrides: Record<string, string>

    Returns Promise<FetchSignaturesConsensusResponse>

    Oracle quote response with signatures

    Throws

    When gateway is unreachable or returns error

    Throws

    When crossbar cannot resolve feed hashes

    Throws

    When insufficient oracles are available

    Since

    2.14.0

    See

    • fetchUpdateBundle - Deprecated equivalent method
    • Queue.fetchQuoteIx - High-level method that uses this internally

    Example

    import { CrossbarClient } from '@switchboard-xyz/common';

    // Initialize crossbar client
    const crossbar = CrossbarClient.default();

    // Single feed quote
    const btcQuote = await gateway.fetchQuote(
      crossbar,
      ['0xef0d8b6fcd0104e3e75096912fc8e1e432893da4f18faedaacca7e5875da620f'], // BTC/USD
      1 // Single signature for fast updates
    );

    // Multi-feed quote for DeFi protocol
    const defiAssets = [
      '0xef0d8b6fcd0104e3e75096912fc8e1e432893da4f18faedaacca7e5875da620f', // BTC/USD
      '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef', // ETH/USD
      '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890', // SOL/USD
      '0x9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba'  // USDC/USD
    ];

    const portfolioQuote = await gateway.fetchQuote(
      crossbar,
      defiAssets,
      5 // Higher consensus for financial operations
    );

    // Access oracle responses
    console.log('Oracle responses:', portfolioQuote.oracle_responses.length);
    console.log('Recent slot:', portfolioQuote.slot);

    // Process individual feed responses
    portfolioQuote.oracle_responses.forEach((oracle, index) => {
      oracle.feed_responses.forEach((feed, feedIndex) => {
        console.log(`Oracle ${index}, Feed ${feedIndex}:`, {
          feedHash: feed.feed_hash,
          value: feed.success_value,
          confidence: feed.min_oracle_samples
        });
      });
    });

fetchRandomnessReveal

  • fetchRandomnessReveal(
        params:
            | {
                randomnessAccount: { toBuffer(): Buffer };
                rpc?: string;
                slot: number;
                slothash: string;
            }
            | { minStalenessSeconds: number; randomnessId: string; timestamp: number },
    ): Promise<RandomnessRevealResponse>

    Fetches the randomness reveal from the gateway.

    Parameters

    • params:
          | {
              randomnessAccount: { toBuffer(): Buffer };
              rpc?: string;
              slot: number;
              slothash: string;
          }
          | { minStalenessSeconds: number; randomnessId: string; timestamp: number }

      The parameters for the randomness reveal.

    Returns Promise<RandomnessRevealResponse>

    The randomness reveal response.

fetchSignaturesConsensus

  • fetchSignaturesConsensus(
        params: {
            feedConfigs: FeedRequest[];
            numSignatures?: number;
            useEd25519?: boolean;
            useTimestamp?: boolean;
            variableOverrides?: Record<string, string>;
        },
    ): Promise<FetchSignaturesConsensusResponse>

    Fetches signatures using consensus mechanism REST API endpoint: /api/v1/fetch_signatures_consensus

    Parameters

    • params: {
          feedConfigs: FeedRequest[];
          numSignatures?: number;
          useEd25519?: boolean;
          useTimestamp?: boolean;
          variableOverrides?: Record<string, string>;
      }

    Returns Promise<FetchSignaturesConsensusResponse>

    A promise that resolves to the consensus response.

    Throws

    if the request fails.

ping

toString

Settings

Member Visibility

On This Page

Variable Overrides
Constructors
Properties
Methods