Merge branch 'main' into mpeter/track-latest-finalized-block-header

Author: m-Peter

Makefile

@@ -19,16 +19,18 @@ OS :=
 COMPILER_FLAGS := CGO_ENABLED=1
 
 EMULATOR_ARGS := --flow-network-id=flow-emulator \
+		--access-node-grpc-host=localhost:3569 \
 		--coinbase=$(EMULATOR_COINBASE) \
-		--coa-address=$(EMULATOR_COA_ADDRESS)  \
-		--coa-key=$(EMULATOR_COA_KEY)  \
+		--coa-address=$(EMULATOR_COA_ADDRESS) \
+		--coa-key=$(EMULATOR_COA_KEY) \
 		--wallet-api-key=2619878f0e2ff438d17835c2a4561cb87b4d24d72d12ec34569acd0dd4af7c21 \
 		--gas-price=0 \
 		--log-writer=console \
 		--tx-state-validation=local-index \
 		--profiler-enabled=true \
 		--profiler-port=6060 \
-		--ws-enabled=true
+		--ws-enabled=true \
+		--coa-tx-lookup-enabled=true
 
 # Set VERSION from command line, environment, or default to SHORT_COMMIT
 VERSION ?= $(SHORT_COMMIT)
@@ -168,7 +170,6 @@ docker-pull-version:
 # Requires the following ENV variables:
 #   - ACCESS_NODE_GRPC_HOST: [access.devnet.nodes.onflow.org:9000 | access.mainnet.nodes.onflow.org:9000]
 #   - FLOW_NETWORK_ID: [flow-testnet, flow-mainnet]
-#   - INIT_CADENCE_HEIGHT: [testnet: 211176670, mainnet: 85981135]
 #   - COINBASE: To be set by the operator. This is an EVM EOA or COA address which is set as the receiver of GW transaction fees (remove 0x prefix)
 #   - COA_ADDRESS: To be set by the operator. This is a Cadence address which funds gateway operations (remove 0x prefix)
 #   - COA_KEY: A full weight, private key belonging to operator COA_ADDRESS (remove 0x prefix). NB: For development use only. We recommend using cloud KMS configuration on mainnet
@@ -215,7 +216,6 @@ endif
 
 	$(call check_and_append,access-node-grpc-host,ACCESS_NODE_GRPC_HOST)
 	$(call check_and_append,flow-network-id,FLOW_NETWORK_ID)
-	$(call check_and_append,init-cadence-height,INIT_CADENCE_HEIGHT)
 	$(call check_and_append,coinbase,COINBASE)
 	$(call check_and_append,coa-address,COA_ADDRESS)
 	$(call check_and_append,coa-key,COA_KEY)

README.md

@@ -2,7 +2,7 @@
 
 # EVM Gateway
 
-**EVM Gateway enables seamless interaction with EVM on Flow, mirroring the experience of engaging with any other EVM blockchain.**
+## EVM Gateway enables seamless interaction with EVM on Flow, mirroring the experience of engaging with any other EVM blockchain
 
 EVM 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.
 
@@ -23,7 +23,7 @@ The basic design of the EVM Gateway is as follows:
 
 # Building
 
-**Build from source**
+## Build from source
 
 ```bash
 # Make sure you pull the latest changes before running `make build`
@@ -76,7 +76,7 @@ It is acceptable to create a single Cadence account for the COA and use the EVM
 
 For 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.
 
-**Run from CLI**
+### Run from CLI
 
 Before running the gateway locally you need to start the Flow Emulator:
 
@@ -96,7 +96,7 @@ make start-local
 Note 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 & transactions.
 This will be improved soon.
 
-**Run with Docker**
+### Run with Docker
 
 Using Docker for local development is also supported. The following target builds the current source directory into a docker image
 
@@ -108,7 +108,7 @@ This target starts the flow emulator and then runs the EVM Gateway using the ima
 make docker-run-local
 ```
 
-**Verify**
+## Verify
 
 To verify the service is up and running:
 
