@exodus/solana-lib 3.18.0 → 3.18.2

package/CHANGELOG.md

@@ -3,6 +3,24 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [3.18.2](https://github.com/ExodusMovement/assets/compare/@exodus/solana-lib@3.18.1...@exodus/solana-lib@3.18.2) (2025-12-16)
+
+**Note:** Version bump only for package @exodus/solana-lib
+
+
+
+
+
+## [3.18.1](https://github.com/ExodusMovement/assets/compare/@exodus/solana-lib@3.18.0...@exodus/solana-lib@3.18.1) (2025-12-15)
+
+
+### Bug Fixes
+
+
+* fix: check SOL transactionBuffer type (#7111)
+
+
+
 ## [3.18.0](https://github.com/ExodusMovement/assets/compare/@exodus/solana-lib@3.15.3...@exodus/solana-lib@3.18.0) (2025-11-26)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/solana-lib",
-  "version": "3.18.0",
+  "version": "3.18.2",
   "description": "Solana utils, such as for cryptography, address encoding/decoding, transaction building, etc.",
   "type": "module",
   "main": "src/index.js",
@@ -47,5 +47,5 @@
     "type": "git",
     "url": "git+https://github.com/ExodusMovement/assets.git"
   },
-  "gitHead": "4c60cc2d7f07229295b801d9f67a336d314711a0"
+  "gitHead": "e0c3dec90d1b6a5a1fac0ab54f3f7c551100ddb7"
 }

package/src/constants.js

