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 signed bytes (every SDK signing path supplies the bytes: the TSS txRequest flows pass signableHex/serializedTxHex, and the prebuild flow cannot sign without them);
    • 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 wallet's own base address is not a valid flush destination — a legit consolidation always targets a forwarder contract), 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 — 20 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
  • multisig consolidation to a v4-salted forwarder for a fee-carrying wallet verifies (the other v4 consumer)
  • the wallet's own base address is rejected as a flush destination (a legit flush always targets a forwarder contract)
  • 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 598 passing (578 on master-with-#10191 + 20 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.

@nvrakesh06
nvrakesh06 force-pushed the nvrakeshreddy/cecho-2719-bitgojs branch from 317636e to a3fd18e Compare November 18, 2026 11:01
@nvrakesh06

Copy link
Copy Markdown
Contributor Author

@claude Please do a thorough review of this PR.

Focus especially on:

• any bugs or incorrect logic in the changes.
• whether these changes could impact existing flows or cause regressions.
• whether the implementation is aligned with the requirement/design.
• whether the changes are correct and complete.
• missing edge cases, validation gaps, and test coverage gaps.

Please call out concrete issues clearly and separate them by severity if possible.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

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


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

I read the full diff of the abstract-eth decoders and erc7984Token.ts, plus the legacy verifier it sits on top of. I did not run the test suites. The author reports 596 passing in sdk-coin-eth, 192 in abstract-eth and 42,051 in statics.

Verdict: no blocking bugs found. The earlier blocking findings are fixed in the code:

  • Unprefixed txHex is handled.
  • The fee address goes into the v4 salt only.
  • v4 flushes with no fee address fail with a named cause.
  • Every field is decoded from the original bytes.

What remains is mostly rollout risk and test gaps.


🟠 Medium: rollout and regression risk (worth confirming before the staging window)

1. The txHex-less rejection changes behavior for every consolidateId-only flow on test/staging (erc7984Token.ts:514-523)

  • Previously these prebuilds returned true. Now they throw.
  • Please confirm no legitimate producer omits txPrebuild.txHex here. One candidate is a TSS txRequest flow, where the bytes live in txRequest.unsignedTxs rather than in the prebuild.
  • If such a flow exists, every consolidation through it breaks on test/staging, and after Release N+1 on prod.
  • The PR tests the rejection, but nothing shows a real flow that still verifies. The ticket's staging validation should explicitly cover this.

2. The env gate is narrower than "non-prod" (erc7984Token.ts:520, :599)

3. Index scan bound of 10000 is still a hard false-reject cliff (erc7984Token.ts:65)

  • This is a documented trade-off, and the error names the range.
  • A rejection (or a v4-skipped miss) runs about 30k synchronous CREATE2 derivations, which is about 450ms by the author's measurement. That blocks the event loop in express and the browser for that long.
  • This only happens on the reject path, but an attacker-controlled prebuild can trigger it on every verify. It is a mild amplification, not a vulnerability.
  • Cheap mitigations:
    • Memoize per (baseAddress, feeAddress, network) the negative result for a given destination.
    • Or reject early when forwarderAddress has a trivially wrong shape.
  • The hint-based unbounded check (Release N+1) is the right fix. Please make sure that item stays on the ticket.

🟡 Low: validation gaps and nits

4. Unvalidated sendMultiSig parameters. The shape check binds to, amount, the forwarder and the inner call. The expireTime, sequenceId and signature args are not checked.

  • This is probably fine, because the server signs them and the on-chain contract enforces them.
  • Add a one-line comment saying this is deliberate, so a later reader doesn't assume it was missed.

5. The base address is accepted as a destination (erc7984Token.ts:~762)

  • In the TSS shape this means to = base and callFromParent(...) passes the destination check.
  • It is argued harmless: a call to the wallet's own address, with the parent and token still bound.
  • It is still the one path where to is not a CREATE2-derived forwarder. A cheap tightening is to allow the base address only in the multisig shape, where it is the expected outer to, and reject it as a flush destination in the TSS shape.

6. Redundant double decode.

  • The legacy path decodes the round-tripped txJson first, and the strict path then decodes the original bytes again.
  • In strict mode both must pass, so behavior is correct. But if the two decodes disagree, the user sees the legacy error rather than the strict one.
  • Consider skipping the legacy decode on test/staging, or at least note the ordering in a comment.

7. Swallowed derivation errors.

  • The bare catch {} at the generateForwarderAddress call is acceptable as explained.
  • Add a comment that fee-less v4 is already skipped before the loop. Then a catch here can only mean a malformed baseAddress, which is already bound earlier.

8. Unsupported tx types.

  • ethers.utils.parseTransaction throws on tx types it does not know (for example type 3 or type 4).
  • That fails closed with "failed to decode original consolidation calldata", which is safe. It is worth a test, so future tx-type support doesn't silently regress it.

Test coverage gaps

The hostile-prebuild, prod-gate and fee-address regression tests look thorough. Missing cases:

  • Unsupported forwarder versions. A forwarder derived at v0 or v3 should fail closed. A test would document the supported set [1, 2, 4, 5].
  • Different tx encodings. The cases are legacy, EIP-2930 and EIP-1559, signed and unsigned. The outer-value and to checks rely on ethers parsing the original bytes, and only some of these are visibly covered.
  • to = null (contract creation) in the TSS shape. The code throws "no destination", but there is no test.
  • Mixed-case or checksummed addresses for to, forwarder and base. The comparisons lowercase everything, so a quick test would lock that in.
  • Multisig + v4. Is there a case of multisig wallet + v4 forwarder + fee address verifying? The TSS v5 shape is covered, but multisig + v4 is the other v4 consumer.
  • No cheap guard on scan cost. A small test could assert the full-miss path finishes within a generous bound, so a future change to the derivation (for example removing the early exit) is noticed.

Alignment with design

  • The implementation matches the stated design: original-bytes decoding, local CREATE2 destination binding, value-word zeroing, and the env gate with prod unchanged.
  • The decoder changes in abstract-eth are additive.
  • The new return fields (amount, callFromParentValue) don't break existing destructuring consumers.
  • CECHO-2719 must stay open after Release N, as the PR already says.

… 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
  (every SDK signing path supplies txHex — the TSS txRequest flows pass
  signableHex/serializedTxHex, and the prebuild flow cannot sign without 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. The wallet's own base address is NOT a valid flush destination —
  a legitimate consolidation always targets a forwarder contract
- 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 (TSS and multisig shapes), the base address
rejected as a flush destination, 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 a3fd18e to bd60198 Compare November 18, 2026 11:30
@nvrakesh06

Copy link
Copy Markdown
Contributor Author

Review disposition (head bd60198) — nothing high-critical; two medium/low items taken as code, the rest verified or passed by design. Suite: sdk-coin-eth 598 passing (+2 for the new cases below), abstract-eth 192, statics 42,051; lint/format/commitlint clean.

🟠 Medium:

  1. txHex-less flows — verified, no breakage: I traced every verifyTransaction call site in sdk-core. Both TSS txRequest paths (utils/tss/ecdsa/ecdsa.ts:1073-1089, ecdsaMPCv2.ts:998-1014) always construct the prebuild with txHex (unsignedTx.signableHex, or serializedTxHex for the TSS_VERIFY_USE_SERIALIZED_TX_HEX coins), and the prebuild/signTransaction flow cannot sign without bytes to begin with. No SDK flow reaches consolidation verification without txHex; the old return true was a zero-inspection artifact, which ticket criterion 3 explicitly ordered removed. The staging validation (tracked on the ticket) should still exercise a real consolidateToken intent flow end-to-end — noted there.
  2. Env gate narrower than non-prod — by design per the agreed rollout: test/staging only, mirroring fix(sdk-coin-eth): enforce strict ERC-7984 delegation verification on test/staging (CECHO-2720) #10191 exactly; the staging/testnet validation item on the ticket is specifically staging+test.
  3. 450ms reject-path scan — passed. Under this threat model the attacker is the compromised platform and already controls everything the client consumes; a ~450ms verify on a hostile prebuild is an inconvenience, not a vulnerability (your own framing). Negative-result memoization only helps against repeated identical hostile prebuilds (an attacker rotates destinations), so it adds verifier state for negligible benefit. The real fix — the hint-based unbounded derivation using the address record's index/salt + version + fee from the prebuild — stays on the ticket for Release N+1.

🟡 Low:

  1. Unbound sendMultiSig expireTime/sequenceId/signature — comment added stating it is deliberate (enforced on-chain and by the co-signature, not client-verifiable).
  2. Base address as destination — adopted, one step further than suggested: the base address is now rejected as a flush destination in both shapes. Rationale: a legitimate consolidation always targets a forwarder contract holding confidential balances; the wallet's own contract/EOA has no callFromParent and holds nothing to flush, and the multisig outer to == base requirement is enforced as its own separate check. This supersedes my earlier thread reply that called the base shortcut intentional. Test added (TSS shape, to = base → rejected).
  3. Double decode ordering — comment added noting the legacy (round-trip) checks run first in all envs, so a decode disagreement surfaces the legacy error before the strict tier runs; both paths must pass.
  4. Catch semantics — comment extended: fee-less v4 is skipped before the loop, so the catch can only be malformed derivation input, which the comparison fails closed on regardless.
  5. Unsupported tx types — passed with rationale: any strict-path decode failure (including ethers v5 refusing type 3/4) fails closed via the shared catch — the property is structural, and pinning ethers-version-specific unparsed-type behavior in a test adds churn without protecting the invariant.

Test gaps:

  • Multisig + v4 + fee — added (verifies; the TSS v5 pair was already covered).
  • Unsupported forwarder versions — passed: an address from an unscanned version is indistinguishable from an attacker address and hits the same already-tested rejection path.
  • tx encodings / to = null / checksummed casing — passed: ethers v5 parses legacy/2930/1559 identically for these fields, the no-destination guard is a trivially readable throw, and every comparison lowercases (fixtures already exercise checksummed inputs like MULTISIG_WALLET_CONTRACT).
  • Scan-cost guard test — passed: timing assertions are flaky by nature; the cost is documented in the constant's comment with the measurement.

CECHO-2719 stays open after Release N; staging/testnet validation remains the outstanding pre-GA item.

@nvrakesh06

Copy link
Copy Markdown
Contributor Author

@claude Please do a thorough review of this PR.

Focus especially on:

• any bugs or incorrect logic in the changes.
• whether these changes could impact existing flows or cause regressions.
• whether the implementation is aligned with the requirement/design.
• whether the changes are correct and complete.
• missing edge cases, validation gaps, and test coverage gaps.

Please call out concrete issues clearly and separate them by severity if possible.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

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


Review of #10192 (CECHO-2719), head bd60198

I read the abstract-eth decoder changes and the strict consolidation path in erc7984Token.ts in full. I did not run the test suites. Your reported counts are 598 passing in sdk-coin-eth, 192 in abstract-eth and 42,051 in statics.

Verdict: no blocking bugs. The prod gate leaves prod behavior unchanged. The main open risk is a false rejection of v4-salted (v5 TSS) consolidations on test/staging (item 1 under Medium). The earlier blocking findings are fixed in the code:

  • Unprefixed txHex: addHexPrefix runs before parseTransaction.
  • Fee address: it goes into the v4 salt only.
  • Original bytes: every field is decoded from the original signed bytes.
  • Base address: it is no longer accepted as a flush destination.

🔴 High

None.

🟠 Medium

1. v5 TSS wallets will probably fail every consolidation on test/staging (erc7984Token.ts:794-817, :847-856)

  • WalletCoinSpecific has no feeAddress. Your own thread says the fee appears only in address records.
  • A v4-salted flush with a fee-less wallet record therefore throws, with a good named cause.
  • This still means that if v5 confidential TSS wallets really lack the fee at the wallet level, strict mode blocks all their consolidations on staging. That includes the main shape this PR targets.
  • Please confirm the field is populated on a real staging v5 wallet before the validation window. If it isn't, the window will only produce failures that don't test anything.
  • If it isn't populated, either land the Release N+1 fee/index piping before enabling strict mode for those wallets, or note on the ticket that v5 TSS is not covered in Release N.

2. Strict mode makes the error ordering depend on the legacy decode (:562-607)

  • The legacy builder round-trip runs first and can throw before the strict tier. This is documented now, and I'm fine with it.
  • One consequence is that txBuilder.from() rejecting a tx that parseTransaction would accept still blocks it on test/staging.
  • It is worth an explicit staging check with a real unsigned signableHex (see Test gaps).

3. Reject-path cost (:818)

  • A rejection runs up to about 30k synchronous CREATE2 derivations, about 450ms by your measurement, blocking the event loop.
  • Your threat-model reasoning is acceptable. A false rejection (index ≥ 10000) also pays this cost.
  • Keep the Release N+1 hint-based check on the ticket.

🟡 Low

4. Chain and fee fields are not bound.

  • chainId, nonce, gasLimit and gasPrice/fee fields of the original tx are not checked in the strict path.
  • Another verifier or the signing layer may cover these. If not, a hostile prebuild can still burn gas or target a different chain.
  • This is outside this ticket's stated scope, but it is worth one line on the ticket.

5. Any wallet-owned forwarder is accepted.

  • The check does not tie the flushed forwarder to the one requested in txParams/recipients. It only requires a derived forwarder of this wallet.
  • This is safe, because parentAddress is bound to the base address and funds return to the wallet.
  • The threat model could use a comment stating this.

6. Silent catch {} in the scan (:828).

  • Acceptable with the existing comment.
  • Note that a malformed baseAddress makes every index throw, so the error you get is "not a wallet-owned forwarder". A malformed base address is bound earlier through the parent comparison, so this is only cosmetic.

7. Decoder return shape (abstract-eth).

  • amount is a string and callFromParentValue is a bigint.
  • Adding bigint to a public return type is additive. Check that no existing consumer JSON-serializes the decoded result, because JSON.stringify throws on bigint.
  • A quick grep of decodeFlushERC7984ForwarderTokenCalldata and decodeSendMultiSigFlushERC7984Data callers would settle it.

Test gaps

  • Unsigned txHex: a case with a real unsigned signableHex for the TSS shape (EIP-1559 unsigned and legacy EIP-155 unsigned) would lock in that parseTransaction accepts what the TSS flow actually produces. I think it does, but the test is cheap.
  • to = null: the no-destination guard has no test (you passed on it; it's low value).
  • v0/v3 forwarders: no test that they fail closed (you passed on it).
  • Multisig + v4 + fee: now covered.
  • Non-zero outer value, base address as destination, prod gate: covered.

Design alignment

  • The strict tier matches the stated design: original-bytes decoding, local CREATE2 destination binding, zero value words, and the env gate with prod unchanged.
  • The decoder changes are additive.
  • CECHO-2719 correctly stays open after Release N. The staging validation of TSS-direct and multisig flows remains the outstanding pre-GA item. Item 1 above is the thing most likely to surface there.

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