{"id":19610689,"url":"https://github.com/onflow/flow-evm-gateway","last_synced_at":"2026-01-12T02:43:49.078Z","repository":{"id":208497753,"uuid":"709390950","full_name":"onflow/flow-evm-gateway","owner":"onflow","description":"FlowEVM Gateway implements an Ethereum-equivalent JSON-RPC API for EVM clients to use","archived":false,"fork":false,"pushed_at":"2025-04-22T08:21:04.000Z","size":4144,"stargazers_count":14,"open_issues_count":35,"forks_count":11,"subscribers_count":26,"default_branch":"main","last_synced_at":"2025-04-22T09:31:46.636Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://developers.flow.com/evm/about","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/onflow.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-24T16:10:15.000Z","updated_at":"2025-04-18T15:35:05.000Z","dependencies_parsed_at":"2023-11-21T20:29:00.750Z","dependency_job_id":"9b0e19e6-eb58-476d-ab4e-09e6db9e6ac4","html_url":"https://github.com/onflow/flow-evm-gateway","commit_stats":null,"previous_names":["onflow/flow-evm-gateway","onflow/flow-evm-grpc"],"tags_count":72,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onflow%2Fflow-evm-gateway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onflow%2Fflow-evm-gateway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onflow%2Fflow-evm-gateway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onflow%2Fflow-evm-gateway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/onflow","download_url":"https://codeload.github.com/onflow/flow-evm-gateway/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251219600,"owners_count":21554444,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-11T10:31:59.578Z","updated_at":"2026-01-12T02:43:49.072Z","avatar_url":"https://github.com/onflow.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"https://assets-global.website-files.com/5f734f4dbd95382f4fdfa0ea/65b0115890bbda5c804f7524_donuts%202-p-500.png\" alt=\"evm\" width=\"300\"/\u003e\n\n# EVM Gateway\n\n## EVM Gateway enables seamless interaction with EVM on Flow, mirroring the experience of engaging with any other EVM blockchain\n\nEVM Gateway implements the Ethereum JSON-RPC API for [EVM on Flow](https://developers.flow.com/evm/about) which conforms to the Ethereum [JSON-RPC specification](https://ethereum.github.io/execution-apis/api-documentation/). The EVM Gateway is tailored for integration with the EVM environment on the Flow blockchain. Rather than implementing the full `geth` stack, the JSON-RPC API available in EVM Gateway is a lightweight implementation that uses Flow's underlying consensus and smart contract language, [Cadence](https://cadence-lang.org/docs/), to handle calls received by the EVM Gateway. For those interested in the underlying implementation details, please refer to the [FLIP #243](https://github.com/onflow/flips/issues/243) (EVM Gateway) and [FLIP #223](https://github.com/onflow/flips/issues/223) (EVM on Flow Core) improvement proposals.\n\nEVM Gateway is compatible with the majority of standard Ethereum JSON-RPC APIs allowing seamless integration with existing Ethereum-compatible web3 tools via HTTP. EVM Gateway honors Ethereum's JSON-RPC namespace system, grouping RPC methods into categories based on their specific purpose. Each method name is constructed using the namespace, an underscore, and the specific method name in that namespace. For example, the `eth_call` method is located within the `eth` namespace. More details on Ethereum JSON-RPC compatibility are available in our [Using EVM](https://developers.flow.com/evm/using#json-rpc-methods) docs.  \n\nNo stake is required to run an EVM Gateway and since they do not participate in consensus they have a lightweight resource footprint. They are recommended as a scaling solution in place of centralized middleware JSON-RPC providers.  \n\n### Design\n\n![design ](./evm-gateway-arch.svg)\n\nThe basic design of the EVM Gateway is as follows:\n\n- Event Ingestion Engine: consumes all Cadence events emitted by the EVM core, filtering for special event type IDs `evm.TransactionExecuted` and `evm.BlockExecuted`. These payloads are decoded and indexed locally. The local index serves all read-only requests to the JSON-RPC including `debug_traceXxxx()` requests.\n- Flow Requester: submits Cadence transactions to a Flow Access Node to change the EVM state. EVM transaction payloads received by the JSON-RPC are wrapped in a Cadence transaction. The Cadence transaction execution unwraps the EVM transaction payload and is provided to the EVM core to execute and change state.\n- JSON-RPC: the client API component that implements functions according to the Ethereum JSON-RPC specification.\n\n\n# Building\n\n## Build from source\n\n```bash\n# Make sure you pull the latest changes before running `make build`\ncd flow-evm-gateway\ngit pull origin main\ngit fetch origin --tags\n\nmake build\n```\nTo view the binary version:\n\n```bash\n./flow-evm-gateway version\n```\n\nTo view all the available flags for running the EVM Gateway Node:\n\n```bash\n./flow-evm-gateway help run\n```\n\nThe binary can then be run by passing the necessary flags:\n\n```bash\n./flow-evm-gateway run {flags}\n```\n\nTo run an emulator based local version for development, with the necessary flags set:\n\n```bash\nmake start-local-bin\n```\n\n# Running\nOperating an EVM Gateway is straightforward. It can either be deployed locally alongside the Flow emulator or configured to connect with any active Flow networks supporting EVM. Given that the EVM Gateway depends solely on [Access Node APIs](https://developers.flow.com/networks/node-ops/access-onchain-data/access-nodes/accessing-data/access-api), it is compatible with any networks offering this API access.\n\n## Key concepts \n\nThe EVM Gateway's role in mediating EVM transactions over to Cadence is how it accrues fees from handling client transactions. Since \nthe gateway submits Cadence transactions wrapping EVM transaction payloads to the Flow Access Node the transaction fee for that must \nbe paid by the EVM Gateway.\n\nThe account used for funding gateway Cadence transactions must be a COA, not an EOA. `--coa-address` is configured with the Cadence address\nof the COA account and the `--coa-key` must belong to the same account. The `--coinbase` account accrues EVM Gateway fees from EVM client\ntransactions and can be either an EVM EOA or COA address.\n\nIt is acceptable to create a single Cadence account for the COA and use the EVM address associated with that for the COINBASE address.\n\n## Running Locally\n\nFor local development, first install [Flow CLI](https://developers.flow.com/tools/flow-cli/install). The examples below require no configuration and are intended for local development.\n\n### Run from CLI\n\nBefore running the gateway locally you need to start the Flow Emulator:\n\n```bash\nflow emulator\n```\n_Make sure flow.json has the emulator account configured to address and private key we will use for starting gateway below. Use `flow init` in a new folder for example config._\n\nPlease refer to the configuration section and read through all the configuration flags before proceeding.\n\nThen you can start the EVM Gateway with:\n\n```bash\nmake start-local\n```\n\nNote that the gateway will be starting from the latest emulator block, so if the emulator is run before any transactions happen in the meantime, the gateway will not fetch those historical blocks \u0026 transactions.\nThis will be improved soon.\n\n### Run with Docker\n\nUsing Docker for local development is also supported. The following target builds the current source directory into a docker image\n\n```bash\nmake docker-build-local\n```\nThis target starts the flow emulator and then runs the EVM Gateway using the image built by the above `make` target \n```bash\nmake docker-run-local\n```\n\n## Verify\n\nTo verify the service is up and running:\n\n```bash\ncurl -XPOST 'localhost:8545'  --header 'Content-Type: application/json' --data-raw '{\"jsonrpc\":\"2.0\",\"method\":\"eth_blockNumber\",\"params\":[],\"id\":1}'\n```\n\nit should return:\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"result\": \"0x2\"\n}\n```\n\n## Running on Testnet\n\nRunning against the testnet with a local build can be done by pointing the gateway to the testnet ANs and providing the correct configuration.\nPlease refer to the configuration section and read through all the configuration flags before proceeding.\n\n### Create Flow account to use for COA\n\nIf you don't already have a Flow account you will need to create account keys using the following command. \n\n```bash\nflow keys generate\n```\n\nThis will output something similar to:\n\n```bash\n🔴️ Store private key safely and don't share with anyone!\nPrivate Key \t\t 3cf8334d.....95c3c54a28e4ad1\nPublic Key \t\t 33a13ade6....85f1b49a197747\nMnemonic \t\t often scare peanut ... boil corn change\nDerivation Path \t m/44'/539'/0'/0/0\nSignature Algorithm \t ECDSA_P256\n```\n\nThen visit https://faucet.flow.com/, and use the generated `Public Key`, to create and fund your Flow testnet account.\nMake sure to use the Flow address and the `Private Key` for the `--coa-address` \u0026 `--coa-key` flags.\n\n### Run EVM Gateway connected to Testnet\n\nBelow is an example configuration for running against testnet, with a preconfigured testnet account.\n\n```bash\n./flow-evm-gateway run \\\n--access-node-spork-hosts=\"access-001.devnet51.nodes.onflow.org:9000,access-001.devnet52.nodes.onflow.org:9000\" \\\n--access-node-grpc-host=access.devnet.nodes.onflow.org:9000 \\\n--flow-network-id=flow-testnet \\\n--ws-enabled=true \\\n--coinbase=FACF71692421039876a5BB4F10EF7A439D8ef61E \\\n--coa-address=\u003c16-character hexadecimal address\u003e \\\n--coa-key=\u003c64-character hexadecimal private key\u003e \\\n--gas-price=100\n```\n\nIf you wish to test this out with your own Access Node, simply set `--access-node-grpc-host` to the DNS or IP where it is hosted.\n\nFor the `--gas-price`, feel free to experiment with different values.\n\nThe `--coinbase` can be any EOA address.\n\nOnce the EVM Gateway is up and running, verify that indexing works with:\n\n```bash\ncurl -s -XPOST 'localhost:8545' --header 'Content-Type: application/json' --data-raw '{\"jsonrpc\":\"2.0\",\"method\":\"eth_blockNumber\",\"params\":[],\"id\":1}'\n```\n\nShould return a response similar to:\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"result\": \"0x68\"\n}\n```\n\n### Run local EVM GW docker container connected to Testnet\n\nTo use the `make` target to connect a container-based gateway instance to testnet requires the following environment variables to be set.\n\n* `ACCESS_NODE_GRPC_HOST`: access.devnet.nodes.onflow.org:9000 \n* `FLOW_NETWORK_ID`: flow-testnet\n* `COINBASE`: FACF71692421039876a5BB4F10EF7A439D8ef61E\n* `COA_ADDRESS`: \u003c16-character hexadecimal address\u003e\n* `COA_KEY`: \u003c64-character hexadecimal private key\u003e\n* `VERSION`: [_repo commit hash or tag version used when building with docker_]\n\nOnce set, this target starts the EVM Gateway for the specified image version and connects it to testnet\n```bash\nmake docker-run\n```\n\n## Mainnet and Node Operations\n\nGuidance for EVM Gateway node operations including considerations for mainnet, hardware specs, monitoring setup and troubleshooting \ncan be found in the EVM Gateway [node operations docs](https://developers.flow.com/networks/node-ops/evm-gateway/evm-gateway-setup).\n\nBelow is an example configuration for running against mainnet, with a preconfigured mainnet account.\n\n```bash\n./flow-evm-gateway run \\\n--access-node-spork-hosts=\"access-001.mainnet25.nodes.onflow.org:9000,access-001.mainnet26.nodes.onflow.org:9000\" \\\n--access-node-grpc-host=access.mainnet.nodes.onflow.org:9000 \\\n--flow-network-id=flow-mainnet \\\n--ws-enabled=true \\\n--coinbase=FACF71692421039876a5BB4F10EF7A439D8ef61E \\\n--coa-address=\u003c16-character hexadecimal address\u003e \\\n--coa-key=\u003c64-character hexadecimal private key\u003e \\\n--gas-price=100000000\n```\n\n## Configuration Flags\n\nThe application can be configured using the following flags at runtime:\n\n| Flag                           | Default Value    | Description                                                                                |\n|--------------------------------|------------------|--------------------------------------------------------------------------------------------|\n| `database-dir`                 | `./db`           | Path to the directory for the database                                                     |\n| `rpc-host`                     | `\"\"`             | Host for the RPC API server                                                                |\n| `rpc-port`                     | `8545`           | Port for the RPC API server (also same for Websockets)                                     |\n| `ws-enabled`                   | `false`          | Enable websocket connections                                                               |\n| `access-node-grpc-host`        | `localhost:3569` | Host to the flow access node gRPC API                                                      |\n| `access-node-spork-hosts`      | `\"\"`             | Previous spork AN hosts, defined as a comma-separated list (e.g. `\"host-1.com,host2.com\"`) |\n| `flow-network-id`              | `flow-emulator`  | Flow network ID (options: `flow-emulator`, `flow-testnet`, `flow-mainnet`)                 |\n| `coinbase`                     | `\"\"`             | Coinbase address to use for fee collection                                                 |\n| `gas-price`                    | `1`              | Static gas price for EVM transactions                                                      |\n| `enforce-gas-price`            | `true`           | Enable enforcing minimum gas price for EVM transactions. When true (default), transactions must specify a gas price greater than or equal to the configured gas price. |\n| `coa-address`                  | `\"\"`             | Flow address holding COA account for submitting transactions                               |\n| `coa-key`                      | `\"\"`             | Private key for the COA address used for transactions                                      |\n| `coa-key-file`                 | `\"\"`             | Path to a JSON file of COA keys for key-rotation (exclusive with `coa-key` flag)           |\n| `coa-cloud-kms-project-id`     | `\"\"`             | Project ID for KMS keys (e.g. `flow-evm-gateway`)                                          |\n| `coa-cloud-kms-location-id`    | `\"\"`             | Location ID for KMS key ring (e.g. 'global')                                               |\n| `coa-cloud-kms-key-ring-id`    | `\"\"`             | Key ring ID for KMS keys (e.g. 'tx-signing')                                               |\n| `coa-cloud-kms-key`            | `\"\"`             | KMS keys and versions, comma-separated (e.g. `\"gw-key-6@1,gw-key-7@1\"`)                    |\n| `log-level`                    | `debug`          | Log verbosity level (`debug`, `info`, `warn`, `error`, `fatal`, `panic`)                   |\n| `log-writer`                   | `stderr`         | Output method for logs (`stderr`, `console`)                                               |\n| `rate-limit`                   | `50`             | Requests per second limit for clients over any protocol (ws/http)                          |\n| `address-header`               | `\"\"`             | Header for client IP when server is behind a proxy                                         |\n| `heartbeat-interval`           | `100`            | Interval for AN event subscription heartbeats                                              |\n| `force-start-height`           | `0`              | Force-set starting Cadence height (local/testing use only)                                 |\n| `wallet-api-key`               | `\"\"`             | ECDSA private key for wallet APIs (local/testing use only)                                 |\n| `filter-expiry`                | `5m`             | Expiry time for idle filters                                                               |\n| `traces-backfill-start-height` | `0`              | Start height for backfilling transaction traces                                            |\n| `traces-backfill-end-height`   | `0`              | End height for backfilling transaction traces                                              |\n| `index-only`                   | `false`          | Run in index-only mode, allowing state queries and indexing but no transaction sending     |\n| `metrics-port`                 | `8080`           | Port for Prometheus metrics                                                                |\n| `profiler-enabled`             | `false`          | Enable the pprof profiler server                                                           |\n| `profiler-host`                | `localhost`      | Host for the pprof profiler                                                                |\n| `profiler-port`                | `6060`           | Port for the pprof profiler                                                                |\n| `tx-state-validation`          | `\"\"`             | When set to `local-index` will validate EVM transaction state locally                      |\n\n\n# EVM Gateway Endpoints\n\nEVM Gateway has public RPC endpoints available for the following environments:\n\n| Name            | Value                                  |\n|-----------------|----------------------------------------|\n| Network Name    | EVM on Flow Testnet                    |\n| Description     | The public RPC URL for Flow Testnet    |\n| RPC Endpoint    | https://testnet.evm.nodes.onflow.org   |\n| Chain ID        | 545                                    |\n| Currency Symbol | FLOW                                   |\n| Block Explorer  | https://evm-testnet.flowscan.io        |\n\n| Name            | Value                                  |\n|-----------------|----------------------------------------|\n| Network Name    | EVM on Flow                            |\n| Description     | The public RPC URL for Flow Mainnet    |\n| RPC Endpoint    | https://mainnet.evm.nodes.onflow.org   |\n| Chain ID        | 747                                    |\n| Currency Symbol | FLOW                                   |\n| Block Explorer  | https://evm.flowscan.io                |\n\nTo connect using Websockets you can use the same DNS names as above but change `https://` with `wss://`, eg: `wss://testnet.evm.nodes.onflow.org`\n\n# JSON-RPC API\nThe EVM Gateway implements APIs according to the Ethereum specification: https://ethereum.org/en/developers/docs/apis/json-rpc/#json-rpc-methods.\n\n## Additional APIs\n- Tracing APIs allow fetching execution traces\n  * `debug_traceTransaction`\n  * `debug_traceBlockByNumber`\n  * `debug_traceBlockByHash`\n  * `debug_traceCall`\n- `debug_flowHeightByBlock` - returns the flow block height for the given EVM block (id or height)\n\n## Unsupported APIs\n- Wallet APIs: we don't officially support wallet APIs (`eth_accounts`, `eth_sign`, `eth_signTransaction`, `eth_sendTransaction`) due to security\n  concerns that come with managing the keys on production environments, however, it is possible to configure the gateway to allow these\n  methods for local development by using a special flag `--wallet-api-key`.\n- Proof API: we don't support obtaining proofs yet, Flow piggy-backs on the Flow consensus, and hence the Flow proofs can be used to verify\n  and trust the EVM environment. We intend to add access to EVM proofs in the future.\n- Access Lists: we don't yet support creating access lists as they don't affect the fees we charge. We might support this in the future\n  to optimize fees, but it currently is not part of our priorities.\n\nA full list of supported methods is available in the [Using EVM](https://developers.flow.com/evm/using#json-rpc-methods) docs.\n\n# Debugging\n\n## Profiler\n\nThe EVM Gateway supports profiling via the `pprof` package. To enable profiling, add the following flags to the command line:\n```\n--profiler-enabled=true\n--profiler-host=localhost\n--profiler-port=6060\n```\n\nThis will start a pprof server on the provided `host` and `port`. You can generate profiles using the following `go tool` commands\n```\ngo tool pprof -http :2000 http://localhost:6060/debug/pprof/profile\n```\n```\ncurl --output trace.out http://localhost:6060/debug/pprof/trace\ngo tool trace -http :2001 trace.out\n```\n\n# Contributing\nWe welcome contributions from the community! Please read our [Contributing Guide](./CONTRIBUTING.md) for information on how to get involved.\n\n# License\nEVM Gateway is released under the Apache License 2.0 license. See the LICENSE file for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonflow%2Fflow-evm-gateway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonflow%2Fflow-evm-gateway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonflow%2Fflow-evm-gateway/lists"}