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
51 changes: 47 additions & 4 deletions modules/sdk-coin-ton/src/lib/explainTransactionWasm.ts
Original file line number Diff line number Diff line change
Expand Up @@ -35,8 +35,49 @@ export interface ExplainTonTransactionWasmOptions {
toAddressBounceable?: boolean;
}

function extractOutputs(
parsed: WasmParsedTransaction,
type EffectiveAmountKind = 'Exact' | 'CarryInboundValue' | 'AllRemainingBalance';

interface ParsedTonSendAction {
mode: number;
nominalAmount?: bigint;
effectiveAmountKind?: EffectiveAmountKind;
carriesInboundValue?: boolean;
carriesAllBalance?: boolean;
destroyAccountIfZero?: boolean;
/** @bitgo/wasm-ton@1.1.1 calls mode-3 nominal grams `amount`. */
amount?: bigint;
destination: string;
destinationBounceable: string;
jettonTransfer?: { destination: string; amount: bigint };
withdrawAmount?: bigint;
}

type ParsedTonTransaction = Omit<WasmParsedTransaction, 'sendActions'> & {
sendActions: ParsedTonSendAction[];
};

function exactNominalAmount(action: ParsedTonSendAction): bigint {
if (
action.mode !== 3 ||
(action.effectiveAmountKind !== undefined && action.effectiveAmountKind !== 'Exact') ||
action.carriesInboundValue === true ||
action.carriesAllBalance === true ||
action.destroyAccountIfZero === true
) {
throw new Error('TON send actions must use exact, non-destructive mode 3');
}

// Only the strict mode-3 allowlist may use the legacy field while deployed
// @bitgo/wasm-ton@1.1.1 is being replaced by the nominalAmount API.
const amount = action.nominalAmount ?? action.amount;
if (amount === undefined) {
throw new Error('TON send action is missing its nominal amount');
}
return amount;
}

export function extractOutputs(
parsed: Pick<ParsedTonTransaction, 'sendActions'>,
toAddressBounceable: boolean
): {
outputs: { address: string; amount: string }[];
Expand All @@ -47,6 +88,8 @@ function extractOutputs(
let withdrawAmount: string | undefined;

for (const action of parsed.sendActions) {
const nominalAmount = exactNominalAmount(action);

if (action.jettonTransfer) {
outputs.push({
address: action.jettonTransfer.destination,
Expand All @@ -57,7 +100,7 @@ function extractOutputs(
// destination respects the original bounce flag (UQ... when bounce=false)
outputs.push({
address: toAddressBounceable ? action.destinationBounceable : action.destination,
amount: String(action.amount),
amount: String(nominalAmount),
});
}

Expand All @@ -83,7 +126,7 @@ export async function explainTonTransaction(params: ExplainTonTransactionWasmOpt
const { Transaction: WasmTonTransaction, parseTransaction } = await loadWasmTon();
const toAddressBounceable = params.toAddressBounceable !== false;
const tx = WasmTonTransaction.fromBytes(Buffer.from(params.txBase64, 'base64'));
const parsed: WasmParsedTransaction = parseTransaction(tx);
const parsed = parseTransaction(tx) as ParsedTonTransaction;

const { outputs, outputAmount, withdrawAmount } = extractOutputs(parsed, toAddressBounceable);

Expand Down
73 changes: 71 additions & 2 deletions modules/sdk-coin-ton/test/unit/explainTransactionWasm.ts
Original file line number Diff line number Diff line change
@@ -1,9 +1,77 @@
import assert from 'assert';
import should from 'should';
import { Transaction as WasmTonTransaction, parseTransaction } from '@bitgo/wasm-ton';
import { explainTonTransaction } from '../../src/lib/explainTransactionWasm';
import { explainTonTransaction, extractOutputs } from '../../src/lib/explainTransactionWasm';
import * as testData from '../resources/ton';

describe('TON WASM explainTransaction', function () {
describe('send mode semantics', function () {
const action = (mode: number, jettonTransfer?: { destination: string; amount: bigint }) => ({
mode,
nominalAmount: 10n,
effectiveAmountKind: mode === 3 ? ('Exact' as const) : ('AllRemainingBalance' as const),
carriesInboundValue: false,
carriesAllBalance: mode !== 3,
destroyAccountIfZero: mode === 160,
destination: 'native-destination',
destinationBounceable: 'native-bounceable-destination',
...(jettonTransfer ? { jettonTransfer } : {}),
});

it('uses nominalAmount for an exact mode-3 native send', function () {
const explained = extractOutputs({ sendActions: [action(3)] }, true);

assert.deepStrictEqual(explained.outputs, [{ address: 'native-bounceable-destination', amount: '10' }]);
explained.outputAmount.should.equal('10');
});

it('retains the jetton amount for an exact mode-3 token send', function () {
const explained = extractOutputs(
{ sendActions: [action(3, { destination: 'jetton-destination', amount: 25n })] },
true
);

assert.deepStrictEqual(explained.outputs, [{ address: 'jetton-destination', amount: '25' }]);
explained.outputAmount.should.equal('25');
});

for (const mode of [128, 160]) {
it(`rejects mode ${mode} jetton sends before exposing token amounts`, function () {
const sendAction = action(mode, { destination: 'attacker', amount: 1n });

assert.throws(() => extractOutputs({ sendActions: [sendAction] }, true), /mode 3/);
});
}

it('rejects carry semantics that conflict with an exact mode', function () {
const carriesInboundValue = {
...action(3),
effectiveAmountKind: 'CarryInboundValue' as const,
carriesInboundValue: true,
};
const carriesAllBalance = {
...action(3),
effectiveAmountKind: 'AllRemainingBalance' as const,
carriesAllBalance: true,
};

assert.throws(() => extractOutputs({ sendActions: [carriesInboundValue] }, true), /mode 3/);
assert.throws(() => extractOutputs({ sendActions: [carriesAllBalance] }, true), /mode 3/);
});

it('rejects a destruction marker even when mode claims an exact amount', function () {
const actionWithDestruction = { ...action(3), destroyAccountIfZero: true };

assert.throws(() => extractOutputs({ sendActions: [actionWithDestruction] }, true), /mode 3/);
});

it('checks every action, including a dangerous later jetton action', function () {
const actions = [action(3), action(128, { destination: 'attacker', amount: 1n })];

assert.throws(() => extractOutputs({ sendActions: actions }, true), /mode 3/);
});
});

describe('explainTonTransaction', function () {
it('should explain a signed send transaction', async function () {
const txBase64 = testData.signedSendTransaction.tx;
Expand Down Expand Up @@ -80,7 +148,8 @@ describe('TON WASM explainTransaction', function () {

parsed.transactionType.should.equal('Transfer');
parsed.sendActions.length.should.be.greaterThan(0);
(typeof parsed.sendActions[0].amount).should.equal('bigint');
const parsedAction = parsed.sendActions[0] as unknown as { nominalAmount?: bigint; amount?: bigint };
(typeof (parsedAction.nominalAmount ?? parsedAction.amount)).should.equal('bigint');
parsed.seqno.should.be.a.Number();
(typeof parsed.expireAt).should.equal('bigint');
});
Expand Down
Loading