@w3lib/solana-batch-call 0.2.1 → 0.3.0

package/src/lpMath.ts

@@ -0,0 +1,205 @@
+/**
+ * 集中流动性（Raydium CLMM / Orca Whirlpool）的定点数计算，与链上程序逐位一致（Q64.64，bigint）。
+ * 两个程序的 tick → 价格换算用的常量和步骤不同（结果在最后几位可能不同），各自照搬；
+ * 数量和手续费的公式两边相同：撤出流动性时向下取整，手续费增长按 u128 回绕相减。
+ */
+
+const Q64 = 1n << 64n
+const U128_MAX = (1n << 128n) - 1n
+const U64_MAX = (1n << 64n) - 1n
+
+export const MIN_TICK = -443636
+export const MAX_TICK = 443636
+
+function checkTick(tick: number): void {
+  if (!Number.isInteger(tick) || tick < MIN_TICK || tick > MAX_TICK) {
+    throw new RangeError(`Tick out of range: ${tick}`)
+  }
+}
+
+// raydium-clmm programs/amm/src/libraries/tick_math.rs（第 0 项对应 abs_tick & 0x1）
+const RAYDIUM_RATIOS = [
+  0xfffcb933bd6fb800n,
+  0xfff97272373d4000n,
+  0xfff2e50f5f657000n,
+  0xffe5caca7e10f000n,
+  0xffcb9843d60f7000n,
+  0xff973b41fa98e800n,
+  0xff2ea16466c9b000n,
+  0xfe5dee046a9a3800n,
+  0xfcbe86c7900bb000n,
+  0xf987a7253ac65800n,
+  0xf3392b0822bb6000n,
+  0xe7159475a2caf000n,
+  0xd097f3bdfd2f2000n,
+  0xa9f746462d9f8000n,
+  0x70d869a156f31c00n,
+  0x31be135f97ed3200n,
+  0x9aa508b5b85a500n,
+  0x5d6af8dedc582cn,
+  0x2216e584f5fan,
+]
+
+/** Raydium CLMM：tick → sqrt 价格（Q64.64） */
+export function raydiumSqrtPriceAtTick(tick: number): bigint {
+  checkTick(tick)
+  const abs = Math.abs(tick)
+  let ratio = abs & 1 ? (RAYDIUM_RATIOS[0] as bigint) : Q64
+  for (let i = 1; i < RAYDIUM_RATIOS.length; i++) {
+    if (abs & (1 << i)) {
+      ratio = (ratio * (RAYDIUM_RATIOS[i] as bigint)) >> 64n
+    }
+  }
+  return tick > 0 ? U128_MAX / ratio : ratio
+}
+
+// orca whirlpools programs/whirlpool/src/math/tick_math.rs：正 tick 用 Q96 常量，负 tick 用 Q64 常量
+const ORCA_POSITIVE = [
+  79232123823359799118286999567n,
+  79236085330515764027303304731n,
+  79244008939048815603706035061n,
+  79259858533276714757314932305n,
+  79291567232598584799939703904n,
+  79355022692464371645785046466n,
+  79482085999252804386437311141n,
+  79736823300114093921829183326n,
+  80248749790819932309965073892n,
+  81282483887344747381513967011n,
+  83390072131320151908154831281n,
+  87770609709833776024991924138n,
+  97234110755111693312479820773n,
+  119332217159966728226237229890n,
+  179736315981702064433883588727n,
+  407748233172238350107850275304n,
+  2098478828474011932436660412517n,
+  55581415166113811149459800483533n,
+  38992368544603139932233054999993551n,
+]
+const ORCA_NEGATIVE = [
+  18445821805675392311n,
+  18444899583751176498n,
+  18443055278223354162n,
+  18439367220385604838n,
+  18431993317065449817n,
+  18417254355718160513n,
+  18387811781193591352n,
+  18329067761203520168n,
+  18212142134806087854n,
+  17980523815641551639n,
+  17526086738831147013n,
+  16651378430235024244n,
+  15030750278693429944n,
+  12247334978882834399n,
+  8131365268884726200n,
+  3584323654723342297n,
+  696457651847595233n,
+  26294789957452057n,
+  37481735321082n,
+]
+
+/** Orca Whirlpool：tick → sqrt 价格（Q64.64） */
+export function orcaSqrtPriceAtTick(tick: number): bigint {
+  checkTick(tick)
+  if (tick >= 0) {
+    let ratio = tick & 1 ? (ORCA_POSITIVE[0] as bigint) : 1n << 96n
+    for (let i = 1; i < ORCA_POSITIVE.length; i++) {
+      if (tick & (1 << i)) {
+        ratio = (ratio * (ORCA_POSITIVE[i] as bigint)) >> 96n
+      }
+    }
+    return ratio >> 32n
+  }
+  const abs = -tick
+  let ratio = abs & 1 ? (ORCA_NEGATIVE[0] as bigint) : Q64
+  for (let i = 1; i < ORCA_NEGATIVE.length; i++) {
+    if (abs & (1 << i)) {
+      ratio = (ratio * (ORCA_NEGATIVE[i] as bigint)) >> 64n
+    }
+  }
+  return ratio
+}
+
+/**
+ * 撤出全部流动性能拿到的两种代币数量（向下取整）。两个程序都按当前 tick（不是价格）判断区间：
+ * tick < 下限只有 token0；tick ≥ 上限只有 token1；否则两种都有
+ */
+export function getAmountsForLiquidity(tick: number, sqrtPrice: bigint, sqrtLower: bigint, sqrtUpper: bigint, liquidity: bigint, tickLower: number, tickUpper: number): [bigint, bigint] {
+  if (liquidity === 0n) {
+    return [0n, 0n]
+  }
+  if (tick < tickLower) {
+    return [amount0Delta(sqrtLower, sqrtUpper, liquidity), 0n]
+  }
+  if (tick < tickUpper) {
+    return [amount0Delta(sqrtPrice, sqrtUpper, liquidity), amount1Delta(sqrtLower, sqrtPrice, liquidity)]
+  }
+  return [0n, amount1Delta(sqrtLower, sqrtUpper, liquidity)]
+}
+
+/** floor(L · 2^64 · (b − a) / (a · b)) */
+function amount0Delta(a: bigint, b: bigint, liquidity: bigint): bigint {
+  const [lo, hi] = a < b ? [a, b] : [b, a]
+  return lo === 0n ? 0n : ((liquidity << 64n) * (hi - lo)) / (lo * hi)
+}
+
+/** floor(L · (b − a) / 2^64) */
+function amount1Delta(a: bigint, b: bigint, liquidity: bigint): bigint {
+  const [lo, hi] = a < b ? [a, b] : [b, a]
+  return (liquidity * (hi - lo)) >> 64n
+}
+
+/** 一个 tick 上用于计算手续费的数据；Orca 的 tick 未初始化时 initialized 为 false */
+export interface TickFeeData {
+  initialized: boolean
+  feeGrowthOutside0: bigint
+  feeGrowthOutside1: bigint
+}
+
+const wrap = (x: bigint) => ((x % (1n << 128n)) + (1n << 128n)) % (1n << 128n)
+
+/**
+ * 区间内的手续费增长（u128 回绕）。Raydium 不区分是否初始化（未初始化的 tick 各项为 0，传 initialized: true 即可）；
+ * Orca 未初始化的 tick：下限按“下方增长 = 全局”、上限按“上方增长 = 0”处理（与程序一致）
+ */
+export function getFeeGrowthInside(
+  tick: number,
+  tickLower: number,
+  lower: TickFeeData,
+  tickUpper: number,
+  upper: TickFeeData,
+  global0: bigint,
+  global1: bigint,
+): [bigint, bigint] {
+  const below = !lower.initialized
+    ? [global0, global1]
+    : tick < tickLower
+      ? [wrap(global0 - lower.feeGrowthOutside0), wrap(global1 - lower.feeGrowthOutside1)]
+      : [lower.feeGrowthOutside0, lower.feeGrowthOutside1]
+  const above = !upper.initialized
+    ? [0n, 0n]
+    : tick < tickUpper
+      ? [upper.feeGrowthOutside0, upper.feeGrowthOutside1]
+      : [wrap(global0 - upper.feeGrowthOutside0), wrap(global1 - upper.feeGrowthOutside1)]
+  return [wrap(global0 - (below[0] as bigint) - (above[0] as bigint)), wrap(global1 - (below[1] as bigint) - (above[1] as bigint))]
+}
+
+/**
+ * 未领取的手续费：已记账的 owed + L · (区间内增长 − 上次记录) / 2^64（向下取整）。
+ * 新增部分超过 u64 时：Orca 程序记为 0（checked_mul_shift_right 失败），这里同样记为 0（正常仓位不会碰到）
+ */
+export function getFeesOwed(owed: bigint, liquidity: bigint, growthInside: bigint, growthLast: bigint): bigint {
+  const delta = (liquidity * wrap(growthInside - growthLast)) >> 64n
+  return owed + (delta > U64_MAX ? 0n : delta)
+}
+
+/** Q64.64 sqrt 价格 → token1 / token0 的价格（按精度换算，浮点数，只用于展示） */
+export function sqrtPriceToPrice(sqrtPrice: bigint, decimals0: number, decimals1: number): number {
+  // 先取高位再转浮点，避免 2^128 级别的整数转换丢精度后再平方
+  const ratio = Number(sqrtPrice) / 2 ** 64
+  return ratio * ratio * 10 ** (decimals0 - decimals1)
+}
+
+/** tick → token1 / token0 的价格（1.0001^tick，按精度换算，只用于展示） */
+export function tickToPrice(tick: number, decimals0: number, decimals1: number): number {
+  return 1.0001 ** tick * 10 ** (decimals0 - decimals1)
+}

package/src/rpc.ts

@@ -17,18 +17,49 @@ export class RpcError extends Error {
     this.name = 'RpcError'
     this.code = code
     this.data = data
+    const kind = classifyRpcError(code, message)
     this.nodeFault =
       code === 403 ||
-      code === 429 ||
       code === -32005 ||
-      // 节点高度没到 minContextSlot：换节点可能成功
-      code === MIN_CONTEXT_SLOT_NOT_REACHED ||
-      /minimum context slot/i.test(message) ||
-      (/forbidden|blocked|personal token|api.?key|rate.?limit|too many|not allowed|unauthori[sz]ed|limit exceeded|disabled|not available|not supported/i.test(message) &&
-        !TOO_MANY_ACCOUNTS.test(message))
+      // 节点高度没到 minContextSlot、限频、服务端临时故障（繁忙、过载、暂不可用、超时）：换节点可能成功；
+      // 临时故障也不应据此关闭批量（降级只会加重负载）
+      kind === 'min-slot' ||
+      kind === 'rate-limited' ||
+      kind === 'transient' ||
+      (/forbidden|blocked|personal token|api.?key|too many|not allowed|unauthori[sz]ed|limit exceeded|disabled|not available|not supported/i.test(message) &&
+        kind !== 'too-many-accounts')
   }
 }
 
