Merge pull request #166 from BitGo/BTC-3025-explain-transaction

feat: add explainTransaction, unified parseTransaction, and TransactionType enum

Author: lcovar

packages/wasm-solana/js/explain.ts

@@ -9,6 +9,7 @@ export * as pubkey from "./pubkey.js";
 export * as transaction from "./transaction.js";
 export * as parser from "./parser.js";
 export * as builder from "./builder.js";
+export * as explain from "./explain.js";
 
 // Top-level class exports for convenience
 export { Keypair } from "./keypair.js";
@@ -20,9 +21,49 @@ export { VersionedTransaction, isVersionedTransaction } from "./versioned.js";
 export type { AddressLookupTableData } from "./versioned.js";
 
 // Top-level function exports
-export { parseTransaction } from "./parser.js";
+export { parseTransactionData } from "./parser.js";
 export { buildFromVersionedData } from "./builder.js";
 export { buildFromIntent, buildFromIntent as buildTransactionFromIntent } from "./intentBuilder.js";
+export { explainTransaction, TransactionType } from "./explain.js";
+
+// Re-export Transaction import for parseTransaction
+import { Transaction as _Transaction } from "./transaction.js";
+
+/**
+ * Parse a Solana transaction from raw bytes.
+ *
+ * Returns a `Transaction` instance that can be both inspected and signed.
+ * Use `.parse()` on the returned Transaction to get decoded instruction data.
+ *
+ * This is the single entry point for working with transactions — like
+ * `BitGoPsbt.fromBytes()` in wasm-utxo.
+ *
+ * @param bytes - Raw transaction bytes
+ * @returns A Transaction that can be inspected (`.parse()`) and signed (`.addSignature()`)
+ *
+ * @example
+ * ```typescript
+ * import { parseTransaction } from '@bitgo/wasm-solana';
+ *
+ * const tx = parseTransaction(txBytes);
+ *
+ * // Inspect
+ * const parsed = tx.parse();
+ * console.log(parsed.feePayer);
+ * for (const instr of parsed.instructionsData) {
+ *   if (instr.type === 'Transfer') {
+ *     console.log(`${instr.amount} lamports to ${instr.toAddress}`);
+ *   }
+ * }
+ *
+ * // Sign
+ * tx.addSignature(pubkey, signature);
+ * const signedBytes = tx.toBytes();
+ * ```
+ */
+export function parseTransaction(bytes: Uint8Array): _Transaction {
+  return _Transaction.fromBytes(bytes);
+}
 
 // Intent builder type exports
 export type {
@@ -36,6 +77,10 @@ export type {
   EnableTokenIntent,
   CloseAtaIntent,
   ConsolidateIntent,
+  AuthorizeIntent,
+  CustomTxIntent,
+  CustomTxInstruction,
+  CustomTxKey,
   SolanaIntent,
   StakePoolConfig,
   BuildFromIntentParams,
@@ -68,7 +113,6 @@ export {
 // Type exports
 export type { AccountMeta, Instruction } from "./transaction.js";
 export type {
-  TransactionInput,
   ParsedTransaction,
   DurableNonce as ParsedDurableNonce,
   InstructionParams,
@@ -94,6 +138,16 @@ export type {
   UnknownInstructionParams,
 } from "./parser.js";
 
+// Explain types
+export type {
+  ExplainedTransaction,
+  ExplainedOutput,
+  ExplainedInput,
+  ExplainOptions,
+  TokenEnablement,
+  StakingAuthorizeInfo,
+} from "./explain.js";
+
 // Versioned transaction builder type exports
 export type {
   AddressLookupTable as BuilderAddressLookupTable,

packages/wasm-solana/js/index.ts

@@ -5,17 +5,9 @@
  * matching BitGoJS's TxData format.
  *
  * All monetary amounts (amount, fee, lamports, poolTokens) are returned as bigint.
- * Accepts both raw bytes and Transaction objects for convenience.
  */
 
 import { ParserNamespace } from "./wasm/wasm_solana.js";
-import type { Transaction } from "./transaction.js";
-import type { VersionedTransaction } from "./versioned.js";
-
-/**
- * Input type for parseTransaction - accepts bytes or Transaction objects.
- */
-export type TransactionInput = Uint8Array | Transaction | VersionedTransaction;
 
 // =============================================================================
 // Instruction Types - matching BitGoJS InstructionParams.
@@ -277,48 +269,19 @@ export interface ParsedTransaction {
 }
 
 // =============================================================================
-// parseTransaction function
+// parseTransactionData function
 // =============================================================================
 
 /**
- * Parse a Solana transaction into structured data.
- *
- * This is the main entry point for transaction parsing. It deserializes the
- * transaction and decodes all instructions into semantic types.
- *
- * All monetary amounts (amount, fee, lamports, poolTokens) are returned as bigint
- * directly from WASM - no post-processing needed.
+ * Parse raw transaction bytes into a plain data object with decoded instructions.
  *
- * Note: This returns the raw parsed data including NonceAdvance instructions.
- * Consumers (like BitGoJS) may choose to filter NonceAdvance from instructionsData
- * since that info is also available in durableNonce.
+ * This is the low-level parsing function. Most callers should use the top-level
+ * `parseTransaction(bytes)` which returns a `Transaction` instance with both
+ * inspection (`.parse()`) and signing (`.addSignature()`) capabilities.
  *
- * @param input - Raw transaction bytes, Transaction, or VersionedTransaction
+ * @param bytes - Raw transaction bytes
  * @returns A ParsedTransaction with all instructions decoded
- * @throws Error if the transaction cannot be parsed
- *
- * @example
- * ```typescript
- * import { parseTransaction, buildTransaction, Transaction } from '@bitgo/wasm-solana';
- *
- * // From bytes
- * const txBytes = Buffer.from(base64EncodedTx, 'base64');
- * const parsed = parseTransaction(txBytes);
- *
- * // Directly from a Transaction object (no roundtrip through bytes)
- * const tx = buildTransaction(intent);
- * const parsed = parseTransaction(tx);
- *
- * console.log(parsed.feePayer);
- * for (const instr of parsed.instructionsData) {
- *   if (instr.type === 'Transfer') {
- *     console.log(`Transfer ${instr.amount} from ${instr.fromAddress} to ${instr.toAddress}`);
- *   }
- * }
- * ```
  */
-export function parseTransaction(input: TransactionInput): ParsedTransaction {
-  // If input is a Transaction or VersionedTransaction, extract bytes
-  const bytes = input instanceof Uint8Array ? input : input.toBytes();
+export function parseTransactionData(bytes: Uint8Array): ParsedTransaction {
   return ParserNamespace.parse_transaction(bytes) as ParsedTransaction;
 }

packages/wasm-solana/js/parser.ts

@@ -1,6 +1,8 @@
 import { WasmTransaction } from "./wasm/wasm_solana.js";
 import { Keypair } from "./keypair.js";
 import { Pubkey } from "./pubkey.js";
+import { parseTransactionData } from "./parser.js";
+import type { ParsedTransaction } from "./parser.js";
 
 /**
  * Account metadata for an instruction
@@ -27,22 +29,29 @@ export interface Instruction {
 }
 
 /**
- * Solana Transaction wrapper for low-level deserialization and inspection.
+ * Solana Transaction — the single object for inspecting and signing transactions.
  *
- * This class provides low-level access to transaction structure.
- * For high-level semantic parsing with decoded instructions, use `parseTransaction()` instead.
+ * Use `parseTransaction(bytes)` to create an instance. The returned Transaction
+ * can be both inspected (`.parse()` for decoded instructions) and signed
+ * (`.addSignature()`, `.signablePayload()`, `.toBytes()`).
  *
  * @example
  * ```typescript
- * import { Transaction, parseTransaction } from '@bitgo/wasm-solana';
+ * import { parseTransaction } from '@bitgo/wasm-solana';
  *
- * // Low-level access:
- * const tx = Transaction.fromBytes(txBytes);
- * console.log(tx.feePayer);
+ * const tx = parseTransaction(txBytes);
  *
- * // High-level parsing (preferred):
- * const parsed = parseTransaction(txBytes);
- * console.log(parsed.instructionsData); // Decoded instruction types
+ * // Inspect decoded instructions
+ * const parsed = tx.parse();
+ * for (const instr of parsed.instructionsData) {
+ *   if (instr.type === 'Transfer') {
+ *     console.log(`${instr.amount} lamports to ${instr.toAddress}`);
+ *   }
+ * }
+ *
+ * // Sign and serialize
+ * tx.addSignature(pubkey, signature);
+ * const signedBytes = tx.toBytes();
  * ```
  */
 export class Transaction {
@@ -237,6 +246,26 @@ export class Transaction {
     this._wasm.sign_with_keypair(keypair.wasm);
   }
 
+  /**
+   * Parse the transaction into decoded instruction data.
+   *
+   * Returns structured data with all instructions decoded into semantic types
+   * (Transfer, StakeActivate, TokenTransfer, etc.) with amounts as bigint.
+   *
+   * @returns A ParsedTransaction with decoded instructions, feePayer, nonce, etc.
+   *
+   * @example
+   * ```typescript
+   * const tx = parseTransaction(txBytes);
+   * const parsed = tx.parse();
+   * console.log(parsed.feePayer);
+   * console.log(parsed.instructionsData); // Decoded instruction types
+   * ```
+   */
+  parse(): ParsedTransaction {
+    return parseTransactionData(this._wasm.to_bytes());
+  }
+
   /**
    * Get the underlying WASM instance (internal use only)
    * @internal

packages/wasm-solana/js/transaction.ts

@@ -5,7 +5,7 @@
  * what BitGoJS's Transaction.toJson() produces.
  */
 import * as assert from "assert";
-import { parseTransaction } from "../js/parser.js";
+import { parseTransactionData as parseTransaction } from "../js/parser.js";
 
 // Helper to decode base64 in tests
 function base64ToBytes(base64: string): Uint8Array {

packages/wasm-solana/test/bitgojs-compat.ts

@@ -8,7 +8,11 @@
 /* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-argument */
 
 import assert from "assert";
-import { buildFromIntent, Transaction, parseTransaction } from "../dist/cjs/js/index.js";
+import {
+  buildFromIntent,
+  Transaction,
+  parseTransactionData as parseTransaction,
+} from "../dist/cjs/js/index.js";
 
 describe("buildFromIntent", function () {
   // Common test params

packages/wasm-solana/test/intentBuilder.ts

@@ -1,5 +1,5 @@
 import * as assert from "assert";
-import { parseTransaction } from "../js/parser.js";
+import { parseTransactionData as parseTransaction } from "../js/parser.js";
 
 // Helper to decode base64 in tests
 function base64ToBytes(base64: string): Uint8Array {

packages/wasm-solana/test/parser.ts

@@ -516,7 +516,8 @@ class SolanaTransactionParser extends BaseComponent {
     try {
       // Parse the transaction
       const bytes = base64ToBytes(txData);
-      const parsed = parseTransaction(bytes);
+      const tx = parseTransaction(bytes);
+      const parsed = tx.parse();
 
       // Render transaction info
       txInfoEl.replaceChildren(this.renderTxInfo(parsed));
@@ -533,7 +534,9 @@ class SolanaTransactionParser extends BaseComponent {
           "section",
           { class: "instructions-section" },
           h("h2", {}, `Instructions (${parsed.instructionsData.length})`),
-          ...parsed.instructionsData.map((instr, idx) => this.renderInstruction(instr, idx)),
+          ...parsed.instructionsData.map((instr: InstructionParams, idx: number) =>
+            this.renderInstruction(instr, idx),
+          ),
         ),
       );
     } catch (e) {