Crate sol_rpc_client

Expand description

Client to interact with the SOL RPC canister

§Examples

§Configuring the client

By default, any RPC endpoint supported by the SOL RPC canister will call 3 providers and require equality between their results. It is possible to customize the client so that another strategy, such as 3-out-of-2 in the example below, is used for all following calls.

use candid::Principal;
use sol_rpc_client::SolRpcClient;
use sol_rpc_types::{ConsensusStrategy, RpcConfig, RpcSources, SolanaCluster};

let client = SolRpcClient::builder_for_ic()
    .with_rpc_sources(RpcSources::Default(SolanaCluster::Mainnet))
    .with_rpc_config(RpcConfig {
        response_consensus: Some(ConsensusStrategy::Threshold {
            total: Some(3),
            min: 2,
        }),
        ..Default::default()
    })
    .build();

§Estimating the amount of cycles to send

Every call made to the SOL RPC canister that triggers HTTPs outcalls (e.g., getSlot) needs to attach some cycles to pay for the call. By default, the client will attach some amount of cycles that should be sufficient for most cases.

If this is not the case, the amount of cycles to be sent can be changed as follows:

Determine the required amount of cycles to send for a particular request. The SOL RPC canister offers some query endpoints (e.g., getSlotCyclesCost) for that purpose. This could help establishing a baseline so that the estimated cycles cost for similar requests can be extrapolated from it instead of making additional queries to the SOL RPC canister.
Override the amount of cycles to send for that particular request. It’s advisable to actually send more cycles than required, since unused cycles will be refunded.

use sol_rpc_client::SolRpcClient;
use sol_rpc_types::MultiRpcResult;

let client = SolRpcClient::builder_for_ic()
    .build();

let request = client.get_slot();

let minimum_required_cycles_amount = request.clone().request_cost().send().await.unwrap();

let slot = request
    .with_cycles(minimum_required_cycles_amount)
    .send()
    .await
    .expect_consistent();

assert_eq!(slot, Ok(332_577_897_u64));

§Overriding client configuration for a specific call

Besides changing the amount of cycles for a particular call as described above, it is sometimes desirable to have a custom configuration for a specific call that is different from the one used by the client for all the other calls.

For example, maybe for most calls a 2 out-of 3 strategy is good enough, but for getSlot your application requires a higher threshold and more robustness with a 3 out-of 5 :

use sol_rpc_client::SolRpcClient;
use sol_rpc_types::{
    ConsensusStrategy, GetSlotRpcConfig, MultiRpcResult, RpcConfig, RpcSources,
    SolanaCluster,
};

let client = SolRpcClient::builder_for_ic()
    .with_rpc_sources(RpcSources::Default(SolanaCluster::Mainnet))
    .with_rpc_config(RpcConfig {
        response_consensus: Some(ConsensusStrategy::Threshold {
            total: Some(3),
            min: 2,
        }),
    ..Default::default()
    })
    .build();

let slot = client
    .get_slot()
    .with_rpc_config(GetSlotRpcConfig {
        response_consensus: Some(ConsensusStrategy::Threshold {
            total: Some(5),
            min: 3,
        }),
        ..Default::default()
    })
    .send()
    .await
    .expect_consistent();

assert_eq!(slot, Ok(332_577_897_u64));

⚠️ Build Requirements

If you are using the sol_rpc_client crate inside a canister, make sure to follow the steps outlined here to ensure your code compiles.

Modules§

ed25519: This module provides some helper functions for the Internet Computer threshold EdDSA signature API in the context of the SOL RPC canister, e.g. signing Solana transactions and fetching and deriving EdDSA public keys. See the documentation for more detailed information on the full threshold Schnorr API.
fixtures: Simple types to create basic unit tests for the crate::SolRpcClient.
nonce: Module for interacting with Solana nonce accounts.

Structs§

ClientBuilder: A ClientBuilder to create a SolRpcClient with custom configuration.
ClientConfig: Client to interact with the SOL RPC canister.
EstimateBlockhashRequestBuilder: A builder to build a request to fetch a recent blockhash. See SolRpcClient::estimate_recent_blockhash.
IcRuntime: Runtime when interacting with a canister running on the Internet Computer.
Request: A request which can be executed with SolRpcClient::execute_request or SolRpcClient::execute_query_request.
RequestBuilder: A builder to construct a Request.
SolRpcClient: Client to interact with the SOL RPC canister.

Enums§

EstimateRecentBlockhashError: An error that occurred while trying to fetch a recent blockhash. See SolRpcClient::estimate_recent_blockhash
SolRpcEndpoint: Endpoint on the SOL RPC canister triggering a call to Solana providers.

Constants§

SOL_RPC_CANISTER: The principal identifying the productive Solana RPC canister under NNS control.

Traits§

Runtime: Abstract the canister runtime so that the client code can be reused:
SolRpcRequest: Solana RPC endpoint supported by the SOL RPC canister.

Crate sol_rpc_clientCopy item path