@w3lib/solana-batch-call 0.0.0-stage → 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,155 @@
+export type Commitment = 'processed' | 'confirmed' | 'finalized';
+/**
+ * tokenPrograms 参数的取值：简写 'spl'（SPL Token）/ 'token-2022'，也可以直接传程序地址
+ * （TOKEN_PROGRAM_ID / TOKEN_2022_PROGRAM_ID）
+ */
+export type TokenProgramName = 'spl' | 'token-2022';
+export type TokenProgramOption = TokenProgramName | (string & {});
+/**
+ * 单项失败（success: false）的原因：
+ * - invalid-address：地址格式非法（不是 base58 的 32 字节）
+ * - not-found：地址合法，但链上没有这个账户（如 mint 不存在）
+ * - not-token：账户存在，但不是代币 mint（或代币账户）
+ * - no-metadata：代币存在，但没有元数据（nfts）
+ * - no-holder：没有持有人（nftOwners：供应量为 0 或已销毁）
+ * - missing-field：代币存在，但请求的字段读不到（tokens），见 errorField
+ */
+export type FailureReason = 'invalid-address' | 'not-found' | 'not-token' | 'no-metadata' | 'no-holder' | 'missing-field';
+/** balances() 的单项结果，字段都是字符串 / 数字 / 布尔 / null，可以直接 JSON.stringify */
+export interface TokenBalance {
+    /** 代币的 mint（原样） */
+    token: string;
+    /** 是否按原生 SOL 查询 */
+    native: boolean;
+    /** 余额（最小单位的十进制字符串）；需要计算时用 BigInt(balance) */
+    balance: string;
+    decimals: number;
+    /** 按 decimals 换算后的十进制字符串，如 "1234.5"；整数不带小数点 */
+    formatted: string;
+    /** 代币所属程序（SPL Token / Token-2022）；主币或未知时为 null */
+    tokenProgram: string | null;
+    /** 仅在 symbol: true 时返回；读不到时为 null */
+    symbol?: string | null;
+    /** 查询失败（mint 不存在、地址非法等）时为 false，balance / formatted 为 "0" */
+    success: boolean;
+    /** 失败原因，仅 success 为 false 时返回 */
+    error?: FailureReason;
+    /** 传了 withSlot / minContextSlot 时返回：读取时节点的 slot（一次查询发了多个请求时取最小的） */
+    slot?: number;
+}
+/** ownerTokens() / getOwnerTokens() 的单项结果（总是 success: true） */
+export interface OwnedToken extends Omit<TokenBalance, 'symbol' | 'error'> {
+    /** 该代币的代币账户数量；大于 1 时 balance 为所有账户的合计 */
+    accounts: number;
+    /** metadata 为 true（默认）时返回；没有元数据或读取失败时为 null（见 metadataStatus） */
+    name?: string | null;
+    symbol?: string | null;
+    /** metadata 为 true 时返回：ok 读到了；missing 确认没有元数据；failed 节点问题没能读到（可以稍后单独用 getTokens 重查） */
+    metadataStatus?: 'ok' | 'missing' | 'failed';
+}
+export interface SolBalance {
+    address: string;
+    /** lamports（十进制字符串） */
+    balance: string;
+    /** 按 9 位精度换算后的 SOL */
+    formatted: string;
+    success: boolean;
+    /** 失败原因（只有 invalid-address），仅 success 为 false 时返回 */
+    error?: FailureReason;
+    /** 传了 withSlot / minContextSlot 时返回：读取时节点的 slot（多个请求时取最小的）；没有发请求（地址全部非法）时不返回 */
+    slot?: number;
+}
+/** tokens() / getTokens() 可选的字段 */
+export type TokenField = 'name' | 'symbol' | 'uri' | 'decimals' | 'supply' | 'tokenProgram' | 'mintAuthority' | 'freezeAuthority' | 'transferFee';
+/** Token-2022 转账手续费的一套配置 */
+export interface TransferFee {
+    /** 费率，万分比（100 = 1%） */
+    basisPoints: number;
+    /** 单笔最多收取的手续费（最小单位的十进制字符串） */
+    maximumFee: string;
+    /** 从这个 epoch 开始生效 */
+    epoch: string;
+}
+/**
+ * tokens() 的 transferFee 字段：顶层是**当前 epoch** 生效的配置（按 getEpochInfo 选 newer / older），
+ * older / newer 是扩展里的两套原始配置。收到的数量 = 转账数量 - min(数量 × basisPoints / 10000 向上取整, maximumFee)
+ */
+export interface TransferFeeConfig extends TransferFee {
+    older: TransferFee;
+    newer: TransferFee;
+}
+export declare const DEFAULT_TOKEN_FIELDS: readonly ["name", "symbol", "decimals"];
+export type DefaultTokenField = (typeof DEFAULT_TOKEN_FIELDS)[number];
+interface TokenFieldTypes {
+    /** 优先取 Token-2022 TokenMetadata 扩展，其次 Metaplex 元数据 */
+    name: string | null;
+    symbol: string | null;
+    uri: string | null;
+    decimals: number | null;
+    /** 最小单位的十进制字符串 */
+    supply: string | null;
+    tokenProgram: string | null;
+    /** 没有 mint 权限（已放弃）时为 null */
+    mintAuthority: string | null;
+    freezeAuthority: string | null;
+    /** Token-2022 转账手续费；SPL Token、没有这个扩展、主币时为 null（不算失败） */
+    transferFee: TransferFeeConfig | null;
+}
+/**
+ * tokens() / getTokens() 的单项结果，只包含请求的字段。
+ * 请求 supply 时额外带 supplyFormatted（按 decimals 换算）。
+ */
+export type TokenDetails<F extends TokenField = DefaultTokenField> = {
+    /** mint 地址 */
+    address: string;
+    native: boolean;
+    /** mint 存在且请求的 name / symbol / uri / decimals / supply 都读到时为 true */
+    success: boolean;
+    /** 失败原因，仅 success 为 false 时返回 */
+    error?: FailureReason;
+    /** error 为 missing-field 时：第一个读不到的字段 */
+    errorField?: F;
+} & {
+    [K in F]: TokenFieldTypes[K];
+} & ('supply' extends F ? {
+    supplyFormatted: string | null;
+} : unknown);
+export type TokenStandard = 'NonFungible' | 'FungibleAsset' | 'Fungible' | 'NonFungibleEdition' | 'ProgrammableNonFungible' | 'ProgrammableNonFungibleEdition';
+/** nfts() / getNfts() 的单项结果（Metaplex 元数据；Token-2022 NFT 只有 name / symbol / uri） */
+export interface NftDetails {
+    mint: string;
+    name: string | null;
+    symbol: string | null;
+    /** 链下元数据 JSON 的地址 */
+    uri: string | null;
+    /** 所属集合；verified 为 false 表示未经集合方签名确认 */
+    collection: {
+        address: string;
+        verified: boolean;
+    } | null;
+    creators: Array<{
+        address: string;
+        verified: boolean;
+        share: number;
+    }>;
+    /** 版税，万分比 */
+    sellerFeeBasisPoints: number | null;
+    tokenStandard: TokenStandard | null;
+    isMutable: boolean | null;
+    updateAuthority: string | null;
+    success: boolean;
+    /** 失败原因，仅 success 为 false 时返回 */
+    error?: FailureReason;
+}
+export interface NftOwner {
+    mint: string;
+    /** 持有人钱包地址 */
+    owner: string | null;
+    /** 持有该 NFT 的代币账户 */
+    tokenAccount: string | null;
+    success: boolean;
+    /** 失败原因，仅 success 为 false 时返回 */
+    error?: FailureReason;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export const DEFAULT_TOKEN_FIELDS = ['name', 'symbol', 'decimals'];
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA0FA,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,UAAU,CAA0C,CAAA"}

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@w3lib/solana-batch-call",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Batched Solana reads: SOL / SPL / Token-2022 balances, token metadata, NFTs. Auto-batching JSON-RPC, getMultipleAccounts chunking, RPC failover. No Solana SDK dependency.",
+  "keywords": [
+    "solana",
+    "spl-token",
+    "token-2022",
+    "metaplex",
+    "batch",
+    "getMultipleAccounts",
+    "json-rpc"
+  ],
+  "license": "MIT",
+  "author": "L",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:live": "LIVE=1 vitest run test/live.test.ts",
+    "prepublishOnly": "pnpm typecheck && pnpm test && pnpm build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/web3-lib/libs.git",
+    "directory": "packages/solana-batch-call"
+  },
+  "homepage": "https://github.com/web3-lib/libs/tree/main/packages/solana-batch-call#readme",
+  "bugs": {
+    "url": "https://github.com/web3-lib/libs/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@noble/hashes": "^1.8.0 || ^2.0.0",
+    "@scure/base": "^2.4.0"
+  },
+  "devDependencies": {
+    "@noble/curves": "^2.4.0"
+  }
+}

