@w3lib/solana-batch-call 0.2.2 → 0.4.0

package/src/write/signer.ts

@@ -0,0 +1,314 @@
+import { base58, base64urlnopad } from '@scure/base'
+
+import { encodeAddress } from '../address.js'
+import { messageSigners, serializeTransaction, splitTransaction } from './transaction.js'
+
+/**
+ * 自定义签名器：对交易消息做 ed25519 签名，返回 64 字节签名。用于 KMS / HSM / 硬件钱包，
+ * 或运行环境的 WebCrypto 不支持 Ed25519 时（如 React Native）自己用 @noble/curves 签名：
+ * `{ address, sign: async (msg) => ed25519.sign(msg, seed) }`
+ */
+export interface WriteSigner {
+  address: string
+  sign(message: Uint8Array): Promise<Uint8Array>
+}
+
+/** Wallet Standard 钱包（Phantom / Solflare / Backpack / OKX 等浏览器钱包都实现了）：`getWallets().get()` 拿到的对象 */
+export interface StandardWalletLike {
+  readonly accounts: ReadonlyArray<{ readonly address: string }>
+  readonly features: Readonly<Record<string, unknown>>
+}
+
+/** @solana/wallet-adapter 的 adapter（`useWallet().wallet.adapter`），或 `useWallet()` 的返回值 */
+export interface WalletAdapterLike {
+  readonly publicKey: { toBase58(): string } | null
+  readonly wallet?: StandardWalletLike | { readonly adapter?: unknown } | null
+}
+
+/** @solana/kit 里的交易（消息字节 + 各签名者的签名） */
+export interface KitTransactionLike {
+  readonly messageBytes: Uint8Array
+  readonly signatures: Readonly<Record<string, Uint8Array | null>>
+}
+
+/**
+ * @solana/kit 的 TransactionSigner：TransactionPartialSigner（signTransactions）或
+ * TransactionModifyingSigner（modifyAndSignTransactions，如 @solana/react 的 useWalletAccountTransactionSigner）。
+ * 也可以用它把不支持 Wallet Standard 的钱包接进来，见 README
+ */
+export interface KitSignerLike {
+  readonly address: string
+  signTransactions?(transactions: readonly KitTransactionLike[]): Promise<ReadonlyArray<Readonly<Record<string, Uint8Array>>>>
+  modifyAndSignTransactions?(transactions: readonly KitTransactionLike[]): Promise<readonly KitTransactionLike[]>
+}
+
+/**
+ * 发交易的钱包，以下都可以：
+ * - 私钥字符串：base58（Phantom 等钱包导出的 64 字节格式，或 32 字节种子），或 solana-keygen 生成的 JSON 数组 `"[12,34,…]"`
+ * - 私钥字节：Uint8Array（64 字节 secretKey 或 32 字节种子）
+ * - @solana/web3.js 的 Keypair（取 secretKey）
+ * - @solana/kit 的 KeyPairSigner（`{ address, keyPair }`，用它的 CryptoKey 签名）或其他 TransactionSigner
+ * - 自定义签名器 WriteSigner
+ * - 浏览器钱包：Wallet Standard 钱包对象（用第一个已连接的账户；指定账户传 `{ wallet, account }`）、
+ *   @solana/wallet-adapter 的 adapter 或 useWallet() 的返回值（钱包需支持 Wallet Standard，主流钱包都支持）。
+ *   同一批交易先全部模拟、再让钱包一次确认全部签名，然后发送
+ *
+ * 私钥只在本地用 WebCrypto 的 Ed25519 签名，错误信息里不会带出私钥内容
+ */
+export type SignerInput =
+  | string
+  | Uint8Array
+  | { secretKey: Uint8Array }
+  | { address: string; keyPair: CryptoKeyPair }
+  | WriteSigner
+  | StandardWalletLike
+  | { wallet: StandardWalletLike; account: { readonly address: string } | string }
+  | WalletAdapterLike
+  | KitSignerLike
+
+/** 本地签名器：直接对消息签名 */
+export interface LocalSigner {
+  kind: 'local'
+  address: string
+  sign(message: Uint8Array): Promise<Uint8Array>
+}
+
+/** 要外部钱包签的交易：消息 + 已有的签名（按 signers 顺序，没签的为 null） */
+export interface SignRequest {
+  message: Uint8Array
+  signers: readonly string[]
+  signatures: ReadonlyArray<Uint8Array | null>
+}
+
+/** 外部钱包签好的交易：钱包可能改了消息（如加了指令），signatures 按新消息的签名者顺序 */
+export interface SignedTransaction {
+  message: Uint8Array
+  signers: string[]
+  signatures: Array<Uint8Array | null>
+}
+
+/** 外部钱包：一次签多笔交易（只弹一次确认） */
+export interface WalletSigner {
+  kind: 'wallet'
+  address: string
+  /** chain：Wallet Standard 的链标识，如 'solana:mainnet'（网络未知时不传） */
+  signTransactions(requests: readonly SignRequest[], chain?: string): Promise<SignedTransaction[]>
+}
+
+/** 归一化后的签名器 */
+export type ResolvedSigner = LocalSigner | WalletSigner
+
+// PKCS#8 封装 ed25519 种子的固定前缀（RFC 8410）
+const PKCS8_PREFIX = Uint8Array.from([0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20])
+
+/** WebCrypto 的类型要求 ArrayBuffer 背书的视图 */
+const view = (bytes: Uint8Array) => bytes as Uint8Array<ArrayBuffer>
+
+function subtle(): SubtleCrypto {
+  const s = globalThis.crypto?.subtle
+  if (!s) {
+    throw new Error('WebCrypto is not available in this runtime; pass a signer with sign(message) instead of a private key')
+  }
+  return s
+}
+
+/** 用 32 字节种子生成签名器：私钥导入 WebCrypto 后不可导出 */
+async function fromSeed(seed: Uint8Array, expected?: Uint8Array): Promise<ResolvedSigner> {
+  // 没有 WebCrypto 时直接给出这个原因（放在 try 外面，不被下面统一改写成“私钥不对”）
+  const crypto = subtle()
+  const pkcs8 = new Uint8Array(48)
+  pkcs8.set(PKCS8_PREFIX)
+  pkcs8.set(seed, 16)
+  let address: string
+  let key: CryptoKey
+  try {
+    // 先以可导出方式导入一次取公钥（JWK 的 x），再以不可导出方式导入用于签名
+    const extractable = await crypto.importKey('pkcs8', pkcs8, { name: 'Ed25519' }, true, ['sign'])
+    const jwk = await crypto.exportKey('jwk', extractable)
+    const publicKey = base64urlnopad.decode(jwk.x as string)
+    address = encodeAddress(publicKey)
+    if (expected && encodeAddress(expected) !== address) {
+      throw new Error('mismatch')
+    }
+    key = await crypto.importKey('pkcs8', pkcs8, { name: 'Ed25519' }, false, ['sign'])
+  } catch (err) {
+    if ((err as Error).message === 'mismatch') {
+      throw new Error('Invalid private key: the public key part does not match')
+    }
+    if ((err as Error).name === 'NotSupportedError' || /algorithm|not supported|unrecognized/i.test((err as Error).message)) {
+      throw new Error('Ed25519 is not supported by this runtime’s WebCrypto; pass a signer with sign(message) instead of a private key')
+    }
+    throw new Error('Invalid private key')
+  } finally {
+    pkcs8.fill(0)
+  }
+  return { kind: 'local', address, sign: async (message) => new Uint8Array(await subtle().sign('Ed25519', key, view(message))) }
+}
+
+function fromBytes(bytes: Uint8Array): Promise<ResolvedSigner> {
+  if (bytes.length === 64) {
+    return fromSeed(bytes.slice(0, 32), bytes.slice(32))
+  }
+  if (bytes.length === 32) {
+    return fromSeed(bytes.slice())
+  }
+  throw new Error('Invalid private key: expected 64 or 32 bytes')
+}
+
+function parseKeyString(value: string): Uint8Array {
+  const text = value.trim()
+  if (text.startsWith('[')) {
+    try {
+      const parsed = JSON.parse(text) as unknown
+      if (Array.isArray(parsed) && parsed.every((n) => Number.isInteger(n) && n >= 0 && n <= 255)) {
+        return Uint8Array.from(parsed as number[])
+      }
+    } catch {
+      // 下面统一报错
+    }
+    throw new Error('Invalid private key: expected a JSON array of bytes')
+  }
+  let bytes: Uint8Array
+  try {
+    bytes = base58.decode(text)
+  } catch {
+    throw new Error('Invalid private key: expected base58 or a JSON array of bytes')
+  }
+  // 32 字节的 base58 字符串和地址长得一样：传错成地址时会悄悄变成另一个钱包，这里不接受（32 字节种子请传 Uint8Array）
+  if (bytes.length === 32) {
+    throw new Error('Invalid private key: a 32-byte base58 string looks like an address; pass the 64-byte secret key (or the seed as a Uint8Array)')
+  }
+  return bytes
+}
+
+async function toSigner(input: SignerInput): Promise<ResolvedSigner> {
+  if (typeof input === 'string') {
+    return fromBytes(parseKeyString(input))
+  }
+  if (input instanceof Uint8Array) {
+    return fromBytes(input)
+  }
+  if (!input || typeof input !== 'object') {
+    throw new Error(INVALID_SIGNER)
+  }
+  const o = input as Record<string, unknown>
+  if (o.secretKey instanceof Uint8Array) {
+    return fromBytes(o.secretKey)
+  }
+  const keyPair = o.keyPair as CryptoKeyPair | undefined
+  if (keyPair?.privateKey && typeof o.address === 'string') {
+    const key = keyPair.privateKey
+    return { kind: 'local', address: o.address, sign: async (message) => new Uint8Array(await subtle().sign('Ed25519', key, view(message))) }
+  }
+  if (typeof o.sign === 'function' && typeof o.address === 'string') {
+    const signer = input as WriteSigner
+    return { kind: 'local', address: signer.address, sign: (message) => signer.sign(message) }
+  }
+  // Wallet Standard 钱包
+  if (isStandardWallet(input)) {
+    return fromStandardWallet(input, undefined)
+  }
+  // { wallet, account }
+  if (isStandardWallet(o.wallet) && (typeof o.account === 'string' || typeof (o.account as { address?: unknown } | undefined)?.address === 'string')) {
+    return fromStandardWallet(o.wallet, typeof o.account === 'string' ? o.account : (o.account as { address: string }).address)
+  }
+  // wallet-adapter：adapter.wallet 是 Wallet Standard 钱包；useWallet() 的返回值是 { wallet: { adapter }, publicKey }
+  if ('publicKey' in o) {
+    const publicKey = (o.publicKey as { toBase58?: () => string } | null)?.toBase58?.()
+    const adapter = (o.wallet as { adapter?: Record<string, unknown> } | null | undefined)?.adapter ?? o
+    const standard = adapter.wallet
+    if (!publicKey) {
+      throw new Error('Wallet is not connected')
+    }
+    if (isStandardWallet(standard)) {
+      return fromStandardWallet(standard, publicKey)
+    }
+    throw new Error("This wallet adapter doesn't support Wallet Standard; wrap it as { address, signTransactions } (see README)")
+  }
+  // @solana/kit 的 TransactionSigner
+  if (typeof o.address === 'string' && (typeof o.signTransactions === 'function' || typeof o.modifyAndSignTransactions === 'function')) {
+    return fromKitSigner(input as KitSignerLike)
+  }
+  throw new Error(INVALID_SIGNER)
+}
+
+const INVALID_SIGNER = 'Invalid signer: expected a private key, a Keypair, a KeyPairSigner, { address, sign }, a browser wallet or a TransactionSigner'
+
+const SIGN_FEATURE = 'solana:signTransaction'
+
+function isStandardWallet(value: unknown): value is StandardWalletLike {
+  const features = (value as { features?: Record<string, unknown> } | null | undefined)?.features
+  return Boolean(features && typeof features === 'object' && SIGN_FEATURE in features && Array.isArray((value as { accounts?: unknown }).accounts))
+}
+
+/** 同一个钱包的签名请求排队：钱包同时只能处理一个确认窗口 */
+const queues = new WeakMap<object, Promise<unknown>>()
+
+function queued<T>(owner: object, task: () => Promise<T>): Promise<T> {
+  const previous = queues.get(owner) ?? Promise.resolve()
+  const run = previous.then(task, task)
+  queues.set(
+    owner,
+    run.catch(() => {}),
+  )
+  return run
+}
+
+interface StandardSignFeature {
+  signTransaction(...inputs: Array<{ account: unknown; transaction: Uint8Array; chain?: string }>): Promise<ReadonlyArray<{ signedTransaction: Uint8Array }>>
+}
+
+function fromStandardWallet(wallet: StandardWalletLike, address: string | undefined): WalletSigner {
+  const account = address === undefined ? wallet.accounts[0] : wallet.accounts.find((a) => a.address === address)
+  if (!account) {
+    throw new Error(address === undefined ? 'Wallet is not connected (no accounts)' : `Wallet account ${address} is not connected`)
+  }
+  const feature = wallet.features[SIGN_FEATURE] as StandardSignFeature
+  return {
+    kind: 'wallet',
+    address: account.address,
+    signTransactions: (requests, chain) =>
+      queued(wallet, async () => {
+        const outputs = await feature.signTransaction(
+          ...requests.map((r) => ({ account, transaction: serializeTransaction({ bytes: r.message, signers: [...r.signers] }, r.signatures), ...(chain ? { chain } : {}) })),
+        )
+        if (outputs.length !== requests.length) {
+          throw new Error('Wallet returned a different number of transactions')
+        }
+        return outputs.map((o) => {
+          const { signatures, message } = splitTransaction(o.signedTransaction)
+          return { message, signers: messageSigners(message), signatures: signatures.map((sig) => (sig.some((b) => b !== 0) ? sig : null)) }
+        })
+      }),
+  }
+}
+
+function fromKitSigner(signer: KitSignerLike): WalletSigner {
+  const toKit = (r: SignRequest): KitTransactionLike => ({ messageBytes: r.message, signatures: Object.fromEntries(r.signers.map((s, i) => [s, r.signatures[i] ?? null])) })
+  return {
+    kind: 'wallet',
+    address: signer.address,
+    signTransactions: (requests) =>
+      queued(signer, async () => {
+        if (typeof signer.modifyAndSignTransactions === 'function') {
+          const signed = await signer.modifyAndSignTransactions(requests.map(toKit))
+          return signed.map((t) => {
+            const signers = messageSigners(t.messageBytes)
+            return { message: t.messageBytes, signers, signatures: signers.map((s) => t.signatures[s] ?? null) }
+          })
+        }
+        const dictionaries = await (signer.signTransactions as NonNullable<KitSignerLike['signTransactions']>)(requests.map(toKit))
+        return requests.map((r, k) => ({ message: r.message, signers: [...r.signers], signatures: r.signers.map((s, i) => dictionaries[k]?.[s] ?? r.signatures[i] ?? null) }))
+      }),
+  }
+}
+
+/** 归一化钱包；同一个输入只解析一次（cache 由调用方按批次传入） */
+export function resolveSigner(input: SignerInput, cache: Map<unknown, Promise<ResolvedSigner>> = new Map()): Promise<ResolvedSigner> {
+  let resolved = cache.get(input)
+  if (!resolved) {
+    resolved = toSigner(input)
+    cache.set(input, resolved)
+  }
+  return resolved
+}

