feat(wasm-solana): add transaction parsing with BitGoJS compatibility

Add comprehensive Solana transaction parsing capabilities via WASM,
providing types and structures compatible with BitGoJS's sdk-coin-sol.

## Rust Layer

### Transaction Deserialization (src/transaction.rs)
- Deserialize legacy Solana transactions from wire format
- Extract fee payer, blockhash, signatures, and account keys
- Provide signable payload for signing operations

### Instruction Decoding (src/instructions/)
- Decode System Program: Transfer, CreateAccount, NonceAdvance, NonceInitialize
- Decode Stake Program: Initialize, Delegate, Deactivate, Withdraw, Authorize
- Decode ComputeBudget: SetComputeUnitLimit, SetComputeUnitPrice
- Decode SPL Token: TransferChecked via token and token-2022 programs
- Decode ATA Program: CreateAssociatedTokenAccount, CloseAccount
- Decode Memo Program
- Unknown instruction fallback with raw data preservation

### High-Level Parser (src/parser.rs)
- Combine CreateAccount + NonceInitialize into CreateNonceAccount
- Combine CreateAccount + StakeInitialize + DelegateStake into StakingActivate
- Detect durable nonce transactions and populate durableNonce field
- Add stakingType field (NATIVE, JITO, MARINADE) to StakingActivate

### WASM Bindings (src/wasm/)
- ParserNamespace::parse_transaction - returns ParsedTransaction as JsValue
- TransactionNamespace - transaction inspection methods

## TypeScript Layer

### Transaction Wrapper (js/transaction.ts)
- Transaction class wrapping WASM with typed methods
- Access to fee payer, blockhash, signatures, instructions, account keys

### Parser Types (js/parser.ts)
- Full TypeScript interfaces matching BitGoJS InstructionParams
- ParsedTransaction interface with feePayer, nonce, durableNonce, instructionsData
- parseTransaction() function with BigInt conversion for SetPriorityFee.fee

### Exports (js/index.ts)
- Export Transaction class and parseTransaction function
- Re-export all instruction parameter types

## Tests
- BitGoJS compatibility tests using actual transaction fixtures
- Transaction deserialization and inspection tests
- Parser instruction type discrimination tests

TICKET: BTC-2929

Author: lcovar

packages/wasm-solana/Cargo.lock

@@ -12,17 +12,25 @@ all = "warn"
 [dependencies]
 wasm-bindgen = "0.2"
 js-sys = "0.3"
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
 # Solana SDK crates
 solana-pubkey = { version = "2.0", features = ["curve25519"] }
 solana-keypair = "2.0"
 solana-signer = "2.0"
-# Ed25519 for deriving pubkey from 32-byte seed (solana-keypair expects 64-byte format)
-ed25519-dalek = { version = "2.1", default-features = false, features = ["std"] }
+solana-transaction = { version = "3.0", features = ["serde", "bincode"] }
+# Instruction decoder interfaces (official Solana crates)
+solana-system-interface = { version = "2.0", features = ["bincode"] }
+solana-stake-interface = { version = "2.0", features = ["bincode"] }
+solana-compute-budget-interface = { version = "2.0", features = ["borsh"] }
+# Serialization
+bincode = "1.3"
+borsh = "1.5"
+base64 = "0.22"
+serde-wasm-bindgen = "0.6"
 
 [dev-dependencies]
 wasm-bindgen-test = "0.3"
-serde = { version = "1.0", features = ["derive"] }
-serde_json = "1.0"
 hex = "0.4"
 
 [profile.release]

packages/wasm-solana/Cargo.toml

@@ -6,7 +6,37 @@ void wasm;
 // Namespace exports for explicit imports
 export * as keypair from "./keypair.js";
 export * as pubkey from "./pubkey.js";
+export * as transaction from "./transaction.js";
+export * as parser from "./parser.js";
 
 // Top-level class exports for convenience
 export { Keypair } from "./keypair.js";
 export { Pubkey } from "./pubkey.js";
