feat: add explainSolTransaction using @bitgo/wasm-solana

[lcovar]

Summary

Add a standalone explainSolTransaction() function to sdk-coin-sol that uses @bitgo/wasm-solana to explain Solana transactions without depending on @solana/web3.js.

This is a thin ~100-line adapter that replaces the need for the legacy 800+ line Transaction class explain logic. The heavy lifting (parsing, instruction combining, type derivation) happens in @bitgo/wasm-solana — this adapter only handles:

• Token name resolution (mint address → sol:usdc via @bitgo/statics)
• bigint → string conversion at the serialization boundary
• StakingAuthorize → StakingAuthorizeRaw type mapping for downstream compatibility
• Mapping to TransactionExplanation interface

Changes

• explainTransactionWasm.ts (new): Standalone adapter that calls @bitgo/wasm-solana's explainTransaction(), resolves token names, maps staking authorize fields, and returns TransactionExplanation including inputs and feePayer
• transaction.ts: Route tsol through WASM-based explain (validates against production traffic before replacing legacy for all networks)
• sol.ts: Add explainTransactionWithWasm() method at coin class level
• iface.ts: Add ataOwnerMap and stakingAuthorize to TransactionExplanation interface
• instructionParamsFactory.ts: Add Jito stake pool operations (StakePoolDepositSol, StakePoolWithdrawStake)
• jitoWasmVerification.ts: New test file verifying Jito liquid staking explain output
• transaction.ts tests: Updated assertions for WASM parity (fee defaults to '0' instead of 'UNAVAILABLE', ataOwnerMap, inputs, feePayer, token name via statics)
• sol.ts tests: Updated explain assertions to include inputs and feePayer returned by WASM path
• webpack config: Add WASM asset handling for @bitgo/wasm-solana
• package.json: Add @bitgo/wasm-solana dependency

Key decisions

• tsol only: WASM path is gated to testnet (tsol) to validate against production traffic before replacing the legacy path for mainnet
• Fee behavior: Returns fee: '0' and feeRate: undefined when fee info not provided (instead of 'UNAVAILABLE'). Downstream already converts UNAVAILABLE → '0', so this is a no-op change
• StakingAuthorizeRaw: WASM can decode both raw and non-raw authorize instructions natively, but downstream expects the StakingAuthorizeRaw type name, so the adapter maps it
• Token names: Resolved via @bitgo/statics. Tokens not in statics return the raw mint address
• inputs/feePayer: Now included in the return so consumers (e.g. wallet-platform) can use the SDK as a single source of truth without calling wasm-solana directly
• Test updates: 26 test assertions updated to include inputs and feePayer — these fields were already on the TransactionExplanation interface but weren't populated by the WASM path until now

Depends on

• BitGoWASM PR #166 — explainTransaction() with StakingAuthorizeInfo, optional lamportsPerSignature (defaults to 5000n)

Test Plan

• All existing sdk-coin-sol tests pass with updated assertions
• New Jito WASM verification tests pass
• Parity verified against legacy Transaction class output for all transaction types

TICKET: BTC-3025

[OttoAllmendinger]

we can move towards bigint a little bit more

where external interfaces force us to string keep it

[OttoAllmendinger]

Suggested change

	let outputAmount = '0';
	let outputAmount = 0n;

[OttoAllmendinger]

let's avoid the internal bigint casts - why is instr.params.amount not a bigint already?

[OttoAllmendinger]

yet another way to sum up things... use bigint instead

[OttoAllmendinger]

I'm guessing the interface forces us to do this ugliness?

[lcovar]

Unfortunately yes, base class forces the return type of string while _id can be string | undefined so it's a bit silly. We have to return a string, i guess we can return an empty string.

Seeing what it would take to update the base class to accept undefined as a return type. It would cause some breaking changes though but lets see. 🤖

[OttoAllmendinger]

Fixing the interface could spiral out of control very quickly, so let's leave it. I just need to know what is hard to change and what is easy to change. You can use the override keyword in typescript to signal that a method or getter implements a base method.

[OttoAllmendinger]

counting on you claude

[OttoAllmendinger]

this whole thing gives me a deja vue

@claude can we consolidate here

[OttoAllmendinger]

🤖 Claude here.

Yes, this output extraction loop is duplicated in three places:

1. Transaction.explainTransaction() (transaction.ts:525-587) using BigNumber
2. WasmTransaction.explainTransaction() (wasm/transaction.ts:206-240) using bigint
3. Sol.explainTransactionWithWasm() (sol.ts:810-860) using bigint

Proposal: extract a shared free function in a new lib/explainUtil.ts:

interface ExplainedOutputs {
  outputs: TransactionRecipient[];
  tokenEnablements: ITokenEnablement[];
  outputAmount: bigint;
  memo?: string;
}

