@exodus/solana-lib 3.9.4 → 3.10.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.10.0](https://github.com/ExodusMovement/assets/compare/@exodus/solana-lib@3.9.5...@exodus/solana-lib@3.10.0) (2025-04-03)
+
+
+### Features
+
+
+* feat(solana): add optional addExternalFeePayerToTransaction (#5345)
+
+
+
+## [3.9.5](https://github.com/ExodusMovement/assets/compare/@exodus/solana-lib@3.9.4...@exodus/solana-lib@3.9.5) (2025-03-25)
+
+
+### License
+
+
+* license: re-license under MIT license (#4814)
+
+
+
 ## [3.9.4](https://github.com/ExodusMovement/assets/compare/@exodus/solana-lib@3.9.3...@exodus/solana-lib@3.9.4) (2025-01-02)
 
 

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2024 Exodus Movement, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,21 @@
-# @exodus/solana-lib
+# @exodus/solana-lib · [![npm version](https://img.shields.io/badge/npm-public-blue.svg?style=flat)](https://www.npmjs.com/package/@exodus/solana-lib)
 
-Solana utils, such as for cryptography, address encoding/decoding, transaction building, etc. See [Asset Packages](../../docs/asset-packages.md) for more detail on this package's role.
+**solana-lib** is a comprehensive library designed for seamless interaction with the Solana blockchain. It provides a robust set of functions and classes to facilitate core blockchain operations.
+
+This library encompasses all the essential tools required for cryptographic operations, including key derivation and signing. It also supports transaction serialization and deserialization, data encoding and decoding, and the crafting of various types of transactions such as regular transactions, token transactions, and staking transactions.
+
+---
+
+## Installation
+
+Install the package via `yarn`:
+
+```bash
+yarn add @exodus/solana-lib
+```
+
+## License
+
+This project is licensed under the MIT License.
+You are free to use, modify, and distribute this software under the terms of the MIT License.
+For more details, see the [LICENSE](LICENSE) file.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/solana-lib",
-  "version": "3.9.4",
+  "version": "3.10.0",
   "description": "Solana utils, such as for cryptography, address encoding/decoding, transaction building, etc.",
   "type": "module",
   "main": "src/index.js",
@@ -10,7 +10,7 @@
     "!src/**/__tests__"
   ],
   "author": "Exodus Movement, Inc.",
-  "license": "ISC",
+  "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
@@ -29,6 +29,7 @@
     "bn.js": "^5.2.1",
     "borsh": "^0.7.0",
     "bs58": "^4.0.1",
+    "lodash": "^4.17.11",
     "minimalistic-assert": "^1.0.1"
   },
   "devDependencies": {
@@ -45,5 +46,5 @@
     "type": "git",
     "url": "git+https://github.com/ExodusMovement/assets.git"
   },
-  "gitHead": "8a6a0d1a70d14e86a9cf4d47b8884939f10be724"
+  "gitHead": "59c4d4a4a7404eb915e4fa722a2afe01d1556046"
 }

package/src/constants.js

@@ -9,6 +9,10 @@ export const STAKE_PROGRAM_ID = StakeProgram.programId
 
 export const TOKEN_PROGRAM_ID = new PublicKey('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA')
 
+export const COMPUTE_BUDGET_PROGRAM_ID = new PublicKey(
+  'ComputeBudget111111111111111111111111111111'
+)
+
 export const TOKEN_2022_PROGRAM_ID = new PublicKey('TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb')
 
 export const MEMO_PROGRAM_ID = new PublicKey('MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr')

package/src/fee-data/README.md

@@ -0,0 +1,44 @@
+# **Computing Fees and Priority Fees in Solana**
+
+In Solana, **fees** and **priority fees** are influenced by network conditions, making them **not fully deterministic** but still **predictable to some extent**.
+
+---
+
+## **1. Computing Base Transaction Fees**
+
+Solana uses a **fixed fee structure** based on transaction size. The base fee is computed as:
+
+base_fee = num_signatures \* signature_fee
+
+- **Signature Fee**: A fixed amount per signature (historically 5000 lamports per signature, but subject to change).
+- **Num Signatures**: Typically 1 for standard transactions, more if using multi-signature accounts.
+
+Thus, if network parameters remain unchanged, you can **deterministically** compute the **base fee**.
+
+---
+
+## **2. Computing Priority Fee (Not Deterministic)**
+
+The **priority fee** is **market-driven**, meaning it depends on **current network congestion**. Users specify the **compute unit price** in lamports per **compute unit**. The total priority fee is then:
+
+priority_fee = compute_units_used \* compute_unit_price
+
+- **Compute Units Used**: Can be estimated based on the transaction complexity but varies based on program execution.
+- **Compute Unit Price**: Set by the user, competes with others in a bidding system.
+
+### **Why is Priority Fee Not Deterministic?**
+
+- The **compute units used** may vary due to transaction execution conditions.
+- The **compute unit price** is market-driven and changes based on network demand.
+
+Thus, **you can estimate priority fees, but they are not deterministic**.
+
+---
+
+## **3. Can You Precompute Fees?**
+
+| Fee Type         | Deterministic? | Notes                                            |
+| ---------------- | -------------- | ------------------------------------------------ |
+| **Base Fee**     | ✅ Yes         | Fixed per signature and transaction size.        |
+| **Priority Fee** | ❌ No          | Market-driven and depends on network congestion. |
+| **Total Fees**   | ⚠️ Estimated   | Can be predicted but not guaranteed.             |

