feat(exit-certificate): remove options.addressDiscovery — Step A always runs state dump + Transfer logs

The two sources cover complementary blind spots (the dump for native-ETH
holders and contracts, the Transfer logs for token holders, including passive
ones), so any single-source run under-covers value. Step A now always runs
both and merges them; the receipt-harvesting fallback and its
options.stepAWindowSize tuning knob are removed along with the option — an
unusable debug_accountRange now fails Step A instead of degrading silently.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: joanestebanr

tools/exit_certificate/CLAUDE.md

@@ -83,13 +83,10 @@ The zero address is **kept** like any other account: tokens transferred to `0x00
 `totalSupply` (a plain transfer is not a burn) and it can hold native ETH, so dropping it would
 leave the certificate unbalanced against the LBT.
 
-- **Option:** `addressDiscovery` — `"auto"` (default: probe `debug_accountRange`, use dump + logs;
-  else fall back to receipt harvesting via `eth_getBlockByNumber` + `eth_getTransactionReceipt` in
-  `stepAWindowSize` windows, which misses internal value transfers), `"stateDump"`, `"logs"`, `"both"`.
-  The sources cover complementary blind spots — the dump cannot see token-only EOAs (not in the
-  account trie) and the logs cannot see accounts that never touched a wrapped token (native-ETH
-  holders, contracts) — so the single-source modes are debugging aids: a run on one source
-  under-covers value and Step F aborts on the LBT mismatch. Use `auto`/`both` for real runs.
+Both sources always run and merge — they cover complementary blind spots (the dump cannot see
+token-only EOAs, not in the account trie; the logs cannot see accounts that never touched a wrapped
+token: native-ETH holders, contracts). There is no fallback: an unusable dump fails Step A.
+
 - **Output:** `step-a-addresses.json` (`[]common.Address`)
 
 ### Step B — EOA balance checking + ERC-20 detection
@@ -409,9 +406,9 @@ Defaults applied by `LoadConfig`:
 - **File chain with capping:** when `ignoreBalanceMismatch=true` produces a capped cert, the effective chain becomes: Step D → Step E → **Step F (capped)** → Step G → … Always check whether `step-f-capped-certificate.json` exists when investigating balance issues.
 - **`--verbose` flag:** the logger defaults to `info` level; pass `--verbose` to enable `debug` output.
 - **SC-locked value can be negative** when genesis state was pre-loaded or the LBT is stale — the genesis-balance guard (`ignoreGenesisBalance=false`, the default) catches this early.
-- **Step A needs an archive node.** `debug_accountRange` at `targetBlock` is the preferred source;
-  when unavailable, the `auto` discovery mode falls back to receipt harvesting (which misses internal
-  value transfers).
+- **Step A needs an archive node exposing `debug_accountRange`.** The state dump at `targetBlock`
+  is mandatory (no fallback): without it Step A fails, since native-ETH holders and contracts would
+  be silently omitted.
 - **Step G2 requires Anvil only in shadow-fork mode** (`options.verifyNewLocalExitRootUsingShadowFork=true`; `anvil` binary in `$PATH`, from the Foundry toolchain). The default off-chain mode needs no Anvil.
 - **FEP chains are not supported.** Only Pessimistic Proof certificates are generated.
 - **`SetClaim` and `UpdatedUnsetGlobalIndexHashChain` events are not handled** — value from those flows may be missing.

tools/exit_certificate/README.md

@@ -84,7 +84,7 @@ The field names are identical in both formats. Pass whichever you created with `
 
 | Field | Required | Description |
 | :---: | :------: | :---------: |
-| `l2RpcUrl` | Yes | L2 JSON-RPC endpoint. Step A uses `debug_accountRange` when available (an archive node is required to query state at `targetBlock`); without it, the `auto` discovery mode falls back to receipt harvesting. |
+| `l2RpcUrl` | Yes | L2 JSON-RPC endpoint. Step A requires `debug_accountRange` (an archive node exposing the `debug` namespace, to query state at `targetBlock`); without it Step A fails. |
 | `l1RpcUrl` | Yes* | L1 JSON-RPC endpoint. Required by Step E (unclaimed deposit detection) and Step I (`L1InfoTreeLeafCount`). Without it Step E is silently skipped and Step I fails — the resulting certificate will be incomplete. |
 | `l2BridgeAddress` | Yes | L2 bridge contract address. |
 | `l1BridgeAddress` | No | L1 bridge contract address. Defaults to `l2BridgeAddress`. |
