feat: use proxy deposit cost for batch stake/unstake explanations

When explaining batch transactions containing proxy operations
(removeProxy+chill+unbond for unstake, bond+addProxy for stake),
use getProxyDepositCost() from @bitgo/wasm-dot to match legacy
account-lib behavior. Bumps @bitgo/wasm-dot dep to ^1.2.0.

Ticket: BTC-3062

Author: lcovar

modules/sdk-coin-dot/package.json

@@ -43,7 +43,7 @@
     "@bitgo/sdk-core": "^36.33.2",
     "@bitgo/sdk-lib-mpc": "^10.9.0",
     "@bitgo/statics": "^58.29.0",
-    "@bitgo/wasm-dot": "^1.1.2",
+    "@bitgo/wasm-dot": "^1.2.0",
     "@polkadot/api": "14.1.1",
     "@polkadot/api-augment": "14.1.1",
     "@polkadot/keyring": "13.5.6",

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

@@ -7,7 +7,7 @@
  */
 
 import { TransactionType } from '@bitgo/sdk-core';
-import { DotTransaction, parseTransaction, type ParsedMethod, type Era } from '@bitgo/wasm-dot';
+import { DotTransaction, parseTransaction, getProxyDepositCost, type ParsedMethod, type Era } from '@bitgo/wasm-dot';
 import type { BatchCallObject, ProxyType, TransactionExplanation, Material, TxData } from './iface';
 
 const MAX_NESTING_DEPTH = 10;
