Struct solana_client::rpc_client::RpcClient[][src]

pub struct RpcClient { /* fields omitted */ }
Expand description

A client of a remote Solana node.

RpcClient communicates with a Solana node over JSON-RPC, with the Solana JSON-RPC protocol. It is the primary Rust interface for querying and transacting with the network from external programs.

This type builds on the underlying RPC protocol, adding extra features such as timeout handling, retries, and waiting on transaction commitment levels. Some methods simply pass through to the underlying RPC protocol. Not all RPC methods are encapsulated by this type, but RpcClient does expose a generic send method for making any RpcRequest.

The documentation for most RpcClient methods contains an “RPC Reference” section that links to the documentation for the underlying JSON-RPC method. The documentation for RpcClient does not reproduce the documentation for the underlying JSON-RPC methods. Thus reading both is necessary for complete understanding.

RpcClients generally communicate over HTTP on port 8899, a typical server URL being “http://localhost:8899”.

By default, requests to confirm transactions only succeed once those transactions are finalized, meaning they are definitely permanently committed. Transactions can be confirmed with less finality by creating RpcClient with an explicit CommitmentConfig, or by calling the various _with_commitment methods, like RpcClient::confirm_transaction_with_commitment.

Errors

Methods on RpcClient return client_error::Result, and many of them return the RpcResult typedef, which contains Response<T> on Ok. Both client_error::Result and RpcResult contain ClientError on error. In the case of RpcResult, the actual return value is in the value field, with RPC contextual information in the context field, so it is common for the value to be accessed with ?.value, as in

let signature = rpc_client.send_transaction(&tx)?;
let statuses = rpc_client.get_signature_statuses(&[signature])?.value;

Requests may timeout, in which case they return a ClientError where the ClientErrorKind is ClientErrorKind::Reqwest, and where the interior reqwest::Errors is_timeout method returns true. The default timeout is 30 seconds, and may be changed by calling an appropriate constructor with a timeout parameter.

Implementations

Create an HTTP RpcClient.

The URL is an HTTP URL, usually for port 8899, as in “http://localhost:8899”.

The client has a default timeout of 30 seconds, and a default commitment level of Finalized.

Examples

let url = "http://localhost:8899".to_string();
let client = RpcClient::new(url);

Create an HTTP RpcClient with specified commitment level.

The URL is an HTTP URL, usually for port 8899, as in “http://localhost:8899”.

The client has a default timeout of 30 seconds, and a user-specified CommitmentLevel via CommitmentConfig.

Examples

let url = "http://localhost:8899".to_string();
let commitment_config = CommitmentConfig::processed();
let client = RpcClient::new_with_commitment(url, commitment_config);

Create an HTTP RpcClient with specified timeout.

The URL is an HTTP URL, usually for port 8899, as in “http://localhost:8899”.

The client has and a default commitment level of Finalized.

Examples

let url = "http://localhost::8899".to_string();
let timeout = Duration::from_secs(1);
let client = RpcClient::new_with_timeout(url, timeout);

Create an HTTP RpcClient with specified timeout and commitment level.

The URL is an HTTP URL, usually for port 8899, as in “http://localhost:8899”.

Examples

let url = "http://localhost::8899".to_string();
let timeout = Duration::from_secs(1);
let commitment_config = CommitmentConfig::processed();
let client = RpcClient::new_with_timeout_and_commitment(
    url,
    timeout,
    commitment_config,
);

Create an HTTP RpcClient with specified timeout and commitment level.

The URL is an HTTP URL, usually for port 8899, as in “http://localhost:8899”.

The confirm_transaction_initial_timeout argument specifies, when confirming a transaction via one of the _with_spinner methods, like RpcClient::send_and_confirm_transaction_with_spinner, the amount of time to allow for the server to initially process a transaction. In other words, setting confirm_transaction_initial_timeout to > 0 allows RpcClient to wait for confirmation of a transaction that the server has not “seen” yet.

Examples

let url = "http://localhost::8899".to_string();
let timeout = Duration::from_secs(1);
let commitment_config = CommitmentConfig::processed();
let confirm_transaction_initial_timeout = Duration::from_secs(10);
let client = RpcClient::new_with_timeouts_and_commitment(
    url,
    timeout,
    commitment_config,
    confirm_transaction_initial_timeout,
);

Create a mock RpcClient.