+/**
+ * JSON-RPC 错误的分类（RpcError.nodeFault、HTTP 5xx 的处理共用，避免两份清单各自维护）：
+ * - method-limit / too-many-accounts：节点对批量 / 单次账户数的限制，按限制重新分批或缩小
+ * - invalid-params：参数错误（-32602），确定性的
+ * - min-slot / rate-limited / transient：节点落后、限频、服务端临时故障，换节点
+ * - internal：-32603 internal error，含义不明确（可能是临时故障，也可能是节点拒绝批量）
+ */
+type RpcErrorKind = 'method-limit' | 'too-many-accounts' | 'invalid-params' | 'min-slot' | 'rate-limited' | 'transient' | 'internal' | 'other'
+
+function classifyRpcError(code: number | undefined, message: string): RpcErrorKind {
+  if (METHOD_LIMIT.test(message)) return 'method-limit'
+  if (TOO_MANY_ACCOUNTS.test(message)) return 'too-many-accounts'
+  if (code === -32602) return 'invalid-params'
+  if (code === MIN_CONTEXT_SLOT_NOT_REACHED || /minimum context slot/i.test(message)) return 'min-slot'
+  if (code === 429 || RATE_LIMITED.test(message)) return 'rate-limited'
+  if (TRANSIENT.test(message)) return 'transient'
+  if (code === -32603) return 'internal'
+  return 'other'
+}
+
+/** 节点限制单个方法在批量里的数量（如 publicnode：“Maximum number of 'getMultipleAccounts' calls in a batch request is 1”） */
+const METHOD_LIMIT = /maximum number of '([^']+)' calls in a batch request is (\d+)/i
+
+/** 限频的报错 */
+const RATE_LIMITED = /rate.?limit|too many requests/i
+
+/** 服务端临时故障的报错（如 -32000 server is busy、-32603 + 503 overloaded） */
+const TRANSIENT = /\bbusy\b|overload|temporar(il)?y|unavailable|try again|timed? ?out|timeout/i
+
 /** 节点限制单次 getMultipleAccounts 的账户数（如 “Too many accounts requested”）：缩小每次的账户数后重试，不是节点故障 */
 const TOO_MANY_ACCOUNTS = /too many accounts/i
 
