EVM RPC

Interact with EVM blockchains from the Internet Computer.

Overview

EVM RPC is an Internet Computer canister smart contract for communicating with Ethereum and other EVM blockchains using an on-chain API.

This canister facilitates API requests to JSON-RPC services such as CloudFlare, Alchemy, Ankr, or BlockPI using HTTPS outcalls. This enables functionality similar to traditional Ethereum dapps, including querying Ethereum smart contract states and submitting raw transactions.

Beyond the Ethereum blockchain, this canister also has partial support for Polygon, Avalanche, and other popular EVM networks. Check out ChainList.org for an extensive list of networks and RPC providers.

You can read more about the inner workings of the EVM RPC canister here.

Documentation

You can find extensive documentation for the EVM RPC canister in the ICP developer docs.

Canister

The EVM RPC canister runs on the fiduciary subnet with the following principal: 7hfb6-caaaa-aaaar-qadga-cai.

Refer to the Reproducible Builds section for information on how to verify the hash of the deployed WebAssembly module.

Quick Start

Add the following to your dfx.json config file (replace the ic principal with any option from the list of available canisters above):

{
  "canisters": {
    "evm_rpc": {
      "type": "custom",
      "candid": "https://github.com/internet-computer-protocol/evm-rpc-canister/releases/latest/download/evm_rpc.did",
      "wasm": "https://github.com/internet-computer-protocol/evm-rpc-canister/releases/latest/download/evm_rpc.wasm.gz",
      "remote": {
        "id": {
          "ic": "7hfb6-caaaa-aaaar-qadga-cai"
        }
      },
      "init_arg": "(record {})"
    }
  }
}

Run the following commands to deploy the canister in your local environment:

# Start the local replica
dfx start --background

# Locally deploy the `evm_rpc` canister
dfx deploy evm_rpc --argument '(record {})'

The EVM RPC canister also supports dfx deps pull. Add the following to your dfx.json file:

{
  "canisters": {
    "evm_rpc": {
      "type": "pull",
      "id": "7hfb6-caaaa-aaaar-qadga-cai"
    }
  }
}

Next, run the following commands:

# Start the local replica
dfx start --background

# Locally deploy the `evm_rpc` canister
dfx deps pull
dfx deps init evm_rpc --argument '(record {})'
dfx deps deploy

Examples

JSON-RPC (IC mainnet)

dfx canister call evm_rpc request '(variant {Chain=0x1},"{\"jsonrpc\":\"2.0\",\"method\":\"eth_gasPrice\",\"params\":[],\"id\":1}",1000)' --wallet $(dfx identity get-wallet --ic) --with-cycles 1000000000 --ic

JSON-RPC (local replica)

# Use a custom provider
dfx canister call evm_rpc request '(variant {Custom=record {url="https://cloudflare-eth.com"}},"{\"jsonrpc\":\"2.0\",\"method\":\"eth_gasPrice\",\"params\":[],\"id\":1}",1000)' --wallet $(dfx identity get-wallet) --with-cycles 1000000000
dfx canister call evm_rpc request '(variant {Custom=record {url="https://ethereum.publicnode.com"}},"{\"jsonrpc\":\"2.0\",\"method\":\"eth_gasPrice\",\"params\":[],\"id\":1}",1000)' --wallet $(dfx identity get-wallet) --with-cycles 1000000000

# Register your own provider (requires `RegisterProvider` authorization)
dfx canister call evm_rpc registerProvider '(record { chainId=1; hostname="cloudflare-eth.com"; credentialPath="/v1/mainnet"; cyclesPerCall=0; cyclesPerMessageByte=0; })'

# Use a specific EVM chain
dfx canister call evm_rpc request '(variant {Chain=0x1},"{\"jsonrpc\":\"2.0\",\"method\":\"eth_gasPrice\",\"params\":[],\"id\":1}",1000)' --wallet $(dfx identity get-wallet) --with-cycles 1000000000

Authorization (local replica)

PRINCIPAL=$(dfx identity get-principal)
dfx canister call evm_rpc authorize "(principal \"$PRINCIPAL\", variant { RegisterProvider })"
dfx canister call evm_rpc getAuthorized '(variant { RegisterProvider })'
dfx canister call evm_rpc deauthorize "(principal \"$PRINCIPAL\", variant { RegisterProvider })"

Reproducible Builds

The EVM RPC canister supports reproducible builds:

Ensure Docker is installed on your machine.
Run scripts/docker-build in your terminal.
Run sha256sum evm_rpc.wasm.gz on the generated file to view the SHA-256 hash.

In order to verify the latest EVM RPC Wasm file, please make sure to download the corresponding version of the source code from the latest GitHub release.

Contributing

Contributions are welcome! Please check out the contributor guidelines for more information.

Run the following commands to set up a local development environment:

# Clone the repository and install dependencies
git clone https://github.com/internet-computer-protocol/evm-rpc-canister
cd evm-rpc-canister
npm install

# Deploy to the local replica
dfx start --background
npm run generate
dfx deploy evm_rpc

# Alternatively, deploy and run test suite
dfx start --background
scripts/e2e

Regenerate language bindings with the generate npm script:

npm run generate

Learn More

Candid interface

Related Projects

evm-rpc-canister-types: Rust types for interacting with the EVM RPC canister.
ic-evm-utils: A convenience crate for interacting with the EVM RPC Canister from canisters written in Rust.
chain-fusion-starter: starter template leveraging chain fusion technology to build EVM coprocessors on the Internet Computer Protocol.
Bitcoin canister: interact with the Bitcoin blockchain from the Internet Computer.
ckETH: a canister-issued Ether twin token on the Internet Computer.
ICP 🔗 ETH: a full-stack starter project for calling Ethereum smart contracts from an IC dapp.