+export { Transaction } from "./transaction.js";
+
+// Top-level function exports
+export { parseTransaction } from "./parser.js";
+
+// Type exports
+export type { AccountMeta, Instruction } from "./transaction.js";
+export type {
+  ParsedTransaction,
+  DurableNonce,
+  InstructionParams,
+  TransferParams,
+  CreateAccountParams,
+  NonceAdvanceParams,
+  CreateNonceAccountParams,
+  StakingActivateParams,
+  StakingDeactivateParams,
+  StakingWithdrawParams,
+  StakingDelegateParams,
+  StakingAuthorizeParams,
+  SetComputeUnitLimitParams,
+  SetPriorityFeeParams,
+  TokenTransferParams,
+  CreateAtaParams,
+  CloseAtaParams,
+  MemoParams,
+  UnknownInstructionParams,
+} from "./parser.js";

packages/wasm-solana/js/index.ts

@@ -0,0 +1,277 @@
+/**
+ * High-level transaction parsing.
+ *
+ * Provides types and functions for parsing Solana transactions into semantic data
+ * matching BitGoJS's TxData format.
+ */
+
+import { ParserNamespace } from "./wasm/wasm_solana.js";
+
+// =============================================================================
+// Instruction Types - matching BitGoJS InstructionParams
+// =============================================================================
+
+/** SOL transfer parameters */
+export interface TransferParams {
+  type: "Transfer";
+  fromAddress: string;
+  toAddress: string;
+  amount: string;
+}
+
+/** Create account parameters */
+export interface CreateAccountParams {
+  type: "CreateAccount";
+  fromAddress: string;
+  newAddress: string;
+  amount: string;
+  space: number;
+  owner: string;
+}
+
+/** Nonce advance parameters */
+export interface NonceAdvanceParams {
+  type: "NonceAdvance";
+  walletNonceAddress: string;
+  authWalletAddress: string;
+}
+
+/** Create nonce account parameters */
+export interface CreateNonceAccountParams {
+  type: "CreateNonceAccount";
+  fromAddress: string;
+  nonceAddress: string;
+  authAddress: string;
+  amount: string;
+}
+
+/** Staking activate parameters */
+export interface StakingActivateParams {
+  type: "StakingActivate";
+  fromAddress: string;
+  stakingAddress: string;
+  amount: string;
+  validator: string;
+  stakingType: "NATIVE" | "JITO" | "MARINADE";
+}
+
+/** Staking deactivate parameters */
+export interface StakingDeactivateParams {
+  type: "StakingDeactivate";
+  stakingAddress: string;
+  fromAddress: string;
+}
+
+/** Staking withdraw parameters */
+export interface StakingWithdrawParams {
+  type: "StakingWithdraw";
+  fromAddress: string;
+  stakingAddress: string;
+  amount: string;
+}
+
+/** Staking delegate parameters */
+export interface StakingDelegateParams {
+  type: "StakingDelegate";
+  stakingAddress: string;
+  fromAddress: string;
+  validator: string;
+}
+
+/** Staking authorize parameters */
+export interface StakingAuthorizeParams {
+  type: "StakingAuthorize";
+  stakingAddress: string;
+  oldAuthorizeAddress: string;
+  newAuthorizeAddress: string;
+  authorizeType: "Staker" | "Withdrawer";
+}
+
+/** Set compute unit limit parameters */
+export interface SetComputeUnitLimitParams {
+  type: "SetComputeUnitLimit";
+  units: number;
+}
+
+/** Set priority fee parameters */
+export interface SetPriorityFeeParams {
+  type: "SetPriorityFee";
+  fee: bigint;
+}
+
+/** Token transfer parameters */
+export interface TokenTransferParams {
+  type: "TokenTransfer";
+  fromAddress: string;
+  toAddress: string;
+  amount: string;
+  sourceAddress: string;
+  tokenAddress?: string;
+}
+
+/** Create associated token account parameters */
+export interface CreateAtaParams {
+  type: "CreateAssociatedTokenAccount";
+  mintAddress: string;
+  ataAddress: string;
+  ownerAddress: string;
+  payerAddress: string;
+}
+
+/** Close associated token account parameters */
+export interface CloseAtaParams {
+  type: "CloseAssociatedTokenAccount";
+  accountAddress: string;
+  destinationAddress: string;
+  authorityAddress: string;
+}
+
+/** Memo parameters */
+export interface MemoParams {
+  type: "Memo";
+  memo: string;
+}
+
+/** Account metadata for unknown instructions */
+export interface AccountMeta {
+  pubkey: string;
+  isSigner: boolean;
+  isWritable: boolean;
+}
+
+/** Unknown instruction parameters */
+export interface UnknownInstructionParams {
+  type: "Unknown";
+  programId: string;
+  accounts: AccountMeta[];
+  data: string; // base64 encoded
+}
+
+/** Union of all instruction parameter types */
+export type InstructionParams =
+  | TransferParams
+  | CreateAccountParams
+  | NonceAdvanceParams
+  | CreateNonceAccountParams
+  | StakingActivateParams
+  | StakingDeactivateParams
+  | StakingWithdrawParams
+  | StakingDelegateParams
+  | StakingAuthorizeParams
+  | SetComputeUnitLimitParams
+  | SetPriorityFeeParams
+  | TokenTransferParams
+  | CreateAtaParams
+  | CloseAtaParams
+  | MemoParams
+  | UnknownInstructionParams;
+
+// =============================================================================
+// ParsedTransaction - matching BitGoJS TxData
+// =============================================================================
+
+/** Durable nonce information */
+export interface DurableNonce {
+  walletNonceAddress: string;
+  authWalletAddress: string;
+}
+
+/**
+ * A fully parsed Solana transaction with decoded instructions.
+ *
+ * This structure matches BitGoJS's TxData interface for seamless integration.
+ */
+export interface ParsedTransaction {
+  /** The fee payer address (base58) */
+  feePayer: string;
+
+  /** Number of required signatures */
+  numSignatures: number;
+
+  /** The blockhash or nonce value (base58) */
+  nonce: string;
+
+  /** If this is a durable nonce transaction, contains the nonce info */
+  durableNonce?: DurableNonce;
+
+  /** All decoded instructions with semantic types */
+  instructionsData: InstructionParams[];
+
+  /** All signatures (base64 encoded) */
+  signatures: string[];
+
+  /** All account keys (base58 strings) */
+  accountKeys: string[];
+}
+
+// =============================================================================
+// parseTransaction function
+// =============================================================================
+
+/** Raw instruction from WASM before post-processing */
+interface RawInstruction {
+  type: string;
+  fee?: string; // Fee comes as string from WASM
+  [key: string]: unknown;
+}
+
+/** Raw parsed transaction from WASM before post-processing */
+interface RawParsedTransaction {
+  feePayer: string;
+  numSignatures: number;
+  nonce: string;
+  durableNonce?: DurableNonce;
+  instructionsData: RawInstruction[];
+  signatures: string[];
+  accountKeys: string[];
+}
+
+/**
+ * Parse a serialized Solana transaction into structured data.
+ *
+ * This is the main entry point for transaction parsing. It deserializes the
+ * transaction bytes and decodes all instructions into semantic types.
+ *
+ * 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.
+ *
+ * @param bytes - The raw transaction bytes (wire format)
+ * @returns A ParsedTransaction with all instructions decoded
+ * @throws Error if the transaction cannot be parsed
+ *
+ * @example
+ * ```typescript
+ * import { parseTransaction } from '@bitgo/wasm-solana';
+ *
+ * const txBytes = Buffer.from(base64EncodedTx, 'base64');
+ * const parsed = parseTransaction(txBytes);
+ *
+ * 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(bytes: Uint8Array): ParsedTransaction {
+  const raw = ParserNamespace.parse_transaction(bytes) as RawParsedTransaction;
+
+  // Post-process instructions:
+  // Convert SetPriorityFee.fee from string to BigInt
+  const instructionsData = raw.instructionsData.map((instr): InstructionParams => {
+    if (instr.type === "SetPriorityFee" && typeof instr.fee === "string") {
+      return {
+        type: "SetPriorityFee",
+        fee: BigInt(instr.fee),
+      };
+    }
+    return instr as unknown as InstructionParams;
+  });
+
+  return {
+    ...raw,
+    instructionsData,
+  };
+}