Skip to content

fix(sdk-coin-eth): strictly verify the multisig enable-token sendMultiSig operation (CECHO-2815) - #10200

Draft
nvrakesh06 wants to merge 1 commit into
masterfrom
nvrakeshreddy/cecho-2815-bitgojs-multisig-enable-token-path
Draft

nvrakesh06 wants to merge 1 commit into
masterfrom
nvrakeshreddy/cecho-2815-bitgojs-multisig-enable-token-path

Conversation

@nvrakesh06

Copy link
Copy Markdown
Contributor

Description

Fixes the client-side verification gap from CECHO-2815: the multisig branch of Erc7984Token.verifyEnableTokenTransaction validated only txPrebuild.buildParams.recipients — client-attached echo data that Wallet.buildTokenEnablements builds from the caller's own enableTokens — so the operation the user actually signs was never inspected.

What actually gets signed (the fix's binding target): onchain-multisig users sign the sendMultiSig operation hash over txPrebuild.recipients[0] (address, amount, data) — never over txHex (Eth.signTransaction → getOperationSha3ForExecuteAndConfirm hashes the platform-supplied recipient verbatim; halfSigned carries no txHex), and the MultiSigV3 contract enforces at execution that the broadcast args hash to that op. So recipients[0] is the single authoritative binding, and the strict flow verifies it in full:

  1. Value — the signed sendMultiSig native value must be 0 (blocks direct native-fund theft).
  2. Calldata — the signed data must decode fail-closed as a delegation calldata (decodeDelegationCallsFromCalldata, CECHO-2720): rejects any other selector (e.g. an ERC-20 approve(attacker, …) theft prebuild) and any smuggled non-delegation inner call.
  3. Target — aclMulticall shape must target the ACL contract; the callFromParent (forwarder) shape is bound on-chain by the forwarder's onlyParent modifier plus the enforced callFromParent target/value — same decision as the TSS path.
  4. Delegation content — verifyStrictEnableTokenCalldata (CECHO-2720 helper, unchanged) binds delegate == pinned enterprise viewing key (fail closed when unpinned), future expiry, and an exact deduplicated match against the requested tokens.
  5. txHex mirror (defense in depth) — when the prebuild carries a txHex, its sendMultiSig args must mirror the recipient exactly: a diverging (decoy) txHex that passes verification while different args get signed is rejected.

Revert path — Flipt flag, default true: gated by cecho-2815-multisig-enable-token-strict-verification, evaluated by the platform and delivered on the prebuild as txPrebuild.featureFlags. Default TRUE — flag absent, unreadable, or true runs the strict verification; only an explicit false reverts to the legacy flow, byte-for-byte, per request, with no SDK redeploy (kill-switch semantics identical in direction to the wrap/unwrap mirror checks).

Carrier contract (WP-side, out of this PR's scope): TransactionPrebuild.featureFlags?: Record<string, boolean> is added to abstract-eth — server-evaluated flags ride the prebuild response; an absent key means that flag's default value, never an error. The Flipt flag definition and the WP plumbing that populates this field are tracked separately (the "Flipt feature" work).

Module-graph note: the flag constant lives in abstract-eth/zamaUtils rather than sdk-coin-eth so consumers can import it without pulling the sdk-coin-eth graph — a value import from erc7984Token.ts would otherwise enter the eth/erc20Token require cycle first and crash module initialization under tsx/esbuild.

Known rollout prerequisite (inherited from CECHO-2720): the strict helper fails closed when zamaViewingKeyAddress is unpinned for the network. Until the Coins Echo team pins the real enterprise viewing keys for mainnet + Hoodi (or the flag is flipped to false), strict-mode enable-token verification throws. Both this PR and #10191 share that prerequisite.

Issue Number

CECHO-2815 (related: CECHO-2720, CECHO-2719)

Type of change

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

How Has This Been Tested?

Unit tests — 13 new multisig strict-path cases in modules/sdk-coin-eth/test/unit/erc7984Token.ts:

  • benign base-wallet enable (aclMulticall shape) passes with the flag absent (default true)
  • benign forwarder enable (callFromParent shape) passes
  • benign enable with a mirroring txHex passes
  • non-zero sendMultiSig value rejected (native fund theft)
  • ERC-20 approve theft prebuild rejected (non-delegation calldata)
  • delegate substitution to an attacker viewing key rejected
  • smuggled non-delegation inner call rejected
  • aclMulticall shape targeted away from the ACL contract rejected
  • callFromParent theft shape (forwarder → attacker contract with funds) rejected
  • decoy txHex whose sendMultiSig args differ from the signed recipient rejected
  • txHex that is not a sendMultiSig envelope rejected
  • prebuild with no recipient (nothing to bind the signature to) rejected
  • explicit flag=false reverts to the legacy flow — a fully hostile prebuild passes, proving the kill switch restores the old behavior byte-for-byte

The five pre-existing legacy-path tests now pin the flag to false (they document the legacy buildParams contract and prove the revert path).

Full-module runs: modules/sdk-coin-eth 591 passing, modules/abstract-eth 188 passing — zero failures. Reproduce: cd modules/sdk-coin-eth && npx mocha (also modules/abstract-eth).

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
  • New and existing unit tests pass locally with my changes

…iSig operation (CECHO-2815)

The multisig branch of Erc7984Token.verifyEnableTokenTransaction compared only
txPrebuild.buildParams.recipients — client-attached echo data built by
Wallet.buildTokenEnablements from the caller's own enableTokens — so the operation
the user actually signs was never inspected. Onchain-multisig users sign the
sendMultiSig operation hash over txPrebuild.recipients[0] (address, amount, data),
never over txHex, and the MultiSigV3 contract enforces at execution that the
broadcast args hash to that op: a compromised platform could serve any recipient
(attacker contract with native value, ERC-20 approve theft, or a delegate
substitution) and the user would first-sign it.

Strict flow (default): bind the signed recipient in full —
  1. sendMultiSig native value must be 0;
  2. the recipient data must decode fail-closed as a delegation calldata
     (rejects approve/transfer and smuggled inner calls);
  3. aclMulticall shape must target the ACL contract (the forwarder shape is
     bound on-chain by onlyParent plus the enforced callFromParent target/value);
  4. verifyStrictEnableTokenCalldata binds delegate == pinned enterprise viewing
     key, future expiry, and an exact deduplicated match against the requested
     tokens (CECHO-2720 helper, unchanged);
  5. when the prebuild carries a txHex, its sendMultiSig args must mirror the
     recipient — a diverging (decoy) txHex is rejected.

Revert path: gated by the Flipt flag cecho-2815-multisig-enable-token-strict-
verification delivered on the prebuild as featureFlags. DEFAULT TRUE — the flag
absent, unreadable, or true runs strict verification; only an explicit false
reverts to the legacy flow, byte-for-byte, per request, with no SDK redeploy.

abstract-eth: TransactionPrebuild.featureFlags carries server-evaluated (Flipt)
flags with the prebuild; the flag constant lives in zamaUtils so consumers can
import it without pulling the sdk-coin-eth module graph (its value import would
otherwise enter the eth/erc20Token require cycle first and crash module init).

Tests: 13 new multisig strict-path cases — benign both delegation shapes, txHex
mirror pass, value theft, approve theft, delegate substitution, smuggled inner
call, wrong ACL target, callFromParent theft shape, decoy txHex, non-sendMultiSig
txHex, missing recipient, and explicit flag=false reverting to the legacy flow.
sdk-coin-eth 591 passing, abstract-eth 188 passing.
@linear-code

linear-code Bot commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

CECHO-2815

@github-actions

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

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