feat(exit-certificate): adapt certificate generation to testnet genesis premints (genesisPrefundETHWei, capMode, nativeSCLockedFromContracts)

[joanestebanr]

🎯 Motivation / Context

This PR adapts the exit-certificate tool to the particularities of testnets, where native funds
are pre-loaded at genesis (e.g. 110,000 ETH on Kurtosis enclaves, 100,000 ETH on Cardona). That
premint breaks several steps of the pipeline, because it inflates account balances without any
matching agglayer deposit:

• The Step F balance check fails: the certificate's native exits include the premint, but the
  agglayer balance and the Step 0 LBT only count genuinely bridged funds.
• The Step C native SC-locked formula (LBT − EOA_accumulated) underflows, clamps to 0 and
  silently drops contract-held ETH from the certificate.
• The premint itself has no collateral on the agglayer, so it can never be bridged out — the
  certificate must always be capped to the bridged amount.

🔄 Changes Summary

• options.genesisPrefundETHWei — declares the native amount (Wei, decimal string) preminted at
  genesis:
  • Step B verifies the declared value against the detected genesis ETH preload total (sum of
    balances at block 0); a mismatch is fatal even with ignoreGenesisBalance=true, since Step F
    would otherwise discount the wrong amount. The genesis-preload error message now explains that
    pre-funding accounts at genesis is not allowed and points at ignoreGenesisBalance=true.
  • Step F subtracts the value from the native-token certificate sum before both the
    agglayer three-way and offline comparisons (via discountGenesisPrefund, floored at zero),
    logging the certificate total, the pre-fund and the difference — so the check balances against
    the genuinely bridged amount.
  • The pre-fund has no agglayer collateral, so even when every check matches Step F emits
    step-f-capped-certificate.json trimming the native exits to min(agglayer, lbt) — no
    ignoreBalanceMismatch needed.
  • Validated by LoadConfig (non-negative base-10 integer).
• options.capMode — "amount" (default) or "appearance". Controls how Step F allocates each
  token's cap budget when trimming exits. "amount" serves the smallest-amount exits first so the
  largest holders (the premint whales) are capped/dropped first; "appearance" serves exits in
  appearance order. Surviving exits keep their original order in both modes. capCertificateExits
  reworked into a greedy per-token allocator.
• options.nativeSCLockedFromContracts — when true (the default), Step C measures the native
  token's SC-locked value directly by summing the ETH held by contract accounts at targetBlock
  (excluding the L2 bridge reserve), instead of deriving it as LBT − EOA_accumulated, which
  underflows on premint chains. Wrapped tokens keep the formula; set to false to fall back to the
  derivation for the native token.
• Step A no longer excludes the zero address — 0x000…000 can hold value (e.g. burned funds)
  that the certificate must account for, so it stays in the collected address set.
• Step F agglayer LBT dump — whenever agglayerAdminURL is set, Step F queries
  admin_getTokenBalance once up front and writes the raw LBT to step-f-agglayer-lbt.json,
  regardless of comparison mode (skipped when OutputDir is unset, i.e. hand-built configs). In
  agglayer mode the response is reused (no second RPC). Added scripts/get-agglayer-lbt.sh to fetch
  the same LBT manually.
• Step F mismatch logs now include the signed certificate−agglayer / certificate−lbt
  differences (collapsed into one when LBT == agglayer).

⚠️ Breaking Changes

• capMode defaults to "amount": with ignoreBalanceMismatch=true, the default cap outcome
  changes (previously appearance-order allocation).
• nativeSCLockedFromContracts defaults to true: Step C now measures the native SC-locked value
  from contract balances by default (set to false for the previous LBT − EOA derivation).
• Step A now includes the zero address in the collected set, so its balances can appear in the
  certificate.

📋 Config Updates

Three new fields under options (all reflected in parameters.toml.example /
parameters.json.example):

• 🧾 genesisPrefundETHWei — amount of native token preminted at genesis, in Wei, as a
  decimal string.
  • Purpose: tells the tool how much native value exists on the chain without agglayer collateral.
    Step B verifies it against the preload actually detected at block 0 (a mismatch aborts, even
    with ignoreGenesisBalance=true); Step F discounts it from the native certificate sum before
    the balance comparison and always emits a capped certificate trimming the native exits to
    min(agglayer, lbt), since the premint can never be bridged out.
  • Values: "" (default — feature disabled, no discount and no premint capping) or any
    non-negative base-10 integer, e.g. "100000000000000000000000" (100,000 ETH). Negative or
    non-numeric values are rejected by LoadConfig.
