@w3lib/solana-batch-call 0.5.0 → 0.7.0

package/src/subpaths/history.ts

@@ -0,0 +1,38 @@
+/**
+ * 交易历史（子路径 `@w3lib/solana-batch-call/history`）：地址的交易整理成统一的 Activity（兑换、转账、授权、流动性、铸造、失败……），
+ * 数据源可换（默认节点：getSignaturesForAddress + getTransaction；可选 Helius 增强历史）。不放在主入口，不用时打包不会带上这部分代码。
+ *
+ * ```ts
+ * import { getHistory, heliusHistory } from '@w3lib/solana-batch-call/history'
+ *
+ * const page = await getHistory(address, { limit: 20 })
+ * const next = await getHistory(address, { cursor: page.nextCursor, types: ['swap'] })
+ * await getHistory(address, { source: [heliusHistory({ apiKey }), rpcHistory()] })   // 依次尝试
+ * ```
+ */
+import { history, type HistoryOptions, type HistoryPage } from '../history.js'
+import { resolve, type ShortcutOptions } from '../shortcuts.js'
+
+export {
+  MAX_HISTORY_LIMIT,
+  activityFromTransaction,
+  history,
+  rpcHistory,
+  type Activity,
+  type ActivityChange,
+  type ActivityType,
+  type HistoryContext,
+  type HistoryOptions,
+  type HistoryPage,
+  type HistorySource,
+  type RpcHistoryOptions,
+} from '../history.js'
+export { activityFromHelius, heliusHistory, type HeliusHistoryOptions } from '../historyHelius.js'
+
+export interface GetHistoryOptions extends HistoryOptions, ShortcutOptions {}
+
+/** 查地址的交易历史，节点参数与 getBalances 相同 */
+export function getHistory(address: string, options: GetHistoryOptions = {}): Promise<HistoryPage> {
+  const { client, own } = resolve(options, ['limit', 'cursor', 'before', 'after', 'types', 'source', 'symbols', 'fetch', 'signal'])
+  return history(client, address, own)
+}

package/src/subpaths/lp.ts

@@ -25,6 +25,7 @@ export {
   type SolanaLpClmmPosition,
   type SolanaLpPosition,
   type SolanaLpProtocol,
+  type SolanaLpReward,
   type SolanaLpToken,
   type SolanaPriceSource,
 } from '../lp.js'
@@ -38,15 +39,18 @@ export {
   getMaxAmounts,
   getMinAmounts,
   getMintAmounts,
+  getRewardGrowthInside,
   nearestUsableTick,
   orcaSqrtPriceAtTick,
   priceToTick,
   raydiumSqrtPriceAtTick,
+  rewardGrowthGlobal,
   sqrtPriceAtTick,
   sqrtPriceToPrice,
   tickAtSqrtPrice,
   tickToPrice,
   type ClmmProgram,
+  type RewardEmission,
   type TickFeeData,
 } from '../lpMath.js'
 
@@ -66,6 +70,6 @@ export interface GetLpPositionsOptions extends LpPositionsOptions, ShortcutOptio
  */
 export function getLpPositions(owner: string, options: GetLpPositionsOptions = {}): Promise<SolanaLpPosition[]> {
   // fetch 同时给节点请求（客户端配置）和查价用，与其他快捷函数一致
-  const { client, own } = resolve(options, ['protocols', 'mints', 'pools', 'includeClosed', 'prices', 'onPriceError', 'signal'])
+  const { client, own } = resolve(options, ['protocols', 'mints', 'pools', 'includeClosed', 'rewards', 'now', 'prices', 'onPriceError', 'signal'])
   return lpPositions(client, owner, { ...own, ...(options.fetch ? { fetch: options.fetch } : {}) })
 }

package/src/subpaths/reclaim.ts

