Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions modules/abstract-eth/src/abstractEthLikeNewCoins.ts
Original file line number Diff line number Diff line change
Expand Up @@ -166,6 +166,12 @@ export interface TransactionPrebuild extends BaseTransactionPrebuild {
eip1559?: EIP1559;
isBatch?: boolean;
};
/**
* Feature flags evaluated server-side (e.g. Flipt) and delivered with the prebuild.
* A flag key absent from the map means that flag is at its default value; consumers
* must treat absence as the default, never as an error.
*/
featureFlags?: Record<string, boolean>;
}

export interface SignFinalOptions {
Expand Down
13 changes: 13 additions & 0 deletions modules/abstract-eth/src/lib/zamaUtils.ts
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,19 @@ export const finalizeUnwrapMethodId = addHexPrefix(
EthereumAbi.methodID('finalizeUnwrap', [...finalizeUnwrapTypes]).toString('hex')
);

/**
* Flipt feature flag (evaluated by the platform, delivered on the prebuild as
* `txPrebuild.featureFlags`) gating the strict multisig enable-token verification
* (CECHO-2815). DEFAULT TRUE: when the flag is absent, unreadable, or true, the strict
* verification runs; only an explicit `false` reverts to the legacy flow. The strict
* path is therefore the default behavior while the flag keeps a full, per-request
* revert path to the pre-CECHO-2815 flow with no SDK redeploy.
*
* Lives here (not in sdk-coin-eth) so consumers can import it without pulling the
* sdk-coin-eth module graph.
*/
export const STRICT_MULTISIG_ENABLE_TOKEN_VERIFICATION_FLAG = 'cecho-2815-multisig-enable-token-strict-verification';

// ---------------------------------------------------------------------------
// Encoding functions
// ---------------------------------------------------------------------------
Expand Down
217 changes: 186 additions & 31 deletions modules/sdk-coin-eth/src/erc7984Token.ts
Original file line number Diff line number Diff line change
Expand Up @@ -40,9 +40,11 @@ import {
finalizeUnwrapMethodId,
UINT64_MAX,
decodeTransferData,
STRICT_MULTISIG_ENABLE_TOKEN_VERIFICATION_FLAG,
} from '@bitgo/abstract-eth';
import { bip32 } from '@bitgo/secp256k1';
import * as _ from 'lodash';
import { BigNumber } from 'bignumber.js';

import { Eth } from './eth';
import { TransactionBuilder } from './lib';
Expand Down Expand Up @@ -826,48 +828,201 @@ export class Erc7984Token extends Eth {

return true;
} else {
// Multisig path: buildParams-level check
const recipients = txPrebuild.buildParams?.recipients as
| Array<{ tokenName?: string; amount?: string }>
| undefined;
if (!recipients || recipients.length === 0) {
throw new Error('verifyEnableTokenTransaction: missing buildParams.recipients for multisig path');
// Multisig path (CECHO-2815). 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 (Eth.signTransaction → getOperationSha3ForExecuteAndConfirm). recipients[0]
// is therefore the authoritative binding, and the strict flow verifies it in full.
//
// Flipt kill switch: the flag defaults to TRUE, so strict verification is the
// default behavior; the platform delivers an explicit false on the prebuild to
// revert to the legacy flow — a per-request revert path with no SDK redeploy.
if (txPrebuild.featureFlags?.[STRICT_MULTISIG_ENABLE_TOKEN_VERIFICATION_FLAG] === false) {
return this.verifyEnableTokenTransactionLegacyMultisig(params);
}
return this.verifyEnableTokenTransactionStrictMultisig(params);
}
}

/**
* Legacy multisig enable-token verification (pre-CECHO-2815), kept verbatim as the
* Flipt revert path. Checks only txPrebuild.buildParams.recipients, which
* Wallet.buildTokenEnablements attaches client-side from the caller's own
* enableTokens — it validates the client's own request, not the prebuild the
* platform returned, and so provides no protection against a compromised platform.
* Do not extend this path; new checks belong in the strict flow.
*/
private verifyEnableTokenTransactionLegacyMultisig(params: VerifyEthTransactionOptions): boolean {
const { txParams, txPrebuild } = params;
const recipients = txPrebuild.buildParams?.recipients as Array<{ tokenName?: string; amount?: string }> | undefined;
if (!recipients || recipients.length === 0) {
throw new Error('verifyEnableTokenTransaction: missing buildParams.recipients for multisig path');
}

// Determine requested token names from txParams
const requestedTokenNames: string[] = [];
if (txParams.enableTokens && txParams.enableTokens.length > 0) {
requestedTokenNames.push(...txParams.enableTokens.map((t) => t.name));
} else if (txParams.recipients && txParams.recipients.length > 0) {
requestedTokenNames.push(
...txParams.recipients.map((r) => r.tokenName).filter((name): name is string => Boolean(name))
);
}

// Determine requested token names from txParams
const requestedTokenNames: string[] = [];
if (txParams.enableTokens && txParams.enableTokens.length > 0) {
requestedTokenNames.push(...txParams.enableTokens.map((t) => t.name));
} else if (txParams.recipients && txParams.recipients.length > 0) {
requestedTokenNames.push(...txParams.recipients.map((r: any) => r.tokenName).filter(Boolean));
// Verify all recipients have tokenName and amount = '0'
for (const recipient of recipients) {
if (!recipient.tokenName) {
throw new Error('verifyEnableTokenTransaction: recipient is missing tokenName in buildParams');
}
if (recipient.amount !== '0') {
throw new Error(
`verifyEnableTokenTransaction: expected amount 0 for token enablement but got ${recipient.amount}`
);
}
}

// Verify all recipients have tokenName and amount = '0'
for (const recipient of recipients) {
if (!recipient.tokenName) {
throw new Error('verifyEnableTokenTransaction: recipient is missing tokenName in buildParams');
}
if (recipient.amount !== '0') {
// Verify requested token names are present in recipients
if (requestedTokenNames.length > 0) {
const recipientTokenNames = recipients.map((r) => r.tokenName);
for (const requested of requestedTokenNames) {
if (!recipientTokenNames.includes(requested)) {
throw new Error(
`verifyEnableTokenTransaction: expected amount 0 for token enablement but got ${recipient.amount}`
`verifyEnableTokenTransaction: requested token ${requested} not found in buildParams recipients`
);
}
}
}

// Verify requested token names are present in recipients
if (requestedTokenNames.length > 0) {
const recipientTokenNames = recipients.map((r) => r.tokenName);
for (const requested of requestedTokenNames) {
if (!recipientTokenNames.includes(requested)) {
throw new Error(
`verifyEnableTokenTransaction: requested token ${requested} not found in buildParams recipients`
);
}
}
}
return true;
}

return true;
/**
* Strict multisig enable-token verification (CECHO-2815) — the default flow.
*
* Onchain-multisig users sign the sendMultiSig operation hash over
* txPrebuild.recipients[0] = (address, amount, data): Eth.signTransaction resolves the
* recipients from the prebuild (never from client params) and hashes the data verbatim,
* halfSigned carries no txHex, and the MultiSigV3 contract enforces at execution that
* the broadcast args hash to the op the user signed. recipients[0] is therefore the
* single authoritative binding, and it is verified here in full:
* 1. amount == 0 — a non-zero sendMultiSig value moves native funds directly.
* 2. the data decodes fail-closed as a delegation calldata — rejects any other
* selector (e.g. an ERC-20 approve theft prebuild) and smuggled inner calls.
* 3. aclMulticall shape: the target must be the ACL contract (root wallet).
* callFromParent shape: the forwarder address is wallet-specific and not
* statically verifiable (same decision as the TSS path); the on-chain
* onlyParent modifier plus the enforced callFromParent target/value close
* the fund-theft vector regardless of which forwarder is targeted.
* 4. verifyStrictEnableTokenCalldata binds the delegate to the pinned enterprise
* viewing key (fail closed when unpinned), a future expiry, an exact
* deduplicated match against the requested tokens, and — for the
* callFromParent shape — target == ACL contract with zero native value.
* 5. When the prebuild carries a txHex, its sendMultiSig args must mirror
* recipients[0] exactly: a diverging txHex (e.g. a decoy that passes
* verification while different args get signed) is rejected.
*/
private async verifyEnableTokenTransactionStrictMultisig(params: VerifyEthTransactionOptions): Promise<boolean> {
const { txParams, txPrebuild } = params;

// Requested tokens: enableTokens when present (prebuildAndSignTransaction merges the
// original params over the buildParams), else the client-built recipients' tokenNames.
const requestedTokenNames: string[] = [];
if (txParams.enableTokens && txParams.enableTokens.length > 0) {
requestedTokenNames.push(...txParams.enableTokens.map((t) => t.name));
} else if (txParams.recipients && txParams.recipients.length > 0) {
requestedTokenNames.push(
...txParams.recipients.map((r) => r.tokenName).filter((name): name is string => Boolean(name))
);
}
if (requestedTokenNames.length === 0) {
throw new Error('verifyEnableTokenTransaction: requested tokens must be non-empty for the multisig strict path');
}
const requestedAddresses = requestedTokenNames.map((name) => {
const tokenCoin = this.bitgo.coin(name) as Erc7984Token;
return tokenCoin.tokenContractAddress.toLowerCase();
});

const network = this.getNetwork() as EthereumNetwork;
const aclContractAddress = network?.zamaAclContractAddress;
if (!aclContractAddress) {
throw new Error('verifyEnableTokenTransaction: zamaAclContractAddress not configured for this network');
}

// The operation that gets signed. Mirror the signer's resolution exactly
// (Eth.signTransaction: txPrebuild.recipients || txPrebuild.txInfo?.recipients).
const recipients = txPrebuild.recipients || txPrebuild.txInfo?.recipients;
if (!Array.isArray(recipients) || recipients.length !== 1) {
throw new Error(
'verifyEnableTokenTransaction: multisig prebuild must carry exactly one recipient — the sendMultiSig operation that gets signed'
);
}
const recipient = recipients[0] as { address?: string; amount?: string | number; data?: string };
if (!recipient.address) {
throw new Error('verifyEnableTokenTransaction: multisig prebuild recipient is missing an address');
}

// 1. The signed sendMultiSig native value must be 0.
if (new BigNumber(recipient.amount ?? 0).comparedTo(0) !== 0) {
throw new Error(`verifyEnableTokenTransaction: expected sendMultiSig value 0 but got ${recipient.amount}`);
}

// 2. Fail-closed delegation decode of the signed data.
const data = recipient.data;
if (!data || data === '0x') {
throw new Error('verifyEnableTokenTransaction: multisig prebuild recipient is missing delegation calldata');
}
const delegation = decodeDelegationCallsFromCalldata(data);

// 3. Shape → target binding (see the callFromParent note above).
if (delegation.shape === 'aclMulticall' && recipient.address.toLowerCase() !== aclContractAddress.toLowerCase()) {
throw new Error(
`verifyEnableTokenTransaction: sendMultiSig target ${recipient.address} does not match ACL contract ${aclContractAddress}`
);
}

// 4. Strict delegation content (delegate pin, expiry, exact deduplicated token set,
// callFromParent target == ACL with zero native value).
this.verifyStrictEnableTokenCalldata(
{ to: recipient.address, data, value: '0' },
aclContractAddress,
requestedAddresses
);

// 5. txHex mirror, defense in depth: when the prebuild carries a txHex, its
// sendMultiSig envelope must encode the same operation that will be signed.
if (txPrebuild.txHex) {
const txBuilder = this.getTransactionBuilder();
txBuilder.from(txPrebuild.txHex);
const txJson = (await txBuilder.build()).toJson();
const txData = txJson.data || '';
if (!txData.toLowerCase().startsWith(sendMultisigMethodId.toLowerCase())) {
throw new Error(
'verifyEnableTokenTransaction: multisig prebuild txHex must be a sendMultiSig call to the wallet contract'
);
}
const decoded = decodeTransferData(txData);
if (decoded.to.toLowerCase() !== recipient.address.toLowerCase()) {
throw new Error(
`verifyEnableTokenTransaction: txHex sendMultiSig target ${decoded.to} does not match the recipient ${recipient.address} that will be signed`
);
}
if (!new BigNumber(decoded.amount).isEqualTo(recipient.amount ?? 0)) {
throw new Error(
`verifyEnableTokenTransaction: txHex sendMultiSig value ${decoded.amount} does not match the recipient amount ${recipient.amount} that will be signed`
);
}
// TransferData.data is typed loosely (bytes); for a sendMultiSig envelope it is the
// hex-encoded calldata, matching the decode in verifyWrapTransaction.
const txHexCalldata = (decoded.data as string).replace(/^0x/, '').toLowerCase();
const signedCalldata = data.replace(/^0x/, '').toLowerCase();
if (txHexCalldata !== signedCalldata) {
throw new Error(
'verifyEnableTokenTransaction: txHex sendMultiSig calldata does not match the recipient calldata that will be signed'
);
}
}

return true;
}

/**
Expand Down
Loading
Loading