package/src/write/transaction.ts

@@ -0,0 +1,181 @@
+import { decodeAddress, encodeAddress } from '../address.js'
+
+/** 交易里的一个账户 */
+export interface AccountMeta {
+  pubkey: string
+  isSigner: boolean
+  isWritable: boolean
+}
+
+/** 一条指令（本库内部格式） */
+export interface Instruction {
+  programId: string
+  keys: AccountMeta[]
+  data: Uint8Array
+}
+
+type AddressLike = string | { toBase58(): string }
+
+/**
+ * 可以传入的指令格式：
+ * - @solana/web3.js 的 TransactionInstruction（`{ programId: PublicKey, keys: [{ pubkey, isSigner, isWritable }], data: Buffer }`）
+ * - @solana/kit 的 Instruction（`{ programAddress, accounts: [{ address, role }], data }`）
+ * - 本库的 Instruction（地址都是 base58 字符串）
+ */
+export type InstructionInput =
+  | { programId: AddressLike; keys: ReadonlyArray<{ pubkey: AddressLike; isSigner: boolean; isWritable: boolean }>; data?: Uint8Array }
+  | { programAddress: string; accounts?: ReadonlyArray<{ address: string; role: number }>; data?: Uint8Array }
+
+/** 单笔交易序列化后的大小上限（字节） */
+export const PACKET_DATA_SIZE = 1232
+
+/** 单笔交易最多锁定的账户数 */
+export const MAX_ACCOUNT_LOCKS = 64
+
+function toAddress(value: AddressLike): string {
+  return typeof value === 'string' ? value : value.toBase58()
+}
+
+/** 统一成本库的指令格式；地址非法时抛错 */
+export function normalizeInstruction(input: InstructionInput): Instruction {
+  if ('programAddress' in input) {
+    // @solana/kit 的 AccountRole：0 只读、1 可写、2 只读签名、3 可写签名
+    const keys = (input.accounts ?? []).map((a) => ({ pubkey: a.address, isSigner: a.role >= 2, isWritable: (a.role & 1) === 1 }))
+    return checked({ programId: input.programAddress, keys, data: input.data ?? new Uint8Array() })
+  }
+  const keys = input.keys.map((k) => ({ pubkey: toAddress(k.pubkey), isSigner: k.isSigner, isWritable: k.isWritable }))
+  return checked({ programId: toAddress(input.programId), keys, data: input.data ? new Uint8Array(input.data) : new Uint8Array() })
+}
+
+function checked(ix: Instruction): Instruction {
+  decodeAddress(ix.programId)
+  ix.keys.forEach((k) => decodeAddress(k.pubkey))
+  return ix
+}
+
+function compactU16(n: number): number[] {
+  const out: number[] = []
+  let rest = n
+  for (;;) {
+    const byte = rest & 0x7f
+    rest >>= 7
+    if (rest === 0) {
+      out.push(byte)
+      return out
+    }
+    out.push(byte | 0x80)
+  }
+}
+
+/** 编译好的消息（legacy 格式） */
+export interface CompiledMessage {
+  /** 要签名的消息字节 */
+  bytes: Uint8Array
+  /** 需要签名的地址，按交易里的签名顺序（第一个是手续费支付者） */
+  signers: string[]
+  /** 所有账户（去重后） */
+  accountKeys: string[]
+  /** 可写账户（查优先费用时用） */
+  writable: string[]
+}
+
+/**
+ * 编译 legacy 消息：账户按 [可写签名, 只读签名, 可写非签名, 只读非签名] 排序，手续费支付者排第一；
+ * 同一账户在多条指令里出现时，签名 / 可写取并集
+ */
+export function compileMessage(payer: string, instructions: readonly Instruction[], blockhash: string): CompiledMessage {
+  const metas = new Map<string, { signer: boolean; writable: boolean; order: number }>()
+  const add = (pubkey: string, signer: boolean, writable: boolean) => {
+    const meta = metas.get(pubkey)
+    if (meta) {
+      meta.signer ||= signer
+      meta.writable ||= writable
+    } else {
+      metas.set(pubkey, { signer, writable, order: metas.size })
+    }
+  }
+  add(payer, true, true)
+  for (const ix of instructions) {
+    ix.keys.forEach((k) => add(k.pubkey, k.isSigner, k.isWritable))
+    add(ix.programId, false, false)
+  }
+  const rank = (m: { signer: boolean; writable: boolean }) => (m.signer ? (m.writable ? 0 : 1) : m.writable ? 2 : 3)
+  const keys = [...metas.entries()].sort(([a, x], [b, y]) => (a === payer ? -1 : b === payer ? 1 : rank(x) - rank(y) || x.order - y.order)).map(([key]) => key)
+  const index = new Map(keys.map((k, i) => [k, i]))
+  const count = (r: number) => keys.filter((k) => rank(metas.get(k) as { signer: boolean; writable: boolean }) === r).length
+  const signers = keys.filter((k) => metas.get(k)?.signer)
+
+  const out: number[] = [signers.length, count(1), count(3)]
+  out.push(...compactU16(keys.length))
+  keys.forEach((k) => out.push(...decodeAddress(k)))
+  out.push(...decodeAddress(blockhash))
+  out.push(...compactU16(instructions.length))
+  for (const ix of instructions) {
+    out.push(index.get(ix.programId) as number)
+    out.push(...compactU16(ix.keys.length))
+    ix.keys.forEach((k) => out.push(index.get(k.pubkey) as number))
+    out.push(...compactU16(ix.data.length))
+    out.push(...ix.data)
+  }
+  return { bytes: new Uint8Array(out), signers, accountKeys: keys, writable: keys.filter((k) => (metas.get(k) as { writable: boolean }).writable) }
+}
+
+/** 签名后的交易字节数（签名数 + 每个签名 64 字节 + 消息） */
+export function transactionSize(message: CompiledMessage): number {
+  return compactU16(message.signers.length).length + 64 * message.signers.length + message.bytes.length
+}
+
+/** 拼成完整的交易：signatures 与 message.signers 顺序一致；没有签名的位置填 0（模拟时用） */
+export function serializeTransaction(message: Pick<CompiledMessage, 'bytes' | 'signers'>, signatures: ReadonlyArray<Uint8Array | null>): Uint8Array {
+  const prefix = compactU16(message.signers.length)
+  const out = new Uint8Array(prefix.length + 64 * message.signers.length + message.bytes.length)
+  out.set(prefix, 0)
+  signatures.forEach((sig, i) => sig && out.set(sig, prefix.length + 64 * i))
+  out.set(message.bytes, prefix.length + 64 * message.signers.length)
+  return out
+}
+
+function readCompactU16(bytes: Uint8Array, offset: number): [value: number, next: number] {
+  let value = 0
+  let o = offset
+  for (let shift = 0; shift < 21; shift += 7) {
+    const b = bytes[o++]
+    if (b === undefined) throw new Error('Invalid transaction: truncated')
+    value |= (b & 0x7f) << shift
+    if (!(b & 0x80)) return [value, o]
+  }
+  throw new Error('Invalid transaction: bad length prefix')
+}
+
+/** 拆开完整交易：签名列表 + 消息字节 */
+export function splitTransaction(bytes: Uint8Array): { signatures: Uint8Array[]; message: Uint8Array } {
+  const [count, start] = readCompactU16(bytes, 0)
+  const signatures: Uint8Array[] = []
+  for (let i = 0; i < count; i++) {
+    signatures.push(bytes.slice(start + 64 * i, start + 64 * (i + 1)))
+  }
+  const message = bytes.slice(start + 64 * count)
+  if (signatures.some((s) => s.length !== 64) || message.length < 3) throw new Error('Invalid transaction: truncated')
+  return { signatures, message }
+}
+
+/** 消息里需要签名的地址（前 numRequiredSignatures 个账户），legacy 和 v0 消息都支持 */
+export function messageSigners(message: Uint8Array): string[] {
+  const versioned = ((message[0] as number) & 0x80) !== 0
+  const header = versioned ? 1 : 0
+  const required = message[header] as number
+  const [, keysStart] = readCompactU16(message, header + 3)
+  return Array.from({ length: required }, (_, i) => encodeAddress(message.slice(keysStart + 32 * i, keysStart + 32 * (i + 1))))
+}
+
+export function sameBytes(a: Uint8Array, b: Uint8Array): boolean {
+  return a.length === b.length && a.every((v, i) => v === b[i])
+}
+
+/** 消息里的 recent blockhash（legacy 和 v0 消息都支持） */
+export function messageBlockhash(message: Uint8Array): string {
+  const header = ((message[0] as number) & 0x80) !== 0 ? 1 : 0
+  const [keys, keysStart] = readCompactU16(message, header + 3)
+  const start = keysStart + 32 * keys
+  return encodeAddress(message.slice(start, start + 32))
+}

