Skip to content

fix(sdk-coin-eth): enforce strict ERC-7984 consolidation verification on test/staging (CECHO-2719) - #10192

Draft
nvrakesh06 wants to merge 2 commits into
masterfrom
nvrakeshreddy/cecho-2719-bitgojs
Draft

nvrakesh06 wants to merge 2 commits into
masterfrom
nvrakeshreddy/cecho-2719-bitgojs

Conversation

@nvrakesh06

@nvrakesh06 nvrakesh06 commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Description

Fixes the client-side verification gap from CECHO-2719: Erc7984Token.verifyConfidentialConsolidation — the verifier for ERC-7984 forwarder consolidation (flush) prebuilds — never checked the transaction value on any of the three levels that can move native funds (outer tx value, sendMultiSig amount, callFromParent value), returned true with zero inspection on consolidateId-only prebuilds, and compared the flush destination only against txPrebuild.recipients — the same untrusted server response as txHex. Sibling of #10191 (CECHO-2720); same rollout plan, riding the same release train. (Rebased onto master after #10191 merged, so this diff is purely the CECHO-2719 changes.)

What this PR does (env-gated on bitgo.env === 'test' || 'staging'; prod keeps legacy behavior for one release cycle):

  1. Value-word surfacing (feat(abstract-eth)): decodeFlushERC7984ForwarderTokenCalldata now returns the callFromParent value it already decoded but dropped, and decodeSendMultiSigFlushERC7984Data surfaces the sendMultiSig amount word it previously skipped. Additive; legacy decode consumers unaffected.

  2. Strict verifier (fix(sdk-coin-eth)): on test/staging, verifyConfidentialConsolidation:

    • requires txHex — a consolidateId alone proves nothing about the bytes that will be signed;
    • binds every field from the original signed bytes (ethers parseTransaction after addHexPrefix — the builder accepts unprefixed txHex, ethers does not): outer tx value 0, outer to, token contract, parent, handle, sendMultiSig amount 0, and callFromParent value 0. The TransactionBuilder.from()/build() round trip re-encodes flush calldata with a hardcoded value 0 and would silently normalize a hostile non-zero value word out of the inspected transaction while the wallet signs the original bytes (found while testing the ticket's hostile prebuilds);
    • validates the destination against locally derived wallet-owned forwarder addresses — CREATE2 forwarders of the wallet base address with per-version salt layouts (v4 only with the wallet's feeAddress; a v4-salted flush whose wallet record carries no fee fails closed with a named cause), the same math deriveAddress/isWalletAddress use — via an early-exit index scan bounded at 10000 (measured ~15µs per derivation; a full miss costs ~450ms on the reject path only) — never against txPrebuild.recipients; fails closed when no wallet-owned forwarder can be derived;
    • multisig shape: the outer to must be the wallet contract (base address);
    • applies identically no matter which (server-controlled) flag routed the prebuild into the consolidation verifier.

    Unlike the enable-token verifier (CECHO-2720) there is no structural backstop here: to = attacker with a zero value still executes an arbitrary call as the wallet, which is why destination binding cannot be skipped.

Rollout plan (tracked in CECHO-2719): this is Release N — strict checks on test/staging only, prod unchanged (no prod rollback concern: prod behavior in this release is identical to current). After staging/testnet validation of real consolidation flows (TSS direct + multisig shapes), Release N+1 removes the env gate and enforces everywhere, published as a minor bump. The ticket must not be closed after Release N alone. Release N+1 hardening proposed on the ticket: pipe the flushed address record's index/salt + forwarderVersion + feeAddress into the prebuild verification data so the derivation can use exact hints instead of a bounded scan.

Issue Number

CECHO-2719

Type of change

  • Bug fix (non-breaking change which fixes an issue)

How Has This Been Tested?

Unit tests — 18 new cases in modules/sdk-coin-eth/test/unit/erc7984Token.ts and 4 decoder cases in modules/abstract-eth/test/unit/zamaUtils.ts:

  • TSS direct theft prebuild (to = attacker, value = balance) rejected
  • TSS direct arbitrary-call prebuild (to = attacker, value = 0) rejected — the no-backstop case
  • multisig theft (sendMultiSig(attacker, balance, flush)) and multisig arbitrary-call (sendMultiSig(attacker, 0, flush)) rejected
  • multisig prebuild with a non-zero outer transaction value rejected
  • multisig prebuild whose outer to is not the wallet contract rejected
  • non-zero callFromParent value rejected even when the destination is a derived forwarder (proves the original-bytes decode)
  • txHex-less consolidateId-only prebuild rejected
  • underivable wallet-owned forwarder set (network without factory addresses) fails closed
  • forwarder derived beyond the derivation index cap rejected with the scanned range named (documents the bound)
  • valid direct consolidation whose txHex is unprefixed still verifies (regression)
  • fee-address wallet still verifies its v1/v2/v5-derived forwarder (regression — the fee address belongs in the v4 salt only)
  • v4-salted forwarder (the TSS v5-wallet shape) rejected with a named cause (missing wallet feeAddress) when the wallet record carries no fee, and verified when it does
  • strict checks fire on staging env as well as test
  • prod gate proof: the exact hostile prebuilds still verify on env === 'prod' (legacy path), demonstrating the gate works in both directions
  • decoder round-trips: callFromParentValue 0n on builder output, 123n on hand-encoded non-zero calldata; sendMultiSig amount 0/non-zero through decodeSendMultiSigFlushERC7984Data

The consolidation fixtures use a locally derived CREATE2 forwarder (Hoodi v1 factory) instead of an arbitrary address, so the existing valid-consolidation tests exercise the strict path without false positives.

Full-module runs on the final head: modules/sdk-coin-eth 596 passing (578 on master-with-#10191 + 18 new), modules/abstract-eth 192 passing (188 + 4), modules/statics 42,051 passing — zero failures. npx commitlint --from=origin/master -V clean; yarn lint and check-fmt clean.

Reproduce: cd modules/sdk-coin-eth && npx mocha (also modules/abstract-eth, modules/statics).

Remaining pre-GA work (per the ticket): exercise real consolidation flows against staging/testnet in strict mode (TSS direct + multisig shapes) before Release N+1 removes the gate — shared validation window with #10191.

Checklist

  • My code follows the style guidelines of this project
  • I have performed a self-review of my own code
  • My code compiles correctly for both Node and Browser environments
  • I have commented my code, particularly in hard-to-understand areas
  • My commits follow Conventional Commits and I have properly described any BREAKING CHANGES
  • The ticket or github issue was included in the commit message as a reference
  • I have made corresponding changes to the documentation and on any new/updated functions and/or methods - jsdoc
  • I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes

@linear-code

linear-code Bot commented Nov 17, 2026

Copy link
Copy Markdown
Contributor

CECHO-2719

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

⚠️ Compatibility checks are failing on Node.js 27-nightly (experimental, non-blocking). This does not block merge, but it signals an incompatibility to fix before this release becomes supported.

View run

@nvrakesh06

Copy link
Copy Markdown
Contributor Author

@claude review

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Claude finished @nvrakesh06's task in 33s —— View job


Review of #10192 (CECHO-2719 strict ERC-7984 consolidation verification)

I read the diff and did not run the tests. The PR is stacked on #10191, so the diff includes the CECHO-2720 commits. I only reviewed the 2719 logic closely. The design is sound: the destination is bound to locally derived CREATE2 forwarders and the value words are decoded from the original bytes. Two points below are worth fixing before merge.

1. The strict checks mix two sources of truth (modules/sdk-coin-eth/src/erc7984Token.ts, verifyConfidentialConsolidation and verifyStrictConsolidationCalldata)

  • The PR correctly notes that the from()/build() round trip normalizes the value word to 0.
  • But tokenContractAddress, parentAddress, encryptedHandle and forwarderAddress are still decoded from the round-tripped txJson. The value words and the original sendMultiSig amount come from parseTransaction(originalTxHex).
  • The signed bytes can therefore differ from what the destination and token checks inspected. Any other field the builder re-encodes or drops has the same blind spot.
  • Suggestion: on test/staging, decode every field (token, parent, handle, forwarder, to, outer value) from the original parsed tx and run all checks on that. Keep the builder only for the legacy path.

2. The outer value check uses txJson.value, not the original bytes

  • txJson.value !== '0' && !== 0 reads the round-tripped value. Use originalTx.value.isZero() from the already-parsed original tx.
  • This also avoids false rejections or acceptances from string formats such as '0x0' or '0.0'.

3. The index cap can reject legitimate consolidations (STRICT_CONSOLIDATION_MAX_DERIVATION_INDEX = 200)

  • A wallet with a forwarder at index 200 or higher will fail closed on test/staging with "not a wallet-owned forwarder address". Nothing in the error points at the cap.
  • The cap is a reasonable security trade-off, but I'd do two things:
    • Mention the cap in the error message.
    • Check the highest known address index if the wallet exposes one (e.g. receiveAddress/coinSpecific index data), so the scan range follows the wallet.
  • This matters for the staging validation window, because a false rejection there could be misread as a server bug.

4. Derivation cost

  • Each verify runs up to 4 versions × 200 CREATE2 derivations (about 800 keccak computations), and the result is rebuilt on every call.
  • Consider caching per (baseAddress, feeAddress, network), or an early exit once forwarderAddress matches. Checking the single claimed forwarder per index and stopping at the first hit would be cheaper.

5. The destination set includes baseAddress

  • deriveWalletOwnedForwarderAddresses seeds the set with the wallet base address, so a flush whose destination is the wallet itself passes.
  • If that is intentional (e.g. TSS where to is the base), add a short comment. If it isn't, remove the seed.

6. Misplaced JSDoc (modules/abstract-eth/src/lib/zamaUtils.ts)

  • The block "Full, fail-closed decode…" sits above interface DecodedDelegation, and a second block sits above the function. This is from the 2720 commits, but it is still wrong.

7. Swallowed errors (nit)

  • The bare catch {} around generateForwarderAddress hides real failures. The "no forwarder derived" error is the only signal. A debug log of the first failure would help.

8. Tests

  • The tests cover the hostile prebuilds well, including the prod-gate proof.
  • Two cases are missing:
    • A multisig prebuild with a non-zero outer tx value. Item 2 should be asserted separately from the inner words.
    • A forwarder at an index above the cap, to document the intended behavior from item 3.

Rollout note

  • Both env gates are duplicated as inline bitgo.env === 'test' || 'staging' checks. A small isStrictVerificationEnv() helper would make the Release N+1 gate removal a single change and avoid missing a site.

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Findings marked 🟡 are optional suggestions and need no follow-up push.

@nvrakesh06
nvrakesh06 force-pushed the nvrakeshreddy/cecho-2719-bitgojs branch from bb9fd93 to 92cb494 Compare November 17, 2026 11:39
@nvrakesh06

Copy link
Copy Markdown
Contributor Author

Review disposition — all findings addressed in 92cb494 (force-pushed; suites: sdk-coin-eth 590 passing, abstract-eth 192, statics 42,051; commitlint --from=origin/master -V clean).

Blocking (🔴), all fixed:

  1. Unprefixed txHex → addHexPrefix before parseTransaction + regression test (previously a valid consolidation would be rejected on test/staging).
  2. Fee address applied to every version's salt → per-version fee (v4 only, matching verifyForwarderAddress) + regression test with a fee-address wallet.
  3. Index cap false rejections → cap raised to 1000, early-exit scan so only rejections pay the full bound, and the rejection error names the scanned range for diagnosability; behavior documented by test. Wallet address data isn't available offline to the verifier, so the local-derivation bound is inherent to the approach.

From the summary:

  • Two sources of truth / outer value from txJson → adopted fully: the strict tier now binds every field (outer value via BigNumber.isZero(), outer to, token, parent, handle, sendMultiSig amount, callFromParent value, destination) from the original signed bytes — the builder round trip is now used only by the legacy path.
  • Derivation cost → early-exit per index.
  • baseAddress in the destination set → intentional; documented in the docstring (a flush targeting the wallet's own base executes against the wallet's own contract/EOA, never an attacker address).
  • Missing tests → both added (multisig non-zero outer value; forwarder beyond the cap).
  • Rollout helper → kept the env check inline at both gate sites instead of a tiny wrapper (matches the CECHO-2720 site, and bitgo.env === 'test' || 'staging' is the greppable Release N+1 target across the family); each site carries the gate comment.
  • Swallowed derivation errors (nit) → kept silent by design: per-index failures are expected (e.g. fee-less v4), and the aggregate "no forwarder derivable" / destination error is the only signal operators need.
  • Misplaced JSDoc above DecodedDelegation → that's in the stacked 2720 commits (fix(sdk-coin-eth): enforce strict ERC-7984 delegation verification on test/staging (CECHO-2720) #10191), flagged there rather than edited in this PR.
  • Duplicate enableTokens edge / dormant zamaViewingKeyAddress → CECHO-2720 scope, answered on their threads and flagged to fix(sdk-coin-eth): enforce strict ERC-7984 delegation verification on test/staging (CECHO-2720) #10191.

…on decoders (CECHO-2719)

decodeFlushERC7984ForwarderTokenCalldata decoded the callFromParent uint256
value but never returned it, and decodeSendMultiSigFlushERC7984Data skipped
the sendMultiSig amount word entirely. Both are now surfaced (callFromParentValue
as bigint, amount as a base-10 string) so verifiers can enforce that a
consolidation moves no native value. Additive only; legacy consumers are
unaffected.
@nvrakesh06
nvrakesh06 force-pushed the nvrakeshreddy/cecho-2719-bitgojs branch from b951a0d to 317636e Compare November 18, 2026 09:03
@nvrakesh06

Copy link
Copy Markdown
Contributor Author

@claude review

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Claude finished @nvrakesh06's task in 34s —— View job


Review of #10192 (CECHO-2719 strict ERC-7984 consolidation verification), re-review of 92cb494

I read the current erc7984Token.ts and the abstract-eth decoders. I did not run the test suites. Your disposition comment reports 590 passing in sdk-coin-eth.

Verdict: no blocking issues. The earlier findings are resolved in the code:

  • Original bytes: verifyStrictConsolidationCalldata now decodes the outer to, value, token, parent, handle, sendMultiSig amount, callFromParent value and forwarder from parseTransaction(addHexPrefix(txHex)). The builder round trip only feeds the legacy path.
  • Unprefixed txHex: handled by addHexPrefix.
  • Fee address: v4 alone uses it, and v4 is skipped without one. This matches verifyForwarderAddress (abstractEthLikeNewCoins.ts:3228-3231).
  • Scan cost: the scan early-exits on a match, and the rejection error names the scanned range.

Remaining points, none blocking:

  1. Index cap (1000). I accept the trade-off. A wallet with a forwarder at index 1000 or higher is rejected on test/staging, and in prod after Release N+1. The cap is documented and tested. Before the gate is removed, I'd compare it against the highest address index on the largest real wallets. The server has that number, and the verifier does not.
  2. Rejection cost. An attacker-supplied destination makes isWalletOwnedForwarderAddress run about 3,000 CREATE2 derivations (versions 1, 2 and 5, plus v4 when the wallet has a fee address). That is acceptable for a client-side verify. Please measure it once, since generateForwarderAddress does ABI encoding and keccak on every call and may cost more than microseconds.
  3. Silent catch {} on derivation. I'm fine with this given the explanation. A comment noting that fee-less v4 is already skipped before the loop would help the next reader.
  4. Base address as a destination. Intentional and documented. It is harmless in the multisig shape (sendMultiSig(base, 0, callFromParent…) makes the wallet call itself). In the TSS shape it is a call to the wallet's own address. The confidentialTransferNoProof recipient is bound to parentAddress, which is checked against the base address.
  5. Version coverage. The set is [1, 2, 4, 5], and getForwarderFactoryAddressesAndForwarderImplementationAddress also supports exactly those versions. A forwarder of any other version, for example v0 or v3, fails closed on test/staging. That is acceptable, but a test would document it.
  6. Env gate. The inline bitgo.env === 'test' || 'staging' checks sit at two sites in this PR. Each carries a comment, so they are easy to find. I'm fine with keeping them inline.

Carried from the stacked #10191 (CECHO-2720), outside this PR's scope:

  • requestedAddresses is not deduplicated, so [A, A] against decoded [A, B] passes the token-set check.
  • zamaViewingKeyAddress is unset on every network, so the delegate check is dormant.
  • A misplaced JSDoc block sits above DecodedDelegation.

Please land these in #10191 before the release train ships.

Rollout: CECHO-2719 must stay open after Release N. The staging and testnet validation of real TSS-direct and multisig consolidations is still outstanding.

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Still open from earlier reviews (1):

  • Unresolved: 1 blocking on lines changed since (possibly already fixed).

If you have decided not to act on one of these findings, resolve its thread (a reply alone leaves it open) and the next review stops counting it. To review this commit again now, use Re-run on its "Claude Code Review" check.

… on test/staging (CECHO-2719)

verifyConfidentialConsolidation never checked the outer transaction value, the
sendMultiSig amount, or the callFromParent native value; returned true with
zero inspection on consolidateId-only prebuilds; and compared the flush
destination only against txPrebuild.recipients, the same untrusted server
response as txHex.

Strict tier (env test/staging; prod keeps legacy behavior for one release
cycle, gate removal tracked in the ticket):
- requires txHex: a consolidateId alone proves nothing about the signed bytes
- binds every field from the ORIGINAL signed bytes (ethers parseTransaction,
  after addHexPrefix — the builder accepts unprefixed txHex, ethers does not):
  outer value 0, outer to (multisig shape must call the wallet contract),
  token contract, parent, handle, sendMultiSig amount 0, callFromParent
  value 0. The TransactionBuilder from()/build() round trip re-encodes flush
  calldata with a hardcoded value 0, which would normalize a hostile value
  word out of the inspected tx while the wallet signs the original bytes
- the flushed forwarder must be a wallet-owned address derived locally from
  wallet data (CREATE2 forwarders of the base address with per-version salt
  layouts — v4 only with the wallet's fee address — early-exit index scan up
  to 10000, measured ~15us per derivation so a full miss costs ~450ms on the
  reject path only), never from the prebuild; fails closed when none can be
  derived
- v4-salted forwarders are not derivable offline when the wallet record
  carries no fee address (the fee is part of the v4 CREATE2 salt); the
  rejection then names the missing fee address instead of silently dropping
  the v4 layout
- applies regardless of which server-controlled flag routed the prebuild into
  the consolidation verifier

Tests: the ticket's hostile prebuilds (direct theft, direct arbitrary call,
multisig theft, multisig arbitrary call, wrong outer contract, non-zero
callFromParent value, txHex-less consolidateId, underivable forwarders) are
rejected on test and staging; the same prebuilds still verify on prod, proving
the gate in both directions. Review regressions: unprefixed txHex accepted,
fee-address wallets keep their v1/v2/v5 forwarders, v4-salted forwarders
rejected with a named cause when the wallet fee address is missing and
verified when it is present, multisig non-zero outer value rejected, and the
derivation index cap is documented by test. The consolidation fixtures use a
locally derived CREATE2 forwarder instead of an arbitrary address.
@nvrakesh06
nvrakesh06 force-pushed the nvrakeshreddy/cecho-2719-bitgojs branch from 317636e to a3fd18e Compare November 18, 2026 11:01

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant