Skip to main content

Setting up an EVM Gateway node

This guide is for running the EVM Gateway node on Flow. The EVM Gateway implements the Ethereum JSON-RPC specification and is the only node type which accepts EVM client connections.

The EVM Gateway is an unstaked, non-participating edge node which consumes Flow protocol state from the configured Flow Access Node and persists the indexed EVM state locally to service EVM client requests. It submits EVM transactions it receives into the Flow network, wrapped using a Cadence transaction, and mutating EVM state when executed. Non-mutating RPC methods only query the local state index of the gateway and are never forwarded to Access Nodes.

Who Should Run an EVM Gateway​

The EVM Gateway can serve as both a dedicated private RPC endpoint and a performance scaling solution, offering similar capabilities to centralized middleware providers like Infura, Alchemy, etc at a fraction of the cost. This is because EVM Gateway nodes connect directly to the Flow network with no middle layer in between.

Applications which generate high call volumes to the JSON-RPC and which may have hit rate limits can benefit from running their own gateway. Self-hosted gateways are dedicated to the operator, enabling the removal of rate limits. Self-hosted gateways connect directly to your chosen Access Node, which you can also run if desired.

Hardware specifications​

TBD

How To Run EVM Gateway

Step 1 - Account Creation​

The EVM Gateway's role in mediating EVM transactions over to Cadence is how it accrues fees from handling client transactions. Since the gateway submits Cadence transactions wrapping EVM transaction payloads to the Flow Access Node the transaction fee for that must be paid by the EVM Gateway.

The account used for funding gateway Cadence transactions must be a COA, not an EOA. --coa-address is configured with the Cadence address of the COA account and the --coa-key must belong to the same account. The --coinbase account accrues EVM Gateway fees from EVM client transactions and can be either an EVM EOA or COA address.

It is acceptable to create a single Cadence account for the COA and use the EVM address associated with that for the COINBASE address.

Create Flow account to use for COA​

If you don't already have a Flow account you will need to create one.

  1. Install Flow Wallet
  2. Once installed you will be able to copy the wallet address, similar to 0x1844efeb3fef2242
  3. Obtain account private key from 
    Settings -> Account List -> Choose Main account -> Private Key -> [Password prompt]
  4. Ensure the wallet is funded from a CEX or other wallet

Step 2 - Build the gateway​

To run EVM Gateway on bare metal or in a VM without the use of docker, select the 'Build from source' tab otherwise refer to the 'Build using Docker' tab.

This will build the EVM gateway binary from source.

For live networks we recommend using the latest release tag.


