feat: add WASM-based DOT transaction parsing and explanation

Add @bitgo/wasm-dot integration for parsing, explaining, and building
DOT transactions using Rust/WASM instead of @polkadot/api.

- wasmParser.ts: adapter that maps wasm-dot's explainTransaction()
  output to BitGoJS TransactionExplanation format (type mapping,
  output/input extraction, fee handling)
- wasmBuilderByteComparison.ts: tests verifying WASM-built transactions
  produce byte-identical signing payloads to legacy txwrapper-polkadot
- Covers: transfers, staking (bond/unbond/withdraw/chill), proxy
  (add/remove), and batch transactions

BTC-0

TICKET: BTC-0

Author: lcovar

modules/sdk-coin-dot/bitgo-wasm-dot-0.0.1.tgz

@@ -43,6 +43,7 @@
     "@bitgo/sdk-core": "^36.30.0",
     "@bitgo/sdk-lib-mpc": "^10.9.0",
     "@bitgo/statics": "^58.24.0",
+    "@bitgo/wasm-dot": "file:bitgo-wasm-dot-0.0.1.tgz",
     "@polkadot/api": "14.1.1",
     "@polkadot/api-augment": "14.1.1",
     "@polkadot/keyring": "13.3.1",

modules/sdk-coin-dot/package.json