function extractOutputsFromInstructions(instructions: InstructionParams[]): ExplainedOutputs {
  const outputs: TransactionRecipient[] = [];
  const tokenEnablements: ITokenEnablement[] = [];
  let outputAmount = 0n;
  let memo: string | undefined;

  for (const instr of instructions) {
    switch (instr.type) {
      case InstructionBuilderTypes.Transfer:
        outputs.push({ address: instr.params.toAddress, amount: instr.params.amount });
        outputAmount += BigInt(instr.params.amount);
        break;
      case InstructionBuilderTypes.TokenTransfer:
        outputs.push({
          address: instr.params.toAddress,
          amount: instr.params.amount,
          tokenName: instr.params.tokenName,
        });
        break;
      case InstructionBuilderTypes.CreateNonceAccount:
        outputs.push({ address: instr.params.nonceAddress, amount: instr.params.amount });
        outputAmount += BigInt(instr.params.amount);
        break;
      case InstructionBuilderTypes.StakingActivate:
        outputs.push({ address: instr.params.stakingAddress, amount: instr.params.amount });
        outputAmount += BigInt(instr.params.amount);
        break;
      case InstructionBuilderTypes.StakingWithdraw:
        outputs.push({ address: instr.params.fromAddress, amount: instr.params.amount });
        outputAmount += BigInt(instr.params.amount);
        break;
      case InstructionBuilderTypes.CreateAssociatedTokenAccount:
        tokenEnablements.push({
          address: instr.params.ataAddress,
          tokenName: instr.params.tokenName,
          tokenAddress: instr.params.mintAddress,
        });
        break;
      case InstructionBuilderTypes.Memo:
        memo = instr.params.memo;
        break;
    }
  }
  return { outputs, tokenEnablements, outputAmount, memo };
}

All three call sites then become thin wrappers that call this, eliminating the duplication. The legacy Transaction.explainTransaction() can convert the bigint result to BigNumber at the boundary if needed (or migrate to bigint too).

[OttoAllmendinger]

@claude suggest a inner func that has a nicer signature with already parsed args

don't we want bigint for amounts anyway?

[OttoAllmendinger]

🤖 Claude here.

Yes, bigint for amounts. The ExplainTransactionOptions.feeInfo.fee and tokenAccountRentExemptAmount come in as string from the external interface (TransactionFee.fee is string in sdk-core), so we should convert exactly once at the boundary.

Proposal — parse external args at the top, then pass typed values into a pure inner function:

interface WasmExplainArgs {
  combinedInstructions: InstructionParams[];
  transactionType: TransactionType;
  memo?: string;
  nonce: string;
  durableNonce?: DurableNonceParams;
  numSignatures: number;
  signatures: Uint8Array[];
  lamportsPerSignature: bigint;
  rentPerAta: bigint;
}

function buildWasmExplanation(args: WasmExplainArgs): SolLibTransactionExplanation {
  const { outputs, tokenEnablements, outputAmount } = extractOutputsFromInstructions(args.combinedInstructions);
  const signatureFee = args.lamportsPerSignature * BigInt(args.numSignatures);
  const rentFee = args.rentPerAta * BigInt(tokenEnablements.length);
  const totalFee = (signatureFee + rentFee).toString();
  const txId = getTransactionId(args.signatures);

  return {
    displayOrder: [ ... ],
    id: txId,
    type: TransactionType[args.transactionType],
    changeOutputs: [],
    changeAmount: '0',
    outputAmount: outputAmount.toString(),
    outputs,
    fee: { fee: totalFee, feeRate: Number(args.lamportsPerSignature) },
    memo: args.memo,
    blockhash: args.nonce,
    durableNonce: args.durableNonce,
    tokenEnablements,
  };
}

Then explainTransactionWithWasm becomes a thin adapter:

explainTransactionWithWasm(params: ExplainTransactionOptions): SolLibTransactionExplanation {
  const txBytes = Buffer.from(params.txBase64, 'base64');
  const wasmTx = WasmTransaction.fromBytes(txBytes);
  const parsed = wasmParseTransaction(txBytes);
  const { instructions, transactionType } = combineWasmInstructionsFromBytes(txBytes);
  const memo = parsed.instructionsData.find((i) => i.type === 'Memo')?.memo;

  return buildWasmExplanation({
    combinedInstructions: instructions,
    transactionType,
    memo,
    nonce: parsed.nonce,
    durableNonce: parsed.durableNonce,
    numSignatures: parsed.numSignatures,
    signatures: wasmTx.signatures,
    lamportsPerSignature: BigInt(params.feeInfo?.fee || '0'),
    rentPerAta: BigInt(params.tokenAccountRentExemptAmount || '0'),
  });
}

String → bigint conversion happens once at the boundary, all arithmetic is native bigint, and .toString() only at the final return where the external interface requires string.

[OttoAllmendinger]

this needs to be a higher level const

[OttoAllmendinger]

🤖 Claude here.

Agreed — should use the existing UNAVAILABLE_TEXT constant from lib/constants.ts instead of a string literal. Same constant is already used in WasmTransaction for the same purpose.

[OttoAllmendinger]

this should not be a coin method

[OttoAllmendinger]

🤖 Claude here.

Agreed. TransactionType is a numeric enum, so TypeScript's reverse mapping already gives us string names. The entire mapTransactionTypeToString method can be replaced with:

TransactionType[transactionType]

This is exactly what the legacy Transaction class does at transaction.ts:645:

type: TransactionType[this.type].toString(),

No switch statement or coin method needed. This should be a standalone expression, not a method on Sol.