feat(abstract-wasm-coin): add pluggable WASM coin adapter module

Introduces modules/abstract-wasm-coin with:
- WasmCoinAdapter interface (deriveAddress, parseTransaction,
  buildTransaction) — no account-lib dependency
- AbstractWasmCoin wrapper with capability checking
- WasmCoinRegistry for adapter registration and dispatch
- Demo adapters for wasm-dot, wasm-solana, wasm-ton
- Unit tests covering registry, capability guards, and dispatch

BitGoJS coin modules retain explain logic, verification policy,
and product semantics; WASM packages own chain-native parsing
and building primitives only.

Ticket: T1-3431
Session-Id: bcc064c3-f85f-4618-8733-8b5cd729b515
Task-Id: f1f9f55c-e450-4e7c-ab54-825b699fd955

Author: OttoAllmendinger

modules/abstract-wasm-coin/.eslintignore

@@ -0,0 +1,4 @@
+node_modules
+.idea
+public
+dist

modules/abstract-wasm-coin/.mocharc.yml

@@ -0,0 +1,8 @@
+require: 'tsx'
+timeout: '60000'
+reporter: 'min'
+reporter-option:
+  - 'cdn=true'
+  - 'json=false'
+exit: true
+spec: ['test/unit/**/*.ts']

modules/abstract-wasm-coin/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@bitgo/abstract-wasm-coin",
+  "version": "1.0.0",
+  "description": "BitGo SDK pluggable WASM coin adapter interface",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "scripts": {
+    "build": "npm run prepare",
+    "build-ts": "yarn tsc --build --incremental --verbose .",
+    "fmt": "prettier --write .",
+    "check-fmt": "prettier --check '**/*.{ts,js,json}'",
+    "clean": "rm -rf ./dist",
+    "lint": "eslint --quiet .",
+    "prepare": "npm run build-ts",
+    "test": "npm run coverage",
+    "coverage": "nyc -- npm run unit-test",
+    "unit-test": "mocha"
+  },
+  "author": "BitGo SDK Team <sdkteam@bitgo.com>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BitGo/BitGoJS.git",
+    "directory": "modules/abstract-wasm-coin"
+  },
+  "lint-staged": {
+    "*.{js,ts}": [
+      "yarn prettier --write",
+      "yarn eslint --fix"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "nyc": {
+    "extension": [
+      ".ts"
+    ]
+  },
+  "dependencies": {
+    "@bitgo/wasm-dot": "^1.7.0",
+    "@bitgo/wasm-solana": "^2.6.0",
+    "@bitgo/wasm-ton": "^1.1.1"
+  },
+  "devDependencies": {
+    "@bitgo/sdk-test": "^9.1.44"
+  },
+  "gitHead": "18e460ddf02de2dbf13c2aa243478188fb539f0c",
+  "files": [
+    "dist"
+  ]
+}

modules/abstract-wasm-coin/src/abstractWasmCoin.ts

@@ -0,0 +1,48 @@
+import type {
+  WasmCoinAdapter,
+  WasmCoinCapability,
+  WasmDerivedAddress,
+  WasmParsedTransaction,
+  WasmBuiltTransaction,
+} from './types';
+
+/**
+ * Abstract wrapper that dispatches calls to a registered WasmCoinAdapter.
+ *
+ * Callers use this class instead of talking to adapters directly so that:
+ *   - capability checks are centralized and consistent
+ *   - the registry can return a uniform type regardless of which adapter is loaded
+ *   - future cross-cutting concerns (telemetry, error wrapping) have one place to live
+ */
+export class AbstractWasmCoin {
+  constructor(private readonly adapter: WasmCoinAdapter) {}
+
+  get coin(): string {
+    return this.adapter.coin;
+  }
+
+  hasCapability(cap: WasmCoinCapability): boolean {
+    return this.adapter.capabilities.has(cap);
+  }
+
+  deriveAddress(params: unknown): Promise<WasmDerivedAddress> {
+    if (!this.adapter.deriveAddress) {
+      throw new Error(`${this.adapter.coin}: deriveAddress is not supported`);
+    }
+    return Promise.resolve(this.adapter.deriveAddress(params as never));
+  }
+
+  parseTransaction(params: unknown): Promise<WasmParsedTransaction> {
+    if (!this.adapter.parseTransaction) {
+      throw new Error(`${this.adapter.coin}: parseTransaction is not supported`);
+    }
+    return Promise.resolve(this.adapter.parseTransaction(params as never));
+  }
+
+  buildTransaction(params: unknown): Promise<WasmBuiltTransaction> {
+    if (!this.adapter.buildTransaction) {
+      throw new Error(`${this.adapter.coin}: buildTransaction is not supported`);
+    }
+    return Promise.resolve(this.adapter.buildTransaction(params as never));
+  }
+}

modules/abstract-wasm-coin/src/adapters/dot.ts

@@ -0,0 +1,76 @@
+/**
+ * Polkadot WASM adapter for abstract-wasm-coin.
+ *
+ * Wraps @bitgo/wasm-dot and exposes:
+ *   - parseTransaction  — decodes a hex-encoded extrinsic into normalized outputs/inputs
+ *
+ * Explain logic (type derivation, staking destination sentinel, batch pattern
+ * detection, proxy deposit cost) stays in sdk-coin-dot/wasmParser.ts.
+ * This adapter is a thin translation layer only.
+ */
+import { DotTransaction, parseTransaction } from '@bitgo/wasm-dot';
+import type { Material } from '@bitgo/wasm-dot';
+import type { WasmCoinAdapter, WasmCoinCapability, WasmParsedTransaction } from '../types';
+
+// =============================================================================
+// Adapter-specific param/result types
+// =============================================================================
+
+export interface DotParseParams {
+  /** Hex-encoded extrinsic bytes. */
+  txHex: string;
+  /** Runtime material (genesisHash, specVersion, metadata, etc.) required for parsing. */
+  material: Material;
+  senderAddress?: string;
+}
+
+export interface DotParsedTransaction extends WasmParsedTransaction {
+  raw: ReturnType<typeof parseTransaction>;
+}
+
+// =============================================================================
+// Adapter implementation
+// =============================================================================
+
+export const dotAdapter: WasmCoinAdapter<never, never, DotParseParams, DotParsedTransaction> = {
+  coin: 'dot',
+  capabilities: new Set<WasmCoinCapability>(['parseTransaction']),
+
+  parseTransaction(params: DotParseParams): DotParsedTransaction {
+    const tx = DotTransaction.fromHex(params.txHex, params.material);
+    const context = {
+      material: params.material,
+      sender: params.senderAddress,
+    };
+    const parsed = parseTransaction(tx, context);
+
+    // Extract the most basic output: dest + value from a transfer, if present.
+    // Explain policy (staking, batch, proxy) stays in sdk-coin-dot.
+    const outputs: Array<{ address: string; amount: string }> = [];
+    const inputs: Array<{ address: string; amount: string }> = [];
+
+    const args = (parsed.method.args ?? {}) as Record<string, unknown>;
+    const key = `${parsed.method.pallet}.${parsed.method.name}`;
+    if (
+      key === 'balances.transfer' ||
+      key === 'balances.transferKeepAlive' ||
+      key === 'balances.transferAllowDeath'
+    ) {
+      const dest = String(args.dest ?? '');
+      const value = String(args.value ?? '0');
+      if (dest) {
+        outputs.push({ address: dest, amount: value });
+        if (params.senderAddress) {
+          inputs.push({ address: params.senderAddress, amount: value });
+        }
+      }
+    }
+
+    return {
+      id: parsed.id ?? undefined,
+      inputs,
+      outputs,
+      raw: parsed,
+    };
+  },
+};

modules/abstract-wasm-coin/src/adapters/solana.ts

@@ -0,0 +1,64 @@
+/**
+ * Solana WASM adapter for abstract-wasm-coin.
+ *
+ * Wraps @bitgo/wasm-solana and exposes:
+ *   - parseTransaction  — decodes a base64-encoded transaction into normalized outputs/inputs
+ *   - buildTransaction  — not yet implemented (wasm-solana building is handled inside sdk-coin-sol)
+ *
+ * Explain logic, fee policy, token naming, and product semantics deliberately
+ * stay in sdk-coin-sol. This adapter is a thin translation layer only.
+ */
+import { Transaction, parseTransaction } from '@bitgo/wasm-solana';
+import type { WasmCoinAdapter, WasmCoinCapability, WasmParsedTransaction } from '../types';
+
+// =============================================================================
+// Adapter-specific param/result types
+// =============================================================================
+
+export interface SolanaParseParams {
+  /** Base64-encoded transaction bytes. */
+  txBase64: string;
+}
+
+export interface SolanaParsedTransaction extends WasmParsedTransaction {
+  raw: ReturnType<typeof parseTransaction>;
+}
+
+// =============================================================================
+// Adapter implementation
+// =============================================================================
+
+export const solanaAdapter: WasmCoinAdapter<never, never, SolanaParseParams, SolanaParsedTransaction> = {
+  coin: 'sol',
+  capabilities: new Set<WasmCoinCapability>(['parseTransaction']),
+
+  parseTransaction(params: SolanaParseParams): SolanaParsedTransaction {
+    const txBytes = Buffer.from(params.txBase64, 'base64');
+    const tx = Transaction.fromBytes(txBytes);
+    const parsed = parseTransaction(tx);
+
+    // Extract normalized outputs (Transfer instructions only — explain logic stays in sdk-coin-sol)
+    const outputs: Array<{ address: string; amount: string }> = [];
+    const inputs: Array<{ address: string; amount: string }> = [];
+
+    for (const instr of parsed.instructionsData) {
+      switch (instr.type) {
+        case 'Transfer':
+          outputs.push({ address: instr.toAddress, amount: String(instr.amount) });
+          inputs.push({ address: instr.fromAddress, amount: String(instr.amount) });
+          break;
+        case 'TokenTransfer':
+          outputs.push({ address: instr.toAddress, amount: String(instr.amount) });
+          inputs.push({ address: instr.fromAddress, amount: String(instr.amount) });
+          break;
+      }
+    }
+
+    // Transaction ID: first signature, undefined when unsigned (all-zeros base58)
+    const ALL_ZEROS = '1111111111111111111111111111111111111111111111111111111111111111';
+    const sig = parsed.signatures[0];
+    const id = sig && sig !== ALL_ZEROS ? sig : undefined;
+
+    return { id, inputs, outputs, raw: parsed };
+  },
+};

modules/abstract-wasm-coin/src/adapters/ton.ts

@@ -0,0 +1,82 @@
+/**
+ * TON WASM adapter for abstract-wasm-coin.
+ *
+ * Wraps @bitgo/wasm-ton and exposes:
+ *   - deriveAddress     — normalizes a raw TON address to bounceable EQ... form
+ *   - parseTransaction  — decodes a base64-encoded TON transaction into normalized outputs/inputs
+ *
+ * Explain logic, verification policy, and product semantics stay in sdk-coin-ton.
+ * This adapter is a thin translation layer only.
+ */
+import { Transaction as WasmTonTransaction, parseTransaction, decode as wasmDecode, encode as wasmEncode } from '@bitgo/wasm-ton';
+import type { WasmCoinAdapter, WasmCoinCapability, WasmDerivedAddress, WasmParsedTransaction } from '../types';
+
+// =============================================================================
+// Adapter-specific param/result types
+// =============================================================================
+
+export interface TonAddressParams {
+  /** Raw address string (any TON format: EQ..., UQ..., workchain:hash hex). */
+  address: string;
+  /** When true (default), return the bounceable EQ... address. */
+  bounceable?: boolean;
+}
+
+export interface TonDerivedAddress extends WasmDerivedAddress {
+  raw: { workchainId: number; addressHash: Uint8Array };
+}
+
+export interface TonParseParams {
+  /** Base64-encoded TON transaction bytes. */
+  txBase64: string;
+  /** When true (default), return bounceable EQ... destination addresses. */
+  toAddressBounceable?: boolean;
+}
+
+export interface TonParsedTransaction extends WasmParsedTransaction {
+  raw: ReturnType<typeof parseTransaction>;
+}
+
+// =============================================================================
+// Adapter implementation
+// =============================================================================
+
+export const tonAdapter: WasmCoinAdapter<TonAddressParams, TonDerivedAddress, TonParseParams, TonParsedTransaction> = {
+  coin: 'ton',
+  capabilities: new Set<WasmCoinCapability>(['deriveAddress', 'parseTransaction']),
+
+  deriveAddress(params: TonAddressParams): TonDerivedAddress {
+    const bounceable = params.bounceable !== false;
+    const decoded = wasmDecode(params.address);
+    const address = wasmEncode(decoded.workchainId, decoded.addressHash, bounceable);
+    return {
+      address,
+      raw: { workchainId: decoded.workchainId, addressHash: decoded.addressHash },
+    };
+  },
+
+  parseTransaction(params: TonParseParams): TonParsedTransaction {
+    const toAddressBounceable = params.toAddressBounceable !== false;
+    const tx = WasmTonTransaction.fromBytes(Buffer.from(params.txBase64, 'base64'));
+    const parsed = parseTransaction(tx);
+
+    const outputs: Array<{ address: string; amount: string }> = [];
+    const inputs: Array<{ address: string; amount: string }> = [];
+
+    for (const action of parsed.sendActions) {
+      const address = toAddressBounceable ? action.destinationBounceable : action.destination;
+      const amount = String(action.jettonTransfer ? action.jettonTransfer.amount : action.amount);
+      outputs.push({ address, amount });
+    }
+
+    // TON is account-model: inputs mirror total output from the sender.
+    const totalAmount = outputs.reduce((sum, o) => sum + BigInt(o.amount), 0n);
+    if (outputs.length > 0) {
+      // Sender address not available from the parsed payload at this layer;
+      // callers that need it should use the raw field.
+      inputs.push({ address: '', amount: String(totalAmount) });
+    }
+
+    return { id: tx.id, inputs, outputs, raw: parsed };
+  },
+};

modules/abstract-wasm-coin/src/demo/dotDemo.ts

@@ -0,0 +1,13 @@
+/**
+ * Demo: Polkadot WASM adapter usage through the abstract-wasm-coin registry.
+ */
+import type { Material } from '@bitgo/wasm-dot';
+import { defaultRegistry } from '../registry';
+import { dotAdapter } from '../adapters/dot';
+
+defaultRegistry.register(dotAdapter);
+
+export async function parseDotTransaction(txHex: string, material: Material, senderAddress?: string) {
+  const wasm = defaultRegistry.get('dot');
+  return wasm.parseTransaction({ txHex, material, senderAddress });
+}

modules/abstract-wasm-coin/src/demo/solanaDemo.ts

@@ -0,0 +1,16 @@
+/**
+ * Demo: Solana WASM adapter usage through the abstract-wasm-coin registry.
+ *
+ * Shows that BitGoJS code can call the same entry point regardless of chain:
+ *   registry.get('sol').parseTransaction(...)
+ */
+import { defaultRegistry } from '../registry';
+import { solanaAdapter } from '../adapters/solana';
+
+// Register the adapter once at startup
+defaultRegistry.register(solanaAdapter);
+
+export async function parseSolanaTransaction(txBase64: string) {
+  const wasm = defaultRegistry.get('sol');
+  return wasm.parseTransaction({ txBase64 });
+}

modules/abstract-wasm-coin/src/demo/tonDemo.ts

@@ -0,0 +1,20 @@
+/**
+ * Demo: TON WASM adapter usage through the abstract-wasm-coin registry.
+ *
+ * Shows both primitives: address normalization and transaction parsing,
+ * called through the same uniform interface as Solana and Polkadot.
+ */
+import { defaultRegistry } from '../registry';
+import { tonAdapter } from '../adapters/ton';
+
+defaultRegistry.register(tonAdapter);
+
+export async function normalizeTonAddress(address: string, bounceable = true) {
+  const wasm = defaultRegistry.get('ton');
+  return wasm.deriveAddress({ address, bounceable });
+}
+
+export async function parseTonTransaction(txBase64: string, toAddressBounceable = true) {
+  const wasm = defaultRegistry.get('ton');
+  return wasm.parseTransaction({ txBase64, toAddressBounceable });
+}