@bitgo/wasm-solana 1.4.1 → 1.4.2

package/dist/cjs/js/transaction.d.ts

@@ -0,0 +1,156 @@
+import { WasmTransaction } from "./wasm/wasm_solana.js";
+import { Pubkey } from "./pubkey.js";
+/**
+ * Account metadata for an instruction
+ */
+export interface AccountMeta {
+    /** The account public key as a base58 string */
+    pubkey: string;
+    /** Whether this account is a signer */
+    isSigner: boolean;
+    /** Whether this account is writable */
+    isWritable: boolean;
+}
+/**
+ * A decoded Solana instruction
+ */
+export interface Instruction {
+    /** The program ID (base58 string) that will execute this instruction */
+    programId: string;
+    /** The accounts required by this instruction */
+    accounts: AccountMeta[];
+    /** The instruction data */
+    data: Uint8Array;
+}
+/**
+ * Solana Transaction wrapper for low-level deserialization and inspection.
+ *
+ * This class provides low-level access to transaction structure.
+ * For high-level semantic parsing with decoded instructions, use `parseTransaction()` instead.
+ *
+ * @example
+ * ```typescript
+ * import { Transaction, parseTransaction } from '@bitgo/wasm-solana';
+ *
+ * // Low-level access:
+ * const tx = Transaction.fromBytes(txBytes);
+ * console.log(tx.feePayer);
+ *
+ * // High-level parsing (preferred):
+ * const parsed = parseTransaction(txBytes);
+ * console.log(parsed.instructionsData); // Decoded instruction types
+ * ```
+ */
+export declare class Transaction {
+    private _wasm;
+    private constructor();
+    /**
+     * Deserialize a transaction from raw bytes
+     * @param bytes - The raw transaction bytes
+     * @returns A Transaction instance
+     */
+    static fromBytes(bytes: Uint8Array): Transaction;
+    /**
+     * Create a Transaction from a WasmTransaction instance.
+     * @internal Used by builder functions
+     */
+    static fromWasm(wasm: WasmTransaction): Transaction;
+    /**
+     * Get the fee payer address as a base58 string
+     * Returns null if there are no account keys (shouldn't happen for valid transactions)
+     */
+    get feePayer(): string | null;
+    /**
+     * Get the recent blockhash as a base58 string
+     */
+    get recentBlockhash(): string;
+    /**
+     * Get the number of signatures in the transaction
+     */
+    get numSignatures(): number;
+    /**
+     * Get the signable message payload (what gets signed)
+     * This is the serialized message that signers sign
+     * @returns The message bytes
+     */
+    signablePayload(): Uint8Array;
+    /**
+     * Serialize the message portion of the transaction.
+     * Alias for signablePayload() - provides compatibility with @solana/web3.js API.
+     * Returns a Buffer for compatibility with code expecting .toString('base64').
+     * @returns The serialized message bytes as a Buffer
+     */
+    serializeMessage(): Buffer;
+    /**
+     * Serialize the transaction to bytes
+     * @returns The serialized transaction bytes
+     */
+    toBytes(): Uint8Array;
+    /**
+     * Get all account keys as Pubkey instances
+     * @returns Array of account public keys
+     */
+    accountKeys(): Pubkey[];
+    /**
+     * Get all signatures as byte arrays.
+     * Provides compatibility with @solana/web3.js Transaction.signatures API.
+     * @returns Array of signature byte arrays
+     */
+    get signatures(): Uint8Array[];
+    /**
+     * Get all signatures as byte arrays (method form).
+     * Alias for the `signatures` property getter.
+     * @returns Array of signature byte arrays
+     */
+    getSignatures(): Uint8Array[];
+    /**
+     * Get all instructions in the transaction.
+     * Returns an array with programId, accounts, and data for each instruction.
+     *
+     * Note: This is a getter property to provide compatibility with code
+     * expecting @solana/web3.js Transaction.instructions API. If you need
+     * to call this as a method, use `getInstructions()` instead.
+     */
+    get instructions(): Instruction[];
+    /**
+     * Get all instructions in the transaction (method form).
+     * Alias for the `instructions` property getter.
+     * @returns Array of instructions with programId, accounts, and data
+     */
+    getInstructions(): Instruction[];
+    /**
+     * Add a signature for a given public key.
+     *
+     * The pubkey must be one of the required signers in the transaction.
+     * The signature must be exactly 64 bytes (Ed25519 signature).
+     *
+     * @param pubkey - The public key as a base58 string
+     * @param signature - The 64-byte signature as Uint8Array
+     * @throws Error if pubkey is not a signer or signature is invalid
+     *
+     * @example
+     * ```typescript
+     * // Add a pre-computed signature (e.g., from TSS)
+     * tx.addSignature(signerPubkey, signatureBytes);
+     *
+     * // Serialize and broadcast
+     * const signedTxBytes = tx.toBytes();
+     * ```
+     */
+    addSignature(pubkey: string, signature: Uint8Array): void;
+    /**
+     * Get the signer index for a public key.
+     *
+     * Returns the index in the signatures array where this pubkey's
+     * signature should be placed, or null if the pubkey is not a signer.
+     *
+     * @param pubkey - The public key as a base58 string
+     * @returns The signer index, or null if not a signer
+     */
+    signerIndex(pubkey: string): number | null;
+    /**
+     * Get the underlying WASM instance (internal use only)
+     * @internal
+     */
+    get wasm(): WasmTransaction;
+}

package/dist/cjs/js/transaction.js

@@ -0,0 +1,176 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Transaction = void 0;
+const wasm_solana_js_1 = require("./wasm/wasm_solana.js");
+const pubkey_js_1 = require("./pubkey.js");
+/**
+ * Solana Transaction wrapper for low-level deserialization and inspection.
+ *
+ * This class provides low-level access to transaction structure.
+ * For high-level semantic parsing with decoded instructions, use `parseTransaction()` instead.
+ *
+ * @example
+ * ```typescript
+ * import { Transaction, parseTransaction } from '@bitgo/wasm-solana';
+ *
+ * // Low-level access:
+ * const tx = Transaction.fromBytes(txBytes);
+ * console.log(tx.feePayer);
+ *
+ * // High-level parsing (preferred):
+ * const parsed = parseTransaction(txBytes);
+ * console.log(parsed.instructionsData); // Decoded instruction types
+ * ```
+ */
+class Transaction {
+    _wasm;
+    constructor(_wasm) {
+        this._wasm = _wasm;
+    }
+    /**
+     * Deserialize a transaction from raw bytes
+     * @param bytes - The raw transaction bytes
+     * @returns A Transaction instance
+     */
+    static fromBytes(bytes) {
+        const wasm = wasm_solana_js_1.WasmTransaction.from_bytes(bytes);
+        return new Transaction(wasm);
+    }
+    /**
+     * Create a Transaction from a WasmTransaction instance.
+     * @internal Used by builder functions
+     */
+    static fromWasm(wasm) {
+        return new Transaction(wasm);
+    }
+    /**
+     * Get the fee payer address as a base58 string
+     * Returns null if there are no account keys (shouldn't happen for valid transactions)
+     */
+    get feePayer() {
+        return this._wasm.fee_payer ?? null;
+    }
+    /**
+     * Get the recent blockhash as a base58 string
+     */
+    get recentBlockhash() {
+        return this._wasm.recent_blockhash;
+    }
+    /**
+     * Get the number of signatures in the transaction
+     */
+    get numSignatures() {
+        return this._wasm.num_signatures;
+    }
+    /**
+     * Get the signable message payload (what gets signed)
+     * This is the serialized message that signers sign
+     * @returns The message bytes
+     */
+    signablePayload() {
+        return this._wasm.signable_payload();
+    }
+    /**
+     * Serialize the message portion of the transaction.
+     * Alias for signablePayload() - provides compatibility with @solana/web3.js API.
+     * Returns a Buffer for compatibility with code expecting .toString('base64').
+     * @returns The serialized message bytes as a Buffer
+     */
+    serializeMessage() {
+        return Buffer.from(this.signablePayload());
+    }
+    /**
+     * Serialize the transaction to bytes
+     * @returns The serialized transaction bytes
+     */
+    toBytes() {
+        return this._wasm.to_bytes();
+    }
+    /**
+     * Get all account keys as Pubkey instances
+     * @returns Array of account public keys
+     */
+    accountKeys() {
+        const keys = Array.from(this._wasm.account_keys());
+        return keys.map((k) => pubkey_js_1.Pubkey.fromBase58(k));
+    }
+    /**
+     * Get all signatures as byte arrays.
+     * Provides compatibility with @solana/web3.js Transaction.signatures API.
+     * @returns Array of signature byte arrays
+     */
+    get signatures() {
+        return Array.from(this._wasm.signatures());
+    }
+    /**
+     * Get all signatures as byte arrays (method form).
+     * Alias for the `signatures` property getter.
+     * @returns Array of signature byte arrays
+     */
+    getSignatures() {
+        return this.signatures;
+    }
+    /**
+     * Get all instructions in the transaction.
+     * Returns an array with programId, accounts, and data for each instruction.
+     *
+     * Note: This is a getter property to provide compatibility with code
+     * expecting @solana/web3.js Transaction.instructions API. If you need
+     * to call this as a method, use `getInstructions()` instead.
+     */
+    get instructions() {
+        const rawInstructions = this._wasm.instructions();
+        return Array.from(rawInstructions);
+    }
+    /**
+     * Get all instructions in the transaction (method form).
+     * Alias for the `instructions` property getter.
+     * @returns Array of instructions with programId, accounts, and data
+     */
+    getInstructions() {
+        return this.instructions;
+    }
+    /**
+     * Add a signature for a given public key.
+     *
+     * The pubkey must be one of the required signers in the transaction.
+     * The signature must be exactly 64 bytes (Ed25519 signature).
+     *
+     * @param pubkey - The public key as a base58 string
+     * @param signature - The 64-byte signature as Uint8Array
+     * @throws Error if pubkey is not a signer or signature is invalid
+     *
+     * @example
+     * ```typescript
+     * // Add a pre-computed signature (e.g., from TSS)
+     * tx.addSignature(signerPubkey, signatureBytes);
+     *
+     * // Serialize and broadcast
+     * const signedTxBytes = tx.toBytes();
+     * ```
+     */
+    addSignature(pubkey, signature) {
+        this._wasm.add_signature(pubkey, signature);
+    }
+    /**
+     * Get the signer index for a public key.
+     *
+     * Returns the index in the signatures array where this pubkey's
+     * signature should be placed, or null if the pubkey is not a signer.
+     *
+     * @param pubkey - The public key as a base58 string
+     * @returns The signer index, or null if not a signer
+     */
+    signerIndex(pubkey) {
+        const idx = this._wasm.signer_index(pubkey);
+        return idx ?? null;
+    }
+    /**
+     * Get the underlying WASM instance (internal use only)
+     * @internal
+     */
+    get wasm() {
+        return this._wasm;
+    }
+}
+exports.Transaction = Transaction;

