From 1c2c8552efaeff5eaa5af0a2867d191e7a5a7b0a Mon Sep 17 00:00:00 2001 From: Jerome P Date: Tue, 10 Dec 2024 12:01:16 -0800 Subject: [PATCH 01/28] Add EVm Gateway node ops section and mainpage --- docs/evm/using.mdx | 12 +- docs/networks/flow-networks/index.md | 6 + .../evm-gateway/_category_.yml | 1 + .../evm-gateway/evm-gateway-setup.md | 263 ++++++++++++++++++ 4 files changed, 276 insertions(+), 6 deletions(-) create mode 100644 docs/networks/node-ops/access-onchain-data/evm-gateway/_category_.yml create mode 100644 docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md diff --git a/docs/evm/using.mdx b/docs/evm/using.mdx index e22f53eabf..db2e322187 100644 --- a/docs/evm/using.mdx +++ b/docs/evm/using.mdx @@ -96,7 +96,7 @@ To use the Flow Wallet Chrome extension: | [eth_getBlockByNumber] | ✅ | | [eth_getBlockTransactionCountByHash] | ✅ | | [eth_getBlockTransactionCountByNumber] | ✅ | -| eth_getBlockReceipts | ✅ | +| [eth_getBlockReceipts] | ✅ | | [eth_getCode] | ✅ | | [eth_getFilterChanges] | ✅ | | [eth_getFilterLogs] | ✅ | @@ -121,11 +121,11 @@ To use the Flow Wallet Chrome extension: | [eth_signTransaction] | 🚧 | Unsupported | | [eth_syncing] | ✅ | | [eth_uninstallFilter] | ✅ | -| eth_maxPriorityFeePerGas | ✅ | -| eth_feeHistory | ✅ | -| debug_traceTransaction | ✅ | -| debug_traceBlockByNumber | ✅ | -| debug_traceBlockByHash | ✅ | +| [eth_maxPriorityFeePerGas] | ✅ | +| [eth_feeHistory] | ✅ | +| [debug_traceTransaction] | ✅ | +| [debug_traceBlockByNumber] | ✅ | +| [debug_traceBlockByHash] | ✅ | **Legend**: ❌ = not supported. 🚧 = work in progress. ✅ = supported. diff --git a/docs/networks/flow-networks/index.md b/docs/networks/flow-networks/index.md index 9fa7028196..793f810551 100644 --- a/docs/networks/flow-networks/index.md +++ b/docs/networks/flow-networks/index.md @@ -5,6 +5,12 @@ sidebar_position: 1 ## About Flow Networks +:::note + +This page provides information on Flow networks RPCs. EVM on Flow network RPCs can be found [here](../evm/networks) + +::: + In addition to Mainnet, developers have access to the Testnet environment, which serves as an essential testing ground for applications and smart contracts prior to their deployment on Mainnet. This ensures that any potential issues can be identified and resolved in a controlled setting, mitigating risks associated with live deployment. Furthermore, during network upgrades, Testnet receives updates ahead of Mainnet. This preemptive update process allows developers to comprehensively test their apps against the latest versions of the nodes, enhancements to the Cadence programming language, and core contract upgrades. This strategy guarantees that when these updates are eventually applied to Mainnet, applications and smart contracts will operate seamlessly, enhancing overall network stability and user experience. diff --git a/docs/networks/node-ops/access-onchain-data/evm-gateway/_category_.yml b/docs/networks/node-ops/access-onchain-data/evm-gateway/_category_.yml new file mode 100644 index 0000000000..a2d462075f --- /dev/null +++ b/docs/networks/node-ops/access-onchain-data/evm-gateway/_category_.yml @@ -0,0 +1 @@ +label: EVM Gateway Nodes diff --git a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md new file mode 100644 index 0000000000..12d3e56fa1 --- /dev/null +++ b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md @@ -0,0 +1,263 @@ +--- +title: Setting up an EVM Gateway node +sidebar_label: EVM Gateway Setup +sidebar_position: 2 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +This guide is for running the [EVM Gateway](https://github.com/onflow/flow-evm-gateway) node on Flow. The EVM Gateway implements the +[Ethereum JSON-RPC specification](https://ethereum.org/en/developers/docs/apis/json-rpc/) 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](https://wallet.flow.com/) + 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 + + + + +```bash +flow keys generate +``` + +This will output something similar to: + +```bash +🔴️ Store private key safely and don't share with anyone! +Private Key 3cf8334d.....95c3c54a28e4ad1 +Public Key 33a13ade6....85f1b49a197747 +Mnemonic often scare peanut ... boil corn change +Derivation Path m/44'/539'/0'/0/0 +Signature Algorithm ECDSA_P256 +``` + +Visit https://faucet.flow.com/, and use the generated `Public Key`, to create and fund your Flow testnet account. + + + + +## 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](https://github.com/onflow/flow-evm-gateway/releases/latest) tag. +```bash +git clone https://github.com/onflow/flow-evm-gateway.git + +cd flow-evm-gateway +git checkout $(curl -s https://api.github.com/repos/onflow/flow-evm-gateway/releases/latest | jq -r .tag_name) +CGO_ENABLED=1 go build -o evm-gateway cmd/main/main.go +``` + + + + +```bash +git clone https://github.com/onflow/flow-evm-gateway.git + +cd flow-evm-gateway +git checkout $(curl -s https://api.github.com/repos/onflow/flow-evm-gateway/releases/latest | jq -r .tag_name) +make docker-build +``` + + + + +## Step 3 - Start Your Node + +Operators will need to refer to the gateway [configuration flags](https://github.com/onflow/flow-evm-gateway?tab=readme-ov-file#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 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. + +```bash +# Set required environment variables +export ACCESS_NODE_GRPC_HOST="access.mainnet.nodes.onflow.org:9000" +export FLOW_NETWORK_ID="flow-mainnet" # or flow-testnet +export INIT_CADENCE_HEIGHT="88226267" # 211176670 for testnet +export COINBASE="${EVM_ADDRESS_WITHOUT_0x}" +export COA_ADDRESS="${CADENCE_ACCOUNT_ADDRESS_WITHOUT_0x}" +export COA_KEY="${CADENCE_ACCOUNT_PRIVATE_KEY_WITHOUT_0x}" +export GAS_PRICE="100" +``` + + + + +Create EVM Gateway service + +```bash +sudo tee </dev/null /etc/systemd/system/gateway.service +[Unit] +Description=Gateway daemon +After=network-online.target + +[Service] +User=$USER +ExecStart=/usr/bin/evm-gateway \ +--access-node-grpc-host=$ACCESS_NODE_GRPC_HOST \ +--flow-network-id=$FLOW_NETWORK_ID \ +--init-cadence-height=$INIT_CADENCE_HEIGHT \ +--ws-enabled=true \ +--coinbase=$COINBASE \ +--coa-address=$COA_ADDRESS \ +--coa-key=$COA_KEY \ +--rate-limit=9999999 \ +--rpc-host=0.0.0.0 \ +--gas-price=$GAS_PRICE +Restart=always +RestartSec=3 +LimitNOFILE=4096 + +[Install] +WantedBy=multi-user.target +EOF + +cat /etc/systemd/system/gateway.service +sudo systemctl enable gateway +``` + + + + +It may be necessary to make local changes to the `docker-run` target to add params which are needed for your requirements. + +```bash +cd flow-evm-gateway +make docker-run +``` + + + + +## 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 +``` +--coa-cloud-kms-project-id=your-project-kms-id \ +--coa-cloud-kms-location-id=global \ +--coa-cloud-kms-key-ring-id=your-project-kms-key-ring-id \ +--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** +```bash +evm_gateway_api_errors_total # Total count of API errors for period +evm_gateway_api_request_duration_seconds_bucket # Histogram metric buckets for API request durations +evm_gateway_api_request_duration_seconds_count # Histogram metric API request count for period +evm_gateway_api_request_duration_seconds_sum # Histogram metric API request sum of values for period +evm_gateway_api_server_panics_total # Total count of server panics for period +evm_gateway_blocks_indexed_total # Total count of EVM blocks indexed +evm_gateway_cadence_block_height # Cadence block height +evm_gateway_evm_account_interactions_total # Count of unique accounts observed for period +evm_gateway_evm_block_height # EVM block height +evm_gateway_operator_balance # Gateway node COA operator account balance +evm_gateway_trace_download_errors_total # Total count of trace download errors +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 +``` +--metrics-port 8080 \ +``` +### Node Status + +For basic node status or keepalive monitoring we recommend automated checks on the following monotonically increasing counter: +``` +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" +10020239 +``` + +## Troubleshooting + +## FAQs + From 05015b976d88f67f7c47f5744bddad2921363144 Mon Sep 17 00:00:00 2001 From: Jerome P Date: Tue, 10 Dec 2024 13:25:56 -0800 Subject: [PATCH 02/28] Add optional docker run args --- .../evm-gateway/evm-gateway-setup.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md index 12d3e56fa1..10a509b4a4 100644 --- a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md +++ b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md @@ -193,6 +193,17 @@ It may be necessary to make local changes to the `docker-run` target to add para cd flow-evm-gateway make docker-run ``` +Additional options are available as follows + +```bash +DOCKER_RUN_DETACHED=true +DOCKER_HOST_MOUNT=[host mount directory] +DOCKER_HOST_PORT=[desired port to expose on host] + +# Example usage + +make DOCKER_RUN_DETACHED=true DOCKER_HOST_PORT=1234 DOCKER_HOST_MOUNT=/my/host/dir docker-run +``` From b4860f1cf8c1944019c4b7689fedde60d3f9b1fb Mon Sep 17 00:00:00 2001 From: j pimmel Date: Tue, 10 Dec 2024 13:28:58 -0800 Subject: [PATCH 03/28] Typo --- docs/networks/flow-networks/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/networks/flow-networks/index.md b/docs/networks/flow-networks/index.md index 793f810551..910cab5fa5 100644 --- a/docs/networks/flow-networks/index.md +++ b/docs/networks/flow-networks/index.md @@ -7,7 +7,7 @@ sidebar_position: 1 :::note -This page provides information on Flow networks RPCs. EVM on Flow network RPCs can be found [here](../evm/networks) +This page provides information on Flow network RPCs. EVM on Flow network RPCs can be found [here](../evm/networks) ::: From 5a09a55e89009c79a3d9b6d7c27edbd0d95244b7 Mon Sep 17 00:00:00 2001 From: Jerome P Date: Tue, 10 Dec 2024 13:47:18 -0800 Subject: [PATCH 04/28] Added missing guidance on how to get private key for COA_KEY --- .../access-onchain-data/evm-gateway/evm-gateway-setup.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md index 10a509b4a4..f8e317e170 100644 --- a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md +++ b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md @@ -130,9 +130,14 @@ If you haven't already got an EVM address and you have the COA account created b * 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 private key is configured for `--coa-address` & `--coa-key` configuration flags. If running multiple EVM Gateway hosts it is standard to +## 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. +To obtain the private key from your wallet account ensure you are in the Cadence account then: + 
Settings -> Account List -> Choose Main account -> Private Key -> [Password prompt]
+ ## Run the gateway Ensure that the following ENV variables have been set. Add/update as required if your configuration differs from those listed. From 24ef40f933be3e62c8117e1e55b68cf100aa33fe Mon Sep 17 00:00:00 2001 From: Jerome P Date: Tue, 10 Dec 2024 13:51:25 -0800 Subject: [PATCH 05/28] Move binary to executable location for systemctl config --- .../access-onchain-data/evm-gateway/evm-gateway-setup.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md index f8e317e170..e7350065a4 100644 --- a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md +++ b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md @@ -97,6 +97,8 @@ git clone https://github.com/onflow/flow-evm-gateway.git cd flow-evm-gateway git checkout $(curl -s https://api.github.com/repos/onflow/flow-evm-gateway/releases/latest | jq -r .tag_name) CGO_ENABLED=1 go build -o evm-gateway cmd/main/main.go +chmod a+x evm-gateway +mv evm-gateway /usr/bin ``` From c6704ba95f729b9163e10f1a01c59675d58d4937 Mon Sep 17 00:00:00 2001 From: Jerome P Date: Tue, 10 Dec 2024 14:03:57 -0800 Subject: [PATCH 06/28] Drop duplicate mention of private key extraction --- .../access-onchain-data/evm-gateway/evm-gateway-setup.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md index e7350065a4..4a3d207d41 100644 --- a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md +++ b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md @@ -117,8 +117,8 @@ make docker-build ## Step 3 - Start Your Node -Operators will need to refer to the gateway [configuration flags](https://github.com/onflow/flow-evm-gateway?tab=readme-ov-file#configuration-flags) and make -adjustments that align with the desired deployment topology. +Operators will need to refer to the gateway [configuration flags](https://github.com/onflow/flow-evm-gateway?tab=readme-ov-file#configuration-flags) and make adjustments that align with the desired +deployment topology. ### EVM Coinbase address @@ -137,9 +137,6 @@ If you haven't already got an EVM address and you have the COA account created b 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. -To obtain the private key from your wallet account ensure you are in the Cadence account then: - 
Settings -> Account List -> Choose Main account -> Private Key -> [Password prompt]
- ## Run the gateway Ensure that the following ENV variables have been set. Add/update as required if your configuration differs from those listed. From 8b084947cfad755fed49c99abe3403e77f56df41 Mon Sep 17 00:00:00 2001 From: Jerome P Date: Tue, 10 Dec 2024 14:07:19 -0800 Subject: [PATCH 07/28] Fix title size --- .../access-onchain-data/evm-gateway/evm-gateway-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md index 4a3d207d41..7f6fea3e32 100644 --- a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md +++ b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md @@ -132,7 +132,7 @@ If you haven't already got an EVM address and you have the COA account created b * 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 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. From 9d9f5cb73e3a61e551575e4dc43e49a6f2dde9b3 Mon Sep 17 00:00:00 2001 From: Jerome P Date: Tue, 10 Dec 2024 14:10:04 -0800 Subject: [PATCH 08/28] Tweak navbar position and title --- .../node-ops/access-onchain-data/evm-gateway/_category_.yml | 2 +- .../access-onchain-data/evm-gateway/evm-gateway-setup.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/networks/node-ops/access-onchain-data/evm-gateway/_category_.yml b/docs/networks/node-ops/access-onchain-data/evm-gateway/_category_.yml index a2d462075f..9df7f0c8cc 100644 --- a/docs/networks/node-ops/access-onchain-data/evm-gateway/_category_.yml +++ b/docs/networks/node-ops/access-onchain-data/evm-gateway/_category_.yml @@ -1 +1 @@ -label: EVM Gateway Nodes +label: EVM Gateway diff --git a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md index 7f6fea3e32..e24d89c5af 100644 --- a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md +++ b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md @@ -1,7 +1,7 @@ --- title: Setting up an EVM Gateway node sidebar_label: EVM Gateway Setup -sidebar_position: 2 +sidebar_position: 3 --- import Tabs from '@theme/Tabs'; From 29142a1d5c95125ba707246d17256e242c4b9f07 Mon Sep 17 00:00:00 2001 From: Jerome P Date: Tue, 10 Dec 2024 14:15:27 -0800 Subject: [PATCH 09/28] Fix naming of the wrong network --- .../access-onchain-data/evm-gateway/evm-gateway-setup.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md index e24d89c5af..58921c7ea9 100644 --- a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md +++ b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md @@ -214,8 +214,8 @@ make DOCKER_RUN_DETACHED=true DOCKER_HOST_PORT=1234 DOCKER_HOST_MOUNT=/my/host/d ## 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 your EVM Gateway is up and running you will see it indexing the 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 From b1c61d0a82b0a2c54ce8518358e356636f7fa7d0 Mon Sep 17 00:00:00 2001 From: Jerome P Date: Tue, 10 Dec 2024 14:18:04 -0800 Subject: [PATCH 10/28] Add troubleshooting items --- .../evm-gateway/evm-gateway-setup.md | 29 +++++++++++++++---- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md index 58921c7ea9..7c7c78caf9 100644 --- a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md +++ b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md @@ -137,7 +137,7 @@ If you haven't already got an EVM address and you have the COA account created b 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 +### Run the gateway Ensure that the following ENV variables have been set. Add/update as required if your configuration differs from those listed. @@ -212,7 +212,7 @@ make DOCKER_RUN_DETACHED=true DOCKER_HOST_PORT=1234 DOCKER_HOST_MOUNT=/my/host/d -## Startup bootstrap indexing +### Startup bootstrap indexing Once your EVM Gateway is up and running you will see it indexing the 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. @@ -222,7 +222,7 @@ To speed up gateway setup we recommend backing up the /flow-evm-gateway/data dir 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 +### 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 @@ -237,7 +237,7 @@ are configured it may result in sequence number collisions if the same key is us --coa-cloud-kms-keys=example-gcp-kms1@1,example-gcp-kms2@1 \ ``` -## Monitoring and Metrics +### 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. @@ -260,7 +260,7 @@ 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 +### Metrics port ``` --metrics-port 8080 \ ``` @@ -274,5 +274,24 @@ curl -s -XPOST 'your-evm-gw-host:8545' --header 'Content-Type: application/json' ## Troubleshooting +### State stream configuration + +The following log entries may occur when `--state-stream-addr` and `--rpc-port` are not set to the same values when running +EVM Gateway on the same logical host as the Flow Access Node. + +```bash +failure in event subscription at height ${INIT-CADENCE-HEIGHT}, with: recoverable: disconnected: error receiving event: rpc error: code = Unimplemented desc = unknown service flow.executiondata.ExecutionDataAPI” +``` +```bash +component execution data indexer initialization failed: could not verify checkpoint file: could not find expected root hash e6d4f4c755666c21d7456441b4d33d3521e5e030b3eae391295577e9130fd715 in checkpoint file which contains: [e10d3c53608a1f195b7969fbc06763285281f64595be491630a1e1bdfbe69161] +``` + +### Access Node not fully synced + +The following log entry will occur when the EVM Gateway attempts to sync with the Access Node but it has not yet synced up to latest block +```bash +failure in event subscription at height ${INIT-CADENCE-HEIGHT}, with: recoverable: disconnected: error receiving event: rpc error: code = FailedPrecondition desc = could not get start height: failed to get lowest indexed height: index not initialized +``` + ## FAQs From 8008785fe05ed7e07e34808ad9c9f201a85c0105 Mon Sep 17 00:00:00 2001 From: Jerome P Date: Tue, 10 Dec 2024 14:20:23 -0800 Subject: [PATCH 11/28] Add missing bare metal startup guidance --- .../evm-gateway/evm-gateway-setup.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md index 7c7c78caf9..e3d319b399 100644 --- a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md +++ b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md @@ -188,6 +188,24 @@ cat /etc/systemd/system/gateway.service sudo systemctl enable gateway ``` +**Start all services** + +```bash +sudo systemctl daemon-reload +sudo systemctl restart access-node +sudo systemctl restart gateway +``` + +**Check logs** + +```bash +# change log settings to persistent if not already +sed -i 's/#Storage=auto/Storage=persistent/g' /etc/systemd/journald.conf +sudo systemctl restart systemd-journald + +journalctl -u access-node.service -f -n 100 +journalctl -u gateway.service -f -n 100 + From dd26cd7390b935c49d1ae72f3999ea659e337f07 Mon Sep 17 00:00:00 2001 From: Jerome P Date: Tue, 10 Dec 2024 14:20:50 -0800 Subject: [PATCH 12/28] Fix title case --- .../access-onchain-data/evm-gateway/evm-gateway-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md index e3d319b399..1ca18b0fe8 100644 --- a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md +++ b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md @@ -155,7 +155,7 @@ export GAS_PRICE="100" -Create EVM Gateway service +**Create EVM Gateway service** ```bash sudo tee </dev/null /etc/systemd/system/gateway.service From 7e799760d541858e69217bd5c3f9762ccf60c45a Mon Sep 17 00:00:00 2001 From: Jerome P Date: Tue, 10 Dec 2024 14:27:07 -0800 Subject: [PATCH 13/28] Fix broken tab --- .../access-onchain-data/evm-gateway/evm-gateway-setup.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md index 1ca18b0fe8..c2beb431f1 100644 --- a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md +++ b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md @@ -205,6 +205,7 @@ sudo systemctl restart systemd-journald journalctl -u access-node.service -f -n 100 journalctl -u gateway.service -f -n 100 +``` From 3dce83d1d18a54f5bac2fdec0133579361923520 Mon Sep 17 00:00:00 2001 From: Jerome P Date: Tue, 10 Dec 2024 14:28:15 -0800 Subject: [PATCH 14/28] Made comment consistent --- .../access-onchain-data/evm-gateway/evm-gateway-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md index c2beb431f1..3530d37764 100644 --- a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md +++ b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md @@ -143,7 +143,7 @@ Ensure that the following ENV variables have been set. Add/update as required if ```bash # Set required environment variables -export ACCESS_NODE_GRPC_HOST="access.mainnet.nodes.onflow.org:9000" +export ACCESS_NODE_GRPC_HOST="access.mainnet.nodes.onflow.org:9000" # or access.devnet.nodes.onflow.org:9000 for testnet export FLOW_NETWORK_ID="flow-mainnet" # or flow-testnet export INIT_CADENCE_HEIGHT="88226267" # 211176670 for testnet export COINBASE="${EVM_ADDRESS_WITHOUT_0x}" From be2eed2ce50baa94eed72b07e613d696e6efaa52 Mon Sep 17 00:00:00 2001 From: Jerome P Date: Tue, 10 Dec 2024 14:35:18 -0800 Subject: [PATCH 15/28] Minor tidyup --- .../access-onchain-data/evm-gateway/evm-gateway-setup.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md index 3530d37764..109097842c 100644 --- a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md +++ b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md @@ -234,12 +234,12 @@ make DOCKER_RUN_DETACHED=true DOCKER_HOST_PORT=1234 DOCKER_HOST_MOUNT=/my/host/d ### Startup bootstrap indexing Once your EVM Gateway is up and running you will see it indexing the 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. +is a lengthy process (possibly 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 +To speed up gateway setup we recommend backing up the `/${GATEWAY_HOME_DIR}/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. +store state snapshots to bootstrap newly created nodes without the delay. ### Account and Key Management From 872d9dbdab6abbeea7f12702418431392d8f78cf Mon Sep 17 00:00:00 2001 From: Jerome P Date: Tue, 10 Dec 2024 14:37:56 -0800 Subject: [PATCH 16/28] Tidy up troublshooting --- .../access-onchain-data/evm-gateway/evm-gateway-setup.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md index 109097842c..fbc194e594 100644 --- a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md +++ b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md @@ -295,8 +295,7 @@ curl -s -XPOST 'your-evm-gw-host:8545' --header 'Content-Type: application/json' ### State stream configuration -The following log entries may occur when `--state-stream-addr` and `--rpc-port` are not set to the same values when running -EVM Gateway on the same logical host as the Flow Access Node. +If you are running an Access Node on the same logical host as the EVM Gateway you may see ehe following log entries. ```bash failure in event subscription at height ${INIT-CADENCE-HEIGHT}, with: recoverable: disconnected: error receiving event: rpc error: code = Unimplemented desc = unknown service flow.executiondata.ExecutionDataAPI” @@ -305,6 +304,9 @@ failure in event subscription at height ${INIT-CADENCE-HEIGHT}, with: recoverabl component execution data indexer initialization failed: could not verify checkpoint file: could not find expected root hash e6d4f4c755666c21d7456441b4d33d3521e5e030b3eae391295577e9130fd715 in checkpoint file which contains: [e10d3c53608a1f195b7969fbc06763285281f64595be491630a1e1bdfbe69161] ``` +To resolve this configure `--state-stream-addr` to use the same address/port combination which is set for Access Node `--rpc-addr`. +This is required by the gateway to allow both the streaming and non-streaming APIs to query using the same connection. + ### Access Node not fully synced The following log entry will occur when the EVM Gateway attempts to sync with the Access Node but it has not yet synced up to latest block From f4b941fc2f0a89c6893388edb3ba4b23c9dda20a Mon Sep 17 00:00:00 2001 From: Jerome P Date: Tue, 10 Dec 2024 14:40:28 -0800 Subject: [PATCH 17/28] Minor fixes --- .../access-onchain-data/evm-gateway/evm-gateway-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md index fbc194e594..d06647905f 100644 --- a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md +++ b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md @@ -203,7 +203,6 @@ sudo systemctl restart gateway sed -i 's/#Storage=auto/Storage=persistent/g' /etc/systemd/journald.conf sudo systemctl restart systemd-journald -journalctl -u access-node.service -f -n 100 journalctl -u gateway.service -f -n 100 ``` @@ -316,3 +315,4 @@ failure in event subscription at height ${INIT-CADENCE-HEIGHT}, with: recoverabl ## FAQs +TBD \ No newline at end of file From 805ac5f52a643cc81e80338b088c3adabb1b2e7f Mon Sep 17 00:00:00 2001 From: Jerome P Date: Tue, 10 Dec 2024 14:43:07 -0800 Subject: [PATCH 18/28] remove redundant line --- .../access-onchain-data/evm-gateway/evm-gateway-setup.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md index d06647905f..b71a9f6034 100644 --- a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md +++ b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md @@ -90,7 +90,6 @@ To run EVM Gateway on bare metal or in a VM without the use of docker, select th This will build the EVM gateway binary from source. -For live networks we recommend using the [latest release](https://github.com/onflow/flow-evm-gateway/releases/latest) tag. ```bash git clone https://github.com/onflow/flow-evm-gateway.git From 6b1c6200b52884a0cc780ebcadf5101f238d9894 Mon Sep 17 00:00:00 2001 From: Jerome P Date: Tue, 10 Dec 2024 14:46:09 -0800 Subject: [PATCH 19/28] Make tab titles less confusing --- .../access-onchain-data/evm-gateway/evm-gateway-setup.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md index b71a9f6034..e798387a98 100644 --- a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md +++ b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md @@ -152,7 +152,7 @@ export GAS_PRICE="100" ``` - + **Create EVM Gateway service** @@ -206,7 +206,7 @@ journalctl -u gateway.service -f -n 100 ``` - + It may be necessary to make local changes to the `docker-run` target to add params which are needed for your requirements. From 3648e40c1765b904e6cf8b06be3309f8f9b71079 Mon Sep 17 00:00:00 2001 From: Jerome P Date: Tue, 10 Dec 2024 14:53:50 -0800 Subject: [PATCH 20/28] Add tab to use Docker image from container registry --- .../access-onchain-data/evm-gateway/evm-gateway-setup.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md index e798387a98..d551625e98 100644 --- a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md +++ b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md @@ -111,6 +111,13 @@ git checkout $(curl -s https://api.github.com/repos/onflow/flow-evm-gateway/rele make docker-build ``` + + + +```bash +docker pull us-west1-docker.pkg.dev/dl-flow-devex-production/development/flow-evm-gateway:${VERSION} +``` + From 78ad0c99eb33c55d9982aefe961daf49334ae2b0 Mon Sep 17 00:00:00 2001 From: Jerome P Date: Tue, 10 Dec 2024 14:56:29 -0800 Subject: [PATCH 21/28] Add comment to run docker images that was pulled for registry --- .../access-onchain-data/evm-gateway/evm-gateway-setup.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md index d551625e98..42f2278834 100644 --- a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md +++ b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md @@ -215,7 +215,9 @@ journalctl -u gateway.service -f -n 100 -It may be necessary to make local changes to the `docker-run` target to add params which are needed for your requirements. +It may be necessary to make local changes to the `docker-run` target to add params which are needed for your requirements. If you pulled a +specific image from the gateway container registry ensure that the `$VERSION` environment variable is set to the same as the image version +you pulled. ```bash cd flow-evm-gateway @@ -233,6 +235,7 @@ DOCKER_HOST_PORT=[desired port to expose on host] make DOCKER_RUN_DETACHED=true DOCKER_HOST_PORT=1234 DOCKER_HOST_MOUNT=/my/host/dir docker-run ``` + From de64fb04e00077ed95d08d839f829616e05fe525 Mon Sep 17 00:00:00 2001 From: Jerome P Date: Tue, 10 Dec 2024 14:59:52 -0800 Subject: [PATCH 22/28] Link to container registry --- .../access-onchain-data/evm-gateway/evm-gateway-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md index 42f2278834..7f4aa04b5a 100644 --- a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md +++ b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md @@ -114,6 +114,7 @@ make docker-build +Registry versions available for download can be found [here](https://console.cloud.google.com/artifacts/docker/dl-flow-devex-production/us-west1/development/flow-evm-gateway). ```bash docker pull us-west1-docker.pkg.dev/dl-flow-devex-production/development/flow-evm-gateway:${VERSION} ``` @@ -235,7 +236,6 @@ DOCKER_HOST_PORT=[desired port to expose on host] make DOCKER_RUN_DETACHED=true DOCKER_HOST_PORT=1234 DOCKER_HOST_MOUNT=/my/host/dir docker-run ``` - From 4733bed70f102f0d239c3d3cc54d158d282ca191 Mon Sep 17 00:00:00 2001 From: j pimmel Date: Tue, 10 Dec 2024 16:00:19 -0800 Subject: [PATCH 23/28] Update docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md Co-authored-by: Vishal <1117327+vishalchangrani@users.noreply.github.com> --- .../access-onchain-data/evm-gateway/evm-gateway-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md index 7f4aa04b5a..92f4b26918 100644 --- a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md +++ b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md @@ -13,7 +13,7 @@ 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 +network, wrapped in 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 From 02e435e6d86e4526650053c34e99267fa8f337ab Mon Sep 17 00:00:00 2001 From: j pimmel Date: Wed, 11 Dec 2024 09:15:56 -0800 Subject: [PATCH 24/28] Update wording in opening description --- .../access-onchain-data/evm-gateway/evm-gateway-setup.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md index 92f4b26918..8e992337b0 100644 --- a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md +++ b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md @@ -11,10 +11,7 @@ This guide is for running the [EVM Gateway](https://github.com/onflow/flow-evm-g [Ethereum JSON-RPC specification](https://ethereum.org/en/developers/docs/apis/json-rpc/) 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 in 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. +The EVM Gateway 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 in 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. It does not participate in the block production process and requires no stake. ## Who Should Run an EVM Gateway From 1b9ddc55413439fd33f3e16c9f3f3bce771ccbda Mon Sep 17 00:00:00 2001 From: j pimmel Date: Wed, 11 Dec 2024 09:20:09 -0800 Subject: [PATCH 25/28] Add guidance to obtain flow cli --- .../access-onchain-data/evm-gateway/evm-gateway-setup.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md index 8e992337b0..459bce0a84 100644 --- a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md +++ b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md @@ -56,11 +56,10 @@ If you don't already have a Flow account you will need to create one. +Install [Flow CLI](https://developers.flow.com/tools/flow-cli/install) if not already installed. ```bash flow keys generate -``` - This will output something similar to: ```bash From afedecebd2eb46cb9972a9aed4e4feda9eb3f3cb Mon Sep 17 00:00:00 2001 From: Jerome P Date: Wed, 11 Dec 2024 09:21:57 -0800 Subject: [PATCH 26/28] Restore missing shell clause closure --- .../access-onchain-data/evm-gateway/evm-gateway-setup.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md index 459bce0a84..a96e85383e 100644 --- a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md +++ b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md @@ -60,8 +60,9 @@ Install [Flow CLI](https://developers.flow.com/tools/flow-cli/install) if not al ```bash flow keys generate +``` This will output something similar to: - +` ```bash 🔴️ Store private key safely and don't share with anyone! Private Key 3cf8334d.....95c3c54a28e4ad1 From 7ff724343fd9d078ea663dbbcc454c78b9506651 Mon Sep 17 00:00:00 2001 From: Jerome P Date: Wed, 11 Dec 2024 10:24:12 -0800 Subject: [PATCH 27/28] Minor nits --- .../access-onchain-data/evm-gateway/evm-gateway-setup.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md index a96e85383e..c566456609 100644 --- a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md +++ b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md @@ -56,6 +56,7 @@ If you don't already have a Flow account you will need to create one. + Install [Flow CLI](https://developers.flow.com/tools/flow-cli/install) if not already installed. ```bash @@ -149,7 +150,7 @@ Ensure that the following ENV variables have been set. Add/update as required if # Set required environment variables export ACCESS_NODE_GRPC_HOST="access.mainnet.nodes.onflow.org:9000" # or access.devnet.nodes.onflow.org:9000 for testnet export FLOW_NETWORK_ID="flow-mainnet" # or flow-testnet -export INIT_CADENCE_HEIGHT="88226267" # 211176670 for testnet +export INIT_CADENCE_HEIGHT="85981134" # 211176670 for testnet export COINBASE="${EVM_ADDRESS_WITHOUT_0x}" export COA_ADDRESS="${CADENCE_ACCOUNT_ADDRESS_WITHOUT_0x}" export COA_KEY="${CADENCE_ACCOUNT_PRIVATE_KEY_WITHOUT_0x}" @@ -284,7 +285,8 @@ 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. -### Metrics port +**Metrics port** + ``` --metrics-port 8080 \ ``` @@ -298,6 +300,9 @@ curl -s -XPOST 'your-evm-gw-host:8545' --header 'Content-Type: application/json' ## Troubleshooting +Join our [Discord](https://discord.com/invite/J6fFnh2xx6) and use the `#flow-evm` channel to ask any questions you may have about +EVM Gateway. + ### State stream configuration If you are running an Access Node on the same logical host as the EVM Gateway you may see ehe following log entries. From 83b8217cf901a0498a1a519916c15e8702c15b64 Mon Sep 17 00:00:00 2001 From: Jerome P Date: Thu, 12 Dec 2024 10:11:44 -0800 Subject: [PATCH 28/28] Add notice about using old versions of data dir --- .../access-onchain-data/evm-gateway/evm-gateway-setup.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md index c566456609..885aa9f187 100644 --- a/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md +++ b/docs/networks/node-ops/access-onchain-data/evm-gateway/evm-gateway-setup.md @@ -247,6 +247,13 @@ To speed up gateway setup we recommend backing up the `/${GATEWAY_HOME_DIR}/data using the same release version. We are currently working on an export/import feature that will enable gateway operators to store state snapshots to bootstrap newly created nodes without the delay. +:::note + +If you are upgrading the gateway from pre-v1.0.0 release versions the indexed data directory will need to be reindexed from genesis. +You will not be able to re-use the DB data dir from the previous versions. + +::: + ### 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