• 🧾 capMode — allocation order used when Step F trims a token's bridge exits to its cap
  budget.
  • Purpose: decides which holders absorb the cut when the certificate's exits exceed the
    collateral (mismatch with ignoreBalanceMismatch=true, or the premint capping above).
  • Values: "amount" (default) — serves the smallest exits first, so the largest holders
    (typically the premint whales) are capped/dropped first and small legitimate holders keep their
    full exits; "appearance" — serves exits in the order they appear in the certificate. Any other
    value is rejected by LoadConfig. Surviving exits keep their original order in both modes.
• 🧾 nativeSCLockedFromContracts — how Step C computes the native token's SC-locked value
  (the amount bridged to exitAddress).
  • Purpose: the derived formula LBT − EOA_accumulated underflows on premint chains (EOA
    balances include the premint, the LBT does not), clamping to 0 and silently dropping
    contract-held ETH from the certificate.
  • Values: true (default) — measure it directly by summing eth_getBalance of every contract
    account at targetBlock, excluding the L2 bridge (its balance is the un-released native
    reserve); false — keep the LBT − EOA derivation. Wrapped tokens always use the formula,
    regardless of this flag.

Example configs updated accordingly:

• 🧾 config-examples/zkevm-cardona.toml sets genesisPrefundETHWei to the 100,000 ETH minted at
  genesis on Cardona.
• 🧾 scripts/configuration_based_on_kurtosis.sh sets genesisPrefundETHWei to the 110,000 ETH
  preminted by the Kurtosis enclave (overridable via the GENESIS_PREFUND_ETH_WEI env var).

✅ Testing

• 🤖 Automatic: go test ./tools/exit_certificate/... — added tests for the pre-fund discount
  and always-cap behaviour (TestDiscountGenesisPrefund,
  TestCompareTokenBalances_GenesisPrefundDiscount, TestRunStepF_PrefundMatchedStillCapsToLBT,
  TestRunStepF_NoPrefundNoCapOnAllMatch), the Step B preload verification
  (TestCheckDeclaredGenesisPrefund, TestRunStepB1GenesisPrefundDeclared), the Step C contract
  measurement (TestRunStepC_NativeSCLockedFromContracts, TestSumContractNativeBalances,
  TestApplyNativeContractLocked), cap allocation (TestLoadConfig_CapMode,
  TestCapCertificateExits_ByAmount*), config loading (TestLoadConfig_GenesisPrefundETHWei) and
  the LBT dump guard (TestRunStepF_EmptyOutputDir_SkipsLBTDump).
• 🧪 Manual: full pipeline run against a Kurtosis enclave
  (scripts/configuration_based_on_kurtosis.sh).

📝 Notes

• An ignoreAddresses option (exclude specific accounts from the certificate exits) was initially
  part of this PR but was removed before merging: it is not in use and complicated other in-flight
  PRs. The branch name still reflects it; the branch will be deleted after merge.
• README/CLAUDE.md docs were audited against the code and corrected (e.g. stepAWindowSize default,
  rollupManagerAddress, Step D holder-bridge exits, conditional Step C/E outputs).

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fbd239ec2b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

Adds new exit-certificate configuration knobs to handle testnet “genesis-preload” balances (via address exclusion and configurable capping strategy), and improves Step F traceability by always persisting the agglayer-side LBT when an admin endpoint is configured.

Changes:

