feat: add EVM RPC canister client

Cargo.toml

@@ -50,7 +50,7 @@ zeroize = { version = "1.8", features = ["zeroize_derive"] }
 regex = "1.11"
 
 [dev-dependencies]
-assert_matches = "1.5"
+assert_matches = { workspace = true }
 candid_parser = { workspace = true }
 ic-crypto-test-utils-reproducible-rng = { git = "https://github.com/dfinity/ic", rev = "release-2024-09-26_01-31-base" }
 ic-management-canister-types = { workspace = true }
@@ -61,7 +61,10 @@ proptest = { workspace = true }
 rand = "0.8"
 
 [workspace.dependencies]
+alloy-primitives = "1.3.0"
+alloy-rpc-types = "1.0.23"
 assert_matches = "1.5.0"
+async-trait = "0.1.88"
 candid = { version = "0.10.13" }
 canlog = { version = "0.2.0", features = ["derive"] }
 candid_parser = { version = "0.1.4" }
@@ -103,4 +106,4 @@ thiserror = "2.0.12"
 url = "2.5"
 
 [workspace]
-members = ["e2e/rust", "evm_rpc_types"]
+members = ["e2e/rust", "evm_rpc_types", "evm_rpc_client"]

evm_rpc_client/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]

evm_rpc_client/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "evm_rpc_client"
+version = "1.4.0"
+description = "Rust client for interacting with the EVM RPC canister"
+license = "Apache-2.0"
+readme = "README.md"
+authors = ["DFINITY Foundation"]
+edition = "2021"
+include = ["src", "Cargo.toml", "CHANGELOG.md", "LICENSE", "README.md"]
+repository = "https://github.com/dfinity/evm-rpc-canister"
+documentation = "https://docs.rs/evm_rpc_client"
+
+[dependencies]
+alloy-primitives = { workspace = true }
+alloy-rpc-types = { workspace = true }
+async-trait = { workspace = true }
+candid = { workspace = true }
+evm_rpc_types = { path = "../evm_rpc_types", features = ["alloy"] }
+ic-cdk = { workspace = true }
+ic-error-types = { workspace = true }
+serde = { workspace = true }
+strum = { workspace = true }
+
+[dev-dependencies]
+tokio = { workspace = true, features = ["full"] }

evm_rpc_client/LICENSE

@@ -0,0 +1 @@
+../LICENSE

evm_rpc_client/NOTICE

@@ -0,0 +1 @@
+../NOTICE

evm_rpc_client/README.md

@@ -0,0 +1,3 @@
+# EVM RPC Client
+
+This crate defines a client for interacting with the EVM RPC canister.

evm_rpc_client/src/fixtures/mod.rs

@@ -0,0 +1,132 @@
+//! Simple types to create basic unit tests for the [`crate::EvmRpcClient`].
+//!
+//! Types and methods for this module are only available for non-canister architecture (non `wasm32`).
+
+use crate::{ClientBuilder, Runtime};
+use async_trait::async_trait;
+use candid::{utils::ArgumentEncoder, CandidType, Decode, Encode, Principal};
+use ic_error_types::RejectCode;
+use serde::de::DeserializeOwned;
+use std::collections::BTreeMap;
+
+impl<R> ClientBuilder<R> {
+    /// Set the runtime to a [`StubRuntime`].
+    pub fn with_stub_responses(self) -> ClientBuilder<StubRuntime> {
+        self.with_runtime(|_runtime| StubRuntime::default())
+    }
+
+    /// Change the runtime to return the given stub response for all calls.
+    pub fn with_default_stub_response<Out: CandidType>(
+        self,
+        stub_response: Out,
+    ) -> ClientBuilder<StubRuntime> {
+        self.with_stub_responses()
+            .with_default_response(stub_response)
+    }
+}
+
+impl ClientBuilder<StubRuntime> {
+    /// Change the runtime to return the given stub response for all calls.
+    pub fn with_default_response<Out: CandidType>(
+        self,
+        stub_response: Out,
+    ) -> ClientBuilder<StubRuntime> {
+        self.with_runtime(|runtime| runtime.with_default_response(stub_response))
+    }
+
+    /// Change the runtime to return the given stub response for calls to the given method.
+    pub fn with_response_for_method<Out: CandidType>(
+        self,
+        method_name: &str,
+        stub_response: Out,
+    ) -> ClientBuilder<StubRuntime> {
+        self.with_runtime(|runtime| runtime.with_response_for_method(method_name, stub_response))
+    }
+}
+
+/// An implementation of [`Runtime`] that always returns the same candid-encoded response
+/// for a given method.
+///
+/// Implement your own [`Runtime`] in case a more refined approach is needed.
+pub struct StubRuntime {
+    default_call_result: Option<Vec<u8>>,
+    method_to_call_result_map: BTreeMap<String, Vec<u8>>,
+}
+
+impl StubRuntime {
+    /// Create a new [`StubRuntime`] with the given default stub response.
+    pub fn new() -> Self {
+        Self {
+            default_call_result: None,
+            method_to_call_result_map: BTreeMap::new(),
+        }
+    }
+
+    /// Create a new [`StubRuntime`] with the given default stub response.
+    pub fn with_default_response<Out: CandidType>(mut self, stub_response: Out) -> Self {
+        let result = Encode!(&stub_response).expect("Failed to encode Candid stub response");
+        self.default_call_result = Some(result);
+        self
+    }
+
+    /// Modify a [`StubRuntime`] to return the given response for the given method
+    pub fn with_response_for_method<Out: CandidType>(
+        mut self,
+        method: &str,
+        stub_response: Out,
+    ) -> Self {
+        self.method_to_call_result_map.insert(
+            method.to_string(),
+            Encode!(&stub_response).expect("Failed to encode Candid stub response"),
+        );
+        self
+    }
+
+    fn call<Out>(&self, method: &str) -> Result<Out, (RejectCode, String)>
+    where
+        Out: CandidType + DeserializeOwned,
+    {
+        let bytes = self
+            .method_to_call_result_map
+            .get(method)
+            .or(self.default_call_result.as_ref())
+            .unwrap_or_else(|| panic!("No available call response value for method `{method}`"));
+        Ok(Decode!(bytes, Out).expect("Failed to decode Candid stub response"))
+    }
+}
+
+impl Default for StubRuntime {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[async_trait]
+impl Runtime for StubRuntime {
+    async fn update_call<In, Out>(
+        &self,
+        _id: Principal,
+        method: &str,
+        _args: In,
+        _cycles: u128,
+    ) -> Result<Out, (RejectCode, String)>
+    where
+        In: ArgumentEncoder + Send,
+        Out: CandidType + DeserializeOwned,
+    {
+        self.call(method)
+    }
+
+    async fn query_call<In, Out>(
+        &self,
+        _id: Principal,
+        method: &str,
+        _args: In,
+    ) -> Result<Out, (RejectCode, String)>
+    where
+        In: ArgumentEncoder + Send,
+        Out: CandidType + DeserializeOwned,
+    {
+        self.call(method)
+    }
+}