@@ -38,11 +69,15 @@ export class HttpError extends Error {
   /** 请求超时（HttpRpcOptions.timeout） */
   readonly timeout: boolean
 
-  constructor(message: string, status?: number, timeout = false) {
+  /** 5xx 的响应体是 JSON-RPC 错误（服务端故障，或节点用 5xx 拒绝批量请求） */
+  readonly rpcError: boolean
+
+  constructor(message: string, status?: number, timeout = false, rpcError = false) {
     super(message)
     this.name = 'HttpError'
     this.status = status
     this.timeout = timeout
+    this.rpcError = rpcError
   }
 }
 
@@ -262,7 +297,7 @@ export class HttpRpc implements RpcTransport {
    * 记下限制并按限制重新分批，返回 true；限制解析不出或这批本来就没超限（避免无限重发）时返回 false
    */
   async #retryWithMethodLimit(items: Pending[], message: string | undefined): Promise<boolean> {
-    const match = /maximum number of '([^']+)' calls in a batch request is (\d+)/i.exec(message ?? '')
+    const match = METHOD_LIMIT.exec(message ?? '')
     const method = match?.[1]
     const limit = Number(match?.[2])
     if (!method || !Number.isFinite(limit) || limit < 1 || items.filter((item) => item.method === method).length <= limit) {
@@ -273,7 +308,8 @@ export class HttpRpc implements RpcTransport {
     return true
   }
 
-  async #dispatch(items: Pending[]): Promise<void> {
+  /** retriedServerError：这一批已经因 5xx + JSON-RPC 错误重试过一次 */
+  async #dispatch(items: Pending[], retriedServerError = false): Promise<void> {
     if (items.length === 1 || !this.#batch) {
       await Promise.all(items.map((item) => this.#single(item)))
       return
@@ -296,6 +332,23 @@ export class HttpRpc implements RpcTransport {
         await Promise.all(items.map((item) => this.#single(item)))
         return
       }
+      // 5xx + -32603（含义不明确：临时故障，或节点用 5xx 拒绝批量）：先原样重试一次批量（偶发故障这次就成功了，不降级）；
+      // 仍然失败时只用第一条单独试探——成功说明是批量本身被拒，暂停批量（10 分钟后重试）并逐条发送其余的；
+      // 失败则是临时故障，其余的直接报错（换节点），不给出问题的节点加量
+      if (err instanceof HttpError && err.rpcError && items.length > 1) {
+        if (!retriedServerError) {
+          await this.#dispatch(items, true)
+          return
+        }
+        const [first, ...rest] = items as [Pending, ...Pending[]]
+        if (await this.#single(first)) {
+          this.#disableBatch()
+          await Promise.all(rest.map((item) => this.#single(item)))
+        } else {
+          rest.forEach((item) => item.reject(err))
+        }
+        return
+      }
       items.forEach((item) => item.reject(err))
       return
     }
@@ -322,7 +375,7 @@ export class HttpRpc implements RpcTransport {
     }
     const byId = new Map((body as RpcResponse[]).map((res) => [res.id, res]))
     // 有的节点把 “方法数量超限” 放在批量结果的某一项里
-    const methodLimited = (body as RpcResponse[]).find((res) => /maximum number of '[^']+' calls in a batch/i.test(res.error?.message ?? ''))
+    const methodLimited = (body as RpcResponse[]).find((res) => METHOD_LIMIT.test(res.error?.message ?? ''))
     if (methodLimited && (await this.#retryWithMethodLimit(items, methodLimited.error?.message))) {
       return
     }
@@ -363,12 +416,15 @@ export class HttpRpc implements RpcTransport {
     await Promise.all(this.#split(items).map((chunk) => this.#dispatch(chunk)))
   }
 
-  async #single(item: Pending, retries = this.#retries): Promise<void> {
+  /** 逐条发送一个调用；返回是否拿到了结果（没有出错） */
+  async #single(item: Pending, retries = this.#retries): Promise<boolean> {
     try {
       const body = (await this.#post({ jsonrpc: '2.0', id: nextId++, method: item.method, params: item.params }, retries)) as RpcResponse
       settle(item, body)
+      return !body?.error
     } catch (err) {
       item.reject(err)
+      return false
     }
   }
 
@@ -414,6 +470,16 @@ export class HttpRpc implements RpcTransport {
       if (!response.ok && !Array.isArray(body) && !(body as RpcResponse)?.error) {
         throw new HttpError(`HTTP ${response.status} from ${this.#safeUrl}`, response.status)
       }
+      // 5xx + 单个 JSON-RPC 错误：
+      // - 繁忙、过载等明确的临时故障：按 HTTP 错误处理，直接换节点（不重试、不逐条，不给过载的节点加量）
+      // - -32603 internal error：含义不明确，标记 rpcError，由 #dispatch 判断是临时故障还是节点用 5xx 拒绝批量
+      // 其他错误（方法数量超限、账户数超限、参数错误、minContextSlot、限频等）照常交给上层按类型处理
+      const bodyError = response.status >= 500 && !Array.isArray(body) ? (body as RpcResponse)?.error : undefined
+      const kind = bodyError ? classifyRpcError(bodyError.code, bodyError.message ?? '') : undefined
+      if (kind === 'transient' || kind === 'internal') {
+        const message = bodyError?.message
+        throw new HttpError(`HTTP ${response.status} from ${this.#safeUrl}${message ? `: ${message}` : ''}`, response.status, false, kind === 'internal')
+      }
       // 有的节点限频时返回 HTTP 200 + JSON-RPC 错误码 429：同样退避重试
       if (attempt < retries && isRateLimited(body)) {
         await new Promise((r) => setTimeout(r, 500 * 2 ** attempt))

package/src/shortcuts.ts

@@ -81,7 +81,7 @@ function sourceKey(source: ShortcutOptions['provider']): string | object | null
  * 拆出节点参数和函数自己的参数（ownKeys），其余作为客户端配置；值为 undefined 的参数忽略。
  * signal 总是作为函数自己的参数（放进客户端配置会让每次调用都新建客户端）
  */
-function resolve<T extends ShortcutOptions, K extends keyof T & string = never>(
+export function resolve<T extends ShortcutOptions, K extends keyof T & string = never>(
   options: T,
   ownKeys: readonly K[] = [],
 ): { client: SolanaClient; own: Pick<T, K> } {

package/src/subpaths/lp.ts

@@ -0,0 +1,62 @@
+/**
+ * LP 仓位（子路径 `@w3lib/solana-batch-call/lp`）：Raydium CLMM / Orca Whirlpool 的仓位 NFT，Raydium AMM v4 / CPMM 的 LP 代币，
+ * 代币数量、未领取的手续费、可选的美元价值。不放在主入口，不用时打包不会带上这部分代码。
+ *
+ * ```ts
+ * import { getLpPositions } from '@w3lib/solana-batch-call/lp'
+ *
+ * await getLpPositions(owner, { provider: 'https://my-rpc…' })                  // 扫描全部代币账户（需要支持 getTokenAccountsByOwner 的节点）
+ * await getLpPositions(owner, { mints: [positionNftMint], prices: true })        // 只看这些代币：免费公共节点也能用
+ * ```
+ */
+import { lpPositions, type LpPositionsOptions, type SolanaLpPosition } from '../lp.js'
+import { resolve, type ShortcutOptions } from '../shortcuts.js'
+
+export {
+  ORCA_WHIRLPOOL_PROGRAM_ID,
+  RAYDIUM_AMM_PROGRAM_ID,
+  RAYDIUM_CLMM_PROGRAM_ID,
+  RAYDIUM_CPMM_PROGRAM_ID,
+  SOLANA_LP_PROTOCOLS,
+  defillamaPrices,
+  lpPositions,
+  type LpPositionsOptions,
+  type SolanaLpAmmPosition,
+  type SolanaLpClmmPosition,
+  type SolanaLpPosition,
+  type SolanaLpProtocol,
+  type SolanaLpToken,
+  type SolanaPriceSource,
+} from '../lp.js'
+export {
+  MAX_TICK,
+  MIN_TICK,
+  getAmountsForLiquidity,
+  getFeeGrowthInside,
+  getFeesOwed,
+  orcaSqrtPriceAtTick,
+  raydiumSqrtPriceAtTick,
+  sqrtPriceToPrice,
+  tickToPrice,
+  type TickFeeData,
+} from '../lpMath.js'
+
+export interface GetLpPositionsOptions extends LpPositionsOptions, ShortcutOptions {}
+
+/**
+ * 查一个地址的 LP 仓位。
+ *
+ * ```ts
+ * await getLpPositions(owner, { provider: 'https://my-rpc…' })
+ * // [{ type: 'clmm', protocol: 'raydium-clmm', pool, positionMint, token0: { symbol: 'SOL', … }, token1: { symbol: 'USDC', … },
+ * //    amount0Formatted: '140.26', amount1Formatted: '6852.2', fees0Formatted: '0.546', fees1Formatted: '59.5', inRange: true, … },
+ * //  { type: 'amm', protocol: 'raydium-amm', pool, lpMint, balance, share: 0.18, amount0Formatted, amount1Formatted, … }]
+ * await getLpPositions(owner, { mints: [nftMint, lpMint], pools: [ammPool] })   // 免费公共节点：指定代币和池子
+ * await getLpPositions(owner, { provider, prices: true })                        // 带美元价值（DefiLlama），按价值排序
+ * ```
+ */
+export function getLpPositions(owner: string, options: GetLpPositionsOptions = {}): Promise<SolanaLpPosition[]> {
+  // fetch 同时给节点请求（客户端配置）和查价用，与其他快捷函数一致
+  const { client, own } = resolve(options, ['protocols', 'mints', 'pools', 'includeClosed', 'prices', 'onPriceError', 'signal'])
+  return lpPositions(client, owner, { ...own, ...(options.fetch ? { fetch: options.fetch } : {}) })
+}

package/src/subpaths/write.ts

@@ -0,0 +1,29 @@
+/**
+ * 批量写操作（子路径 `@w3lib/solana-batch-call/write`）：批量调用程序、一对多转账、多钱包归集。
+ * 不放在主入口，只做查询时打包不会带上这部分代码。不依赖 Solana SDK，签名用运行环境的 WebCrypto（Ed25519）。
+ *
+ * ```ts
+ * import { SolanaClient, NATIVE_MINT } from '@w3lib/solana-batch-call'
+ * import { batchCall, batchCollect, batchTransfer } from '@w3lib/solana-batch-call/write'
+ *
+ * const client = new SolanaClient(rpcUrl)
+ * await batchTransfer(client, secretKey, [{ to: a, formatted: '0.5' }, { to: b, token: USDC, formatted: '20' }])
+ * await batchCollect(client, [key1, key2], hotWallet, { tokens: [USDC, NATIVE_MINT], feePayer: gasKey })
+ * await batchCall(client, [{ from: key1, instructions: [ix1, ix2] }])
+ * ```
+ */
+export { batchCall, type BatchCallMode, type BatchCallOptions, type WriteCall } from '../write/batch.js'
+export { batchCollect, type BatchCollectOptions, type CollectItemResult, type CollectResult } from '../write/collect.js'
+export { batchTransfer, type BatchTransferOptions, type TransferItem, type TransferMode, type TransferResult } from '../write/transfer.js'
+export {
+  COMPUTE_BUDGET_PROGRAM_ID,
+  closeAccount,
+  createAssociatedTokenAccountIdempotent,
+  setComputeUnitLimit,
+  setComputeUnitPrice,
+  systemTransfer,
+  transferChecked,
+} from '../write/instructions.js'
+export type { SendOptions, WriteResult, WriteStatus } from '../write/send.js'
+export type { SignerInput, WriteSigner } from '../write/signer.js'
+export type { AccountMeta, Instruction, InstructionInput } from '../write/transaction.js'

package/src/write/batch.ts

@@ -0,0 +1,78 @@
+import type { SolanaClient } from '../client.js'
+import { emptyOutcome, sendUnits, toWriteResult, type SendOptions, type Unit, type WriteResult } from './send.js'
+import { resolveSigner, type SignerInput } from './signer.js'
+import { COMPUTE_BUDGET_PROGRAM_ID } from './instructions.js'
+import { normalizeInstruction, type InstructionInput } from './transaction.js'
+
+/** 一个写调用：一组要原子执行的指令 */
+export interface WriteCall {
+  /** 发送的钱包（指令里的签名者之一）；不传 feePayer 时也由它付手续费 */
+  from: SignerInput
+  /** 指令：@solana/web3.js 的 TransactionInstruction、@solana/kit 的 Instruction 或本库格式，一个或多个 */
+  instructions: InstructionInput | readonly InstructionInput[]
+  /** 指令需要的其他签名者（如新建账户的 Keypair） */
+  signers?: readonly SignerInput[]
+}
+
+/**
+ * - 'pack'（默认）：同一手续费支付者的相邻调用打包进同一笔交易（不超过 1232 字节、64 个账户），
+ *   模拟时失败的调用会被剔除、其余照常发送；同一笔交易上链后才失败时一起回滚
+ * - 'tx'：每个调用一笔交易
+ */
+export type BatchCallMode = 'pack' | 'tx'
+
+export interface BatchCallOptions extends SendOptions {
+  mode?: BatchCallMode
+  /** 'pack' 时每笔交易最多几个调用，默认不限（只受交易大小限制） */
+  batchSize?: number
+  /**
+   * 某个调用发送前失败（模拟失败等）后，同一支付者后面的调用是否继续。默认 false（后面的标记为 skipped）。
+   * 交易不等上一笔确认就连续发出，已经发出、之后上链失败的交易拦不住后面已发出的交易
+   */
+  continueOnError?: boolean
+}
+
+/**
+ * 批量调用程序（写操作）。结果与 calls 一一对应。
+ *
+ * ```ts
+ * await batchCall(client, [
+ *   { from: key1, instructions: [ix1, ix2] },   // 同一个调用里的指令原子执行
+ *   { from: key2, instructions: ix3 },
+ * ], { feePayer: gasKey })                       // 手续费都由 gasKey 付，不同钱包的调用也能打包进同一笔交易
+ * ```
+ */
+export async function batchCall(client: SolanaClient, calls: readonly WriteCall[], options: BatchCallOptions = {}): Promise<WriteResult[]> {
+  const cache = new Map()
+  const feePayer = options.feePayer === undefined ? undefined : await resolveSigner(options.feePayer, cache)
+  const prepared = await Promise.all(
+    calls.map(async (call, i) => {
+      const from = await resolveSigner(call.from, cache)
+      const signers = [from, ...(await Promise.all((call.signers ?? []).map((s) => resolveSigner(s, cache))))]
+      const list = Array.isArray(call.instructions) ? (call.instructions as readonly InstructionInput[]) : [call.instructions as InstructionInput]
+      // 库会自动加计算单元上限和优先费用指令；调用里自带的同类指令去掉（重复会让整笔交易失败），优先费用用 priorityFee 选项
+      const instructions = list.map(normalizeInstruction).filter((ix) => !(ix.programId === COMPUTE_BUDGET_PROGRAM_ID && (ix.data[0] === 2 || ix.data[0] === 3)))
+      const payer = feePayer ?? from
+      const known = new Set([payer.address, ...signers.map((s) => s.address)])
+      const missing = instructions.flatMap((ix) => ix.keys).find((k) => k.isSigner && !known.has(k.pubkey))
+      if (missing) {
+        throw new Error(`calls[${i}]: an instruction requires the signature of ${missing.pubkey}; pass it in signers`)
+      }
+      return { from, signers, instructions, payer }
+    }),
+  )
+  const results = prepared.map((p, i) => toWriteResult(i, p.from.address, emptyOutcome('skipped')))
+  const units: Unit[] = prepared.map((p, i) => ({
+    instructions: p.instructions,
+    payer: p.payer,
+    signers: p.signers.filter((s) => s.address !== p.payer.address),
+    continueOnError: options.continueOnError,
+    onUpdate: (outcome) => {
+      results[i] = toWriteResult(i, p.from.address, outcome)
+      options.onUpdate?.(results[i] as WriteResult)
+    },
+  }))
+  await sendUnits(client, units, options, { batchSize: (options.mode ?? 'pack') === 'tx' ? 1 : options.batchSize })
+  return results
+}
+