@@ -131,7 +131,7 @@ it should return:
 Running against the testnet with a local build can be done by pointing the gateway to the testnet ANs and providing the correct configuration.
 Please refer to the configuration section and read through all the configuration flags before proceeding.
 
-**Create Flow account to use for COA**
+### Create Flow account to use for COA
 
 If you don't already have a Flow account you will need to create account keys using the following command. 
 
@@ -153,27 +153,23 @@ Signature Algorithm 	 ECDSA_P256
 Then visit https://faucet.flow.com/, and use the generated `Public Key`, to create and fund your Flow testnet account.
 Make sure to use the Flow address and the `Private Key` for the `--coa-address` & `--coa-key` flags.
 
-**Run local EVM Gateway connected to Testnet**
+### Run EVM Gateway connected to Testnet
 
 Below is an example configuration for running against testnet, with a preconfigured testnet account.
 
 ```bash
 ./flow-evm-gateway run \
+--access-node-spork-hosts="access-001.devnet51.nodes.onflow.org:9000,access-001.devnet52.nodes.onflow.org:9000" \
 --access-node-grpc-host=access.devnet.nodes.onflow.org:9000 \
---access-node-spork-hosts=access-001.devnet51.nodes.onflow.org:9000 \
 --flow-network-id=flow-testnet \
---init-cadence-height=211176670 \
 --ws-enabled=true \
 --coinbase=FACF71692421039876a5BB4F10EF7A439D8ef61E \
---coa-address=62631c28c9fc5a91 \
---coa-key=2892fba444f1d5787739708874e3b01160671924610411ac787ac1379d420f49 \
+--coa-address=<16-character hexadecimal address> \
+--coa-key=<64-character hexadecimal private key> \
 --gas-price=100
 ```
 
-The `--init-cadence-height` is the Flow block height to start indexing from. To index the full EVM state, from its beginning, the proper value for this flag for testnet is `211176670`. This is the height where the `EVM` contract was first deployed on testnet, and this is where the EVM state starts from.
-
 If 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.
-**Note:** You need to make sure that the testnet Access Node which the gateway is connected to has indexed at least up to Flow block height `211176670`.
 
 For the `--gas-price`, feel free to experiment with different values.
 
@@ -195,16 +191,15 @@ Should return a response similar to:
 }
 ```
 
-**Run local EVM GW docker container connected to Testnet**
+### Run local EVM GW docker container connected to Testnet
 
-To use the `make` target to connect a container based gateway instance to testnet requires the following environment variables to be set. 
+To use the `make` target to connect a container-based gateway instance to testnet requires the following environment variables to be set.
 
 * `ACCESS_NODE_GRPC_HOST`: access.devnet.nodes.onflow.org:9000 
 * `FLOW_NETWORK_ID`: flow-testnet
-* `INIT_CADENCE_HEIGHT`: 211176670
 * `COINBASE`: FACF71692421039876a5BB4F10EF7A439D8ef61E
-* `COA_ADDRESS`: 62631c28c9fc5a91
-* `COA_KEY`: 2892fba444f1d5787739708874e3b01160671924610411ac787ac1379d420f49 
+* `COA_ADDRESS`: <16-character hexadecimal address>
+* `COA_KEY`: <64-character hexadecimal private key>
 * `VERSION`: [_repo commit hash or tag version used when building with docker_]
 
 Once set, this target starts the EVM Gateway for the specified image version and connects it to testnet
@@ -217,6 +212,20 @@ make docker-run
 Guidance for EVM Gateway node operations including considerations for mainnet, hardware specs, monitoring setup and troubleshooting 
 can be found in the EVM Gateway [node operations docs](https://developers.flow.com/networks/node-ops/evm-gateway/evm-gateway-setup).
 
+Below is an example configuration for running against mainnet, with a preconfigured mainnet account.
+
+```bash
+./flow-evm-gateway run \
+--access-node-spork-hosts="access-001.mainnet25.nodes.onflow.org:9000,access-001.mainnet26.nodes.onflow.org:9000" \
+--access-node-grpc-host=access.mainnet.nodes.onflow.org:9000 \
+--flow-network-id=flow-mainnet \
+--ws-enabled=true \
+--coinbase=FACF71692421039876a5BB4F10EF7A439D8ef61E \
+--coa-address=<16-character hexadecimal address> \
+--coa-key=<64-character hexadecimal private key> \
+--gas-price=100000000
+```
+
 ## Configuration Flags
 
 The application can be configured using the following flags at runtime:
@@ -231,7 +240,6 @@ The application can be configured using the following flags at runtime:
 | `access-node-spork-hosts`      | `""`             | Previous spork AN hosts, defined as a comma-separated list (e.g. `"host-1.com,host2.com"`) |
 | `flow-network-id`              | `flow-emulator`  | Flow network ID (options: `flow-emulator`, `flow-testnet`, `flow-mainnet`)                 |
 | `coinbase`                     | `""`             | Coinbase address to use for fee collection                                                 |
-| `init-cadence-height`          | `0`              | Cadence block height to start indexing; avoid using on a new network                       |
 | `gas-price`                    | `1`              | Static gas price for EVM transactions                                                      |
 | `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. |
 | `coa-address`                  | `""`             | Flow address holding COA account for submitting transactions                               |
