Skip to content

Commit

Permalink
Merge pull request #3641 from dfinity/gdemay/update-evm-rpc-docs
Browse files Browse the repository at this point in the history 
docs: update outdated docs for EVM RPC v2
  • Loading branch information
@gregorydemay
gregorydemay authored Oct 23, 2024
2 parents d709cba + c34263b commit 6363baf
Show file tree
Hide file tree
Showing 3 changed files with 33 additions and 67 deletions.
77 changes: 20 additions & 57 deletions docs/developer-docs/multi-chain/ethereum/evm-rpc/evm-rpc-canister.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ The following JSON-RPC methods are available as part of the canister's [Candid i
- [`eth_getTransactionCount`](https://docs.alchemy.com/reference/eth-gettransactioncount): Queries the number of transactions for a specified address.
- [`eth_getTransactionReceipt`](https://docs.alchemy.com/reference/eth-gettransactionreceipt): Queries details about a submitted transaction.
- [`eth_sendRawTransaction`](https://docs.alchemy.com/reference/eth-sendrawtransaction): Submits a signed transaction to the Ethereum network.
- [`eth_call`](https://docs.alchemy.com/reference/eth-call): Query the state of a smart contract.

Other RPC methods, including those specific to non-Ethereum networks, may be accessed using the canister's `request` method.

Expand All @@ -33,6 +34,7 @@ The EVM RPC canister has built-in support for the following [Ethereum JSON-RPC p
- [BlockPI](https://blockpi.io/): Ethereum mainnet, Sepolia testnet, L2 chains.
- [Cloudflare Web3](https://www.cloudflare.com/application-services/products/web3/): Ethereum mainnet.
- [Public Node](https://www.publicnode.com/): Ethereum mainnet, Sepolia testnet, L2 chains.
- [LlamaNodes](https://llamanodes.com/): Ethereum mainnet, Sepolia testnet, L2 chains.

Many of the providers on [ChainList.org](https://chainlist.org/) can be called using the canister's `request` method.

Expand Down Expand Up @@ -61,7 +63,7 @@ dfx start --background
# Locally deploy the `evm_rpc` canister
dfx deps pull
dfx deps init evm_rpc --argument '(record { nodesInSubnet = 31 })'
dfx deps init evm_rpc --argument '(record {})'
dfx deps deploy
```

Expand Down Expand Up @@ -90,7 +92,7 @@ Then start the local replica and deploy the canister locally with a specified nu

```
dfx start --clean --background
dfx deploy evm_rpc --argument '(record { nodesInSubnet = 31 })'
dfx deploy evm_rpc --argument '(record {})'
```

### Fork the EVM RPC canister
Expand All @@ -104,7 +106,7 @@ git clone https://github.com/internet-computer-protocol/evm-rpc-canister
To deploy your own canister on the mainnet, run the `dfx deploy` command with the `--network ic` flag:

```
dfx deploy evm_rpc --network ic --argument '(record { nodesInSubnet = 31 })'
dfx deploy evm_rpc --network ic --argument '(record {})'
```

Note that when deploying your own canister, you may encounter API rate limits. Refer to the [replacing API keys](#replacing-api-keys) section to learn how to configure API credentials.
Expand Down Expand Up @@ -938,15 +940,6 @@ dfx canister call evm_rpc --wallet $(dfx identity get-wallet) --with-cycles 1000
</TabItem>
</AdornedTabs>

## Authorization (local replica)

```bash
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 })"
```

## Specifying RPC services

`RpcServices` is used to specify which HTTPS outcall APIs to use in the request. There are several ways to use specific JSON-RPC services:
Expand Down Expand Up @@ -979,30 +972,10 @@ type RpcService = variant {
};
```

## Registering your own provider

To register your own RPC provider in your local replica, you can use the following commands:

```bash
# Authorize your dfx identity to add an RPC provider
OWNER_PRINCIPAL=$(dfx identity get-principal)
dfx canister call evm_rpc authorize "(principal \"$OWNER_PRINCIPAL\", variant { RegisterProvider })"

# Register a provider
dfx canister call evm_rpc registerProvider '(record { chainId=1; hostname="cloudflare-eth.com"; credentialPath="/v1/mainnet"; cyclesPerCall=1000; cyclesPerMessageByte=100; })'
```

The `registerProvider` command has the following input parameters:

- `chainId`: The ID of the blockchain network.
- `hostname`: The JSON-RPC API hostname.
- `credentialPath`: The path to the RPC authentication.
- `cyclesPerCall`: The amount of cycles charged per RPC call.
- `cyclesPerMessageByte`: The amount of cycles charged per message byte.

## Replacing API keys

If you want to add or change the API key in your local replica or a deployed fork of the canister, the first step is to determine the relevant `providerId` for the API.
If you are a controller or a principal autorized to manage API keys (given upon canister initialization in the `manageApiKeys` field), you can replace the API keys used by the EVM RPC canister.
The first step is to determine the relevant `providerId` that identifies a supported JSON RPC provider.

Run the following command to view all registered providers:

Expand All @@ -1013,33 +986,23 @@ dfx canister call evm_rpc getProviders
You should see a list of values. Look for the `providerId`, which in this case is `0`:

```
(
vec {
record {
cyclesPerCall = 0 : nat64;
owner = principal "k3uua-wskan-xmpt3-e5bpx-ibj67-azbop-s26l5-kaakn-64bvk-y4jlc-oqe";
hostname = "cloudflare-eth.com";
primary = false;
chainId = 1 : nat64;
cyclesPerMessageByte = 0 : nat64;
providerId = 0 : nat64;
};
}
)
```

Update the configuration for an existing provider using the `updateProvider` method:

```bash
dfx canister call evm_rpc updateProvider '(record { providerId = 0; credentialPath = opt "/path/to/YOUR-API-KEY" })'
record {
access = variant {
Authenticated = record {
publicUrl = opt "https://cloudflare-eth.com/v1/mainnet";
auth = variant { BearerToken = record { url = "https://cloudflare-eth.com/v1/mainnet";} };
}
};
alias = opt variant { EthMainnet = variant { Cloudflare } };
chainId = 1 : nat64;
providerId = 0 : nat64;
};
```

Note that `credentialPath` should include everything after the hostname. For example, an RPC provider with hostname `rpc.example.org` and credential path `/path/to/secret` will resolve to `https://rpc.example.org/path/to/secret`.

Some RPC services expect the API key in a request header instead of a URI path. In this case, use a command such as the following:
Update the configuration for an existing provider using the `updateApiKeys` method:

```bash
dfx canister call evm_rpc updateProvider '(record { providerId = 0; credentialHeaders = opt vec { record { name = "HEADER_NAME"; value = "HEADER_VALUE" } } })'
dfx canister call evm_rpc updateApiKeys '(vec { record { 0 : nat64; opt "YOUR-API-KEY" } } )'
```

## Error messages
Expand Down
2 changes: 1 addition & 1 deletion docs/developer-docs/multi-chain/ethereum/evm-rpc/how-it-works.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ By default for Candid-RPC methods such as `eth_getTransactionReceipt`, the EVM R

## Authentication

Each call to a JSON-RPC endpoint requires an API key to authenticate with the RPC provider. The EVM RPC canister manages these keys on behalf of the developer, but a developer's personal keys may be passed to the call instead if desired. API keys typically have a subscription fee associated with them, but developers who use the EVM RPC canister's pre-configured keys do not need to subscribe to the RPC services themselves.
Certain JSON-RPC endpoints require an API key to authenticate with the RPC provider. The EVM RPC canister is already configured with the required API keys, although a developer can still choose to use custom providers (with or without API keys) to make the call instead if desired. API keys typically have a subscription fee associated with them, but developers who use the EVM RPC canister's pre-configured keys do not need to subscribe to the RPC services themselves.

When not using API keys, developers should be mindful of:

Expand Down
21 changes: 12 additions & 9 deletions docs/developer-docs/multi-chain/ethereum/evm-rpc/overview.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";

- Submitting a signed transaction.

- Querying the state of a smart contract.

To use the EVM RPC canister, you can send requests to the [instance deployed on the mainnet](https://dashboard.internetcomputer.org/canister/7hfb6-caaaa-aaaar-qadga-cai), or you can fork the source code and deploy your own instance of the canister.

The source code for this project is available on GitHub ([internet-computer-protocol/evm-rpc-canister](https://github.com/internet-computer-protocol/evm-rpc-canister) ⭐️) under the Apache 2.0 license.
Expand All @@ -45,13 +47,14 @@ Below is a list of terms used to describe different aspects of using the EVM RPC
## Supported JSON-RPC providers


| | Ethereum Mainnet | Arbitrum One | Base Mainnet | Optimism Mainnet |
|------------------|------------------|--------------|--------------|------------------|
| Alchemy | ✅ | ✅ | ✅ | ✅ |
| Ankr | ✅ | ✅ | ✅ | ✅ |
| BlockPi | ✅ | ✅ | ✅ | ✅ |
| Cloudflare | ✅ | | | |
| PublicNode | ✅ | ✅ | ✅ | ✅ |
| | Ethereum Mainnet | Arbitrum One | Base Mainnet | Optimism Mainnet |
|------------|------------------|--------------|--------------|------------------|
| Alchemy | ✅ | ✅ | ✅ | ✅ |
| Ankr | ✅ | ✅ | ✅ | ✅ |
| BlockPi | ✅ | ✅ | ✅ | ✅ |
| Cloudflare | ✅ | | | |
| LlamaNodes | ✅ | ✅ | ✅ | ✅ |
| PublicNode | ✅ | ✅ | ✅ | ✅ |

## Management of API keys

Expand All @@ -65,7 +68,7 @@ RPC providers often require API keys be used to authenticate RPC requests. Authe

- Storing API keys securely is not supported at the platform level and requires developers to use their own strategies for protecting their keys, creating an additional complexity for developers who want to use reproducible builds. Personal keys are also visible to all nodes on the ICP subnet. [Learn more about authentication](how-it-works.mdx#authentication).

To provide a solution for developers, the production EVM RPC manages the API keys for each RPC provider on behalf of the developer. If a developer wants to use their own API keys, however, they can [pass their own keys](evm-rpc-canister.mdx#replacing-api-keys) to the EVM RPC canister. Test variations of the EVM RPC canister do not use API keys.
To provide a solution for developers, the production EVM RPC canister is configured with the required API keys. If a developer wants to use their own providers with their own API keys, however, they can [pass their own keys](evm-rpc-canister.mdx#replacing-api-keys) to the EVM RPC canister. Test variations of the EVM RPC canister do not use API keys.

## Costs

Expand All @@ -75,7 +78,7 @@ Learn more about the [costs of EVM RPC requests](costs.mdx).

## Deployed canister

The EVM RPC canister runs on the 31-node [fiduciary subnet](https://internetcomputer.org/docs/current/concepts/subnet-types#fiduciary-subnets) with the following principal: [`7hfb6-caaaa-aaaar-qadga-cai`](https://dashboard.internetcomputer.org/canister/7hfb6-caaaa-aaaar-qadga-cai).
The EVM RPC canister runs on the 34-node [fiduciary subnet](https://internetcomputer.org/docs/current/concepts/subnet-types#fiduciary-subnets) with the following principal: [`7hfb6-caaaa-aaaar-qadga-cai`](https://dashboard.internetcomputer.org/canister/7hfb6-caaaa-aaaar-qadga-cai).

Refer to the [GitHub repository](https://github.com/internet-computer-protocol/evm-rpc-canister?tab=readme-ov-file#reproducible-builds) for information on how to verify the hash of the deployed WebAssembly module.

Expand Down

0 comments on commit 6363baf

Please sign in to comment.