@@ -1,4 +1,10 @@
-import { PublicKey, StakeProgram, SystemProgram } from './vendor/index.js'
+import {
+  PublicKey,
+  StakeProgram,
+  SystemProgram,
+  Token2022Program,
+  TokenProgram,
+} from './vendor/index.js'
 
 export const SPL_ASSOCIATED_TOKEN_ACCOUNT_PROGRAM_ID = new PublicKey(
   'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL'
@@ -7,13 +13,13 @@ export const SYSTEM_PROGRAM_ID = SystemProgram.programId
 
 export const STAKE_PROGRAM_ID = StakeProgram.programId
 
-export const TOKEN_PROGRAM_ID = new PublicKey('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA')
+export const TOKEN_PROGRAM_ID = TokenProgram.programId
 
 export const COMPUTE_BUDGET_PROGRAM_ID = new PublicKey(
   'ComputeBudget111111111111111111111111111111'
 )
 
-export const TOKEN_2022_PROGRAM_ID = new PublicKey('TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb')
+export const TOKEN_2022_PROGRAM_ID = Token2022Program.programId
 
 export const MEMO_PROGRAM_ID = new PublicKey('MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr')
 

package/src/tx/common.js

@@ -1,5 +1,6 @@
 import { VersionedTransaction } from '@exodus/solana-web3.js'
 import base58 from 'bs58'
+import assert from 'minimalistic-assert'
 
 export function isVersionedTransaction(tx) {
   return Number.isInteger(tx.version)
@@ -14,6 +15,7 @@ export function transactionToBase58(tx) {
 }
 
 export function deserializeTransaction(tx) {
+  assert(tx instanceof Uint8Array, 'tx must be a Buffer or Uint8Array')
   return VersionedTransaction.deserialize(tx)
 }
 

package/src/tx/instruction-normalizer.js

@@ -0,0 +1,28 @@
+import bs58 from 'bs58'
+
+export function getAccountKeys(message) {
+  // versioned: staticAccountKeys, legacy: accountKeys
+  return message.staticAccountKeys || message.accountKeys
+}
+
+export function normalizeInstruction(instruction) {
+  // legacy: bs58 string, versioned: Uint8Array
+  let normalizedData = instruction.data
+  if (typeof instruction.data === 'string') {
+    normalizedData = bs58.decode(instruction.data)
+  }
+
+  return {
+    programIdIndex: instruction.programIdIndex,
+    // versioned: accountKeyIndexes, legacy: accounts
+    accounts: instruction.accountKeyIndexes || instruction.accounts,
+    data: normalizedData,
+  }
+}
+
+export function getNormalizedInstructions(message) {
+  // versioned: compiledInstructions, legacy: instructions
+  const instructions = message.compiledInstructions || message.instructions || []
+
+  return instructions.map((instruction) => normalizeInstruction(instruction))
+}

package/src/tx/parse-tx-buffer.js

@@ -1,264 +1,217 @@
-import bs58 from 'bs58'
-
-import { SYSTEM_PROGRAM_ID, TOKEN_2022_PROGRAM_ID, TOKEN_PROGRAM_ID } from '../constants.js'
+import { SYSTEM_PROGRAM_ID } from '../constants.js'
 import {
+  StakeInstruction,
   SYSTEM_INSTRUCTION_LAYOUTS,
   SystemInstruction,
-  TOKEN_INSTRUCTION_LAYOUTS,
   TokenInstruction,
 } from '../vendor/index.js'
+import { toBuffer } from '../vendor/utils/to-buffer.js'
 import { deserializeTransaction } from './common.js'
+import { getAccountKeys, getNormalizedInstructions } from './instruction-normalizer.js'
 
-// Helper function to check if an instruction is a token transfer
-function isTokenTransferInstruction(instruction, accountKeys) {
-  if (!instruction || instruction.programIdIndex === undefined) return false
-
-  const programId = accountKeys[instruction.programIdIndex]
-
-  if (!programId.equals(TOKEN_PROGRAM_ID) && !programId.equals(TOKEN_2022_PROGRAM_ID)) {
-    return false
-  }
-
-  // Must have at least 3 accounts (from, to, authority, and potentially more for delegate transfers)
-  if (!Array.isArray(instruction.accounts) || instruction.accounts.length < 3) {
-    return false
-  }
-
-  // Check if the instruction data is transfer (0x03), transferChecked (0x0c/12),
-  // or TransferFeeExtension (0x1a/26) with TransferCheckedWithFee sub-instruction
-  // Note: Must handle both formats because this is called from isTokenTransfer()
-  // which uses non-normalized instructions
-  try {
-    let data = instruction.data
-    if (typeof data === 'string') {
-      data = bs58.decode(data)
-    }
+const InstructionKind = {
+  TOKEN: 'token',
+  SYSTEM_TRANSFER: 'systemTransfer',
+  STAKE: 'stake',
+}
 
-    const instructionType = data[0]
+// Get staked amount from CreateWithSeed instruction that created the stake account
+function getStakedAmountFromCreateWithSeed(stakeAddress, instructions, accountKeys) {
+  for (const instruction of instructions) {
+    const programId = accountKeys[instruction.programIdIndex]
+    if (!programId.equals(SYSTEM_PROGRAM_ID)) continue
 
-    // Accept Transfer, TransferChecked, and TransferFeeExtension
+    const buffer = toBuffer(instruction.data)
     if (
-      instructionType !== TOKEN_INSTRUCTION_LAYOUTS.Transfer.index &&
-      instructionType !== TOKEN_INSTRUCTION_LAYOUTS.TransferChecked.index &&
-      instructionType !== TOKEN_INSTRUCTION_LAYOUTS.TransferFeeExtension.index
+      buffer.length < 4 ||
+      buffer.readUInt32LE(0) !== SYSTEM_INSTRUCTION_LAYOUTS.CreateWithSeed.index
     ) {
-      return false
+      continue
     }
 
-    // For TransferFeeExtension, check if it's specifically TransferCheckedWithFee (sub-instruction 1)
-    if (instructionType === TOKEN_INSTRUCTION_LAYOUTS.TransferFeeExtension.index) {
-      if (data.length < 2) return false
-      const subInstruction = data[1]
-      if (subInstruction !== 1) return false // Only support TransferCheckedWithFee
-    }
-  } catch {
-    return false
-  }
+    // Check if this instruction created our stake account
+    const newAccountPubkey = accountKeys[instruction.accounts[1]].toBase58()
+    if (newAccountPubkey !== stakeAddress) continue
 
-  return true
+    const { lamports } = SystemInstruction.decodeCreateWithSeedData(instruction.data)
+    return lamports
+  }
 }
 
-export function isTokenTransfer(tx) {
-  const { message } = tx
-  const { accountKeys, instructions } = message
+// TODO: Unify with parseTransaction in solana-api and use there as well?
+// TODO: add support for swap instructions
+export async function parseTxBuffer(buffer, api) {
+  const transaction = deserializeTransaction(buffer)
+  const { message } = transaction
 
-  if (!Array.isArray(accountKeys) || !Array.isArray(instructions)) return false
+  const accountKeys = getAccountKeys(message)
+  const instructions = getNormalizedInstructions(message)
 
-  // Search for any token transfer instruction
-  return instructions.some((instruction) => isTokenTransferInstruction(instruction, accountKeys))
-}
+  if (!Array.isArray(accountKeys) || !Array.isArray(instructions)) {
+    throw new TypeError('Invalid transaction structure')
+  }
 
-// Helper function to check if an instruction is a SOL transfer
-function isSolTransferInstruction(instruction, accountKeys) {
-  if (!instruction || instruction.programIdIndex === undefined) return false
+  const decodedEntries = []
 
-  const programId = accountKeys[instruction.programIdIndex]
+  for (const [index, instruction] of instructions.entries()) {
+    try {
+      const decoded = decodeInstructionEntry({ instruction, accountKeys })
+      if (decoded) {
+        decodedEntries.push({
+          ...decoded,
+          instruction,
+          index,
+        })
+      }
+    } catch {
+      // Skip unsupported instructions
+    }
+  }
 
-  if (!programId.equals(SYSTEM_PROGRAM_ID)) return false
+  const parsedInstructions = []
+  for (const entry of decodedEntries) {
+    const parsed = await parseDecodedInstruction(entry, {
+      accountKeys,
+      api,
+      instructions,
+    })
+    if (parsed) parsedInstructions.push(parsed)
+  }
 
-  // Must have exactly 2 accounts (from, to)
-  if (!Array.isArray(instruction.accounts) || instruction.accounts.length !== 2) {
-    return false
+  if (parsedInstructions.length === 0) {
+    throw new Error('No supported instructions found in transaction')
   }
 
-  // Check if the instruction data starts with 0x02 (System Transfer)
-  // Note: Must handle both formats because this is called from isSolanaTransfer()
-  // which uses non-normalized instructions
+  return parsedInstructions
+}
+
+async function getMintAddressFromTokenAccount(tokenAccountAddress, api) {
   try {
-    let data = instruction.data
-    if (typeof data === 'string') {
-      data = bs58.decode(data)
+    const accountInfo = await api.getAccountInfo(tokenAccountAddress)
+    if (accountInfo?.data?.parsed?.info?.mint) {
+      return accountInfo.data.parsed.info.mint
     }
-
-    const buffer = Buffer.from(data)
-    if (buffer.readUInt32LE(0) !== SYSTEM_INSTRUCTION_LAYOUTS.Transfer.index) return false
   } catch {
-    return false
+    // Ignore errors when fetching mint address
   }
 
-  return true
+  return null
 }
 
-export function isSolanaTransfer(tx) {
-  const { message } = tx
-  const { accountKeys, instructions } = message
-
-  if (!Array.isArray(accountKeys) || !Array.isArray(instructions)) return false
-
-  return instructions.some((instruction) => isSolTransferInstruction(instruction, accountKeys))
-}
+function decodeInstructionEntry({ instruction, accountKeys }) {
+  const { accounts } = instruction
+  const buffer = toBuffer(instruction.data)
 
-// Helper to normalize account keys for both versioned and legacy transactions
-function getAccountKeys(message) {
-  // Versioned transactions use staticAccountKeys
-  if (message.staticAccountKeys) {
-    return message.staticAccountKeys
+  if (TokenInstruction.isProgramInstruction(instruction, accountKeys)) {
+    TokenInstruction.validateInstruction(instruction)
+    return {
+      kind: InstructionKind.TOKEN,
+      decoded: TokenInstruction.decodeInstructionData(buffer, accounts, accountKeys),
+    }
   }
 
-  // Legacy transactions use accountKeys
-  return message.accountKeys
-}
-
-// Helper to normalize a single instruction (handles both compiled and regular instructions)
-function normalizeInstruction(instruction) {
-  let normalizedData = instruction.data
-  if (typeof instruction.data === 'string') {
-    normalizedData = bs58.decode(instruction.data)
+  if (SystemInstruction.isProgramInstruction(instruction, accountKeys)) {
+    SystemInstruction.validateInstruction(instruction)
+    return {
+      kind: InstructionKind.SYSTEM_TRANSFER,
+      decoded: SystemInstruction.decodeInstructionData(buffer, accounts, accountKeys),
+    }
   }
 
-  return {
-    programIdIndex: instruction.programIdIndex,
-    accounts: instruction.accountKeyIndexes || instruction.accounts,
-    data: normalizedData,
+  if (StakeInstruction.isProgramInstruction(instruction, accountKeys)) {
+    StakeInstruction.validateInstruction(instruction)
+    return {
+      kind: InstructionKind.STAKE,
+      decoded: StakeInstruction.decodeInstructionData(buffer, accounts, accountKeys),
+    }
   }
+
+  return null
 }
 
-// Helper to normalize instructions for both versioned and legacy transactions
-function getInstructions(message) {
-  let instructions
-  // Versioned transactions use compiledInstructions
-  if (message.compiledInstructions) {
-    instructions = message.compiledInstructions
-  } else if (message.instructions) {
-    // Legacy transactions use instructions
-    instructions = message.instructions
-  } else {
-    return []
+async function parseDecodedInstruction(entry, context) {
+  switch (entry.kind) {
+    case InstructionKind.TOKEN:
+      return parseTokenInstruction(entry, context)
+    case InstructionKind.SYSTEM_TRANSFER:
+      return parseSystemInstruction(entry, context)
+    case InstructionKind.STAKE:
+      return parseStakeInstruction(entry, context)
+    default:
+      return null
   }
-
-  return instructions.map((inst) => normalizeInstruction(inst))
 }
 
-// TODO: Unify with parseTransaction in solana-api and use there as well?
-// TODO: add support for swap and stake instructions
-export async function parseTxBuffer(buffer, api) {
-  const transaction = deserializeTransaction(buffer)
-  const { message } = transaction
+async function parseTokenInstruction({ decoded, index, instruction }, { accountKeys, api }) {
+  const programId = accountKeys[instruction.programIdIndex]
+  const { fromTokenAccount, toTokenAccount, mintAddress } = decoded
+
+  let fromOwner = fromTokenAccount
+  let toOwner = toTokenAccount
+  let resolvedMint = mintAddress
+
+  if (api) {
+    const ownerPromises = [
+      api.getTokenAddressOwner(fromTokenAccount),
+      api.getTokenAddressOwner(toTokenAccount),
+    ]
+    if (!resolvedMint) {
+      ownerPromises.push(getMintAddressFromTokenAccount(fromTokenAccount, api))
+    }
 
-  // Normalize account keys and instructions (versioned vs legacy)
-  const accountKeys = getAccountKeys(message)
-  const instructions = getInstructions(message)
+    const [fromOwnerRaw, toOwnerRaw, fetchedMint] = await Promise.all(ownerPromises)
+    fromOwner = fromOwnerRaw || fromTokenAccount
+    toOwner = toOwnerRaw || toTokenAccount
+    if (!resolvedMint) resolvedMint = fetchedMint
+  }
 
-  if (!Array.isArray(accountKeys) || !Array.isArray(instructions)) {
-    throw new TypeError('Invalid transaction structure')
+  const parsedInstruction = {
+    method: decoded.method,
+    from: fromOwner,
+    to: toOwner,
+    amount: decoded.amount,
+    programId: programId.toBase58(),
+    instructionIndex: index,
+    fromTokenAccount,
+    toTokenAccount,
+    mintAddress: resolvedMint,
   }
 
-  const parsedInstructions = []
+  if (decoded.decimals !== undefined) parsedInstruction.decimals = decoded.decimals
+  if (decoded.fee !== undefined) parsedInstruction.fee = decoded.fee
 
-  try {
-    for (const [index, instruction] of instructions.entries()) {
-      if (isTokenTransferInstruction(instruction, accountKeys)) {
-        const decoded = TokenInstruction.decodeInstructionData(instruction.data)
-        const programId = accountKeys[instruction.programIdIndex]
-
-        // Transfer (3): [source, destination, authority]
-        // TransferChecked (12): [source, mint, destination, authority, ...]
-        // TransferCheckedWithFee (26,1): [source, mint, destination, authority, ...]
-        let fromTokenAccount, toTokenAccount, mintAddress
-
-        if (decoded.method === 'transferChecked' || decoded.method === 'transferCheckedWithFee') {
-          // TransferChecked and TransferCheckedWithFee: mint is at index 1, destination at index 2
-          fromTokenAccount = accountKeys[instruction.accounts[0]].toBase58()
-          mintAddress = accountKeys[instruction.accounts[1]].toBase58() // Mint directly from accounts
-          toTokenAccount = accountKeys[instruction.accounts[2]].toBase58()
-        } else {
-          // Transfer: destination is at index 1
-          fromTokenAccount = accountKeys[instruction.accounts[0]].toBase58()
-          toTokenAccount = accountKeys[instruction.accounts[1]].toBase58()
-          mintAddress = null
-        }
-
-        // Get token account owners in parallel (requires API calls)
-        let fromOwner, toOwner
-        if (api) {
-          ;[fromOwner, toOwner, mintAddress] = await Promise.all([
-            api.getTokenAddressOwner(fromTokenAccount),
-            api.getTokenAddressOwner(toTokenAccount),
-            mintAddress
-              ? Promise.resolve(mintAddress)
-              : getMintAddressFromTokenAccount(fromTokenAccount, api),
-          ])
-          // Fallback to token account address if owner lookup fails
-          fromOwner = fromOwner || fromTokenAccount
-          toOwner = toOwner || toTokenAccount
-        } else {
-          fromOwner = fromTokenAccount
-          toOwner = toTokenAccount
-        }
-
-        const parsedInstruction = {
-          method: decoded.method,
-          from: fromOwner,
-          to: toOwner,
-          amount: decoded.amount,
-          programId: programId.toBase58(),
-          instructionIndex: index,
-          fromTokenAccount,
-          toTokenAccount,
-          mintAddress,
-        }
-
-        // Include decimals if it's a transferChecked instruction
-        if (decoded.decimals !== undefined) {
-          parsedInstruction.decimals = decoded.decimals
-        }
-
-        parsedInstructions.push(parsedInstruction)
-      } else if (isSolTransferInstruction(instruction, accountKeys)) {
-        const { amount, method } = SystemInstruction.decodeInstructionData(instruction.data)
-        const programId = accountKeys[instruction.programIdIndex]
-
-        parsedInstructions.push({
-          method,
-          from: accountKeys[instruction.accounts[0]].toBase58(),
-          to: accountKeys[instruction.accounts[1]].toBase58(),
-          amount,
-          programId: programId.toBase58(),
-          instructionIndex: index,
-        })
-      }
-    }
-  } catch (error) {
-    console.log('instruction parsing error', error)
-    throw error
-  }
+  return parsedInstruction
+}
 
-  if (parsedInstructions.length === 0) {
-    throw new Error('No supported instructions found in transaction')
-  }
+function parseSystemInstruction({ decoded, index, instruction }, { accountKeys }) {
+  const programId = accountKeys[instruction.programIdIndex]
 
-  return parsedInstructions
+  return {
+    method: decoded.method,
+    from: decoded.from,
+    to: decoded.to,
+    amount: decoded.amount,
+    programId: programId.toBase58(),
+    instructionIndex: index,
+  }
 }
 
-async function getMintAddressFromTokenAccount(tokenAccountAddress, api) {
-  try {
-    const accountInfo = await api.getAccountInfo(tokenAccountAddress)
-    if (accountInfo?.data?.parsed?.info?.mint) {
-      return accountInfo.data.parsed.info.mint
-    }
-  } catch (error) {
-    console.log('Error getting mint address:', error)
+function parseStakeInstruction({ decoded, index, instruction }, { accountKeys, instructions }) {
+  const programId = accountKeys[instruction.programIdIndex]
+  const { stakeAccount: stakeAddress, ...rest } = decoded
+
+  const parsedInstruction = {
+    method: decoded.method,
+    stakeAddress,
+    programId: programId.toBase58(),
+    instructionIndex: index,
+    ...rest,
   }
 
-  return null
+  if (decoded.method === 'delegate' && parsedInstruction.amount === undefined) {
+    const amount = getStakedAmountFromCreateWithSeed(stakeAddress, instructions, accountKeys)
+    if (amount !== undefined) parsedInstruction.amount = amount
+  }
+
+  return parsedInstruction
 }

package/src/tx/prepare-for-signing.js

@@ -1,6 +1,7 @@
 import { isNumberUnit } from '@exodus/currency'
 import { VersionedTransaction } from '@exodus/solana-web3.js'
 import BN from 'bn.js'
+import assert from 'minimalistic-assert'
 
 import { createMetaplexTransferTransaction } from '../helpers/metaplex-transfer.js'
 import Transaction from '../transaction.js'
@@ -42,6 +43,10 @@ export function prepareForSigning(unsignedTx, { checkBalances = true } = {}) {
 
   // Recreate a Web3.js Transaction instance if the buffer provided.
   if (transactionBuffer) {
+    assert(
+      unsignedTx.txData.transactionBuffer instanceof Uint8Array,
+      'transactionBuffer must be a Buffer or Uint8Array'
+    )
     return deserializeTransactionBytes(transactionBuffer)
   }
 

package/src/vendor/index.js

@@ -9,4 +9,10 @@ export * from './stake-program.js'
 export * from './sysvar.js'
 export * from './transaction.js'
 export * from './constants.js'
-export { TOKEN_INSTRUCTION_LAYOUTS, TokenInstruction } from './token-program.js'
+export {
+  Token2022Program,
+  TOKEN_INSTRUCTION_LAYOUTS,
+  TokenInstruction,
+  TokenProgram,
+  TRANSFER_FEE_SUB_INSTRUCTIONS,
+} from './token-program.js'

package/src/vendor/stake-program.js

@@ -1,4 +1,5 @@
 import * as BufferLayout from '@exodus/buffer-layout'
+import BN from 'bn.js'
 
 import { decodeData, encodeData } from './instruction.js'
 import { PublicKey } from './publickey.js'
@@ -177,6 +178,52 @@ export const STAKE_INSTRUCTION_LAYOUTS = Object.freeze({
  * Stake Instruction class
  */
 export const StakeInstruction = {
+  /**
+   * Check if an instruction belongs to the Stake program (program ID check only)
+   * @param {Object} instruction - Normalized instruction object
+   * @param {Array} accountKeys - Account public keys array
+   * @returns {boolean} True if this is a stake program instruction
+   */
+  isProgramInstruction(instruction, accountKeys) {
+    if (!instruction || instruction.programIdIndex === undefined) return false
+    const programId = accountKeys[instruction.programIdIndex]
+    return programId.equals(StakeProgram.programId)
+  },
+
+  /**
+   * Validate instruction data for decoding (length, type, accounts)
+   * Only supports fund movement instructions: Delegate, Deactivate, Withdraw, Split
+   * @param {Object} instruction - Normalized instruction object
+   * @throws {Error} If instruction is invalid for decoding
+   */
+  validateInstruction(instruction) {
+    if (!Array.isArray(instruction.accounts) || instruction.accounts.length === 0) {
+      throw new Error('Stake instruction requires at least 1 account')
+    }
+
+    const buffer = Buffer.from(instruction.data)
+    if (buffer.length < 4) {
+      throw new Error('Stake instruction data too short')
+    }
+
+    const instructionType = buffer.readUInt32LE(0)
+
+    switch (instructionType) {
+      case STAKE_INSTRUCTION_LAYOUTS.Delegate.index:
+      case STAKE_INSTRUCTION_LAYOUTS.Deactivate.index:
+        return
+      case STAKE_INSTRUCTION_LAYOUTS.Split.index:
+      case STAKE_INSTRUCTION_LAYOUTS.Withdraw.index:
+        if (buffer.length < 12) {
+          throw new Error('Split/Withdraw instruction data too short')
+        }
+
+        return
+      default:
+        throw new Error(`Unsupported stake instruction type: ${instructionType}`)
+    }
+  },
+
   /**
    * Decode a stake instruction and retrieve the instruction type.
    */
@@ -286,6 +333,67 @@ export const StakeInstruction = {
       )
     }
   },
+
+  /**
+   * Decode raw staking instruction data.
+   * Only supports fund movement instructions: Delegate, Deactivate, Withdraw, Split
+   * IMPORTANT: Call isProgramInstruction() and validateInstruction() first.
+   * @param {Buffer} buffer - Instruction data buffer
+   * @param {Array} accounts - Account indices array
+   * @param {Array} accountKeys - Account public keys array
+   * @returns {Object} Decoded staking data with method and relevant fields
+   */
+  decodeInstructionData(buffer, accounts, accountKeys) {
+    const getAccountAddress = (index) => {
+      const accountIndex = accounts[index]
+      if (accountIndex === undefined) return null
+      const key = accountKeys[accountIndex]
+      return key ? key.toBase58() : null
+    }
+
+    const instructionType = buffer.readUInt32LE(0)
+
+    switch (instructionType) {
+      case STAKE_INSTRUCTION_LAYOUTS.Delegate.index:
+        // Accounts: [stakeAccount, voteAccount, clock, stakeHistory, stakeConfig, stakeAuthority]
+        return {
+          method: 'delegate',
+          stakeAccount: getAccountAddress(0),
+          validator: getAccountAddress(1),
+          stakeAuthority: getAccountAddress(5),
+        }
+
+      case STAKE_INSTRUCTION_LAYOUTS.Deactivate.index:
+        // Accounts: [stakeAccount, clock, stakeAuthority]
+        return {
+          method: 'deactivate',
+          stakeAccount: getAccountAddress(0),
+          stakeAuthority: getAccountAddress(2),
+        }
+
+      case STAKE_INSTRUCTION_LAYOUTS.Withdraw.index:
+        // Accounts: [stakeAccount, to, clock, stakeHistory, withdrawAuthority]
+        return {
+          method: 'withdraw',
+          stakeAccount: getAccountAddress(0),
+          amount: new BN(buffer.slice(4, 12), 'le'),
+          to: getAccountAddress(1),
+          withdrawAuthority: getAccountAddress(4),
+        }
+
+      case STAKE_INSTRUCTION_LAYOUTS.Split.index:
+        // Accounts: [stakeAccount, splitStakeAccount, stakeAuthority]
+        return {
+          method: 'split',
+          stakeAccount: getAccountAddress(0),
+          splitStakeAccount: getAccountAddress(1),
+          amount: new BN(buffer.slice(4, 12), 'le'),
+        }
+
+      default:
+        throw new Error(`Unsupported stake instruction type: ${instructionType}`)
+    }
+  },
 }
 
 /**

package/src/vendor/system-program.js

@@ -7,6 +7,7 @@ import { PublicKey } from './publickey.js'
 import { SYSVAR_RECENT_BLOCKHASHES_PUBKEY, SYSVAR_RENT_PUBKEY } from './sysvar.js'
 import { Transaction, TransactionInstruction } from './transaction.js'
 import * as Layout from './utils/layout.js'
+import { toBuffer } from './utils/to-buffer.js'
 
 /**
  * Create account system transaction params
@@ -199,6 +200,40 @@ export const SYSTEM_INSTRUCTION_LAYOUTS = Object.freeze({
  * System Instruction class
  */
 export const SystemInstruction = {
+  /**
+   * Check if an instruction belongs to the System program (program ID check only)
+   * @param {Object} instruction - Normalized instruction object
+   * @param {Array} accountKeys - Account public keys array
+   * @returns {boolean} True if this is a system program instruction
+   */
+  isProgramInstruction(instruction, accountKeys) {
+    if (!instruction || instruction.programIdIndex === undefined) return false
+    const programId = accountKeys[instruction.programIdIndex]
+    return programId.equals(SystemProgram.programId)
+  },
+
+  /**
+   * Validate instruction data for transfer decoding (length, type, accounts)
+   * @param {Object} instruction - Normalized instruction object
+   * @throws {Error} If instruction is invalid for decoding
+   */
+  validateInstruction(instruction) {
+    if (!Array.isArray(instruction.accounts) || instruction.accounts.length !== 2) {
+      throw new Error('System transfer instruction requires exactly 2 accounts')
+    }
+
+    const buffer = toBuffer(instruction.data)
+    // Transfer layout: u32 instruction + u64 lamports = 12 bytes
+    if (buffer.length < 12) {
+      throw new Error('System transfer instruction data too short')
+    }
+
+    const instructionType = buffer.readUInt32LE(0)
+    if (instructionType !== SYSTEM_INSTRUCTION_LAYOUTS.Transfer.index) {
+      throw new Error(`Unsupported system instruction type: ${instructionType}`)
+    }
+  },
+
   /**
    * Decode a system instruction and retrieve the instruction type.
    */
@@ -260,27 +295,40 @@ export const SystemInstruction = {
   },
 
   /**
-   * Decode raw instruction data (for use in parseTxBuffer)
+   * Decode raw instruction data.
+   * IMPORTANT: Call isProgramInstruction() and validateInstruction() first.
+   * @param {Buffer} buffer - Instruction data buffer
+   * @param {Array} accounts - Account indices array
+   * @param {Array} accountKeys - Account public keys array
+   * @returns {Object} Decoded instruction data with amount, method, and accounts
+   */
+  decodeInstructionData(buffer, accounts, accountKeys) {
+    const { lamports } = decodeData(SYSTEM_INSTRUCTION_LAYOUTS.Transfer, buffer)
+    return {
+      method: 'systemTransfer',
+      amount: new BN(lamports),
+      from: accountKeys[accounts[0]].toBase58(),
+      to: accountKeys[accounts[1]].toBase58(),
+    }
+  },
+
+  /**
+   * Decode raw CreateWithSeed instruction data
    * @param {Buffer} data - Raw instruction data buffer
-   * @returns {Object} Decoded instruction data with amount and method
+   * @returns {Object} Decoded instruction data with lamports, seed, space, programId
    */
-  decodeInstructionData(data) {
+  decodeCreateWithSeedData(data) {
     const buffer = Buffer.from(data)
-
-    try {
-      const { lamports } = decodeData(SYSTEM_INSTRUCTION_LAYOUTS.Transfer, buffer)
-      return {
-        amount: new BN(lamports),
-        method: 'systemTransfer',
-      }
-    } catch (err) {
-      // Provide more specific error for non-transfer instructions
-      if (err.message.includes('instruction index mismatch')) {
-        const instructionType = buffer.readUInt32LE(0)
-        throw new Error(`Unsupported instruction type for SystemProgram: ${instructionType}`)
-      }
-
-      throw err
+    const { base, seed, lamports, space, programId } = decodeData(
+      SYSTEM_INSTRUCTION_LAYOUTS.CreateWithSeed,
+      buffer
+    )
+    return {
+      basePubkey: new PublicKey(base),
+      seed,
+      lamports: new BN(lamports),
+      space,
+      programId: new PublicKey(programId),
     }
   },
 

package/src/vendor/token-program.js

@@ -1,5 +1,32 @@
 import BN from 'bn.js'
 
+import { PublicKey } from './publickey.js'
+import { toBuffer } from './utils/to-buffer.js'
+
+/**
+ * Token Program
+ */
+export const TokenProgram = {
+  /**
+   * Public key that identifies the Token program
+   */
+  get programId() {
+    return new PublicKey('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA')
+  },
+}
+
+/**
+ * Token-2022 (Token Extensions) Program
+ */
+export const Token2022Program = {
+  /**
+   * Public key that identifies the Token-2022 program
+   */
+  get programId() {
+    return new PublicKey('TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb')
+  },
+}
+
 /**
  * Token Program instruction layouts
  * Token-2022 (Token Extensions) is backward compatible with these instruction types
@@ -119,62 +146,110 @@ export const TRANSFER_FEE_SUB_INSTRUCTIONS = Object.freeze({
  */
 export const TokenInstruction = {
   /**
-   * Decode raw SPL Token instruction data (for use in parseTxBuffer)
-   * @param {Buffer} data - Instruction data buffer
-   * @returns {Object} Decoded instruction data with amount, method, and optional decimals/fee
+   * Check if an instruction belongs to the Token program (program ID check only)
+   * @param {Object} instruction - Normalized instruction object
+   * @param {Array} accountKeys - Account public keys array
+   * @returns {boolean} True if this is a token program instruction
    */
-  decodeInstructionData(data) {
-    // Ensure we have a Buffer to work with
-    const buffer = Buffer.from(data)
+  isProgramInstruction(instruction, accountKeys) {
+    if (!instruction || instruction.programIdIndex === undefined) return false
+    const programId = accountKeys[instruction.programIdIndex]
+    return programId.equals(TokenProgram.programId) || programId.equals(Token2022Program.programId)
+  },
+
+  /**
+   * Validate instruction data for transfer decoding (length, type, accounts)
+   * @param {Object} instruction - Normalized instruction object
+   * @throws {Error} If instruction is invalid for decoding
+   */
+  validateInstruction(instruction) {
+    if (!Array.isArray(instruction.accounts) || instruction.accounts.length < 3) {
+      throw new Error('Token instruction requires at least 3 accounts')
+    }
+
+    const data = toBuffer(instruction.data)
+    if (data.length < 9) {
+      throw new Error('Token instruction data too short')
+    }
+
+    const instructionType = data[0]
 
-    if (buffer.length < 9) throw new Error('Instruction data too short for SPL transfer')
+    if (instructionType === TOKEN_INSTRUCTION_LAYOUTS.Transfer.index) {
+      return
+    }
+
+    if (instructionType === TOKEN_INSTRUCTION_LAYOUTS.TransferChecked.index) {
+      if (data.length < 10) {
+        throw new Error('TransferChecked instruction data too short')
+      }
+
+      return
+    }
+
+    if (instructionType === TOKEN_INSTRUCTION_LAYOUTS.TransferFeeExtension.index) {
+      if (data.length < 19) {
+        throw new Error('TransferCheckedWithFee instruction data too short')
+      }
+
+      if (data[1] !== TRANSFER_FEE_SUB_INSTRUCTIONS.TransferCheckedWithFee) {
+        throw new Error(`Unsupported TransferFeeExtension sub-instruction: ${data[1]}`)
+      }
 
+      return
+    }
+
+    throw new Error(`Unsupported token instruction type: ${instructionType}`)
+  },
+
+  /**
+   * Decode raw SPL Token instruction data.
+   * IMPORTANT: Call isProgramInstruction() and validateInstruction() first.
+   * @param {Buffer} buffer - Instruction data buffer
+   * @param {Array} accounts - Account indices array
+   * @param {Array} accountKeys - Account public keys array
+   * @returns {Object} Decoded instruction data with amount, method, accounts, and optional decimals/fee
+   */
+  decodeInstructionData(buffer, accounts, accountKeys) {
     const instructionType = buffer[0]
+    const getAddress = (index) => accountKeys[accounts[index]].toBase58()
 
     // Handle TransferFeeExtension (Token-2022 instruction 26)
     if (instructionType === TOKEN_INSTRUCTION_LAYOUTS.TransferFeeExtension.index) {
-      // TransferFeeExtension has a sub-instruction type at byte 1
-      if (buffer.length < 2) throw new Error('Instruction data too short for TransferFeeExtension')
-
-      const subInstructionType = buffer[1]
-      // TransferCheckedWithFee sub-instruction (1)
-      if (subInstructionType === TRANSFER_FEE_SUB_INSTRUCTIONS.TransferCheckedWithFee) {
-        // Format: [26, 1, amount(8), decimals(1), fee(8)]
-        if (buffer.length < 18) {
-          throw new Error('Instruction data too short for transferCheckedWithFee')
-        }
-
-        const amountBytes = buffer.slice(2, 10)
-        const amountBN = new BN(amountBytes, 'le')
-        const decimals = buffer[10]
-        const feeBytes = buffer.slice(11, 19)
-        const feeBN = new BN(feeBytes, 'le')
-
-        return {
-          amount: amountBN,
-          method: 'transferCheckedWithFee',
-          decimals,
-          fee: feeBN,
-        }
+      // Format: [26, 1, amount(8), decimals(1), fee(8)]
+      return {
+        method: 'transferCheckedWithFee',
+        amount: new BN(buffer.slice(2, 10), 'le'),
+        decimals: buffer[10],
+        fee: new BN(buffer.slice(11, 19), 'le'),
+        // Accounts: [source, mint, destination, authority]
+        fromTokenAccount: getAddress(0),
+        mintAddress: getAddress(1),
+        toTokenAccount: getAddress(2),
       }
-
-      // Other TransferFeeExtension sub-instructions not supported yet
-      throw new Error(`Unsupported TransferFeeExtension sub-instruction: ${subInstructionType}`)
     }
 
-    const amountBytes = buffer.slice(1, 9)
-    const amountBN = new BN(amountBytes, 'le')
+    const amount = new BN(buffer.slice(1, 9), 'le')
 
     if (instructionType === TOKEN_INSTRUCTION_LAYOUTS.Transfer.index) {
-      return { amount: amountBN, method: 'transfer' }
+      // Accounts: [source, destination, authority]
+      return {
+        method: 'transfer',
+        amount,
+        fromTokenAccount: getAddress(0),
+        mintAddress: null,
+        toTokenAccount: getAddress(1),
+      }
     }
 
-    if (instructionType === TOKEN_INSTRUCTION_LAYOUTS.TransferChecked.index) {
-      if (buffer.length < 10) throw new Error('Instruction data too short for transferChecked')
-      const decimals = buffer[9]
-      return { amount: amountBN, method: 'transferChecked', decimals }
+    // TransferChecked
+    // Accounts: [source, mint, destination, authority]
+    return {
+      method: 'transferChecked',
+      amount,
+      decimals: buffer[9],
+      fromTokenAccount: getAddress(0),
+      mintAddress: getAddress(1),
+      toTokenAccount: getAddress(2),
     }
-
-    throw new Error(`Unsupported instruction type: ${instructionType}`)
   },
 }