• Introduces options.ignoreAddresses (validated) and wires Step B outputs to record+exclude those balances (step-b-ignored-balances.json).
• Adds options.capMode (amount default / appearance) and updates Step F capping logic to allocate per-token budget according to the selected mode.
• Updates Step F to dump agglayer LBT to step-f-agglayer-lbt.json when agglayerAdminURL is set, plus adds a helper script to fetch it manually.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tools/exit_certificate/types.go	Extends Step B/F result structs and clarifies capped-certificate semantics.
tools/exit_certificate/step_f.go	Adds agglayer LBT dump + capMode-aware capping allocator implementation.
tools/exit_certificate/step_f_test.go	Updates existing cap tests and adds new coverage for CapModeByAmount.
tools/exit_certificate/step_b.go	Extracts and removes ignored-address balances before building EOA/accumulated outputs.
tools/exit_certificate/step_b_helpers_test.go	Adds unit test for extractIgnoredBalances.
tools/exit_certificate/scripts/get-agglayer-lbt.sh	New helper script to fetch agglayer LBT via admin_getTokenBalance.
tools/exit_certificate/run.go	Persists ignored-balances output and threads capMode into final-certificate capping.
tools/exit_certificate/README.md	Documents new options and updated Step F behavior/output.
tools/exit_certificate/parameters.toml.example	Adds capMode and ignoreAddresses examples and updates Step F description.
tools/exit_certificate/parameters.json.example	Adds capMode and ignoreAddresses examples.
tools/exit_certificate/filenames.go	Adds new output filenames for ignored balances and agglayer LBT dump.
tools/exit_certificate/config.go	Adds options, defaults, validation, and merging for ignoreAddresses and capMode.
tools/exit_certificate/config_test.go	Adds tests for ignoreAddresses and capMode validation/defaulting.
tools/exit_certificate/CLAUDE.md	Updates internal tool documentation to reflect new options and Step F LBT dump.

[joanestebanr]

@claude

[joanestebanr]

@codex review

[claude]

Claude finished @joanestebanr's task in 1m 57s —— View job

---

PR Review Complete ✅

🚀 What's New

This PR adapts the exit-certificate tool for testnets where funds are pre-loaded at genesis (typically 100,000 ETH). Genesis-injected native funds inflate the native-token LBT total without a matching agglayer deposit, causing Step F balance check failures. The PR introduces:

• genesisPrefundETHWei option: Declares the genesis-minted amount so Step F subtracts it from the native LBT entry before comparing
• capMode option: Controls how Step F allocates cap budgets when trimming exits ("amount" favors small holders, "appearance" uses original order)
• nativeSCLockedFromContracts (default true): Step C measures native SC-locked value from contract ETH balances instead of LBT − EOA derivation
• Step F agglayer LBT dump: Always persists step-f-agglayer-lbt.json when agglayerAdminURL is set
• Step A includes zero address: 0x000…000 can hold value (e.g., burned funds) and is now included in address collection

🐛 Bug Fixes

None - this is primarily a feature enhancement for testnet support.

📋 Config Updates

• genesisPrefundETHWei: Optional decimal string in Wei (e.g., "100000000000000000000000" for 100,000 ETH). Default: ""
• capMode: "amount" (default) or "appearance". Default: "amount"
• nativeSCLockedFromContracts: Boolean, default: true
• Example: Cardona config now sets genesisPrefundETHWei = "100000000000000000000000"

⚠️ Breaking Changes

Minor behavior change: capMode defaults to "amount" (previously behavior was appearance-order). When ignoreBalanceMismatch=true, the default cap outcome changes to favor small holders over large ones.

---

Code Review Findings

🔴 Required Issues

None found - code quality is high with appropriate safety checks.

🟡 Suggested Improvements

1. Magic Number in decimalBase Constant (config.go, step_b.go, step_f.go)

Priority: Low
Location: Multiple files use base-10 parsing with inline decimalBase references

The code uses decimalBase (value 10) for base-10 integer parsing throughout. This is fine, but decimalBase isn't defined - I suspect it's defined elsewhere as a const. Consider making it a package-level constant if not already:

const decimalBase = 10

Current locations using it:

• config.go:242, 214, 309, 321, 417
• step_b.go:214
• step_f.go:139, 154, 309, 415

2. Verbose Step F Mismatch Logging

Priority: Low
Location: step_f.go:93-108

The mismatch logging includes redundant information when LBT equals agglayer. The conditional formatting helps, but could be simplified:

if c.LBTAmount != "" && c.LBTAmount != c.AgglayerAmount {
    // Show both diffs only when different
}

This is actually well-handled already - good job!

3. Consider Extracting Cap Allocation Logic

Priority: Low
Location: step_f.go:477-589

The capCertificateExits function is quite complex (110+ lines). The logic is clear, but consider extracting the allocation order computation and cap application into separate helper functions for better testability:

// computeCapOutcomes(exits, remaining, mode) -> []capExit
// applyCapOutcomes(exits, outcomes) -> []*BridgeExit

Current implementation is acceptable, but this would improve maintainability.

4. Genesis Prefund Validation Edge Case