@@ -0,0 +1,58 @@
+/**
+ * 账户回收（子路径 `@w3lib/solana-batch-call/reclaim`）：扫描钱包里关闭后能退回租金（SOL）的账户并批量关闭：空的代币账户、垃圾币（销毁后关闭）、
+ * Wrapped SOL（解包）、已清空的 Orca Whirlpool / Raydium CLMM 仓位。给出每项和合计能拿回多少 lamports，发送前用 /simulate 模拟。
+ * 不放在主入口，不用时打包不会带上这部分代码；发送的代码按需加载。
+ *
+ * ```ts
+ * import { getReclaimable, reclaim } from '@w3lib/solana-batch-call/reclaim'
+ *
+ * const r = await getReclaimable(owner, { provider: 'https://my-rpc…' })
+ * r.totalLamports                                          // 全部能拿回的 lamports
+ * const { simulation, results } = await reclaim(client, key, r.items.filter((i) => i.selected))
+ * ```
+ */
+import { reclaimable, type Reclaimable, type ReclaimableOptions } from '../reclaim.js'
+import { resolve, type ShortcutOptions } from '../shortcuts.js'
+
+export {
+  buildReclaim,
+  reclaim,
+  reclaimable,
+  simulateReclaim,
+  type BuildReclaimOptions,
+  type JunkContext,
+  type ReclaimBlocker,
+  type ReclaimCall,
+  type ReclaimCallResult,
+  type ReclaimItem,
+  type ReclaimKind,
+  type ReclaimOptions,
+  type ReclaimPlan,
+  type ReclaimableOptions,
+  type ReclaimQuery,
+  type ReclaimResult,
+  type ReclaimSimulation,
+  type ReclaimSimulationOptions,
+  type Reclaimable,
+} from '../reclaim.js'
+export type { PlanSimulation } from '../batchPlan.js'
+export { burnChecked, closeAccount, harvestWithheldTokensToMint } from '../write/instructions.js'
+
+export interface GetReclaimableOptions extends ReclaimableOptions, ShortcutOptions {}
+
+/**
+ * 扫描钱包里能回收租金的账户，节点参数与 getBalances 相同。默认列出全部代币账户（需要支持 getTokenAccountsByOwner 的节点），
+ * 免费公共节点传 `mints` 只看指定代币的 ATA。
+ *
+ * ```ts
+ * const r = await getReclaimable(owner, { provider: 'https://my-rpc…' })
+ * // { totalLamports: '45862080', selectedLamports: '41302080',
+ * //   items: [{ kind: 'empty-token', account, mint, lamports: '2039280', selected: true, reasons: ['empty'] },
+ * //           { kind: 'junk-token', symbol: 'claim-rewards.xyz', lamports: '2039280', selected: true, reasons: ['no-price', 'spam-name'] }, …],
+ * //   blocked: [{ kind: 'empty-token', blocker: 'frozen', … }] }
+ * ```
+ */
+export function getReclaimable(owner: string, options: GetReclaimableOptions = {}): Promise<Reclaimable> {
+  const { client, own } = resolve(options, ['mints', 'junk', 'positions', 'prices', 'maxJunkUsd', 'risk', 'isJunk', 'signal'])
+  return reclaimable(client, owner, { ...own, ...(options.fetch ? { fetch: options.fetch } : {}) })
+}

package/src/subpaths/simulate.ts

@@ -0,0 +1,37 @@
+/**
+ * 交易模拟（子路径 `@w3lib/solana-batch-call/simulate`）：不签名、不发送，在主网模拟一笔交易，给出余额变化、授权变化（delegate / SetAuthority / 关闭账户）、
+ * 指令说明、程序错误、手续费和警告。输入可以是 base64 的交易，也可以直接是本库构建器的输出。不放在主入口，不用时打包不会带上这部分代码；价格、风险检查按需加载。
+ *
+ * ```ts
+ * import { buildSwap } from '@w3lib/solana-batch-call/swap'
+ * import { getSimulation } from '@w3lib/solana-batch-call/simulate'
+ *
+ * const plan = await getSwapQuote(owner, { tokenIn: NATIVE_MINT, tokenOut: USDC, amountInFormatted: '0.5' })
+ * const sim = await getSimulation(plan)            // 或 getSimulation(base64Tx, { owner })
+ * if (!sim.success || sim.warnings.some((w) => w.severity === 'danger')) throw new Error(sim.error ?? sim.warnings[0].message)
+ * ```
+ */
+import { resolve, type ShortcutOptions } from '../shortcuts.js'
+import { simulate, type SimulateInput, type SimulateOptions, type SimulationResult } from '../simulate.js'
+
+export {
+  failureText,
+  simulate,
+  type ApprovalChange,
+  type ApprovalChangeKind,
+  type SimulateInput,
+  type SimulateOptions,
+  type SimulatedBalanceChange,
+  type SimulationResult,
+  type SimulationWarning,
+  type WarningSeverity,
+} from '../simulate.js'
+export { decodeInstruction, type DecodedInstruction } from '../decode.js'
+
+export interface GetSimulationOptions extends SimulateOptions, ShortcutOptions {}
+
+/** 模拟一笔交易，节点参数与 getBalances 相同 */
+export function getSimulation(input: SimulateInput, options: GetSimulationOptions = {}): Promise<SimulationResult> {
+  const { client, own } = resolve(options, ['owner', 'signers', 'watch', 'step', 'prices', 'risk', 'fetch', 'signal'])
+  return simulate(client, input, own)
+}

package/src/swap/index.ts

@@ -3,7 +3,7 @@
  * （直接兑换，或经过 SOL / USDC / USDT 的两跳），按链上状态在本地报价（照搬各程序的计算），选输出最多的；
  * 按滑点算最少收到的数量，构建指令（SOL 自动包装 / 解包、缺少的代币账户自动创建），发送同 /write
  */
-import { getAssociatedTokenAddress, isAddress } from '../address.js'
+import { getAssociatedTokenAddress, InvalidAddressError, isAddress } from '../address.js'
 import type { SolanaClient } from '../client.js'
 import { NATIVE_MINT, TOKEN_PROGRAM_ID } from '../constants.js'
 import { formatUnits, parseTokenAccount, type AccountInfo } from '../layout.js'
@@ -180,7 +180,7 @@ export async function buildSwap(client: SolanaClient, owner: string, params: Sol
   const tokenIn = nativeIn ? NATIVE_MINT : params.tokenIn
   const tokenOut = nativeOut ? NATIVE_MINT : params.tokenOut
   for (const mint of [tokenIn, tokenOut]) {
-    if (!isAddress(mint)) throw new Error(`Invalid mint address: ${mint}`)
+    if (!isAddress(mint)) throw new InvalidAddressError(`Invalid mint address: ${mint}`, mint)
   }
   if (tokenIn === tokenOut) throw new Error(nativeIn || nativeOut ? 'Wrapping / unwrapping SOL is not a swap' : 'tokenIn and tokenOut are the same')
   const protocols = new Set(options.protocols ?? SWAP_PROTOCOLS)
@@ -192,7 +192,7 @@ export async function buildSwap(client: SolanaClient, owner: string, params: Sol
     if (!isAddress(m)) throw new Error(`Invalid intermediate mint: ${m}`)
   }
   for (const p of options.pools ?? []) {
-    if (!isAddress(p)) throw new Error(`Invalid pool address: ${p}`)
+    if (!isAddress(p)) throw new InvalidAddressError(`Invalid pool address: ${p}`, p)
   }
 
   // 1. 一次读：候选池子（PDA 推导 + 传入的）、Clock、各代币的 mint

package/src/tokenDetails.ts

@@ -0,0 +1,240 @@
+// 代币详情（tokens）、NFT 元数据（nfts）、NFT 持有人（nftOwners）
+
+import type { AccountInfo, TransferFeeInfo } from './layout.js'
+import { getMetadataAddress, isAddress } from './address.js'
+import type { RequestOptions, TokensOptions } from './client.js'
+import { SOL_DECIMALS, TOKEN_2022_PROGRAM_ID } from './constants.js'
+import { formatUnits, parseTokenAccount, parseTransferFeeConfig } from './layout.js'
+import { RpcError } from './rpc.js'
+import type { ReadContext } from './balances.js'
+import type { QueryContext } from './accountReader.js'
+import { getMeta, learnMeta, safeParseMetaplex, safeParseMint } from './tokenMeta.js'
+import {
+  DEFAULT_TOKEN_FIELDS,
+  type FailureReason,
+  type NftDetails,
+  type NftOwner,
+  type TokenDetails,
+  type TokenField,
+  type TokenStandard,
+  type TransferFee,
+  type TransferFeeConfig,
+} from './types.js'
+
+const TOKEN_STANDARDS: readonly TokenStandard[] = [
+  'NonFungible',
+  'FungibleAsset',
+  'Fungible',
+  'NonFungibleEdition',
+  'ProgrammableNonFungible',
+  'ProgrammableNonFungibleEdition',
+]
+
+export async function tokensOf<F extends TokenField>(rc: ReadContext, mints: readonly string[], options: TokensOptions<F>): Promise<TokenDetails<F>[]> {
+  const fields = (options.fields ?? DEFAULT_TOKEN_FIELDS) as readonly F[]
+  const wanted = new Set<TokenField>(fields)
+  const scope = rc.scope
+  const ctx: QueryContext = { signal: options.signal }
+  const needsNames = wanted.has('name') || wanted.has('symbol') || wanted.has('uri')
+  const addresses: string[] = []
+  const plan = mints.map((mint) => {
+    if (rc.nativeMints.has(mint) || !isAddress(mint)) {
+      return { mint, mintIndex: -1, metadataIndex: -1 }
+    }
+    const meta = getMeta(scope, mint)
+    // uri / supply / 权限 / 手续费不缓存，需要时总要读 mint；name / symbol 命中缓存时可以省掉元数据账户
+    const cachedOnly =
+      !wanted.has('uri') &&
+      !wanted.has('supply') &&
+      !wanted.has('mintAuthority') &&
+      !wanted.has('freezeAuthority') &&
+      !wanted.has('transferFee') &&
+      (!wanted.has('decimals') || meta.decimals !== undefined) &&
+      (!wanted.has('tokenProgram') || meta.tokenProgram !== undefined) &&
+      (!wanted.has('name') || meta.name !== undefined) &&
+      (!wanted.has('symbol') || meta.symbol !== undefined)
+    if (cachedOnly) {
+      return { mint, mintIndex: -1, metadataIndex: -1 }
+    }
+    const namesCached = (!wanted.has('name') || meta.name !== undefined) && (!wanted.has('symbol') || meta.symbol !== undefined) && !wanted.has('uri')
+    return {
+      mint,
+      mintIndex: addresses.push(mint) - 1,
+      metadataIndex: needsNames && !namesCached ? addresses.push(getMetadataAddress(mint)) - 1 : -1,
+    }
+  })
+  const [accounts, epoch] = await Promise.all([
+    addresses.length ? rc.reader.accounts(addresses, ctx) : Promise.resolve([] as (AccountInfo | null)[]),
+    // 手续费按当前 epoch 选新 / 旧配置；和账户读取在同一个批量请求里
+    wanted.has('transferFee') && addresses.length
+      ? rc.reader.call<{ epoch: number | string }>(ctx, 'getEpochInfo', [{ commitment: rc.commitment }]).then((res) => BigInt(res.epoch))
+      : Promise.resolve(null),
+  ])
+
+  return plan.map(({ mint, mintIndex, metadataIndex }) => {
+    const native = rc.nativeMints.has(mint)
+    const values: Record<TokenField, unknown> & { exists: boolean } = native
+      ? { exists: true, name: 'Solana', symbol: 'SOL', uri: null, decimals: SOL_DECIMALS, supply: null, tokenProgram: null, mintAuthority: null, freezeAuthority: null, transferFee: null }
+      : tokenValues(
+          rc,
+          mint,
+          mintIndex === -1 ? null : (accounts[mintIndex] ?? null),
+          metadataIndex === -1 ? null : (accounts[metadataIndex] ?? null),
+          mintIndex !== -1,
+          mintIndex !== -1 && metadataIndex !== -1,
+          epoch,
+        )
+    const out: Record<string, unknown> = { address: mint, native }
+    let missing: F | undefined
+    for (const field of fields) {
+      out[field] = values[field] ?? null
+      // 权限为 null 表示没有权限、手续费为 null 表示没有手续费，都是有效值；主币没有 uri / supply / tokenProgram
+      const nullable =
+        field === 'mintAuthority' || field === 'freezeAuthority' || field === 'transferFee' || (native && (field === 'uri' || field === 'supply' || field === 'tokenProgram'))
+      if (out[field] === null && !nullable) {
+        missing ??= field
+      }
+    }
+    if (wanted.has('supply')) {
+      const supply = values.supply as string | null
+      const decimals = values.decimals as number | null
+      out.supplyFormatted = supply === null || decimals === null ? null : formatUnits(BigInt(supply), decimals)
+    }
+    const error: FailureReason | undefined = native
+      ? undefined
+      : !isAddress(mint)
+        ? 'invalid-address'
+        : !values.exists
+          ? accounts[mintIndex]
+            ? 'not-token'
+            : 'not-found'
+          : missing
+            ? 'missing-field'
+            : undefined
+    out.success = error === undefined
+    if (error) {
+      out.error = error
+      if (error === 'missing-field') {
+        out.errorField = missing
+      }
+    }
+    return out as TokenDetails<F>
+  })
+}
+
+function tokenValues(
+  rc: ReadContext,
+  mint: string,
+  mintAccount: AccountInfo | null,
+  metadataAccount: AccountInfo | null,
+  fetchedMint: boolean,
+  lookedForNames: boolean,
+  epoch: bigint | null,
+): Record<TokenField, unknown> & { exists: boolean } {
+  const scope = rc.scope
+  const meta = learnMeta(scope, mint, mintAccount, metadataAccount, lookedForNames)
+  const info = mintAccount ? safeParseMint(mintAccount) : null
+  const uri = info?.metadata?.uri ?? (metadataAccount ? (safeParseMetaplex(metadataAccount)?.uri ?? null) : null)
+  const feeConfig = info && mintAccount?.owner === TOKEN_2022_PROGRAM_ID ? parseTransferFeeConfig(mintAccount.data) : null
+  return {
+    // 读了 mint 账户就以它为准（不存在则 false）；没读说明请求的字段全部命中缓存
+    exists: fetchedMint ? info !== null : true,
+    name: meta.name ?? null,
+    symbol: meta.symbol ?? null,
+    uri,
+    decimals: meta.decimals ?? null,
+    supply: info ? info.supply.toString() : null,
+    tokenProgram: meta.tokenProgram ?? null,
+    mintAuthority: info?.mintAuthority ?? null,
+    freezeAuthority: info?.freezeAuthority ?? null,
+    transferFee: feeConfig ? toTransferFeeConfig(feeConfig.older, feeConfig.newer, epoch) : null,
+  }
+}
+
+function toTransferFee(fee: TransferFeeInfo): TransferFee {
+  return { basisPoints: fee.basisPoints, maximumFee: fee.maximumFee.toString(), epoch: fee.epoch.toString() }
+}
+
+/** 当前生效的配置：epoch >= newer.epoch 用 newer，否则 older；不知道当前 epoch 时按 newer */
+function toTransferFeeConfig(older: TransferFeeInfo, newer: TransferFeeInfo, epoch: bigint | null): TransferFeeConfig {
+  const current = epoch === null || epoch >= newer.epoch ? newer : older
+  return { ...toTransferFee(current), older: toTransferFee(older), newer: toTransferFee(newer) }
+}
+
+/** 批量查 NFT 元数据（Metaplex；Token-2022 NFT 取 TokenMetadata 扩展），一次 getMultipleAccounts */
+export async function nftsOf(rc: ReadContext, mints: readonly string[], options: RequestOptions): Promise<NftDetails[]> {
+  const scope = rc.scope
+  const addresses: string[] = []
+  const plan = mints.map((mint) =>
+    isAddress(mint) ? { mint, metadataIndex: addresses.push(getMetadataAddress(mint)) - 1, mintIndex: addresses.push(mint) - 1 } : { mint, metadataIndex: -1, mintIndex: -1 },
+  )
+  const accounts = addresses.length ? await rc.reader.accounts(addresses, { signal: options.signal }) : []
+  return plan.map(({ mint, metadataIndex, mintIndex }): NftDetails => {
+    const metadataAccount = metadataIndex === -1 ? null : (accounts[metadataIndex] ?? null)
+    const mintAccount = mintIndex === -1 ? null : (accounts[mintIndex] ?? null)
+    learnMeta(scope, mint, mintAccount, metadataAccount, mintIndex !== -1)
+    const metaplex = metadataAccount ? safeParseMetaplex(metadataAccount) : null
+    const ext = mintAccount ? (safeParseMint(mintAccount)?.metadata ?? null) : null
+    if (!metaplex && !ext) {
+      const error: FailureReason = mintIndex === -1 ? 'invalid-address' : !mintAccount ? 'not-found' : !safeParseMint(mintAccount) ? 'not-token' : 'no-metadata'
+      return { mint, name: null, symbol: null, uri: null, collection: null, creators: [], sellerFeeBasisPoints: null, tokenStandard: null, isMutable: null, updateAuthority: null, success: false, error }
+    }
+    return {
+      mint,
+      name: ext?.name ?? metaplex?.name ?? null,
+      symbol: ext?.symbol ?? metaplex?.symbol ?? null,
+      uri: ext?.uri ?? metaplex?.uri ?? null,
+      collection: metaplex?.collection ?? null,
+      creators: metaplex?.creators ?? [],
+      sellerFeeBasisPoints: metaplex?.sellerFeeBasisPoints ?? null,
+      tokenStandard: metaplex?.tokenStandard == null ? null : (TOKEN_STANDARDS[metaplex.tokenStandard] ?? null),
+      isMutable: metaplex?.isMutable ?? null,
+      updateAuthority: metaplex?.updateAuthority ?? null,
+      success: true,
+    }
+  })
+}
+
+/**
+ * 批量查 NFT 持有人：getTokenLargestAccounts（合并成一个批量请求）+ 一次 getMultipleAccounts。
+ * 节点拒绝的 mint（不存在 / 不是代币）在同一次 getMultipleAccounts 里读 mint 账户区分原因
+ */
+export async function nftOwnersOf(rc: ReadContext, mints: readonly string[], options: RequestOptions): Promise<NftOwner[]> {
+  const ctx: QueryContext = { signal: options.signal }
+  const largest = await Promise.all(
+    mints.map((mint): Promise<{ tokenAccount: string | null; rejected: boolean }> =>
+      isAddress(mint)
+        ? rc.reader.call<{ value: Array<{ address: string; amount: string }> }>(ctx, 'getTokenLargestAccounts', [mint, { commitment: rc.commitment }])
+            .then((res) => ({ tokenAccount: res.value.find((a) => a.amount !== '0')?.address ?? null, rejected: false }))
+            .catch((err: unknown) => {
+              // mint 不存在 / 不是代币：该项失败；节点问题照常抛出
+              if (err instanceof RpcError && !err.nodeFault) return { tokenAccount: null, rejected: true }
+              throw err
+            })
+        : Promise.resolve({ tokenAccount: null, rejected: false }),
+    ),
+  )
+  const toRead = largest.flatMap(({ tokenAccount, rejected }, i) => (tokenAccount ? [tokenAccount] : rejected ? [mints[i] as string] : []))
+  const accounts = toRead.length ? await rc.reader.accounts(toRead, ctx) : []
+  const byAddress = new Map(toRead.map((a, i) => [a, accounts[i] ?? null]))
+  return mints.map((mint, i): NftOwner => {
+    const { tokenAccount, rejected } = largest[i] ?? { tokenAccount: null, rejected: false }
+    if (!isAddress(mint)) {
+      return { mint, owner: null, tokenAccount: null, success: false, error: 'invalid-address' }
+    }
+    if (rejected) {
+      return { mint, owner: null, tokenAccount: null, success: false, error: byAddress.get(mint) ? 'not-token' : 'not-found' }
+    }
+    const account = tokenAccount ? byAddress.get(tokenAccount) : null
+    let owner: string | null = null
+    if (account) {
+      try {
+        owner = parseTokenAccount(account.data).owner
+      } catch {
+        owner = null
+      }
+    }
+    // 没有余额大于 0 的代币账户（供应量为 0 / 已销毁），或代币账户刚被关闭
+    return owner ? { mint, owner, tokenAccount, success: true } : { mint, owner: null, tokenAccount: null, success: false, error: 'no-holder' }
+  })
+}