package/dist/cjs/js/versioned.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Versioned Transaction Support
+ *
+ * Handles both legacy and versioned (MessageV0) Solana transactions.
+ * Versioned transactions use Address Lookup Tables (ALTs) to compress
+ * transaction size by referencing accounts via lookup table indices.
+ */
+import { WasmVersionedTransaction } from "./wasm/wasm_solana.js";
+import type { RawVersionedTransactionData } from "./builder.js";
+/**
+ * Address Lookup Table data extracted from versioned transactions.
+ */
+export interface AddressLookupTableData {
+    /** The lookup table account address (base58) */
+    accountKey: string;
+    /** Indices of writable accounts in the lookup table */
+    writableIndexes: Uint8Array;
+    /** Indices of readonly accounts in the lookup table */
+    readonlyIndexes: Uint8Array;
+}
+/**
+ * Account metadata for instructions.
+ */
+export interface VersionedAccountMeta {
+    /** Account index within the transaction */
+    index: number;
+    /** Account pubkey (only present for static accounts) */
+    pubkey?: string;
+    /** Whether this account is from an Address Lookup Table */
+    isLookupTable: boolean;
+    /** Whether this account is a signer */
+    isSigner: boolean;
+}
+/**
+ * Instruction from a versioned transaction.
+ */
+export interface VersionedInstruction {
+    /** Program ID */
+    programId: string;
+    /** Accounts used by the instruction */
+    accounts: VersionedAccountMeta[];
+    /** Instruction data */
+    data: Uint8Array;
+}
+/**
+ * Detect if transaction bytes represent a versioned transaction (MessageV0).
+ *
+ * @param bytes - Raw transaction bytes
+ * @returns true if versioned, false if legacy
+ */
+export declare function isVersionedTransaction(bytes: Uint8Array): boolean;
+/**
+ * Versioned Transaction class.
+ *
+ * Handles both legacy and versioned (MessageV0) transactions.
+ * Provides access to Address Lookup Table data for versioned transactions.
+ */
+export declare class VersionedTransaction {
+    private inner;
+    private constructor();
+    /**
+     * Deserialize a transaction from raw bytes.
+     * Automatically handles both legacy and versioned formats.
+     */
+    static fromBytes(bytes: Uint8Array): VersionedTransaction;
+    /**
+     * Deserialize a transaction from base64 string.
+     */
+    static fromBase64(base64: string): VersionedTransaction;
+    /**
+     * Create a VersionedTransaction from a WasmVersionedTransaction instance.
+     * @internal Used by builder functions
+     */
+    static fromWasm(wasm: WasmVersionedTransaction): VersionedTransaction;
+    /**
+     * Create a versioned transaction from raw MessageV0 data.
+     *
+     * This is used for the `fromVersionedTransactionData()` path where we have
+     * pre-compiled versioned data (indexes + ALT refs). No instruction compilation
+     * is needed - this just constructs the transaction from the raw structure.
+     *
+     * @param data - Raw versioned transaction data
+     * @returns A VersionedTransaction instance
+     *
+     * @example
+     * ```typescript
+     * const tx = VersionedTransaction.fromVersionedData({
+     *   staticAccountKeys: ['pubkey1', 'pubkey2', ...],
+     *   addressLookupTables: [
+     *     { accountKey: 'altPubkey', writableIndexes: [0, 1], readonlyIndexes: [2] }
+     *   ],
+     *   versionedInstructions: [
+     *     { programIdIndex: 0, accountKeyIndexes: [1, 2], data: 'base58EncodedData' }
+     *   ],
+     *   messageHeader: {
+     *     numRequiredSignatures: 1,
+     *     numReadonlySignedAccounts: 0,
+     *     numReadonlyUnsignedAccounts: 3
+     *   },
+     *   recentBlockhash: 'blockhash'
+     * });
+     * ```
+     */
+    static fromVersionedData(data: RawVersionedTransactionData): VersionedTransaction;
+    /**
+     * Check if this is a versioned transaction (MessageV0).
+     */
+    get isVersioned(): boolean;
+    /**
+     * Get the fee payer address.
+     */
+    get feePayer(): string | undefined;
+    /**
+     * Get the recent blockhash.
+     */
+    get recentBlockhash(): string;
+    /**
+     * Get the number of instructions.
+     */
+    get numInstructions(): number;
+    /**
+     * Get the number of signatures.
+     */
+    get numSignatures(): number;
+    /**
+     * Get the signable message payload.
+     */
+    signablePayload(): Uint8Array;
+    /**
+     * Serialize the message portion of the transaction.
+     * Alias for signablePayload() - provides compatibility with @solana/web3.js API.
+     * Returns a Buffer for compatibility with code expecting .toString('base64').
+     * @returns The serialized message bytes as a Buffer
+     */
+    serializeMessage(): Buffer;
+    /**
+     * Serialize the transaction to bytes.
+     */
+    toBytes(): Uint8Array;
+    /**
+     * Serialize the transaction to base64.
+     */
+    toBase64(): string;
+    /**
+     * Get static account keys (accounts stored directly in the message).
+     * For versioned transactions, additional accounts may be referenced via ALTs.
+     */
+    staticAccountKeys(): string[];
+    /**
+     * Get Address Lookup Table data.
+     * Returns empty array for legacy transactions.
+     */
+    addressLookupTables(): AddressLookupTableData[];
+    /**
+     * Get all signatures as byte arrays.
+     * Provides compatibility with @solana/web3.js Transaction.signatures API.
+     */
+    get signatures(): Uint8Array[];
+    /**
+     * Add a signature for a given public key.
+     *
+     * @param pubkey - The public key as base58 string
+     * @param signature - The 64-byte Ed25519 signature
+     */
+    addSignature(pubkey: string, signature: Uint8Array): void;
+    /**
+     * Get the signer index for a public key.
+     * Returns undefined if the pubkey is not a required signer.
+     */
+    signerIndex(pubkey: string): number | undefined;
+    /**
+     * Get all instructions.
+     * Note: For versioned transactions, account indices may reference
+     * accounts from Address Lookup Tables.
+     */
+    instructions(): VersionedInstruction[];
+}