@@ -286,14 +294,15 @@ To connect using Websockets you can use the same DNS names as above but change `
 # JSON-RPC API
 The EVM Gateway implements APIs according to the Ethereum specification: https://ethereum.org/en/developers/docs/apis/json-rpc/#json-rpc-methods.
 
-**Additional APIs**
-- Tracing APIs allows you to fetch execution traces
-    * `debug_traceTransaction`
-    * `debug_traceBlockByNumber`
-    * `debug_traceBlockByHash`
+## Additional APIs
+- Tracing APIs allow fetching execution traces
+  * `debug_traceTransaction`
+  * `debug_traceBlockByNumber`
+  * `debug_traceBlockByHash`
+  * `debug_traceCall`
 - `debug_flowHeightByBlock` - returns the flow block height for the given EVM block (id or height)
 
-**Unsupported APIs**
+## Unsupported APIs
 - Wallet APIs: we don't officially support wallet APIs (`eth_accounts`, `eth_sign`, `eth_signTransaction`, `eth_sendTransaction`) due to security
   concerns that come with managing the keys on production environments, however, it is possible to configure the gateway to allow these
   methods for local development by using a special flag `--wallet-api-key`.

api/pull.go

@@ -247,6 +247,10 @@ func (api *PullAPI) NewFilter(ctx context.Context, criteria filters.FilterCriter
 		return "", err
 	}
 
+	if !logs.ValidCriteriaLimits(criteria) {
+		return "", errs.ErrExceedLogQueryLimit
+	}
+
 	latest, err := api.blocks.LatestEVMHeight()
 	if err != nil {
 		return "", err

api/stream.go

@@ -14,6 +14,7 @@ import (
 	"github.com/onflow/flow-evm-gateway/config"
 	ethTypes "github.com/onflow/flow-evm-gateway/eth/types"
 	"github.com/onflow/flow-evm-gateway/models"
+	errs "github.com/onflow/flow-evm-gateway/models/errors"
 	"github.com/onflow/flow-evm-gateway/services/logs"
 	"github.com/onflow/flow-evm-gateway/storage"
 )
@@ -92,6 +93,10 @@ func (s *StreamAPI) NewPendingTransactions(ctx context.Context, fullTx *bool) (*
 
 // Logs creates a subscription that fires for all new log that match the given filter criteria.
 func (s *StreamAPI) Logs(ctx context.Context, criteria filters.FilterCriteria) (*rpc.Subscription, error) {
+	if !logs.ValidCriteriaLimits(criteria) {
+		return nil, errs.ErrExceedLogQueryLimit
+	}
+
 	return newSubscription(
 		ctx,
 		s.logger,

bootstrap/bootstrap.go

@@ -81,9 +81,15 @@ type Bootstrap struct {
 }
 
 func New(config config.Config) (*Bootstrap, error) {
-	logger := zerolog.New(config.LogWriter).
-		With().Timestamp().Str("version", api.Version).
-		Logger().Level(config.LogLevel)
+	var logger zerolog.Logger
+
+	if config.Logger != nil {
+		logger = *config.Logger
+	} else {
+		logger = zerolog.New(config.LogWriter).
+			With().Timestamp().Str("version", api.Version).
+			Logger().Level(config.LogLevel)
+	}
 
 	client, err := setupCrossSporkClient(config, logger)
 	if err != nil {
@@ -143,8 +149,8 @@ func (b *Bootstrap) StartEventIngestion(ctx context.Context) error {
 
 	chainID := b.config.FlowNetworkID
 
-	// the event subscriber takes the first block to sync from the Access node, which is the block
-	// after the latest cadence block
+	// the event subscriber takes the first block to sync from the Access node,
+	// which is the block after the latest cadence block
 	nextCadenceHeight := latestCadenceHeight + 1
 	// Special case when using a local Emulator as Access Node. The Emulator
 	// always starts at block height 0, so if we try to subscribe at block
@@ -153,7 +159,7 @@ func (b *Bootstrap) StartEventIngestion(ctx context.Context) error {
 		nextCadenceHeight -= 1
 	}
 
-	// create event subscriber
+	// create EVM event subscriber
 	subscriber := ingestion.NewRPCEventSubscriber(
 		b.logger,
 		b.client,

config/config.go

@@ -30,7 +30,8 @@ const (
 
 	// Mainnet height at which the `EVM` system contract was first deployed.
 	// This is the first height at which the EVM state starts.
-	MainnetInitCadenceHeight = uint64(85981134)
+	// reference: https://github.com/onflow/flow/blob/9203b57a04d422360de257bcd92c522a2f51d3b0/sporks.json#L91
+	MainnetInitCadenceHeight = uint64(85981135)
 )
 
 type TxStateValidation string
@@ -80,6 +81,8 @@ type Config struct {
 	LogLevel zerolog.Level
 	// LogWriter defines the writer used for logging
 	LogWriter io.Writer
+	// Logger if you bring your own
+	Logger *zerolog.Logger
 	// RateLimit requests made by the client identified by IP over any protocol (ws/http).
 	RateLimit uint64
 	// Address header used to identified clients, usually set by the proxy

go.mod

@@ -4,15 +4,15 @@ go 1.25.0
 
 require (
 	github.com/cockroachdb/pebble v1.1.5
-	github.com/ethereum/go-ethereum v1.16.3
+	github.com/ethereum/go-ethereum v1.16.4
 	github.com/goccy/go-json v0.10.4
 	github.com/hashicorp/go-multierror v1.1.1
 	github.com/hashicorp/golang-lru/v2 v2.0.7
 	github.com/holiman/uint256 v1.3.2
-	github.com/onflow/atree v0.10.1
-	github.com/onflow/cadence v1.7.0
-	github.com/onflow/flow-go v0.43.1-rc.4.0.20250930135247-97f6643af6f8
-	github.com/onflow/flow-go-sdk v1.8.2
+	github.com/onflow/atree v0.11.0
+	github.com/onflow/cadence v1.8.1
+	github.com/onflow/flow-go v0.43.3-0.20251020174348-b36af5491350
+	github.com/onflow/flow-go-sdk v1.9.0
 	github.com/prometheus/client_golang v1.20.5
 	github.com/rs/cors v1.8.0
 	github.com/rs/zerolog v1.33.0
@@ -25,7 +25,7 @@ require (
 	go.uber.org/ratelimit v0.3.1
 	golang.org/x/exp v0.0.0-20241217172543-b2144cdd0a67
 	golang.org/x/sync v0.16.0
-	google.golang.org/grpc v1.75.0
+	google.golang.org/grpc v1.75.1
 )
 
 require (
@@ -58,7 +58,7 @@ require (
 	github.com/cockroachdb/tokenbucket v0.0.0-20230807174530-cc333fc44b06 // indirect
 	github.com/consensys/gnark-crypto v0.18.0 // indirect
 	github.com/coreos/go-semver v0.3.0 // indirect
-	github.com/crate-crypto/go-eth-kzg v1.3.0 // indirect
+	github.com/crate-crypto/go-eth-kzg v1.4.0 // indirect
 	github.com/crate-crypto/go-ipa v0.0.0-20240724233137-53bbb0ceb27a // indirect
 	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
 	github.com/deckarep/golang-set/v2 v2.6.0 // indirect
@@ -71,7 +71,8 @@ require (
 	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/ef-ds/deque v1.0.4 // indirect
 	github.com/emicklei/dot v1.6.2 // indirect
-	github.com/ethereum/c-kzg-4844/v2 v2.1.0 // indirect
+	github.com/ethereum/c-kzg-4844/v2 v2.1.3 // indirect
+	github.com/ethereum/go-bigmodexpfix v0.0.0-20250911101455-f9e208c548ab // indirect
 	github.com/ethereum/go-verkle v0.2.2 // indirect
 	github.com/felixge/httpsnoop v1.0.4 // indirect
 	github.com/ferranbt/fastssz v0.1.4 // indirect
@@ -89,7 +90,7 @@ require (
 	github.com/golang/glog v1.2.5 // indirect
 	github.com/golang/protobuf v1.5.4 // indirect
 	github.com/golang/snappy v0.0.5-0.20231225225746-43d5d4cd4e0e // indirect
-	github.com/google/pprof v0.0.0-20241210010833-40e02aabc2ad // indirect
+	github.com/google/pprof v0.0.0-20250630185457-6e76a2b096b5 // indirect
 	github.com/google/s2a-go v0.1.9 // indirect
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/googleapis/enterprise-certificate-proxy v0.3.6 // indirect
@@ -152,14 +153,14 @@ require (
 	github.com/onflow/flow-ft/lib/go/templates v1.0.1 // indirect
 	github.com/onflow/flow-nft/lib/go/contracts v1.3.0 // indirect
 	github.com/onflow/flow-nft/lib/go/templates v1.3.0 // indirect
-	github.com/onflow/flow/protobuf/go/flow v0.4.15 // indirect
+	github.com/onflow/flow/protobuf/go/flow v0.4.16 // indirect
 	github.com/onflow/go-ethereum v1.13.4 // indirect
 	github.com/onflow/sdks v0.6.0-preview.1 // indirect
 	github.com/onsi/ginkgo v1.16.4 // indirect
 	github.com/onsi/gomega v1.18.1 // indirect
 	github.com/pbnjay/memory v0.0.0-20210728143218-7b4eea64cf58 // indirect
 	github.com/pelletier/go-toml/v2 v2.2.1 // indirect
-	github.com/pierrec/lz4 v2.6.1+incompatible // indirect
+	github.com/pierrec/lz4/v4 v4.1.22 // indirect
 	github.com/pion/dtls/v2 v2.2.12 // indirect
 	github.com/pion/logging v0.2.2 // indirect
 	github.com/pion/stun/v2 v2.0.0 // indirect
@@ -184,7 +185,7 @@ require (
 	github.com/spf13/viper v1.15.0 // indirect
 	github.com/stretchr/objx v0.5.2 // indirect
 	github.com/subosito/gotenv v1.4.2 // indirect
-	github.com/supranational/blst v0.3.14 // indirect
+	github.com/supranational/blst v0.3.16-0.20250831170142-f48500c1fdbe // indirect
 	github.com/syndtr/goleveldb v1.0.1-0.20210819022825-2ae1ddf74ef7 // indirect
 	github.com/texttheater/golang-levenshtein/levenshtein v0.0.0-20200805054039-cae8b0eaed6c // indirect
 	github.com/tklauser/go-sysconf v0.3.12 // indirect
@@ -210,7 +211,7 @@ require (
 	golang.org/x/crypto v0.41.0 // indirect
 	golang.org/x/net v0.43.0 // indirect
 	golang.org/x/oauth2 v0.30.0 // indirect
-	golang.org/x/sys v0.35.0 // indirect
+	golang.org/x/sys v0.36.0 // indirect
 	golang.org/x/text v0.28.0 // indirect
 	golang.org/x/time v0.12.0 // indirect
 	golang.org/x/xerrors v0.0.0-20240903120638-7835f813f4da // indirect