package/src/fee-data/index.js

@@ -4,9 +4,10 @@ export const createFeeData = ({ asset }) =>
   new FeeData({
     config: {
       fee: `0.000005 ${asset.ticker}`,
+      baseFee: `0.000005 ${asset.ticker}`,
       priorityFee: 1_000_000,
       fuelThreshold: `0.000015 ${asset.ticker}`,
-      computeUnitsMultiplier: 4, // compute units buffer
+      computeUnitsMultiplier: 1, // compute units buffer, increasing to > 1 can cause Dust issues.
     },
     mainKey: 'fee',
     currency: asset.currency,

package/src/helpers/tokenTransfer.js

@@ -63,7 +63,6 @@ function createIx(
 export const createTokenTransferInstruction = (owner, fromTokenAddress, to, amount) => {
   const sourcePubkey = new PublicKey(fromTokenAddress) // the token ADDRESS needed!
   const destinationPubkey = new PublicKey(to)
-  console.log(`destination token address: ${destinationPubkey.toBase58()}`)
   const ownerAccountOrWalletPublicKey = new PublicKey(owner) // the only native SOL address
 
   return Token.createTransferInstruction(

package/src/tx/common.js

@@ -1,3 +1,4 @@
+import { VersionedTransaction } from '@exodus/solana-web3.js'
 import base58 from 'bs58'
 
 export function isVersionedTransaction(tx) {
@@ -12,6 +13,10 @@ export function transactionToBase58(tx) {
   return base58.encode(tx.serialize())
 }
 
+export function deserializeTransaction(tx) {
+  return VersionedTransaction.deserialize(tx)
+}
+
 export function getTxId(tx) {
   const signature = getFirstSignature(tx)
   if (signature === null) {

package/src/tx/create-unsigned-tx.js

@@ -6,6 +6,7 @@ export function createUnsignedTx({
   fee,
   feeData,
   recentBlockhash,
+  useFeePayer,
   // Tokens related:
   tokenMintAddress,
   destinationAddressType,
@@ -73,6 +74,7 @@ export function createUnsignedTx({
     },
     txMeta: {
       assetName: asset.name,
+      useFeePayer,
     },
   }
 }

package/src/tx/index.js

@@ -7,4 +7,6 @@ export * from './decode-tx-instructions.js'
 export * from './build-raw-transaction.js'
 export * from './sign-hardware.js'
 export * from './prepare-for-signing.js'
-export { transactionToBase58 } from './common.js'
+export * from './verify-only-fee-payer-changed.js'
+export * from './parse-tx-buffer.js'
+export { transactionToBase58, deserializeTransaction } from './common.js'

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

@@ -0,0 +1,136 @@
+import BN from 'bn.js'
+import bs58 from 'bs58'
+
+import { COMPUTE_BUDGET_PROGRAM_ID, SYSTEM_PROGRAM_ID, TOKEN_PROGRAM_ID } from '../constants.js'
+import { deserializeTransaction } from './common.js'
+
+function decodeSPLTransferData(base58Data) {
+  const buffer = bs58.decode(base58Data)
+
+  // 1 byte
+  if (buffer[0] !== 3) {
+    throw new Error(`Unsupported instruction type: ${buffer[0]}`)
+  }
+
+  const amountBytes = buffer.slice(1, 9)
+  const amountBN = new BN(amountBytes, 'le')
+
+  return { amount: amountBN, method: 'transfer' }
+}
+
+function decodeSystemTransferData(base58Data) {
+  const buffer = bs58.decode(base58Data)
+
+  // 4 bytes
+  if (buffer.readUInt32LE(0) !== 2) {
+    throw new Error(`Unsupported instruction type for SystemProgram: ${buffer.readUInt32LE(0)}`)
+  }
+
+  const amountBytes = buffer.slice(4, 12)
+  const amountBN = new BN(amountBytes, 'le')
+
+  return {
+    amount: amountBN,
+    method: 'systemTransfer',
+  }
+}
+
+// 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
+
+  const [ix1, ix2, ix3] = instructions
+  if (
+    !accountKeys[ix1.programIdIndex].equals(COMPUTE_BUDGET_PROGRAM_ID) ||
+    !accountKeys[ix2.programIdIndex].equals(COMPUTE_BUDGET_PROGRAM_ID)
+  ) {
+    return false
+  }
+
+  if (!accountKeys[ix3.programIdIndex].equals(TOKEN_PROGRAM_ID)) return false
+
+  if (!Array.isArray(ix3.accounts) || ix3.accounts.length !== 3) return false
+
+  try {
+    const data = bs58.decode(ix3.data)
+    if (data[0] !== 0x03) return false
+  } catch {
+    return false
+  }
+
+  return true
+}
+
+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 (
+    !accountKeys[instructions[0].programIdIndex].equals(COMPUTE_BUDGET_PROGRAM_ID) ||
+    !accountKeys[instructions[1].programIdIndex].equals(COMPUTE_BUDGET_PROGRAM_ID)
+  ) {
+    return false
+  }
+
+  const ix = instructions[2]
+  if (!accountKeys[ix.programIdIndex].equals(SYSTEM_PROGRAM_ID)) return false
+
+  if (!Array.isArray(ix.accounts) || ix.accounts.length !== 2) return false
+
+  try {
+    const data = bs58.decode(ix.data)
+    if (data[0] !== 0x02) return false
+  } catch {
+    return false
+  }
+
+  return true
+}
+
+// TODO: Unify with parseTransaction in solana-api and use there as well?
+// TODO: support more tx types.
+export async function parseTxBuffer(buffer, api) {
+  const transaction = deserializeTransaction(buffer)
+
+  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,
+      }
+    }
+
+    if (isSolanaTransfer(transaction)) {
+      const mainInstruction = transaction.message.instructions[2]
+      const { amount, method } = decodeSystemTransferData(mainInstruction.data)
+
+      return {
+        method,
+        from: transaction.message.accountKeys[mainInstruction.accounts[0]],
+        to: transaction.message.accountKeys[mainInstruction.accounts[1]],
+        amount,
+      }
+    }
+  } catch (error) {
+    console.log('transaction check error', error)
+  }
+
+  throw new Error('Transaction not supported for buffer parsing')
+}

package/src/tx/verify-only-fee-payer-changed.js

@@ -0,0 +1,98 @@
+import lodash from 'lodash'
+import assert from 'minimalistic-assert'
+
+export function verifyOnlyFeePayerChanged(beforeTx, afterTx) {
+  assert(
+    beforeTx.signatures.length + 1 === afterTx.signatures.length &&
+      beforeTx.message.header.numRequiredSignatures + 1 ===
+        afterTx.message.header.numRequiredSignatures,
+    'A signature was not added for the new signer'
+  )
+  beforeTx.signatures.forEach((signature, index) => {
+    assert(
+      lodash.isEqual(signature, afterTx.signatures[index + 1]),
+      'Existing signatures do not match'
+    )
+  })
+  assert(
+    beforeTx.message.accountKeys.length + 1 === afterTx.message.accountKeys.length,
+    'Fee payer account key was not added'
+  )
+  beforeTx.message.accountKeys.forEach((accountKey, index) => {
+    assert(
+      lodash.isEqual(accountKey, afterTx.message.accountKeys[index + 1]),
+      'Existing account keys do not match'
+    )
+  })
+
+  assert(
+    beforeTx.message.instructions.length === afterTx.message.instructions.length,
+    'No new instructions are allowed'
+  )
+
+  beforeTx.message.instructions.forEach(({ programIdIndex }, index) => {
+    assert(
+      programIdIndex + 1 === afterTx.message.instructions[index]?.programIdIndex,
+      'Instructions program ids were not updated'
+    )
+  })
+
+  beforeTx.message.instructions.forEach(({ accounts }, index) => {
+    assert(
+      lodash.isEqual(
+        accounts.map((id) => id + 1),
+        afterTx.message.instructions[index].accounts
+      ),
+      'Instructions account key indexes were not updated'
+    )
+  })
+
+  beforeTx.message.instructions.forEach((instruction, index) => {
+    assert(
+      lodash.isEqual(
+        { ...instruction, accounts: null, programIdIndex: null },
+        {
+          ...afterTx.message.instructions[index],
+          accounts: null,
+          programIdIndex: null,
+        }
+      ),
+      'Instructions do not match in some attributes'
+    )
+  })
+
+  assert(
+    lodash.isEqual(
+      {
+        ...beforeTx,
+        signatures: null,
+        message: null,
+      },
+      {
+        ...afterTx,
+
+        signatures: null,
+        message: null,
+      }
+    ),
+    'Transactions do not match in some attributes'
+  )
+
+  assert(
+    lodash.isEqual(
+      {
+        ...beforeTx.message,
+        header: { ...beforeTx.message.header, numRequiredSignatures: null },
+        accountKeys: null,
+        instructions: null,
+      },
+      {
+        ...afterTx.message,
+        header: { ...afterTx.message.header, numRequiredSignatures: null },
+        accountKeys: null,
+        instructions: null,
+      }
+    ),
+    'Transactions do not match in some attributes'
+  )
+}