@@ -7,6 +7,7 @@ import {
   Environments,
   ExplanationResult,
   KeyPair,
+  TransactionType,
   MPCAlgorithm,
   ParsedTransaction,
   ParseTransactionOptions,
@@ -39,6 +40,8 @@ import {
   Transaction,
   TransactionBuilderFactory,
   Utils,
+  explainDotTransaction,
+  type DotWasmExplanation,
 } from './lib';
 import '@polkadot/api-augment';
 import { ApiPromise, WsProvider } from '@polkadot/api';
@@ -58,14 +61,6 @@ export interface TransactionPrebuild {
   transaction: Interface.TxData;
 }
 
-export interface ExplainTransactionOptions {
-  txPrebuild: TransactionPrebuild;
-  publicKey: string;
-  feeInfo: {
-    fee: string;
-  };
-}
-
 export interface VerifiedTransactionParameters {
   txHex: string;
   prv: string;
@@ -209,6 +204,25 @@ export class Dot extends BaseCoin {
    * @param unsignedTransaction
    */
   async explainTransaction(unsignedTransaction: UnsignedTransaction): Promise<ExplanationResult> {
+    // Testnet uses WASM-based parsing (no @polkadot/api dependency).
+    if (this.getChain() === 'tdot') {
+      const material = dotUtils.getMaterial(coins.get(this.getChain()));
+      const wasmExplain = explainDotTransaction({
+        txHex: unsignedTransaction.serializedTxHex,
+        material,
+      });
+      return {
+        ...wasmExplain,
+        type: TransactionType[wasmExplain.type],
+        outputs: wasmExplain.outputs.map((o) => ({
+          ...o,
+          valueString: String(o.amount),
+        })),
+        sequenceId: wasmExplain.nonce,
+        blockNumber: unsignedTransaction.coinSpecific?.blockNumber,
+      };
+    }
+
     let outputAmount = 0;
     unsignedTransaction.parsedTx.outputs.forEach((o) => {
       outputAmount += parseInt(o.valueString, 10);
@@ -239,6 +253,15 @@ export class Dot extends BaseCoin {
     return explanationResult;
   }
 
+  /**
+   * Explain a DOT transaction from hex using WASM parsing.
+   * Bypasses txwrapper-polkadot rebuild — delegates to explainDotTransaction().
+   */
+  explainTransactionWithWasm(txHex: string, senderAddress?: string): DotWasmExplanation {
+    const material = dotUtils.getMaterial(coins.get(this.getChain()));
+    return explainDotTransaction({ txHex, material, senderAddress });
+  }
+
   verifySignTransactionParams(params: SignTransactionOptions): VerifiedTransactionParameters {
     const prv = params.prv;
 

modules/sdk-coin-dot/src/dot.ts

@@ -16,4 +16,6 @@ export { TransactionBuilderFactory } from './transactionBuilderFactory';
 export { SingletonRegistry } from './singletonRegistry';
 export { NativeTransferBuilder } from './nativeTransferBuilder';
 export { RemoveProxyBuilder } from './proxyBuilder';
+export { explainDotTransaction } from './wasmParser';
+export type { ExplainDotTransactionParams, DotWasmExplanation, DotInput } from './wasmParser';
 export { Interface, Utils };

modules/sdk-coin-dot/src/lib/index.ts

@@ -38,6 +38,7 @@ import {
 } from './iface';
 import { getAddress, getDelegateAddress } from './iface_utils';
 import utils from './utils';
+import { explainDotTransaction } from './wasmParser';
 import BigNumber from 'bignumber.js';
 import { Vec } from '@polkadot/types';
 import { PalletConstantMetadataV14 } from '@polkadot/types/interfaces';
@@ -338,6 +339,17 @@ export class Transaction extends BaseTransaction {
 
   /** @inheritdoc */
   explainTransaction(): TransactionExplanation {
+    // Testnet uses WASM-based parsing (no @polkadot/api dependency).
+    // This validates the WASM path against production traffic before
+    // replacing the legacy implementation for all networks.
+    if (this._coinConfig.name === 'tdot' && this._dotTransaction) {
+      return explainDotTransaction({
+        txHex: this.toBroadcastFormat(),
+        material: utils.getMaterial(this._coinConfig),
+        senderAddress: this._sender,
+      });
+    }
+
     const result = this.toJson();
     const displayOrder = ['outputAmount', 'changeAmount', 'outputs', 'changeOutputs', 'fee', 'type'];
     const outputs: TransactionRecipient[] = [];

modules/sdk-coin-dot/src/lib/transaction.ts

@@ -0,0 +1,88 @@
+import { TransactionType } from '@bitgo/sdk-core';
+import {
+  explainTransaction,
+  TransactionType as WasmTransactionType,
+  type ExplainedTransaction as WasmExplainedTransaction,
+} from '@bitgo/wasm-dot';
+import type { TransactionExplanation, Material } from './iface';
+
+/**
+ * Input entry for a DOT transaction.
+ * For account-model chains, there's typically one input (the sender).
+ */
+export interface DotInput {
+  address: string;
+  value: number;
+  valueString: string;
+}
+
+/**
+ * Extended explanation returned by WASM-based parsing.
+ * Includes fields needed by wallet-platform that aren't in the base TransactionExplanation.
+ */
+export interface DotWasmExplanation extends TransactionExplanation {
+  sender: string;
+  nonce: number;
+  isSigned: boolean;
+  methodName: string;
+  inputs: DotInput[];
+}
+
+/** Map WASM TransactionType (string enum) to sdk-core TransactionType (numeric enum) via name lookup */
+function mapTransactionType(wasmType: WasmTransactionType): TransactionType {
+  return TransactionType[wasmType as keyof typeof TransactionType] ?? TransactionType.Send;
+}
+
+/**
+ * Options for the WASM-based DOT transaction explanation adapter.
+ */
+export interface ExplainDotTransactionParams {
+  txHex: string;
+  material: Material;
+  senderAddress?: string;
+}
+
+/**
+ * Explain a DOT transaction using the WASM parser.
+ *
+ * Thin adapter over @bitgo/wasm-dot's explainTransaction that maps
+ * WASM types to BitGoJS TransactionExplanation format.
+ * Analogous to explainSolTransaction for Solana.
+ */
+export function explainDotTransaction(params: ExplainDotTransactionParams): DotWasmExplanation {
+  const explained: WasmExplainedTransaction = explainTransaction(params.txHex, {
+    context: { material: params.material, sender: params.senderAddress },
+  });
+
+  const sender = explained.sender || params.senderAddress || '';
+  const type = mapTransactionType(explained.type);
+  const methodName = `${explained.method.pallet}.${explained.method.name}`;
+
+  // Map WASM outputs to BitGoJS format
+  const outputs = explained.outputs.map((o) => ({
+    address: o.address,
+    amount: o.amount === 'ALL' ? '0' : o.amount,
+  }));
+
+  // Map WASM inputs to BitGoJS format (with numeric value for legacy compat)
+  const inputs: DotInput[] = explained.inputs.map((i) => {
+    const value = i.value === 'ALL' ? 0 : parseInt(i.value || '0', 10);
+    return { address: i.address, value, valueString: i.value };
+  });
+
+  return {
+    displayOrder: ['outputAmount', 'changeAmount', 'outputs', 'changeOutputs', 'fee', 'type', 'sequenceId', 'id'],
+    id: explained.id || '',
+    outputs,
+    outputAmount: explained.outputAmount,
+    changeOutputs: [],
+    changeAmount: '0',
+    fee: { fee: explained.tip || '0', type: 'tip' },
+    type,
+    sender,
+    nonce: explained.nonce,
+    isSigned: explained.isSigned,
+    methodName,
+    inputs,
+  };
+}

modules/sdk-coin-dot/src/lib/wasmParser.ts

@@ -7,7 +7,10 @@ import { Dot, Tdot, KeyPair } from '../../src';
 import * as testData from '../fixtures';
 import { chainName, txVersion, genesisHash, specVersion } from '../resources';
 import * as sinon from 'sinon';
-import { Wallet } from '@bitgo/sdk-core';
+import { TransactionType, Wallet } from '@bitgo/sdk-core';
+import { coins } from '@bitgo/statics';
+import { buildTransaction, type BuildContext, type Material } from '@bitgo/wasm-dot';
+import utils from '../../src/lib/utils';
 
 describe('DOT:', function () {
   let bitgo: TestBitGoAPI;
@@ -152,7 +155,7 @@ describe('DOT:', function () {
 
   describe('Explain Transactions:', () => {
     it('should explain an unsigned transfer transaction', async function () {
-      const explainedTransaction = await basecoin.explainTransaction(testData.unsignedTransaction);
+      const explainedTransaction = await prodCoin.explainTransaction(testData.unsignedTransaction);
       explainedTransaction.should.deepEqual({
         displayOrder: [
           'outputAmount',
@@ -185,6 +188,67 @@ describe('DOT:', function () {
     });
   });
 
+  describe('Explain Transactions (WASM):', () => {
+    const coin = coins.get('tdot');
+    const material = utils.getMaterial(coin);
+    const SENDER = testData.accounts.account1.address;
+    const RECIPIENT = testData.accounts.account2.address;
+
+    function wasmContext(nonce = 0): BuildContext {
+      return {
+        sender: SENDER,
+        nonce,
+        material: material as Material,
+        validity: { firstValid: testData.westendBlock.blockNumber, maxDuration: 2400 },
+        referenceBlock: testData.westendBlock.hash,
+      };
+    }
+
+    it('should explain a transfer via explainTransactionWithWasm', function () {
+      const tx = buildTransaction({ type: 'transfer', to: RECIPIENT, amount: 1000000000000n }, wasmContext());
+      const explained = basecoin.explainTransactionWithWasm(tx.toHex(), SENDER);
+
+      assert.strictEqual(explained.type, TransactionType.Send);
+      assert.strictEqual(explained.outputs.length, 1);
+      assert.strictEqual(explained.outputs[0].address, RECIPIENT);
+      assert.strictEqual(explained.outputs[0].amount, '1000000000000');
+      assert.strictEqual(explained.outputAmount, '1000000000000');
+      assert.strictEqual(explained.sender, SENDER);
+      assert.strictEqual(explained.methodName, 'balances.transferKeepAlive');
+    });
+
+    it('should explain a staking bond via explainTransactionWithWasm', function () {
+      const tx = buildTransaction({ type: 'stake', amount: 5000000000000n, payee: { type: 'stash' } }, wasmContext(1));
+      const explained = basecoin.explainTransactionWithWasm(tx.toHex(), SENDER);
+
+      assert.strictEqual(explained.type, TransactionType.StakingActivate);
+      assert.strictEqual(explained.outputs.length, 1);
+      assert.strictEqual(explained.outputs[0].address, 'STAKING');
+      assert.strictEqual(explained.outputs[0].amount, '5000000000000');
+    });
+
+    it('should explain a transfer via coin class explainTransaction (WASM path)', async function () {
+      const tx = buildTransaction({ type: 'transfer', to: RECIPIENT, amount: 1000000000000n }, wasmContext());
+      const unsignedTransaction = {
+        serializedTxHex: tx.toHex(),
+        signableHex: tx.toHex(),
+        derivationPath: 'm/0',
+        parsedTx: { outputs: [], spendAmount: '0', inputs: [] },
+        entryValues: undefined,
+        coinSpecific: { blockNumber: 12345 },
+      };
+      const explained = await basecoin.explainTransaction(unsignedTransaction);
+
+      assert.strictEqual(explained.type, 'Send');
+      assert.strictEqual(explained.outputs.length, 1);
+      assert.strictEqual(explained.outputs[0].address, RECIPIENT);
+      assert.strictEqual(explained.outputs[0].amount, '1000000000000');
+      assert.strictEqual(explained.outputs[0].valueString, '1000000000000');
+      assert.strictEqual(explained.sequenceId, 0);
+      assert.strictEqual(explained.blockNumber, 12345);
+    });
+  });
+
   describe('Recover Transactions:', () => {
     const sandBox = sinon.createSandbox();
     const destAddr = testData.accounts.account1.address;