@exodus/solana-lib 3.16.0 → 3.18.0

package/CHANGELOG.md

@@ -3,6 +3,26 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [3.18.0](https://github.com/ExodusMovement/assets/compare/@exodus/solana-lib@3.15.3...@exodus/solana-lib@3.18.0) (2025-11-26)
+
+
+### Features
+
+
+* feat: Solana support Close Authority Sponsorship in fee payer (#6767)
+
+
+
+## [3.17.0](https://github.com/ExodusMovement/assets/compare/@exodus/solana-lib@3.15.3...@exodus/solana-lib@3.17.0) (2025-11-13)
+
+
+### Features
+
+
+* feat: Solana support Close Authority Sponsorship in fee payer (#6767)
+
+
+
 ## [3.16.0](https://github.com/ExodusMovement/assets/compare/@exodus/solana-lib@3.15.3...@exodus/solana-lib@3.16.0) (2025-11-11)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/solana-lib",
-  "version": "3.16.0",
+  "version": "3.18.0",
   "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": "e8b0a919196eda921b8bc532f5632180c2bef508"
+  "gitHead": "4c60cc2d7f07229295b801d9f67a336d314711a0"
 }

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

@@ -1,63 +1,97 @@
-import BN from 'bn.js'
 import bs58 from 'bs58'
 
-import { COMPUTE_BUDGET_PROGRAM_ID, SYSTEM_PROGRAM_ID, TOKEN_PROGRAM_ID } from '../constants.js'
+import { SYSTEM_PROGRAM_ID, TOKEN_2022_PROGRAM_ID, TOKEN_PROGRAM_ID } from '../constants.js'
+import {
+  SYSTEM_INSTRUCTION_LAYOUTS,
+  SystemInstruction,
+  TOKEN_INSTRUCTION_LAYOUTS,
+  TokenInstruction,
+} from '../vendor/index.js'
 import { deserializeTransaction } from './common.js'
 
-function decodeSPLTransferData(base58Data) {
-  const buffer = bs58.decode(base58Data)
+// Helper function to check if an instruction is a token transfer
+function isTokenTransferInstruction(instruction, accountKeys) {
+  if (!instruction || instruction.programIdIndex === undefined) return false
 
-  // 1 byte
-  if (buffer[0] !== 3) {
-    throw new Error(`Unsupported instruction type: ${buffer[0]}`)
-  }
+  const programId = accountKeys[instruction.programIdIndex]
 
-  const amountBytes = buffer.slice(1, 9)
-  const amountBN = new BN(amountBytes, 'le')
+  if (!programId.equals(TOKEN_PROGRAM_ID) && !programId.equals(TOKEN_2022_PROGRAM_ID)) {
+    return false
+  }
 
-  return { amount: amountBN, method: 'transfer' }
-}
+  // 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
+  }
 
-function decodeSystemTransferData(base58Data) {
-  const buffer = bs58.decode(base58Data)
+  // 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)
+    }
 
-  // 4 bytes
-  if (buffer.readUInt32LE(0) !== 2) {
-    throw new Error(`Unsupported instruction type for SystemProgram: ${buffer.readUInt32LE(0)}`)
-  }
+    const instructionType = data[0]
 
-  const amountBytes = buffer.slice(4, 12)
-  const amountBN = new BN(amountBytes, 'le')
+    // Accept Transfer, TransferChecked, and TransferFeeExtension
+    if (
+      instructionType !== TOKEN_INSTRUCTION_LAYOUTS.Transfer.index &&
+      instructionType !== TOKEN_INSTRUCTION_LAYOUTS.TransferChecked.index &&
+      instructionType !== TOKEN_INSTRUCTION_LAYOUTS.TransferFeeExtension.index
+    ) {
+      return false
+    }
 
-  return {
-    amount: amountBN,
-    method: 'systemTransfer',
+    // 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
   }
+
+  return true
 }
 
-// TODO support more tx types/options
 export function isTokenTransfer(tx) {
   const { message } = tx
   const { accountKeys, instructions } = message
 
-  if (!Array.isArray(accountKeys) || accountKeys.length !== 6) return false
-  if (!Array.isArray(instructions) || instructions.length !== 3) return false
+  if (!Array.isArray(accountKeys) || !Array.isArray(instructions)) return false
 
-  const [ix1, ix2, ix3] = instructions
-  if (
-    !accountKeys[ix1.programIdIndex].equals(COMPUTE_BUDGET_PROGRAM_ID) ||
-    !accountKeys[ix2.programIdIndex].equals(COMPUTE_BUDGET_PROGRAM_ID)
-  ) {
-    return false
-  }
+  // Search for any token transfer instruction
+  return instructions.some((instruction) => isTokenTransferInstruction(instruction, accountKeys))
+}
+
+// Helper function to check if an instruction is a SOL transfer
+function isSolTransferInstruction(instruction, accountKeys) {
+  if (!instruction || instruction.programIdIndex === undefined) return false
+
+  const programId = accountKeys[instruction.programIdIndex]
 
-  if (!accountKeys[ix3.programIdIndex].equals(TOKEN_PROGRAM_ID)) return false
+  if (!programId.equals(SYSTEM_PROGRAM_ID)) return false
 
-  if (!Array.isArray(ix3.accounts) || ix3.accounts.length !== 3) return false
+  // Must have exactly 2 accounts (from, to)
+  if (!Array.isArray(instruction.accounts) || instruction.accounts.length !== 2) {
+    return false
+  }
 
+  // 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
   try {
-    const data = bs58.decode(ix3.data)
-    if (data[0] !== 0x03) return false
+    let data = instruction.data
+    if (typeof data === 'string') {
+      data = bs58.decode(data)
+    }
+
+    const buffer = Buffer.from(data)
+    if (buffer.readUInt32LE(0) !== SYSTEM_INSTRUCTION_LAYOUTS.Transfer.index) return false
   } catch {
     return false
   }
@@ -69,68 +103,162 @@ export function isSolanaTransfer(tx) {
   const { message } = tx
   const { accountKeys, instructions } = message
 
-  if (!Array.isArray(accountKeys) || accountKeys.length !== 5) return false
-  if (!Array.isArray(instructions) || instructions.length !== 3) return false
+  if (!Array.isArray(accountKeys) || !Array.isArray(instructions)) return false
 
-  if (
-    !accountKeys[instructions[0].programIdIndex].equals(COMPUTE_BUDGET_PROGRAM_ID) ||
-    !accountKeys[instructions[1].programIdIndex].equals(COMPUTE_BUDGET_PROGRAM_ID)
-  ) {
-    return false
+  return instructions.some((instruction) => isSolTransferInstruction(instruction, accountKeys))
+}
+
+// Helper to normalize account keys for both versioned and legacy transactions
+function getAccountKeys(message) {
+  // Versioned transactions use staticAccountKeys
+  if (message.staticAccountKeys) {
+    return message.staticAccountKeys
   }
 
-  const ix = instructions[2]
-  if (!accountKeys[ix.programIdIndex].equals(SYSTEM_PROGRAM_ID)) return false
+  // Legacy transactions use accountKeys
+  return message.accountKeys
+}
 
-  if (!Array.isArray(ix.accounts) || ix.accounts.length !== 2) return false
+// 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)
+  }
 
-  try {
-    const data = bs58.decode(ix.data)
-    if (data[0] !== 0x02) return false
-  } catch {
-    return false
+  return {
+    programIdIndex: instruction.programIdIndex,
+    accounts: instruction.accountKeyIndexes || instruction.accounts,
+    data: normalizedData,
+  }
+}
+
+// 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 []
   }
 
-  return true
+  return instructions.map((inst) => normalizeInstruction(inst))
 }
 
 // TODO: Unify with parseTransaction in solana-api and use there as well?