_10
git clone https://github.com/onflow/flow-evm-gateway.git
_10
_10
cd flow-evm-gateway
_10
git checkout $(curl -s https://api.github.com/repos/onflow/flow-evm-gateway/releases/latest | jq -r .tag_name)
_10
CGO_ENABLED=1 go build -o evm-gateway cmd/main/main.go
_10
chmod a+x evm-gateway
_10
mv evm-gateway /usr/bin

Step 3 - Start Your Node​

Operators will need to refer to the gateway configuration flags and make adjustments that align with the desired deployment topology.

EVM Coinbase address​

If this is your first time setting up the gateway we need to ensure that an EVM COA or EOA address is available to configure the COINBASE. This account can be an account created using Metamask or other web3.js wallet, or otherwise can be the EVM address corresponding to the Flow Wallet COA account created above.

If you haven't already got an EVM address and you have the COA account created by Flow Wallet above then follow the steps below:

  • Click top left burger icon to show current profile
  • Click 'Enable the path to EVM on Flow' button
  • Your EVM account will now be available to use in the left nav account view
  • When you switch to that account you can obtain its EVM address

COA Address and Key​

COA address and private key is configured for --coa-address & --coa-key configuration flags. If running multiple EVM Gateway hosts it is standard to share the same COA address and key across n hosts.

Run the gateway​

Ensure that the following ENV variables have been set. Add/update as required if your configuration differs from those listed.


_10
# Set required environment variables
_10
export ACCESS_NODE_GRPC_HOST="access.mainnet.nodes.onflow.org:9000"
_10
export FLOW_NETWORK_ID="flow-mainnet" # or flow-testnet
_10
export INIT_CADENCE_HEIGHT="88226267" # 211176670 for testnet
_10
export COINBASE="${EVM_ADDRESS_WITHOUT_0x}"
_10
export COA_ADDRESS="${CADENCE_ACCOUNT_ADDRESS_WITHOUT_0x}"
_10
export COA_KEY="${CADENCE_ACCOUNT_PRIVATE_KEY_WITHOUT_0x}"
_10
export GAS_PRICE="100"

Create EVM Gateway service


_28
sudo tee <<EOF >/dev/null /etc/systemd/system/gateway.service
_28
[Unit]
_28
Description=Gateway daemon
_28
After=network-online.target
_28
_28
[Service]
_28
User=$USER
_28
ExecStart=/usr/bin/evm-gateway \
_28
--access-node-grpc-host=$ACCESS_NODE_GRPC_HOST \
_28
--flow-network-id=$FLOW_NETWORK_ID \
_28
--init-cadence-height=$INIT_CADENCE_HEIGHT \
_28
--ws-enabled=true \
_28
--coinbase=$COINBASE \
_28
--coa-address=$COA_ADDRESS \
_28
--coa-key=$COA_KEY \
_28
--rate-limit=9999999 \
_28
--rpc-host=0.0.0.0 \
_28
--gas-price=$GAS_PRICE
_28
Restart=always
_28
RestartSec=3
_28
LimitNOFILE=4096
_28
_28
[Install]
_28
WantedBy=multi-user.target
_28
EOF
_28
_28
cat /etc/systemd/system/gateway.service
_28
sudo systemctl enable gateway

Startup bootstrap indexing​

Once your EVM Gateway is up and running you will see it indexing the EVM on Flow network which was configured. At the present time this is a lengthy process (possible 1-3 days, depending on CPU core count) during which time the gateway will not respond to queries. Once the data is fully indexed the gateway can serve requests to clients.

To speed up gateway setup we recommend backing up the /flow-evm-gateway/data directory to use when creating additional nodes using the same release version. We are currently working on an export/import feature that will enable gateway operators to store state snapshots which can be used to bootstrap the creation of new nodes and mitigate the slow startup time.

Account and Key Management​

EVM Gateway allows for Google and AWS Key Management Service (KMS) setup, which is the recommended way of setting up the gateway for live networks. We recommend creating multiple KMS keys for the same Flow account (ideally 10 or more), how many depends on the desired transaction throughput, since the keys are used in rotation when submitting the transactions. If too few keys are configured it may result in sequence number collisions if the same key is used concurrently by multiple EVM client requests.

KMS Configuration​


_10
--coa-cloud-kms-project-id=your-project-kms-id \
_10
--coa-cloud-kms-location-id=global \
_10
--coa-cloud-kms-key-ring-id=your-project-kms-key-ring-id \
_10
--coa-cloud-kms-keys=example-gcp-kms1@1,example-gcp-kms2@1 \

Monitoring and Metrics​

The EVM Gateway reports Prometheus metrics which are a way to monitor the gateway's availability and progress. The database folder size may also need to be monitored to prevent disk full issues.

Metric labels


_12
evm_gateway_api_errors_total # Total count of API errors for period
_12
evm_gateway_api_request_duration_seconds_bucket # Histogram metric buckets for API request durations
_12
evm_gateway_api_request_duration_seconds_count # Histogram metric API request count for period
_12
evm_gateway_api_request_duration_seconds_sum # Histogram metric API request sum of values for period
_12
evm_gateway_api_server_panics_total # Total count of server panics for period
_12
evm_gateway_blocks_indexed_total # Total count of EVM blocks indexed
_12
evm_gateway_cadence_block_height # Cadence block height
_12
evm_gateway_evm_account_interactions_total # Count of unique accounts observed for period
_12
evm_gateway_evm_block_height # EVM block height
_12
evm_gateway_operator_balance # Gateway node COA operator account balance
_12
evm_gateway_trace_download_errors_total # Total count of trace download errors
_12
evm_gateway_txs_indexed_total # Total count of indexed transactions

Alerts are recommended to be configured on server panics, low operator balance, and disk usage metrics.

Configuration​


_10
--metrics-port 8080 \

Node Status​

For basic node status or keepalive monitoring we recommend automated checks on the following monotonically increasing counter:


_10
curl -s -XPOST 'your-evm-gw-host:8545' --header 'Content-Type: application/json' --data-raw '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' | jq -r '.result' | xargs printf "%d\n"
_10
10020239

Troubleshooting​

FAQs​