See the MockSender documentation for an explanation of how it treats the url argument.

Examples

// Create an `RpcClient` that always succeeds
let url = "succeeds".to_string();
let successful_client = RpcClient::new_mock(url);
// Create an `RpcClient` that always fails
let url = "fails".to_string();
let successful_client = RpcClient::new_mock(url);

Create a mock RpcClient.

See the MockSender documentation for an explanation of how it treats the url argument.

Examples

// Create a mock with a custom repsonse to the `GetBalance` request
let account_balance = 50;
let account_balance_response = json!(Response {
    context: RpcResponseContext { slot: 1 },
    value: json!(account_balance),
});

let mut mocks = HashMap::new();
mocks.insert(RpcRequest::GetBalance, account_balance_response);
let url = "succeeds".to_string();
let client = RpcClient::new_mock_with_mocks(url, mocks);

Create an HTTP RpcClient from a SocketAddr.

The client has a default timeout of 30 seconds, and a default commitment level of Finalized.

Examples

let addr = SocketAddr::from(([127, 0, 0, 1], 8899));
let client = RpcClient::new_socket(addr);

Create an HTTP RpcClient from a SocketAddr with specified commitment level.

The client has a default timeout of 30 seconds, and a user-specified CommitmentLevel via CommitmentConfig.

Examples

let addr = SocketAddr::from(([127, 0, 0, 1], 8899));
let commitment_config = CommitmentConfig::processed();
let client = RpcClient::new_socket_with_commitment(
    addr,
    commitment_config
);

Create an HTTP RpcClient from a SocketAddr with specified timeout.

The client has and a default commitment level of Finalized.

Examples

let addr = SocketAddr::from(([127, 0, 0, 1], 8899));
let timeout = Duration::from_secs(1);
let client = RpcClient::new_socket_with_timeout(addr, timeout);

Get the configured default commitment level.

The commitment config may be specified during construction, and determines how thoroughly committed a transaction must be when waiting for its confirmation or otherwise checking for confirmation. If not specified, the default commitment level is Finalized.

The default commitment level is overridden when calling methods that explicitly provide a CommitmentConfig, like RpcClient::confirm_transaction_with_commitment.

Check the confirmation status of a transaction.

Returns true if the given transaction succeeded and has been committed with the configured commitment level, which can be retrieved with the commitment method.

Note that this method does not wait for a transaction to be confirmed — it only checks whether a transaction has been confirmed. To submit a transaction and wait for it to confirm, use send_and_confirm_transaction.

This method returns false if the transaction failed, even if it has been confirmed.

RPC Reference

This method is built on the getSignatureStatuses RPC method.

Examples

// Transfer lamports from Alice to Bob and wait for confirmation
let (recent_blockhash, _) = rpc_client.get_recent_blockhash()?;
let tx = system_transaction::transfer(&alice, &bob.pubkey(), lamports, recent_blockhash);
let signature = rpc_client.send_transaction(&tx)?;

loop {
    let confirmed = rpc_client.confirm_transaction(&signature)?;
    if confirmed {
        break;
    }
}

Check the confirmation status of a transaction.

Returns an RpcResult with value true if the given transaction succeeded and has been committed with the given commitment level.

Note that this method does not wait for a transaction to be confirmed — it only checks whether a transaction has been confirmed. To submit a transaction and wait for it to confirm, use send_and_confirm_transaction.

This method returns an RpcResult with value false if the transaction failed, even if it has been confirmed.

RPC Reference

This method is built on the getSignatureStatuses RPC method.

Examples

// Transfer lamports from Alice to Bob and wait for confirmation
let (recent_blockhash, _) = rpc_client.get_recent_blockhash()?;
let tx = system_transaction::transfer(&alice, &bob.pubkey(), lamports, recent_blockhash);
let signature = rpc_client.send_transaction(&tx)?;

loop {
    let commitment_config = CommitmentConfig::processed();
    let confirmed = rpc_client.confirm_transaction_with_commitment(&signature, commitment_config)?;
    if confirmed.value {
        break;
    }
}

Examples

// Transfer lamports from Alice to Bob
let (recent_blockhash, _) = rpc_client.get_recent_blockhash()?;
let tx = system_transaction::transfer(&alice, &bob.pubkey(), lamports, recent_blockhash);
let signature = rpc_client.send_transaction(&tx)?;

Examples

// Transfer lamports from Alice to Bob
let (recent_blockhash, _) = rpc_client.get_recent_blockhash()?;
let tx = system_transaction::transfer(&alice, &bob.pubkey(), lamports, recent_blockhash);
let config = RpcSendTransactionConfig {
    skip_preflight: true,
    .. RpcSendTransactionConfig::default()
};
let signature = rpc_client.send_transaction_with_config(
    &tx,
    config,
)?;

Examples

// Transfer lamports from Alice to Bob
let (recent_blockhash, _) = rpc_client.get_recent_blockhash()?;
let tx = system_transaction::transfer(&alice, &bob.pubkey(), lamports, recent_blockhash);
let result = rpc_client.simulate_transaction(&tx)?;
assert!(result.value.err.is_none());

Examples

// Transfer lamports from Alice to Bob
let (recent_blockhash, _) = rpc_client.get_recent_blockhash()?;
let tx = system_transaction::transfer(&alice, &bob.pubkey(), lamports, recent_blockhash);
let config = RpcSimulateTransactionConfig {
    sig_verify: false,
    .. RpcSimulateTransactionConfig::default()
};
let result = rpc_client.simulate_transaction_with_config(
    &tx,
    config,
)?;
assert!(result.value.err.is_none());

Examples

let slot = rpc_client.get_snapshot_slot()?;

Examples

let signature = rpc_client.send_transaction(&tx)?;
let status = rpc_client.get_signature_status(&signature)?;

Gets the statuses of a list of transaction signatures.

The returned vector of TransactionStatus has the same length as the input slice.

For any transaction that has not been processed by the network, the value of the corresponding entry in the returned vector is None. As a result, a transaction that has recently been submitted will not have a status immediately.

To submit a transaction and wait for it to confirm, use send_and_confirm_transaction.

This function ignores the configured confirmation level, and returns the transaction status whatever it is. It does not wait for transactions to be processed.

This function only searches a node’s recent history, including all recent slots, plus up to [MAX_RECENT_BLOCKHASHES][solana_sdk::clock::MAX_RECENT_BLOCKHASHES] rooted slots. To search the full transaction history use the get_signature_statuses_with_history method.

Errors

Any individual TransactionStatus may have triggered an error during processing, in which case its err field will be Some.

RPC Reference

This method corresponds directly to the getSignatureStatuses RPC method.

Examples

// Send lamports from Alice to Bob and wait for the transaction to be processed
let (recent_blockhash, _) = rpc_client.get_recent_blockhash()?;
let tx = system_transaction::transfer(&alice, &bob.pubkey(), lamports, recent_blockhash);
let signature = rpc_client.send_transaction(&tx)?;

let status = loop {
   let statuses = rpc_client.get_signature_statuses(&[signature])?.value;
   if let Some(status) = statuses[0].clone() {
       break status;
   }
   std::thread::sleep(Duration::from_millis(100));
};

assert!(status.err.is_none());

Gets the statuses of a list of transaction signatures.

The returned vector of TransactionStatus has the same length as the input slice.

For any transaction that has not been processed by the network, the value of the corresponding entry in the returned vector is None. As a result, a transaction that has recently been submitted will not have a status immediately.

To submit a transaction and wait for it to confirm, use send_and_confirm_transaction.

This function ignores the configured confirmation level, and returns the transaction status whatever it is. It does not wait for transactions to be processed.

This function searches a node’s full ledger history and (if implemented) long-term storage. To search for transactions in recent slots only use the get_signature_statuses method.

Errors

Any individual TransactionStatus may have triggered an error during processing, in which case its err field will be Some.

RPC Reference

This method corresponds directly to the getSignatureStatuses RPC method, with the searchTransactionHistory configuration option set to true.

Examples

// Check if an old transaction exists
let signature = get_old_transaction_signature();
let (recent_blockhash, _) = rpc_client.get_recent_blockhash()?;
let statuses = rpc_client.get_signature_statuses_with_history(&[signature])?.value;
if statuses[0].is_none() {
    println!("old transaction does not exist");
}

Examples

let signature = rpc_client.send_transaction(&tx)?;
let commitment_config = CommitmentConfig::processed();
let status = rpc_client.get_signature_status_with_commitment(
    &signature,
    commitment_config,
)?;

Examples

let signature = rpc_client.send_transaction(&tx)?;
let commitment_config = CommitmentConfig::processed();
let search_transaction_history = true;
let status = rpc_client.get_signature_status_with_commitment_and_history(
    &signature,
    commitment_config,
    search_transaction_history,
)?;

Examples

let slot = rpc_client.get_slot()?;

Examples

let commitment_config = CommitmentConfig::processed();
let slot = rpc_client.get_slot_with_commitment(commitment_config)?;

Examples

let block_height = rpc_client.get_block_height()?;

Examples

let commitment_config = CommitmentConfig::processed();
let block_height = rpc_client.get_block_height_with_commitment(
    commitment_config,
)?;

Examples

let start_slot = 1;
let limit = 3;
let leaders = rpc_client.get_slot_leaders(start_slot, limit)?;

Get block production for the current epoch.

Examples

let production = rpc_client.get_block_production()?;

Examples

let leader = rpc_client.get_slot_leaders(start_slot, limit)?;
let leader = leader[0];
let range = RpcBlockProductionConfigRange {
    first_slot: 0,
    last_slot: Some(0),
};
let config = RpcBlockProductionConfig {
    identity: Some(leader.to_string()),
    range: Some(range),
    commitment: Some(CommitmentConfig::processed()),
};
let production = rpc_client.get_block_production_with_config(
    config
)?;

Examples

let stake_account = stake_account_keypair.pubkey();
let epoch = rpc_client.get_epoch_info()?;
let activation = rpc_client.get_stake_activation(
    stake_account,
    Some(epoch.epoch),
)?;

Examples

let supply = rpc_client.supply()?;

Examples

let commitment_config = CommitmentConfig::processed();
let supply = rpc_client.supply_with_commitment(
    commitment_config,
)?;

Examples

let commitment_config = CommitmentConfig::processed();
let config = RpcLargestAccountsConfig {
    commitment: Some(commitment_config),
    filter: Some(RpcLargestAccountsFilter::Circulating),
};
let accounts = rpc_client.get_largest_accounts_with_config(
    config,
)?;

Examples

let accounts = rpc_client.get_vote_accounts()?;

Examples

let commitment_config = CommitmentConfig::processed();
let accounts = rpc_client.get_vote_accounts_with_commitment(
    commitment_config,
)?;

Examples

let vote_pubkey = vote_keypair.pubkey();
let commitment = CommitmentConfig::processed();
let config = RpcGetVoteAccountsConfig {
    vote_pubkey: Some(vote_pubkey.to_string()),
    commitment: Some(commitment),
    keep_unstaked_delinquents: Some(true),
    delinquent_slot_distance: Some(10),
};
let accounts = rpc_client.get_vote_accounts_with_config(
    config,
)?;
👎 Deprecated since 1.7.0:

Please use RpcClient::get_block() instead

👎 Deprecated since 1.7.0:

Please use RpcClient::get_block_with_encoding() instead

👎 Deprecated since 1.7.0:

Please use RpcClient::get_block_with_config() instead

👎 Deprecated since 1.7.0:

Please use RpcClient::get_blocks() instead

👎 Deprecated since 1.7.0:

Please use RpcClient::get_blocks_with_commitment() instead

👎 Deprecated since 1.7.0:

Please use RpcClient::get_blocks_with_limit() instead

👎 Deprecated since 1.7.0:

Please use RpcClient::get_blocks_with_limit_and_commitment() instead

👎 Deprecated since 1.7.0:

Please use RpcClient::get_signatures_for_address() instead

👎 Deprecated since 1.7.0:

Please use RpcClient::get_signatures_for_address_with_config() instead

👎 Deprecated since 1.7.0:

Please use RpcClient::get_transaction() instead

👎 Deprecated since 1.7.0:

Please use RpcClient::get_transaction_with_config() instead

Note that get_account returns Err(..) if the account does not exist whereas get_account_with_commitment returns Ok(None) if the account does not exist.

Request the balance of the account pubkey.

Request the transaction count.

Poll the server to confirm a transaction.

Poll the server to confirm a transaction.

Poll the server to confirm a transaction.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Performs the conversion.

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Performs the conversion.

The alignment of pointer.

The type for initializers.

Initializes a with the given initializer. Read more

Dereferences the given pointer. Read more

Mutably dereferences the given pointer. Read more

Drops the object pointed to by the given pointer. Read more

Should always be Self

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.