-// TODO: support more tx types.
+// TODO: add support for swap and stake instructions
 export async function parseTxBuffer(buffer, api) {
   const transaction = deserializeTransaction(buffer)
+  const { message } = transaction
+
+  // Normalize account keys and instructions (versioned vs legacy)
+  const accountKeys = getAccountKeys(message)
+  const instructions = getInstructions(message)
+
+  if (!Array.isArray(accountKeys) || !Array.isArray(instructions)) {
+    throw new TypeError('Invalid transaction structure')
+  }
+
+  const parsedInstructions = []
 
   try {
-    if (isTokenTransfer(transaction)) {
-      const mainInstruction = transaction.message.instructions[2]
-      const { amount, method } = decodeSPLTransferData(mainInstruction.data)
-
-      const fromTokenAddress =
-        transaction.message.accountKeys[mainInstruction.accounts[0]].toBase58()
-      const toTokenAddress = transaction.message.accountKeys[mainInstruction.accounts[1]].toBase58()
-      const from = await api.getTokenAddressOwner(fromTokenAddress)
-      const to = await api.getTokenAddressOwner(toTokenAddress)
-      return {
-        method,
-        from,
-        to,
-        amount,
+    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
+  }
 
-    if (isSolanaTransfer(transaction)) {
-      const mainInstruction = transaction.message.instructions[2]
-      const { amount, method } = decodeSystemTransferData(mainInstruction.data)
+  if (parsedInstructions.length === 0) {
+    throw new Error('No supported instructions found in transaction')
+  }
 
-      return {
-        method,
-        from: transaction.message.accountKeys[mainInstruction.accounts[0]],
-        to: transaction.message.accountKeys[mainInstruction.accounts[1]],
-        amount,
-      }
+  return parsedInstructions
+}
+
+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('transaction check error', error)
+    console.log('Error getting mint address:', error)
   }
 
-  throw new Error('Transaction not supported for buffer parsing')
+  return null
 }

package/src/vendor/index.js

@@ -9,3 +9,4 @@ 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'

package/src/vendor/system-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 { NONCE_ACCOUNT_LENGTH } from './nonce-account.js'
@@ -258,6 +259,31 @@ export const SystemInstruction = {
     }
   },
 