@@ -104,14 +104,12 @@ The field names are identical in both formats. Pass whichever you created with `
 | Field | Default | Description |
 | :---: | :-----: | :---------: |
 | `blockRange` | `5000` | Block range per `eth_getLogs` query (Steps 0, B, E). |
-| `stepAWindowSize` | `150000` | Number of blocks loaded into memory per iteration by Step A's receipt-harvesting fallback (used when `debug_accountRange` is unavailable in `auto` mode). |
 | `concurrencyLimit` | `20` | Max concurrent RPC requests. |
 | `rpcBatchSize` | `200` | Max calls per JSON-RPC batch request. |
 | `rpcDelayMs` | `0` | Delay between RPC batches (rate limiting). |
 | `outputDir` | `./output` | Directory for intermediate and final output files. Relative paths resolve from the config file directory. |
 | `l1StartBlock` | `0` | L1 block to start scanning from (Step E). |
-| `l2StartBlock` | `0` | L2 block to start scanning from (Step A's receipt-harvesting fallback only; the state dump reads the trie at `targetBlock` and the Transfer-log scan always starts at genesis). |
-| `addressDiscovery` | `"auto"` | Step A address-discovery strategy: `"auto"` (probe `debug_accountRange` and use state dump + Transfer logs, else fall back to receipt harvesting + Transfer logs), `"stateDump"`, `"logs"`, or `"both"`. The two sources cover complementary blind spots, so the single-source modes are for debugging only: `"stateDump"` misses token-only EOAs and `"logs"` misses native-ETH holders and contracts (see [Step A](#step-a--collect-addresses)). Unknown values fall back to `"auto"` with a warning. |
+| `l2StartBlock` | `0` | Sanity guard: Step A errors if `targetBlock` is below this value. The state dump reads the trie at `targetBlock` and the Transfer-log scan always starts at genesis. |
 | `agglayerAdminURL` | `""` | Agglayer admin RPC endpoint. Required for Step F in agglayer mode (Step F errors if it runs without this set). Not needed when `useAgglayerAdminToStepFCheck: false` (offline LBT mode). |
 | `agglayerAdminToken` | `""` | Optional bearer token for authenticating requests to `agglayerAdminURL`. Leave empty when the admin endpoint is unauthenticated; set it only when the endpoint is protected (e.g. behind Google Cloud IAP). |
 | `agglayerClient` | `{}` | Agglayer gRPC client config (same as aggsender's `agglayer.ClientConfig`). Set at least `agglayerClient.GRPC.URL`. Required for Steps H, SUBMIT, and WAIT. |
@@ -220,7 +218,7 @@ This produces and signs the certificate but **does not submit it**. SUBMIT and W
 | :--: | ---- | ------------ |
 | CHECK | Verify prerequisites | Checks Anvil, L1 RPC, network type (PP only), threshold = 1, no custom gas token. |
 | 0 | Generate LBT | Resolves `targetBlock` to a concrete block number, then scans `NewWrappedToken` events and fetches `totalSupply` per wrapped token at that block. |
-| A | Collect addresses | Discovers every value-holding address from the final state (`debug_accountRange` state dump) plus `Transfer` event logs per wrapped token. Strategy selected by `addressDiscovery` (`auto` falls back to receipt harvesting when `debug_accountRange` is unavailable). |
+| A | Collect addresses | Discovers every value-holding address from the final state (`debug_accountRange` state dump, for native-ETH holders and contracts) plus `Transfer` event logs per wrapped token (for token holders). Both sources always run and merge. |
 | B | EOA balances + ERC-20 detection | B1: classifies addresses and fetches ETH/token balances for EOAs. B2: probes contracts for the ERC-20 interface and checks if they hold tracked wrapped tokens. B3: fetches holder breakdowns for `extraErc20Contracts` (skips any already processed by B2). |
 | C | SC-locked value | Computes value locked in contracts: `SC_locked = LBT_totalSupply − EOA_accumulated` per token. With `nativeSCLockedFromContracts=true` the native token's SC-locked value is measured from actual contract ETH balances instead. |
 | D | Build certificate | Creates the `Certificate` with `BridgeExit` entries for every (EOA, token) pair, every decomposed ERC-20 holder (Step C holder bridges), and every token with SC-locked value. |
@@ -317,18 +315,9 @@ Discovers every value-holding address at `targetBlock` from the **final state**
 1. **State dump** — walks the entire account trie at `targetBlock` via paginated `debug_accountRange` calls: every account with non-zero balance/nonce/code (all native-ETH holders and every contract) in `O(#accounts)`. The node's `debug_accountRange` dialect (geth vs erigon/cdk-erigon) is auto-detected on the first page.
 2. **`Transfer` event logs** — scans `eth_getLogs` for each wrapped token (list from the Step 0 LBT) across `[0, targetBlock]`, collecting the indexed `from`/`to` of every `Transfer`. This surfaces token-only EOAs that have no nonce/balance/code and therefore appear in neither a state dump nor a trace. The scan deliberately starts at block 0 (not `l2StartBlock`) so passive holders that received tokens early are not dropped.
 
-The strategy is selected by `options.addressDiscovery`:
+Both sources always run and their results are merged: they cover complementary blind spots (the state dump cannot see token-only EOAs, which do not exist in the account trie; the Transfer logs cannot see accounts that never touched a wrapped token, i.e. native-ETH holders and contracts), so neither is sufficient on its own.
 
-| Value | Behaviour |
-| ----- | --------- |
-| `auto` (default) | Probe `debug_accountRange`; if supported, use state dump + Transfer logs. Otherwise fall back to **receipt harvesting** (block bodies + `eth_getTransactionReceipt` from `l2StartBlock`, in windows of `options.stepAWindowSize`) + Transfer logs, with a warning — the fallback misses internal value transfers (a CALL with value to a fresh address leaves no receipt entry). |
-| `stateDump` | State dump only. **Misses token-only EOAs**: an ERC-20 transfer only mutates the token contract's storage, so a recipient with no nonce/balance/code does not exist in the account trie. |
-| `logs` | Transfer logs only. **Misses native-ETH holders and contracts**: an account that never sent or received a wrapped token appears in no `Transfer` event, so it is never discovered and Step B never fetches its balances. (Addresses that *are* discovered do get both their token **and** ETH balances fetched.) |
-| `both` | State dump + Transfer logs; errors if `debug_accountRange` is unavailable. |
-
-The two sources cover complementary blind spots, so **`stateDump` and `logs` alone are debugging modes** (e.g. to isolate one source or compare their outputs) — a certificate generated from a single source under-covers value and Step F will abort on the resulting LBT mismatch. Use `auto` or `both` for a real run.
-
-The state dump fails loudly (instead of returning a truncated or empty set) when the node keeps returning a non-empty pagination cursor past the page cap or returns 0 accounts (e.g. a geth archive node without address preimages) — in `auto` mode the latter triggers the receipt-harvesting fallback.
+The state dump fails loudly (instead of returning a truncated or empty set) when `debug_accountRange` is unavailable, when the node keeps returning a non-empty pagination cursor past the page cap, or when it returns 0 accounts (e.g. a geth archive node without address preimages) — there is no fallback, since a run without the dump would silently omit every native-ETH holder and contract.
 
 The **zero address** (`0x000…000`) is treated like any other account: a plain `transfer(0x0, amount)` is not a burn (the tokens remain in `totalSupply`) and native ETH can be sent there too, so its balances must be scanned and covered by the certificate for the totals to reconcile with the LBT.
 

tools/exit_certificate/cmd/main.go

@@ -26,10 +26,8 @@ Pipeline steps (run in order by default):
      for wrapped token mappings.
 
   A  Collect every value-holding address at the target block via a state-trie
-     dump (debug_accountRange) plus Transfer-event logs per wrapped token.
-     Strategy is set via options.addressDiscovery (auto | stateDump | logs |
-     both); "auto" falls back to receipt harvesting when debug_accountRange is
-     unavailable.
+     dump (debug_accountRange, for native-ETH holders and contracts) plus
+     Transfer-event logs per wrapped token (for token holders).
 
   B  Scan EOA native-token balances and wrapped-token balances for every address
      found in step A.

tools/exit_certificate/config-examples/zkevm-cardona.toml

@@ -38,14 +38,12 @@ Password = "<PASSWORD>"
 
 [options]
 blockRange = 10000
-stepAWindowSize = 10000
 concurrencyLimit = 10
 rpcBatchSize = 99
 rpcDelayMs = 10
 outputDir = "./output-cardona"
 l1StartBlock = 5157692
 l2StartBlock = 0
-addressDiscovery = "auto"
 ignoreGenesisBalance = false
 ignoreUnclaimed = false
 ignoreBalanceMismatch = false

tools/exit_certificate/config-examples/zkevm-mainnet.toml

@@ -38,14 +38,12 @@ Password = "<PASSWORD>"
 
 [options]
 blockRange = 10000
-stepAWindowSize = 20000
 concurrencyLimit = 200
 rpcBatchSize = 99
 rpcDelayMs = 10
 outputDir = "./output-mainnet"
 l1StartBlock = 22431675
 l2StartBlock = 0
-addressDiscovery = "auto"
 ignoreGenesisBalance = false
 ignoreUnclaimed = false
 ignoreBalanceMismatch = false

tools/exit_certificate/config.go

@@ -19,11 +19,7 @@ import (
 
 // Options holds tuning parameters for RPC parallelism and output.
 type Options struct {
-	BlockRange int `json:"blockRange"`
-	// StepAWindowSize is the number of blocks loaded into memory at once by Step A's
-	// receipt-harvesting fallback (used when debug_accountRange is unavailable in "auto" mode).
-	// Defaults to 150000, independently of BlockRange.
-	StepAWindowSize  int    `json:"stepAWindowSize"`
+	BlockRange       int    `json:"blockRange"`
 	ConcurrencyLimit int    `json:"concurrencyLimit"`
 	RPCBatchSize     int    `json:"rpcBatchSize"`
 	RPCDelayMs       int    `json:"rpcDelayMs"`
@@ -52,12 +48,6 @@ type Options struct {
 	// genesis premint, clamping to 0 and silently dropping contract-held ETH. Set to false to fall
 	// back to the LBT − EOA derivation for the native token.
 	NativeSCLockedFromContracts bool `json:"nativeSCLockedFromContracts"`
-	// AddressDiscovery selects the strategy used by Step A to collect value-holding addresses:
-	// "stateDump" (debug_accountRange only), "logs" (Transfer logs only), "both", or "auto"
-	// (the default: probe debug_accountRange and use both, else fall back to receipt harvesting
-	// plus Transfer logs). The single-source modes are debugging aids — the dump misses token-only
-	// EOAs and the logs miss native-ETH holders and contracts — so real runs need "auto" or "both".
-	AddressDiscovery string `json:"addressDiscovery"`
 	// IgnoreBalanceMismatch suppresses the error returned by Step F when token balances
 	// do not match. Set to true only when investigating discrepancies without blocking the pipeline.
 	IgnoreBalanceMismatch bool `json:"ignoreBalanceMismatch"`
@@ -153,21 +143,18 @@ type Config struct {
 
 const (
 	defaultBlockRange       = 5000
-	defaultStepAWindowSize  = 150000
 	defaultConcurrencyLimit = 20
 	defaultRPCBatchSize     = 200
 )
 
 var defaultOptions = Options{
 	BlockRange:                            defaultBlockRange,
-	StepAWindowSize:                       defaultStepAWindowSize,
 	ConcurrencyLimit:                      defaultConcurrencyLimit,
 	RPCBatchSize:                          defaultRPCBatchSize,
 	RPCDelayMs:                            0,
 	OutputDir:                             "output",
 	L1StartBlock:                          0,
 	L2StartBlock:                          0,
-	AddressDiscovery:                      addressDiscoveryAuto,
 	UseAgglayerAdminToStepFCheck:          true,
 	VerifyNewLocalExitRootUsingShadowFork: true,
 	CapMode:                               CapModeNone,
@@ -410,9 +397,6 @@ func mergeScalarOptions(opts *Options, raw *rawOpts, configDir string) {
 	if raw.BlockRange > 0 {
 		opts.BlockRange = raw.BlockRange
 	}
-	if raw.StepAWindowSize > 0 {
-		opts.StepAWindowSize = raw.StepAWindowSize
-	}
 	if raw.ConcurrencyLimit > 0 {
 		opts.ConcurrencyLimit = raw.ConcurrencyLimit
 	}
@@ -431,9 +415,6 @@ func mergeScalarOptions(opts *Options, raw *rawOpts, configDir string) {
 	if raw.L2StartBlock > 0 {
 		opts.L2StartBlock = raw.L2StartBlock
 	}
-	if raw.AddressDiscovery != "" {
-		opts.AddressDiscovery = raw.AddressDiscovery
-	}
 	if raw.AgglayerAdminURL != "" {
 		opts.AgglayerAdminURL = raw.AgglayerAdminURL
 	}
@@ -531,14 +512,12 @@ type rawConfig struct {
 
 type rawOpts struct {
 	BlockRange                            int                    `json:"blockRange"`
-	StepAWindowSize                       int                    `json:"stepAWindowSize"`
 	ConcurrencyLimit                      int                    `json:"concurrencyLimit"`
 	RPCBatchSize                          int                    `json:"rpcBatchSize"`
 	RPCDelayMs                            int                    `json:"rpcDelayMs"`
 	OutputDir                             string                 `json:"outputDir"`
 	L1StartBlock                          uint64                 `json:"l1StartBlock"`
 	L2StartBlock                          uint64                 `json:"l2StartBlock"`
-	AddressDiscovery                      string                 `json:"addressDiscovery"`
 	AgglayerAdminURL                      string                 `json:"agglayerAdminURL"`
 	AgglayerAdminToken                    string                 `json:"agglayerAdminToken"`
 	AgglayerClient                        *agglayer.ClientConfig `json:"agglayerClient"`

tools/exit_certificate/config_test.go

@@ -345,59 +345,13 @@ func TestLoadConfig_DefaultOptions(t *testing.T) {
 	cfg, err := LoadConfig(path)
 	require.NoError(t, err)
 	require.Equal(t, 5000, cfg.Options.BlockRange)
-	require.Equal(t, 150000, cfg.Options.StepAWindowSize)
 	require.Equal(t, 20, cfg.Options.ConcurrencyLimit)
 	require.Equal(t, 200, cfg.Options.RPCBatchSize)
 	require.Equal(t, 0, cfg.Options.RPCDelayMs)
 	require.Equal(t, uint64(0), cfg.Options.L1StartBlock)
 	require.True(t, cfg.Options.UseAgglayerAdminToStepFCheck)
 }
 
-func TestLoadConfig_StepAWindowSize(t *testing.T) {
-	t.Parallel()
-
-	t.Run("explicit value is read from file", func(t *testing.T) {
-		t.Parallel()
-
-		path := filepath.Join(t.TempDir(), "cfg.json")
-		data := `{
-			"l2RpcUrl": "http://localhost:8545",
-			"l2BridgeAddress": "0x2a3DD3EB832aF982ec71669E178424b10Dca2EDe",
-			"exitAddress": "0x0000000000000000000000000000000000000001",
-			"targetBlock": "100",
-			"options": {
-				"agglayerAdminURL": "https://admin.example.com",
-				"stepAWindowSize": 2000
-			}
-		}`
-		require.NoError(t, os.WriteFile(path, []byte(data), 0o600))
-
-		cfg, err := LoadConfig(path)
-		require.NoError(t, err)
-		require.Equal(t, 2000, cfg.Options.StepAWindowSize)
-	})
-
-	t.Run("defaults to 5000 when absent", func(t *testing.T) {
-		t.Parallel()
-
-		path := filepath.Join(t.TempDir(), "cfg.json")
-		data := `{
-			"l2RpcUrl": "http://localhost:8545",
-			"l2BridgeAddress": "0x2a3DD3EB832aF982ec71669E178424b10Dca2EDe",
-			"exitAddress": "0x0000000000000000000000000000000000000001",
-			"targetBlock": "100",
-			"options": {
-				"agglayerAdminURL": "https://admin.example.com"
-			}
-		}`
-		require.NoError(t, os.WriteFile(path, []byte(data), 0o600))
-
-		cfg, err := LoadConfig(path)
-		require.NoError(t, err)
-		require.Equal(t, defaultStepAWindowSize, cfg.Options.StepAWindowSize)
-	})
-}
-
 func TestLoadConfig_RelativeOutputDir(t *testing.T) {
 	t.Parallel()
 
@@ -524,7 +478,6 @@ func TestMergeOptions_BoolFlags(t *testing.T) {
 		"options": {
 			"agglayerAdminURL": "https://admin.example.com",
 			"ignoreGenesisBalance": true,
-			"addressDiscovery": "stateDump",
 			"ignoreBalanceMismatch": true,
 			"ignoreUnclaimed": true
 		}
@@ -534,7 +487,6 @@ func TestMergeOptions_BoolFlags(t *testing.T) {
 	cfg, err := LoadConfig(path)
 	require.NoError(t, err)
 	require.True(t, cfg.Options.IgnoreGenesisBalance)
-	require.Equal(t, addressDiscoveryStateDump, cfg.Options.AddressDiscovery)
 	require.True(t, cfg.Options.IgnoreBalanceMismatch)
 	require.True(t, cfg.Options.IgnoreUnclaimed)
 }