package/src/write/transfer.ts

@@ -0,0 +1,189 @@
+import { getAssociatedTokenAddress, isAddress } from '../address.js'
+import type { SolanaClient } from '../client.js'
+import { NATIVE_MINT, SOL_DECIMALS } from '../constants.js'
+import { formatUnits, parseUnits } from '../layout.js'
+import type { TokenBalance } from '../types.js'
+import { createAssociatedTokenAccountIdempotent, systemTransfer, transferChecked } from './instructions.js'
+import { emptyOutcome, sendUnits, toWriteResult, type SendOptions, type TxOutcome, type Unit, type WriteResult } from './send.js'
+import { resolveSigner, type ResolvedSigner, type SignerInput } from './signer.js'
+import type { Instruction } from './transaction.js'
+
+/** 一个收款项：amount（最小单位）和 formatted（按精度换算后，如 '1.5'）二选一 */
+export interface TransferItem {
+  /** 收款钱包地址（代币转到它的关联代币账户 ATA，没有时自动创建） */
+  to: string
+  /** 数量，最小单位（lamports / 代币最小单位），bigint 或十进制字符串 */
+  amount?: bigint | number | string
+  /** 按精度换算后的数量，如 '1.5'；小数位超过精度时报错（不四舍五入） */
+  formatted?: string
+  /** 这一项转的代币 mint，默认 options.token */
+  token?: string
+}
+
+/**
+ * - 'pack'（默认）：同一笔交易里打包多个收款人（Solana 原生支持一笔交易多条转账指令，不需要 Disperse 这样的合约），
+ *   按交易大小上限自动分笔；模拟失败的收款项（如收款账户被冻结）单独标记失败，其余照常发送
+ * - 'tx'：每个收款人一笔交易
+ */
+export type TransferMode = 'pack' | 'tx'
+
+export interface BatchTransferOptions extends SendOptions {
+  /** 默认转的代币 mint，默认原生 SOL（NATIVE_MINT）；每项也可以单独指定 token */
+  token?: string
+  mode?: TransferMode
+  /** 'pack' 时每笔交易最多几个收款人，默认不限（按交易大小，SOL 约 20 个一笔，代币约 10 个） */
+  batchSize?: number
+  /** 发送前检查余额够不够（按代币汇总），不够时抛错、什么都不发。默认 true（SOL 不含手续费和新建账户的租金） */
+  checkBalance?: boolean
+  /** 收款人没有该代币的 ATA 时自动创建（租金约 0.00204 SOL，由手续费支付者付）。默认 true；false 时这些收款项失败 */
+  createAccounts?: boolean
+}
+
+/** 单个收款项的结果 */
+export interface TransferResult extends WriteResult {
+  /** 收款钱包 */
+  to: string
+  token: string
+  native: boolean
+  /** 数量（最小单位） */
+  amount: string
+  /** 按精度换算后的数量 */
+  formatted: string
+  /** 是否为收款人新建了代币账户（这一项额外付了租金） */
+  createdAccount: boolean
+}
+
+/** 解析后的收款项 */
+interface Planned {
+  index: number
+  to: string
+  token: string
+  native: boolean
+  amount: bigint
+  decimals: number
+  tokenProgram: string | null
+}
+
+/**
+ * 一对多批量转账（SOL / SPL Token / Token-2022，可混合）。结果与 recipients 一一对应。
+ *
+ * ```ts
+ * await batchTransfer(client, privateKey, [
+ *   { to: a, formatted: '0.5' },                 // 默认代币（options.token，默认 SOL）
+ *   { to: b, token: USDC, formatted: '20' },     // 代币：收款人没有 ATA 时自动创建
+ * ])
+ * ```
+ */
+export async function batchTransfer(client: SolanaClient, from: SignerInput, recipients: readonly TransferItem[], options: BatchTransferOptions = {}): Promise<TransferResult[]> {
+  const cache = new Map()
+  const signer = await resolveSigner(from, cache)
+  const payer = options.feePayer === undefined ? signer : await resolveSigner(options.feePayer, cache)
+  const planned = await plan(client, signer.address, recipients, options)
+
+  // 收款人的 ATA 是否存在：一次 getMultipleAccounts
+  const atas = planned.map((p) => (p.native ? null : getAssociatedTokenAddress(p.to, p.token, p.tokenProgram as string)))
+  const needed = [...new Set(atas.filter((a): a is string => a !== null))]
+  const existing = new Set<string>()
+  if (needed.length) {
+    const accounts = await client.accounts(needed, { signal: options.signal })
+    needed.forEach((a, i) => accounts[i] && existing.add(a))
+  }
+
+  const results = planned.map((p) => toTransferResult(p, toWriteResult(p.index, signer.address, emptyOutcome('skipped')), false))
+  const units: Unit[] = []
+  /** 已经安排创建的 ATA：同一个收款人同一种代币有多项时只在第一项创建（后面的项在同一组里按顺序发送，模拟失败时会等前面的确认） */
+  const creating = new Set<string>()
+  planned.forEach((p, i) => {
+    const ata = atas[i] ?? null
+    const create = ata !== null && !existing.has(ata) && !creating.has(ata)
+    if (create) creating.add(ata)
+    if (create && options.createAccounts === false) {
+      results[i] = toTransferResult(p, toWriteResult(p.index, signer.address, emptyOutcome('failed', 'recipient has no token account (createAccounts is false)')), false)
+      return
+    }
+    units.push({
+      instructions: transferInstructions(signer, payer, p, ata, create),
+      payer,
+      signers: payer.address === signer.address ? [] : [signer],
+      continueOnError: true,
+      onUpdate: (outcome: TxOutcome) => {
+        results[i] = toTransferResult(p, toWriteResult(p.index, signer.address, outcome), create && outcome.status === 'confirmed')
+        options.onUpdate?.(results[i] as TransferResult)
+      },
+    })
+  })
+  await sendUnits(client, units, options, { batchSize: (options.mode ?? 'pack') === 'tx' ? 1 : options.batchSize })
+  return results
+}
+
+/** 转账指令：SOL 直接转；代币按需先创建收款人的 ATA，再 TransferChecked */
+export function transferInstructions(signer: ResolvedSigner, payer: ResolvedSigner, p: Pick<Planned, 'to' | 'token' | 'native' | 'amount' | 'tokenProgram'> & { decimals: number | null }, ata: string | null, create: boolean): Instruction[] {
+  if (p.native) {
+    return [systemTransfer(signer.address, p.to, p.amount)]
+  }
+  const program = p.tokenProgram as string
+  const source = getAssociatedTokenAddress(signer.address, p.token, program)
+  const destination = ata ?? getAssociatedTokenAddress(p.to, p.token, program)
+  return [
+    ...(create ? [createAssociatedTokenAccountIdempotent(payer.address, destination, p.to, p.token, program)] : []),
+    transferChecked(source, p.token, destination, signer.address, p.amount, p.decimals as number, program),
+  ]
+}
+
+/** 解析数量（formatted 按精度换算）、代币程序，并检查余额 */
+async function plan(client: SolanaClient, owner: string, recipients: readonly TransferItem[], options: BatchTransferOptions): Promise<Planned[]> {
+  const defaultToken = options.token ?? NATIVE_MINT
+  const tokens = [...new Set(recipients.map((r) => r.token ?? defaultToken))]
+  const balances = tokens.length ? await client.balances(owner, tokens, { signal: options.signal }) : []
+  const info = new Map(balances.map((b, i) => [tokens[i] as string, b]))
+  const planned = recipients.map((item, index): Planned => {
+    const token = item.token ?? defaultToken
+    const balance = info.get(token)
+    if (!isAddress(item.to)) {
+      throw new Error(`recipients[${index}]: invalid address ${item.to}`)
+    }
+    if ((item.amount === undefined) === (item.formatted === undefined)) {
+      throw new Error(`recipients[${index}]: pass exactly one of amount / formatted`)
+    }
+    const native = client.isNativeMint(token)
+    if (!native && (!balance?.success || !balance.tokenProgram)) {
+      throw new Error(`recipients[${index}]: cannot read token ${token} (${balance?.error ?? 'unknown error'})`)
+    }
+    // 原生 SOL 的精度固定；代币读不到时上面已经报错
+    const decimals = native ? SOL_DECIMALS : (balance as TokenBalance).decimals
+    let amount: bigint
+    if (item.formatted !== undefined) {
+      amount = parseUnits(item.formatted, decimals)
+    } else {
+      amount = BigInt(item.amount as bigint | number | string)
+    }
+    if (amount < 0n || amount >= 2n ** 64n) {
+      throw new Error(`recipients[${index}]: amount out of range`)
+    }
+    return { index, to: item.to, token, native, amount, decimals, tokenProgram: native ? null : (balance?.tokenProgram ?? null) }
+  })
+  if (options.checkBalance ?? true) {
+    const totals = new Map<string, bigint>()
+    planned.forEach((p) => totals.set(p.token, (totals.get(p.token) ?? 0n) + p.amount))
+    for (const [token, total] of totals) {
+      // 读到这里时余额都读成功了（代币读不到时上面已经报错，原生 SOL 总能读到）
+      const balance = info.get(token) as TokenBalance
+      if (BigInt(balance.balance) < total) {
+        throw new Error(`Insufficient balance of ${token}: need ${total}, have ${balance.balance}`)
+      }
+    }
+  }
+  return planned
+}
+
+function toTransferResult(p: Planned, result: WriteResult, createdAccount: boolean): TransferResult {
+  return {
+    ...result,
+    to: p.to,
+    token: p.token,
+    native: p.native,
+    amount: p.amount.toString(),
+    formatted: formatUnits(p.amount, p.decimals),
+    createdAccount,
+  }
+}