package/dist/cjs/js/versioned.js

@@ -0,0 +1,197 @@
+"use strict";
+/**
+ * Versioned Transaction Support
+ *
+ * Handles both legacy and versioned (MessageV0) Solana transactions.
+ * Versioned transactions use Address Lookup Tables (ALTs) to compress
+ * transaction size by referencing accounts via lookup table indices.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VersionedTransaction = void 0;
+exports.isVersionedTransaction = isVersionedTransaction;
+const wasm_solana_js_1 = require("./wasm/wasm_solana.js");
+/**
+ * Detect if transaction bytes represent a versioned transaction (MessageV0).
+ *
+ * @param bytes - Raw transaction bytes
+ * @returns true if versioned, false if legacy
+ */
+function isVersionedTransaction(bytes) {
+    return (0, wasm_solana_js_1.is_versioned_transaction)(bytes);
+}
+/**
+ * Versioned Transaction class.
+ *
+ * Handles both legacy and versioned (MessageV0) transactions.
+ * Provides access to Address Lookup Table data for versioned transactions.
+ */
+class VersionedTransaction {
+    inner;
+    constructor(inner) {
+        this.inner = inner;
+    }
+    /**
+     * Deserialize a transaction from raw bytes.
+     * Automatically handles both legacy and versioned formats.
+     */
+    static fromBytes(bytes) {
+        return new VersionedTransaction(wasm_solana_js_1.WasmVersionedTransaction.from_bytes(bytes));
+    }
+    /**
+     * Deserialize a transaction from base64 string.
+     */
+    static fromBase64(base64) {
+        const bytes = Uint8Array.from(Buffer.from(base64, "base64"));
+        return VersionedTransaction.fromBytes(bytes);
+    }
+    /**
+     * Create a VersionedTransaction from a WasmVersionedTransaction instance.
+     * @internal Used by builder functions
+     */
+    static fromWasm(wasm) {
+        return new VersionedTransaction(wasm);
+    }
+    /**
+     * Create a versioned transaction from raw MessageV0 data.
+     *
+     * This is used for the `fromVersionedTransactionData()` path where we have
+     * pre-compiled versioned data (indexes + ALT refs). No instruction compilation
+     * is needed - this just constructs the transaction from the raw structure.
+     *
+     * @param data - Raw versioned transaction data
+     * @returns A VersionedTransaction instance
+     *
+     * @example
+     * ```typescript
+     * const tx = VersionedTransaction.fromVersionedData({
+     *   staticAccountKeys: ['pubkey1', 'pubkey2', ...],
+     *   addressLookupTables: [
+     *     { accountKey: 'altPubkey', writableIndexes: [0, 1], readonlyIndexes: [2] }
+     *   ],
+     *   versionedInstructions: [
+     *     { programIdIndex: 0, accountKeyIndexes: [1, 2], data: 'base58EncodedData' }
+     *   ],
+     *   messageHeader: {
+     *     numRequiredSignatures: 1,
+     *     numReadonlySignedAccounts: 0,
+     *     numReadonlyUnsignedAccounts: 3
+     *   },
+     *   recentBlockhash: 'blockhash'
+     * });
+     * ```
+     */
+    static fromVersionedData(data) {
+        // Build the transaction using WASM and wrap in TypeScript class
+        const wasm = wasm_solana_js_1.BuilderNamespace.build_from_versioned_data(data);
+        return VersionedTransaction.fromWasm(wasm);
+    }
+    /**
+     * Check if this is a versioned transaction (MessageV0).
+     */
+    get isVersioned() {
+        return this.inner.is_versioned;
+    }
+    /**
+     * Get the fee payer address.
+     */
+    get feePayer() {
+        return this.inner.fee_payer ?? undefined;
+    }
+    /**
+     * Get the recent blockhash.
+     */
+    get recentBlockhash() {
+        return this.inner.recent_blockhash;
+    }
+    /**
+     * Get the number of instructions.
+     */
+    get numInstructions() {
+        return this.inner.num_instructions;
+    }
+    /**
+     * Get the number of signatures.
+     */
+    get numSignatures() {
+        return this.inner.num_signatures;
+    }
+    /**
+     * Get the signable message payload.
+     */
+    signablePayload() {
+        return this.inner.signable_payload();
+    }
+    /**
+     * Serialize the message portion of the transaction.
+     * Alias for signablePayload() - provides compatibility with @solana/web3.js API.
+     * Returns a Buffer for compatibility with code expecting .toString('base64').
+     * @returns The serialized message bytes as a Buffer
+     */
+    serializeMessage() {
+        return Buffer.from(this.signablePayload());
+    }
+    /**
+     * Serialize the transaction to bytes.
+     */
+    toBytes() {
+        return this.inner.to_bytes();
+    }
+    /**
+     * Serialize the transaction to base64.
+     */
+    toBase64() {
+        return Buffer.from(this.toBytes()).toString("base64");
+    }
+    /**
+     * Get static account keys (accounts stored directly in the message).
+     * For versioned transactions, additional accounts may be referenced via ALTs.
+     */
+    staticAccountKeys() {
+        return Array.from(this.inner.static_account_keys());
+    }
+    /**
+     * Get Address Lookup Table data.
+     * Returns empty array for legacy transactions.
+     */
+    addressLookupTables() {
+        const alts = this.inner.address_lookup_tables();
+        return Array.from(alts).map((alt) => ({
+            accountKey: alt.accountKey,
+            writableIndexes: alt.writableIndexes,
+            readonlyIndexes: alt.readonlyIndexes,
+        }));
+    }
+    /**
+     * Get all signatures as byte arrays.
+     * Provides compatibility with @solana/web3.js Transaction.signatures API.
+     */
+    get signatures() {
+        return Array.from(this.inner.signatures());
+    }
+    /**
+     * Add a signature for a given public key.
+     *
+     * @param pubkey - The public key as base58 string
+     * @param signature - The 64-byte Ed25519 signature
+     */
+    addSignature(pubkey, signature) {
+        this.inner.add_signature(pubkey, signature);
+    }
+    /**
+     * Get the signer index for a public key.
+     * Returns undefined if the pubkey is not a required signer.
+     */
+    signerIndex(pubkey) {
+        return this.inner.signer_index(pubkey) ?? undefined;
+    }
+    /**
+     * Get all instructions.
+     * Note: For versioned transactions, account indices may reference
+     * accounts from Address Lookup Tables.
+     */
+    instructions() {
+        const instructions = this.inner.instructions();
+        return Array.from(instructions);
+    }
+}
+exports.VersionedTransaction = VersionedTransaction;