+  /**
+   * Decode raw instruction data (for use in parseTxBuffer)
+   * @param {Buffer} data - Raw instruction data buffer
+   * @returns {Object} Decoded instruction data with amount and method
+   */
+  decodeInstructionData(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
+    }
+  },
+
   /**
    * Decode an allocate system instruction and retrieve the instruction params.
    */

package/src/vendor/token-program.js

@@ -0,0 +1,180 @@
+import BN from 'bn.js'
+
+/**
+ * Token Program instruction layouts
+ * Token-2022 (Token Extensions) is backward compatible with these instruction types
+ *
+ * Reference: https://github.com/solana-program/token/blob/81ba155af8684c224c943af16ac3d70f5cad5e93/pinocchio/interface/src/instruction.rs
+ */
+
+/**
+ * An enumeration of valid SPL Token InstructionType's
+ */
+export const TOKEN_INSTRUCTION_LAYOUTS = Object.freeze({
+  InitializeMint: {
+    index: 0,
+  },
+  InitializeAccount: {
+    index: 1,
+  },
+  InitializeMultisig: {
+    index: 2,
+  },
+  Transfer: {
+    index: 3,
+    // Accounts: [source, destination, authority]
+  },
+  Approve: {
+    index: 4,
+  },
+  Revoke: {
+    index: 5,
+  },
+  SetAuthority: {
+    index: 6,
+  },
+  MintTo: {
+    index: 7,
+  },
+  Burn: {
+    index: 8,
+  },
+  CloseAccount: {
+    index: 9,
+  },
+  FreezeAccount: {
+    index: 10,
+  },
+  ThawAccount: {
+    index: 11,
+  },
+  TransferChecked: {
+    index: 12,
+    // Accounts: [source, mint, destination, authority]
+  },
+  ApproveChecked: {
+    index: 13,
+  },
+  MintToChecked: {
+    index: 14,
+  },
+  BurnChecked: {
+    index: 15,
+  },
+  InitializeAccount2: {
+    index: 16,
+  },
+  SyncNative: {
+    index: 17,
+  },
+  InitializeAccount3: {
+    index: 18,
+  },
+  InitializeMultisig2: {
+    index: 19,
+  },
+  InitializeMint2: {
+    index: 20,
+  },
+  GetAccountDataSize: {
+    index: 21,
+  },
+  InitializeImmutableOwner: {
+    index: 22,
+  },
+  AmountToUiAmount: {
+    index: 23,
+  },
+  UiAmountToAmount: {
+    index: 24,
+  },
+  // Token-2022 Extension Instructions
+  InitializeMintCloseAuthority: {
+    index: 25,
+  },
+  TransferFeeExtension: {
+    index: 26,
+    // Used for TransferCheckedWithFee operations
+    // Sub-instructions: InitializeTransferFeeConfig(0), TransferCheckedWithFee(1), etc.
+  },
+  WithdrawExcessLamports: {
+    index: 38,
+  },
+})
+
+/**
+ * TransferFeeExtension sub-instruction types
+ */
+export const TRANSFER_FEE_SUB_INSTRUCTIONS = Object.freeze({
+  InitializeTransferFeeConfig: 0,
+  TransferCheckedWithFee: 1,
+  WithdrawWithheldTokensFromMint: 2,
+  WithdrawWithheldTokensFromAccounts: 3,
+  HarvestWithheldTokensToMint: 4,
+  SetTransferFee: 5,
+})
+
+/**
+ * Token Instruction class
+ */
+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
+   */
+  decodeInstructionData(data) {
+    // Ensure we have a Buffer to work with
+    const buffer = Buffer.from(data)
+
+    if (buffer.length < 9) throw new Error('Instruction data too short for SPL transfer')
+
+    const instructionType = buffer[0]
+
+    // 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,
+        }
+      }
+
+      // 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')
+
+    if (instructionType === TOKEN_INSTRUCTION_LAYOUTS.Transfer.index) {
+      return { amount: amountBN, method: 'transfer' }
+    }
+
+    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 }
+    }
+
+    throw new Error(`Unsupported instruction type: ${instructionType}`)
+  },
+}