@@ -180,11 +180,30 @@ function buildExplanation(params: {
   const parsed = parseTransaction(tx, context);
 
   const typeName = deriveTransactionType(parsed.method, 0);
-  const outputs = extractOutputs(parsed.method, 0);
   const sender = parsed.sender ?? params.senderAddress;
-  const inputs: { address: string; value: string }[] = sender
-    ? outputs.map((o) => ({ address: sender, value: o.amount }))
-    : [];
+
+  // Check for batch patterns that need proxy deposit cost handling
+  const batchInfo = detectProxyBatch(parsed.method);
+  let outputs: { address: string; amount: string }[];
+  let inputs: { address: string; value: string }[];
+
+  if (batchInfo && sender) {
+    const proxyDepositCost = getProxyDepositCost(params.material.metadata).toString();
+    if (batchInfo.type === 'unstake') {
+      // Unstaking batch (removeProxy + chill + unbond): proxy deposit refund flows
+      // from proxy address back to sender. The unbond amount is NOT in inputs/outputs.
+      outputs = [{ address: sender, amount: proxyDepositCost }];
+      inputs = [{ address: batchInfo.proxyAddress, value: proxyDepositCost }];
+    } else {
+      // Staking batch (bond + addProxy): bond amount + proxy deposit cost
+      const bondOutputs = extractOutputs(parsed.method, 0).filter((o) => o.address === 'STAKING');
+      outputs = [...bondOutputs, { address: batchInfo.proxyAddress, amount: proxyDepositCost }];
+      inputs = outputs.map((o) => ({ address: sender, value: o.amount }));
+    }
+  } else {
+    outputs = extractOutputs(parsed.method, 0);
+    inputs = sender ? outputs.map((o) => ({ address: sender, value: o.amount })) : [];
+  }
 
   const outputAmount = outputs.reduce((sum, o) => {
     if (o.amount === 'ALL') return sum;
@@ -297,6 +316,55 @@ function extractOutputs(method: ParsedMethod, depth: number): { address: string;
   }
 }
 
+// =============================================================================
+// Batch proxy detection
+// =============================================================================
+
+interface ProxyBatchInfo {
+  type: 'stake' | 'unstake';
+  proxyAddress: string;
+}
+
+/**
+ * Detect batch transactions involving proxy operations (stake/unstake batches).
+ *
+ * Legacy account-lib reports proxy deposit cost (ProxyDepositBase + ProxyDepositFactor)
+ * as the value for these batches instead of the bond/unbond amount.
+ *
+ * Unstaking batch: removeProxy + chill + unbond
+ * Staking batch: bond + addProxy
+ */
+function detectProxyBatch(method: ParsedMethod): ProxyBatchInfo | undefined {
+  const key = `${method.pallet}.${method.name}`;
+  if (key !== 'utility.batch' && key !== 'utility.batchAll') return undefined;
+
+  const calls = ((method.args ?? {}) as Record<string, unknown>).calls as ParsedMethod[] | undefined;
+  if (!calls || calls.length === 0) return undefined;
+
+  const callKeys = calls.map((c) => `${c.pallet}.${c.name}`);
+
+  // Unstaking batch: removeProxy + chill + unbond (3 calls)
+  if (
+    calls.length === 3 &&
+    callKeys[0] === 'proxy.removeProxy' &&
+    callKeys[1] === 'staking.chill' &&
+    callKeys[2] === 'staking.unbond'
+  ) {
+    const removeProxyArgs = (calls[0].args ?? {}) as Record<string, unknown>;
+    const proxyAddress = String(removeProxyArgs.delegate ?? '');
+    return { type: 'unstake', proxyAddress };
+  }
+
+  // Staking batch: bond + addProxy (2 calls)
+  if (calls.length === 2 && callKeys[0] === 'staking.bond' && callKeys[1] === 'proxy.addProxy') {
+    const addProxyArgs = (calls[1].args ?? {}) as Record<string, unknown>;
+    const proxyAddress = String(addProxyArgs.delegate ?? '');
+    return { type: 'stake', proxyAddress };
+  }
+
+  return undefined;
+}
+
 // =============================================================================
 // Helpers
 // =============================================================================

modules/sdk-coin-dot/test/unit/wasmParserExplanation.ts

@@ -0,0 +1,237 @@
+/**
+ * WASM Parser Explanation Tests
+ *
+ * Tests for explainDotTransaction, specifically verifying batch transaction
+ * handling with proxy deposit costs matches legacy account-lib behavior.
+ *
+ * Uses WASM-built transactions (not legacy rawTx fixtures) since the WASM
+ * parser requires metadata-compatible signed extension encoding.
+ */
+
+import assert from 'assert';
+import { coins } from '@bitgo/statics';
+import { TransactionType } from '@bitgo/sdk-core';
+import { explainDotTransaction } from '../../src/lib/wasmParser';
+import { buildTransaction, type BuildContext, type Material as WasmMaterial } from '@bitgo/wasm-dot';
+import type { Material } from '../../src/lib/iface';
+import { accounts, westendBlock } from '../fixtures';
+import utils from '../../src/lib/utils';
+
+describe('WASM Parser Explanation', function () {
+  const coin = coins.get('tdot');
+  // utils.getMaterial returns the iface Material shape; cast to WasmMaterial for buildTransaction
+  const material = utils.getMaterial(coin) as Material & WasmMaterial;
+
+  function createWasmContext(overrides: Partial<BuildContext> = {}): BuildContext {
+    return {
+      sender: accounts.account1.address,
+      nonce: 0,
+      tip: 0n,
+      material,
+      validity: {
+        firstValid: westendBlock.blockNumber,
+        maxDuration: 2400,
+      },
+      referenceBlock: westendBlock.hash,
+      ...overrides,
+    };
+  }
+
+  describe('Batch unstake (removeProxy + chill + unbond)', function () {
+    it('should explain batch unstake with proxy deposit cost', function () {
+      const unbondAmount = 5000000000000n; // 5 DOT
+      const proxyDelegate = accounts.account2.address;
+
+      // Build a batch unstake tx: removeProxy + chill + unbond
+      const wasmTx = buildTransaction(
+        {
+          type: 'batch',
+          calls: [
+            { type: 'removeProxy', delegate: proxyDelegate, proxyType: 'Staking', delay: 0 },
+            { type: 'chill' },
+            { type: 'unstake', amount: unbondAmount },
+          ],
+          atomic: true,
+        },
+        createWasmContext()
+      );
+
+      const txHex = wasmTx.toBroadcastFormat();
+      const explanation = explainDotTransaction({
+        txHex,
+        material,
+        senderAddress: accounts.account1.address,
+      });
+
+      // Should be Batch type
+      assert.strictEqual(explanation.type, TransactionType.Batch);
+      assert.ok(explanation.methodName.includes('batchAll'), `Expected batchAll, got ${explanation.methodName}`);
+
+      // Outputs should contain proxy deposit cost, NOT the unbond amount
+      assert.strictEqual(explanation.outputs.length, 1, 'Should have exactly one output (proxy deposit cost)');
+      const output = explanation.outputs[0];
+      assert.strictEqual(output.address, accounts.account1.address, 'Output should go to sender (deposit refund)');
+      const proxyDepositCost = BigInt(output.amount);
+      assert.ok(proxyDepositCost > 0n, 'Proxy deposit cost should be positive');
+      // The proxy deposit cost should NOT equal the unbond amount
+      assert.notStrictEqual(proxyDepositCost, unbondAmount, 'Should use proxy deposit cost, not unbond amount');
+
+      // Input should come from the proxy delegate address
+      assert.strictEqual(explanation.inputs.length, 1, 'Should have exactly one input');
+      assert.strictEqual(explanation.inputs[0].address, proxyDelegate, 'Input should come from proxy delegate');
+      assert.strictEqual(
+        explanation.inputs[0].valueString,
+        output.amount,
+        'Input value should equal proxy deposit cost'
+      );
+    });
+
+    it('proxy deposit cost should be consistent across calls', function () {
+      const proxyDelegate = accounts.account2.address;
+      const wasmTx = buildTransaction(
+        {
+          type: 'batch',
+          calls: [
+            { type: 'removeProxy', delegate: proxyDelegate, proxyType: 'Staking', delay: 0 },
+            { type: 'chill' },
+            { type: 'unstake', amount: 1000000000000n },
+          ],
+          atomic: true,
+        },
+        createWasmContext()
+      );
+
+      const txHex = wasmTx.toBroadcastFormat();
+      const explanation1 = explainDotTransaction({ txHex, material, senderAddress: accounts.account1.address });
+      const explanation2 = explainDotTransaction({ txHex, material, senderAddress: accounts.account1.address });
+
+      assert.strictEqual(explanation1.outputs[0].amount, explanation2.outputs[0].amount);
+    });
+
+    it('should work with non-atomic batch (utility.batch)', function () {
+      const proxyDelegate = accounts.account2.address;
+      const wasmTx = buildTransaction(
+        {
+          type: 'batch',
+          calls: [
+            { type: 'removeProxy', delegate: proxyDelegate, proxyType: 'Staking', delay: 0 },
+            { type: 'chill' },
+            { type: 'unstake', amount: 3000000000000n },
+          ],
+          atomic: false,
+        },
+        createWasmContext()
+      );
+
+      const txHex = wasmTx.toBroadcastFormat();
+      const explanation = explainDotTransaction({ txHex, material, senderAddress: accounts.account1.address });
+
+      assert.strictEqual(explanation.type, TransactionType.Batch);
+      assert.strictEqual(explanation.outputs.length, 1);
+      assert.ok(BigInt(explanation.outputs[0].amount) > 0n);
+      assert.strictEqual(explanation.inputs[0].address, proxyDelegate);
+    });
+  });
+
+  describe('Batch stake (bond + addProxy)', function () {
+    it('should explain batch stake with bond amount and proxy deposit cost', function () {
+      const bondAmount = 10000000000000n; // 10 DOT
+      const proxyDelegate = accounts.account2.address;
+
+      const wasmTx = buildTransaction(
+        {
+          type: 'batch',
+          calls: [
+            { type: 'stake', amount: bondAmount, payee: { type: 'staked' } },
+            { type: 'addProxy', delegate: proxyDelegate, proxyType: 'Staking', delay: 0 },
+          ],
+          atomic: true,
+        },
+        createWasmContext()
+      );
+
+      const txHex = wasmTx.toBroadcastFormat();
+      const explanation = explainDotTransaction({ txHex, material, senderAddress: accounts.account1.address });
+
+      assert.strictEqual(explanation.type, TransactionType.Batch);
+
+      // Should have two outputs: bond amount (STAKING) + proxy deposit cost (to proxy delegate)
+      assert.strictEqual(explanation.outputs.length, 2, 'Should have bond + proxy deposit outputs');
+
+      const stakingOutput = explanation.outputs.find((o) => o.address === 'STAKING');
+      assert.ok(stakingOutput, 'Should have STAKING output for bond amount');
+      assert.strictEqual(BigInt(stakingOutput!.amount), bondAmount, 'Bond amount should match');
+
+      const proxyOutput = explanation.outputs.find((o) => o.address !== 'STAKING');
+      assert.ok(proxyOutput, 'Should have proxy deposit output');
+      assert.strictEqual(proxyOutput!.address, proxyDelegate);
+      assert.ok(BigInt(proxyOutput!.amount) > 0n, 'Proxy deposit cost should be positive');
+
+      // All inputs should come from sender
+      assert.strictEqual(explanation.inputs.length, 2);
+      for (const input of explanation.inputs) {
+        assert.strictEqual(input.address, accounts.account1.address);
+      }
+    });
+  });
+
+  describe('Non-batch transactions (should not be affected)', function () {
+    it('should explain transfer normally', function () {
+      const wasmTx = buildTransaction(
+        { type: 'transfer', to: accounts.account2.address, amount: 1000000000000n, keepAlive: true },
+        createWasmContext()
+      );
+
+      const explanation = explainDotTransaction({
+        txHex: wasmTx.toBroadcastFormat(),
+        material,
+        senderAddress: accounts.account1.address,
+      });
+
+      assert.strictEqual(explanation.type, TransactionType.Send);
+      assert.strictEqual(explanation.outputs.length, 1);
+      assert.strictEqual(explanation.outputs[0].address, accounts.account2.address);
+      assert.strictEqual(explanation.outputs[0].amount, '1000000000000');
+    });
+
+    it('should explain single unstake (unbond) normally', function () {
+      const wasmTx = buildTransaction({ type: 'unstake', amount: 5000000000000n }, createWasmContext());
+
+      const explanation = explainDotTransaction({
+        txHex: wasmTx.toBroadcastFormat(),
+        material,
+        senderAddress: accounts.account1.address,
+      });
+
+      assert.strictEqual(explanation.type, TransactionType.StakingUnlock);
+      assert.strictEqual(explanation.outputs.length, 1);
+      assert.strictEqual(explanation.outputs[0].address, 'STAKING');
+      assert.strictEqual(explanation.outputs[0].amount, '5000000000000');
+    });
+
+    it('should explain batch of transfers normally (no proxy involved)', function () {
+      const wasmTx = buildTransaction(
+        {
+          type: 'batch',
+          calls: [
+            { type: 'transfer', to: accounts.account2.address, amount: 1000000000000n, keepAlive: true },
+            { type: 'transfer', to: accounts.account3.address, amount: 2000000000000n, keepAlive: true },
+          ],
+          atomic: true,
+        },
+        createWasmContext()
+      );
+
+      const explanation = explainDotTransaction({
+        txHex: wasmTx.toBroadcastFormat(),
+        material,
+        senderAddress: accounts.account1.address,
+      });
+
+      assert.strictEqual(explanation.type, TransactionType.Batch);
+      assert.strictEqual(explanation.outputs.length, 2);
+      assert.strictEqual(explanation.outputs[0].amount, '1000000000000');
+      assert.strictEqual(explanation.outputs[1].amount, '2000000000000');
+    });
+  });
+});