package/src/address.ts

@@ -0,0 +1,134 @@
+import { sha256 } from '@noble/hashes/sha2.js'
+import { base58 } from '@scure/base'
+
+import { ASSOCIATED_TOKEN_PROGRAM_ID, METADATA_PROGRAM_ID } from './constants.js'
+
+/** 是否是合法的 Solana 地址（base58，32 字节） */
+export function isAddress(value: unknown): value is string {
+  if (typeof value !== 'string' || value.length < 32 || value.length > 44) {
+    return false
+  }
+  try {
+    return base58.decode(value).length === 32
+  } catch {
+    return false
+  }
+}
+
+export function decodeAddress(address: string): Uint8Array {
+  const bytes = base58.decode(address)
+  if (bytes.length !== 32) {
+    throw new Error(`Invalid Solana address: ${address}`)
+  }
+  return bytes
+}
+
+export function encodeAddress(bytes: Uint8Array): string {
+  return base58.encode(bytes)
+}
+
+// ed25519：-x² + y² = 1 + d·x²·y²（mod p）
+const P = 2n ** 255n - 19n
+const D = 37095705934669439343138083508754565189542113879843219016388785533085940283555n
+
+/** x^(2^k) mod p */
+function pow2k(x: bigint, k: number): bigint {
+  let r = x
+  for (let i = 0; i < k; i++) r = (r * r) % P
+  return r
+}
+
+/** x^((p-1)/2) mod p（欧拉判别法），(p-1)/2 = (2^250 - 1)·2^4 + 6，用加法链：约 254 次平方 + 12 次乘法 */
+function legendre(x: bigint): bigint {
+  const b2 = (((x * x) % P) * x) % P // x^(2^2-1)
+  const b4 = (pow2k(b2, 2) * b2) % P
+  const b5 = (pow2k(b4, 1) * x) % P
+  const b10 = (pow2k(b5, 5) * b5) % P
+  const b20 = (pow2k(b10, 10) * b10) % P
+  const b40 = (pow2k(b20, 20) * b20) % P
+  const b80 = (pow2k(b40, 40) * b40) % P
+  const b160 = (pow2k(b80, 80) * b80) % P
+  const b240 = (pow2k(b160, 80) * b80) % P
+  const b250 = (pow2k(b240, 10) * b10) % P
+  return (pow2k(b250, 4) * ((b2 * b2) % P)) % P
+}
+
+/**
+ * 32 字节是否是合法的 ed25519 压缩点（PDA 必须不在曲线上）。
+ * 按 RFC 8032 5.1.3 解压缩，与 @noble/curves 的 Point.fromBytes（web3.js 的 isOnCurve 同样如此）一致：
+ * y ≥ p、x = 0 但符号位为 1 都算不在曲线上。只需判断 x² = (y² - 1) / (d·y² + 1) 有没有解，不必真的开方
+ */
+export function isOnCurve(bytes: Uint8Array): boolean {
+  if (bytes.length !== 32) {
+    return false
+  }
+  let y = 0n
+  for (let i = 31; i >= 0; i--) {
+    y = (y << 8n) | BigInt(i === 31 ? (bytes[i] as number) & 0x7f : (bytes[i] as number))
+  }
+  if (y >= P) {
+    return false
+  }
+  const y2 = (y * y) % P
+  const u = (y2 - 1n + P) % P
+  const v = (D * y2 + 1n) % P // d 不是平方数，v 不会为 0
+  if (u === 0n) {
+    // x = 0：符号位必须为 0
+    return ((bytes[31] as number) & 0x80) === 0
+  }
+  // u / v 是平方数 ⇔ u·v 是平方数（欧拉判别法）
+  return legendre((u * v) % P) === 1n
+}
+
+const PDA_MARKER = new TextEncoder().encode('ProgramDerivedAddress')
+
+function concat(parts: Uint8Array[]): Uint8Array {
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0))
+  let offset = 0
+  for (const part of parts) {
+    out.set(part, offset)
+    offset += part.length
+  }
+  return out
+}
+
+// PDA 推导是纯计算但要做多次 sha256 + 曲线判断，结果缓存
+const pdaCache = new Map<string, string>()
+
+/**
+ * 推导 PDA（与 web3.js PublicKey.findProgramAddressSync 相同），返回地址。
+ * seeds 每项不超过 32 字节。
+ */
+export function findProgramAddress(seeds: Uint8Array[], programId: string): string {
+  const key = `${programId}:${seeds.map((s) => encodeAddress(s)).join(',')}`
+  const cached = pdaCache.get(key)
+  if (cached) {
+    return cached
+  }
+  const program = decodeAddress(programId)
+  for (let bump = 255; bump >= 0; bump--) {
+    const hash = sha256(concat([...seeds, new Uint8Array([bump]), program, PDA_MARKER]))
+    if (!isOnCurve(hash)) {
+      const address = encodeAddress(hash)
+      if (pdaCache.size > 10_000) {
+        pdaCache.clear()
+      }
+      pdaCache.set(key, address)
+      return address
+    }
+  }
+  throw new Error('Unable to find a viable program address bump seed')
+}
+
+/** 关联代币账户（ATA）地址 */
+export function getAssociatedTokenAddress(owner: string, mint: string, tokenProgram: string): string {
+  return findProgramAddress([decodeAddress(owner), decodeAddress(tokenProgram), decodeAddress(mint)], ASSOCIATED_TOKEN_PROGRAM_ID)
+}
+
+/** Metaplex Token Metadata 账户地址 */
+export function getMetadataAddress(mint: string): string {
+  return findProgramAddress(
+    [new TextEncoder().encode('metadata'), decodeAddress(METADATA_PROGRAM_ID), decodeAddress(mint)],
+    METADATA_PROGRAM_ID,
+  )
+}