Priority: Low
Location: step_b.go:210-226 (checkDeclaredGenesisPrefund)

The validation compares declared genesis prefund against detected EOA balances at block 0. However, if an EOA was funded at genesis but is not in the Step A address collection (because it never transacted), the comparison would be incorrect. This is probably an acceptable risk since:

• Such addresses would also be missing from the certificate
• The guard is already strong enough for typical cases

Consider adding a note in the documentation about this edge case.

🟢 Optional Observations

1. Excellent Test Coverage

The PR includes comprehensive test coverage:

• TestLoadConfig_GenesisPrefundETHWei
• TestLoadConfig_CapMode
• TestCapCertificateExits_ByAmountCapsLargest
• TestCapCertificateExits_ByAmountDropsLargest
• TestCheckDeclaredGenesisPrefund
• TestRunStepB1GenesisPrefundDeclared
• TestDiscountGenesisPrefund
• TestCompareTokenBalances_GenesisPrefundDiscount
• TestRunStepC_NativeSCLockedFromContracts

SonarQube reports 91.1% coverage on new code - excellent!

2. Good Separation of Concerns

The implementation cleanly separates:

• Config validation (LoadConfig)
• Genesis prefund detection (checkGenesisBalances)
• Genesis prefund discount (discountGenesisPrefund)
• Cap allocation logic (capCertificateExits, capAllocationOrder)

3. Comprehensive Documentation

README.md and CLAUDE.md are well-maintained and accurately reflect the new options. The PR description is exceptionally detailed.

4. Robust Error Handling

• Genesis prefund mismatch is never suppressed (even with ignoreGenesisBalance=true)
• Negative values are caught at config loading time
• Invalid cap modes are rejected early
• Step F LBT dump is skipped safely when OutputDir is empty

5. Good Logging Practices

The implementation includes appropriate logging at all levels:

• Info level for normal operations
• Warn level for mismatches and edge cases (e.g., genesis preload)
• Debug level for detailed cap operation traces

---

Security Considerations

✅ No Security Issues Found

The implementation includes appropriate security measures:

1. Input Validation: genesisPrefundETHWei is validated as non-negative base-10 integer at config load time
2. Genesis Prefund Verification: Declared prefund is verified against detected genesis balances (line step_b.go:179-181)
3. Underflow Protection: Genesis prefund discount is floored at zero (step_f.go:173-177)
4. Safe Cap Budget: Cap budget stays min(agglayer, lbt) regardless of prefund discount
5. No Privilege Escalation: New features don't introduce privilege escalation risks

---

Performance Considerations

✅ No Performance Concerns

• Step F LBT dump: Only writes when OutputDir is set (avoids accidental file pollution)
• Native contract balance sum: Uses existing batch RPC infrastructure with appropriate concurrency limits
• Cap allocation: O(n log n) for amount-based sorting, which is acceptable for typical exit counts
• Genesis balance check: Reuses existing fetchETHBalances infrastructure

---

Code Quality Assessment

✅ Excellent Overall

• Go best practices: Follows Go conventions (errors wrapped with context, early returns, clear naming)
• Repository standards: Adheres to CLAUDE.md guidelines (uses require in tests, proper error wrapping)
• Type safety: Uses *big.Int for all amount handling (no float precision issues)
• Immutability: capExitCopy creates deep copies to avoid modifying original certificate
• Testing: Comprehensive unit tests with good edge case coverage
• Documentation: README accurately describes new options with examples

---

Recommendations

For Immediate Merge

✅ This PR is ready to merge. No blocking issues found.

For Future Improvements

1. Consider extracting capCertificateExits helper functions for better testability (low priority)
2. Document the genesis prefund EOA collection edge case in README (low priority)
3. Verify decimalBase is defined as a package constant (trivial)

---

Summary

This is a well-designed, thoroughly tested, and carefully implemented feature for handling testnet genesis pre-funds. The code quality is high, with appropriate safety checks, comprehensive test coverage (91.1%), and excellent documentation. The implementation correctly handles the complex interaction between genesis prefunds, LBT totals, and agglayer balance comparisons.

Recommendation: ✅ Approve and merge

The minor suggestions above are optional improvements that don't block merging. Great work! 🎉

---

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f7ad6bc5c9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[sonarqubecloud]

Quality Gate passed

Issues
5 New issues
0 Accepted issues

Measures
0 Security Hotspots
91.4% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud