Crate evm_rpc_client

Expand description

Client to interact with the EVM RPC canister

§Examples

§Configuring the client

By default, any RPC endpoint supported by the EVM 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 2-out-of-3 in the example below, is used for all following calls.

use evm_rpc_client::EvmRpcClient;
use evm_rpc_types::{ConsensusStrategy, RpcConfig, RpcServices};

let client = EvmRpcClient::builder_for_ic()
    .with_rpc_sources(RpcServices::EthMainnet(None))
    .with_consensus_strategy(ConsensusStrategy::Threshold {
        total: Some(3),
        min: 2,
    })
    .build();

By default, the client will return Candid output types for all calls. It is also possible to customize the client so that it returns alloy types instead. Note that this requires the alloy Cargo feature to be enabled.

use evm_rpc_client::EvmRpcClient;

let client = EvmRpcClient::builder_for_ic()
    .with_alloy()
    .build();

§Estimating the amount of cycles to send

Every call made to the EVM RPC canister that triggers HTTPs outcalls (e.g., eth_getLogs) 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 EVM RPC canister offers some query endpoints (e.g., eth_getLogsCyclesCost) 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 EVM 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 alloy_primitives::{address, U256};
use alloy_rpc_types::BlockNumberOrTag;
use evm_rpc_client::EvmRpcClient;

let client = EvmRpcClient::builder_for_ic()
    .with_alloy()
    .build();

let request = client
    .get_transaction_count((
        address!("0xdac17f958d2ee523a2206206994597c13d831ec7"),
        BlockNumberOrTag::Latest,
    ));

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

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

assert_eq!(result, Ok(U256::ONE));

§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 eth_getLogs your application requires a higher threshold and more robustness with a 3-out-of-5 :

use alloy_primitives::{address, U256};
use alloy_rpc_types::BlockNumberOrTag;
use evm_rpc_client::EvmRpcClient;
use evm_rpc_types::{ConsensusStrategy, RpcServices};

let client = EvmRpcClient::builder_for_ic()
    .with_alloy()
    .with_rpc_sources(RpcServices::EthMainnet(None))
    .with_consensus_strategy(ConsensusStrategy::Threshold {
        total: Some(3),
        min: 2,
    })
    .build();

let result = client
    .get_transaction_count((
        address!("0xdac17f958d2ee523a2206206994597c13d831ec7"),
        BlockNumberOrTag::Latest,
    ))
    .with_cycles(20_000_000_000)
    .send()
    .await
    .expect_consistent();

assert_eq!(result, Ok(U256::ONE));

Modules§

fixtures: Simple types to create basic unit tests for the crate::EvmRpcClient.

Structs§

CandidResponseConverter: Defines Candid response types.
ClientBuilder: A ClientBuilder to create a EvmRpcClient with custom configuration.
ClientConfig: Configuration for the EVM RPC canister client.
DoubleCycles: Retry strategy where the request is re-tried with double the cycles when it fails due to a ProviderError::TooFewCycles error.
EvmRpcClient: Client to interact with the EVM RPC canister.
IcRuntime: Runtime when interacting with a canister running on the Internet Computer.
NoRetry: Never perform any retries.
Request: A request which can be executed with EvmRpcClient::execute_request or EvmRpcClient::execute_query_request.
RequestBuilder: A builder to construct a Request.

Enums§

EvmRpcEndpoint: Endpoint on the EVM RPC canister triggering a call to EVM providers.
IcError: Error returned by the Internet Computer when making an inter-canister call.

Constants§

EVM_RPC_CANISTER: The principal identifying the productive EVM RPC canister under NNS control.

Traits§

EvmRpcConfig: Common behavior for the RPC config for EVM RPC canister endpoints.
RetryPolicy: Defines how and when requests made by EvmRpcClient should be retried.
Runtime: Abstract the canister runtime so that the client code can be reused: