@w3lib/evm-batch-call 0.6.0 → 0.7.0

package/src/fees.ts

@@ -0,0 +1,201 @@
+/**
+ * 手续费估算（子路径 `@w3lib/evm-batch-call/fees`）：EIP-1559 的 baseFee 和三档优先费（按最近区块的 eth_feeHistory），
+ * 一笔交易的手续费（含 OP Stack / Scroll 的 L1 数据费）；Tron 按能量 / 带宽和账户剩余的资源算要烧的 TRX
+ */
+import type { BigNumberish } from 'ethers'
+
+import { getNativeCurrency } from './chains.js'
+import { formatUnits } from './erc20.js'
+import type { Provider } from './provider.js'
+import { isTronChain } from './tron.js'
+
+export type FeeLevel = 'slow' | 'normal' | 'fast'
+
+/** 一档费用（wei 的十进制字符串）：EIP-1559 链是 maxFeePerGas / maxPriorityFeePerGas，legacy 链是 gasPrice */
+export type FeeLevelEstimate = { maxFeePerGas: string; maxPriorityFeePerGas: string } | { gasPrice: string }
+
+export interface FeeEstimate {
+  type: 'eip1559' | 'legacy'
+  /** 下一个区块的 baseFee（wei）；legacy 链为 null */
+  baseFee: string | null
+  slow: FeeLevelEstimate
+  normal: FeeLevelEstimate
+  fast: FeeLevelEstimate
+}
+
+export interface EstimateFeesOptions {
+  /** 看最近多少个区块，默认 20 */
+  blocks?: number
+  /** 三档优先费取各区块交易优先费的百分位，默认 [10, 50, 90] */
+  percentiles?: readonly [number, number, number]
+  /** maxFeePerGas = baseFee × baseFeeMultiplier + 优先费，默认 2（baseFee 连涨几个区块也够） */
+  baseFeeMultiplier?: number
+}
+
+interface FeeHistory {
+  baseFeePerGas?: string[]
+  reward?: string[][]
+}
+
+/** 节点的 JSON-RPC send（ethers 的 JsonRpcProvider / BrowserProvider） */
+type Sender = { send(method: string, params: unknown[]): Promise<unknown> }
+
+async function send<T>(provider: Provider, method: string, params: unknown[]): Promise<T> {
+  const { runOnNodes } = await import('./write/rpc.js')
+  return runOnNodes(provider.rpc, method, async (node) => {
+    if (typeof (node as Partial<Sender>).send !== 'function') throw new Error(`${method} is not supported by this node; pass an RPC URL or an ethers Provider`)
+    return (await (node as unknown as Sender).send(method, params)) as T
+  })
+}
+
+const median = (values: bigint[]): bigint => {
+  if (!values.length) return 0n
+  const sorted = [...values].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
+  return sorted[Math.floor(sorted.length / 2)] as bigint
+}
+
+/**
+ * 当前的手续费建议（EVM 链）：baseFee 取下一个区块的，三档优先费是最近区块里交易优先费的百分位的中位数；
+ * 节点不支持 eth_feeHistory 或链上没有 baseFee 时按 eth_gasPrice（三档为 1、1、1.2 倍）。Tron 用 estimateCost
+ *
+ * ```ts
+ * const fees = await estimateFees(provider)
+ * // { type: 'eip1559', baseFee: '1200000000', slow: { maxFeePerGas, maxPriorityFeePerGas }, normal: {…}, fast: {…} }
+ * ```
+ */
+export async function estimateFees(provider: Provider, options: EstimateFeesOptions = {}): Promise<FeeEstimate> {
+  if (isTronChain(await provider.getChainId())) throw new Error('estimateFees is for EVM chains; use estimateCost on Tron')
+  const blocks = Math.max(1, Math.min(1024, Math.floor(options.blocks ?? 20)))
+  const percentiles = options.percentiles ?? [10, 50, 90]
+  if (!percentiles.every((p, i) => p >= 0 && p <= 100 && (i === 0 || p >= (percentiles[i - 1] as number)))) throw new RangeError('percentiles must be ascending numbers in [0, 100]')
+  const multiplier = options.baseFeeMultiplier ?? 2
+  let history: FeeHistory | null = null
+  try {
+    history = await send<FeeHistory>(provider, 'eth_feeHistory', [`0x${blocks.toString(16)}`, 'latest', [...percentiles]])
+  } catch (err) {
+    // 只有节点 / 链不支持 feeHistory 时才按 gasPrice；网络等其他错误照常抛出（不要在 EIP-1559 链上悄悄退回 legacy）
+    if (!/not (supported|available|found)|unsupported|does not exist|unknown method|-32601|method.*not/i.test(err instanceof Error ? err.message : String(err))) throw err
+    history = null
+  }
+  const baseFees = history?.baseFeePerGas ?? []
+  const next = baseFees.length ? BigInt(baseFees[baseFees.length - 1] as string) : 0n
+  if (!history || !baseFees.length || next === 0n) {
+    const gasPrice = BigInt(await send<string>(provider, 'eth_gasPrice', []))
+    const level = (n: bigint, d: bigint) => ({ gasPrice: ((gasPrice * n) / d).toString() })
+    return { type: 'legacy', baseFee: null, slow: level(1n, 1n), normal: level(1n, 1n), fast: level(6n, 5n) }
+  }
+  const rewards = history.reward ?? []
+  // 每档：各区块这个百分位的优先费取中位数（空区块的 0 不算）
+  const tip = (k: number) => median(rewards.map((r) => BigInt(r[k] ?? '0')).filter((v) => v > 0n))
+  const base = (next * BigInt(Math.round(multiplier * 1000))) / 1000n
+  const level = (priority: bigint) => ({ maxFeePerGas: (base + priority).toString(), maxPriorityFeePerGas: priority.toString() })
+  const [slow, normal, fast] = [tip(0), tip(1), tip(2)]
+  // 优先费不递减（区块很空时三档可能相同）
+  return { type: 'eip1559', baseFee: next.toString(), slow: level(slow), normal: level(normal > slow ? normal : slow), fast: level(fast > normal ? fast : normal > slow ? normal : slow) }
+}
+
+export interface CostCall {
+  /** 发送者（预估 gas、Tron 上按它剩余的资源算） */
+  from: string
+  to: string
+  data?: string
+  value?: BigNumberish
+}
+
+export interface EvmCostEstimate {
+  type: 'evm'
+  gasLimit: string
+  /** 这一档的每 gas 价格：EIP-1559 是 baseFee + 优先费（预计实际付的），legacy 是 gasPrice */
+  gasPrice: string
+  /** gasLimit × gasPrice（wei） */
+  fee: string
+  /** 最多付多少：gasLimit × maxFeePerGas（legacy 同 fee） */
+  maxFee: string
+  /** OP Stack / Scroll 的 L1 数据费（wei，含 25% 余量），其他链为 0 */
+  l1Fee: string
+  /** fee + l1Fee（wei）和按主币精度换算的值 */
+  total: string
+  totalFormatted: string
+  symbol: string | null
+}
+
+export interface TronCost {
+  type: 'tron'
+  energy: number
+  bandwidth: number
+  /** 剩余能量 / 带宽不够时要烧的 TRX（sun） */
+  energyBurn: string
+  bandwidthBurn: string
+  /** 转 TRX 给没激活的地址（激活费算在 bandwidthBurn 里） */
+  activates: boolean
+  energyPrice: string
+  bandwidthPrice: string
+  /** energyBurn + bandwidthBurn（sun）和按 TRX 换算的值 */
+  total: string
+  totalFormatted: string
+  symbol: 'TRX'
+}
+
+export type CostEstimate = EvmCostEstimate | TronCost
+
+export interface EstimateCostOptions extends EstimateFeesOptions {
+  /** 用哪一档，默认 'normal' */
+  level?: FeeLevel
+  /** 已经查好的费用建议（多笔交易共用，不再查一次） */
+  fees?: FeeEstimate
+}
+
+/**
+ * 估算一笔交易的手续费：EVM 预估 gas × 这一档的价格（+ L1 数据费）；Tron 模拟能量，按发送者剩余的资源算要烧的 TRX。
+ * 预估 gas 会执行一遍交易，revert 时抛出
+ *
+ * ```ts
+ * await estimateCost(provider, { from: user, to: USDT, data })   // { type: 'evm', gasLimit, fee, total, totalFormatted: '0.00042', symbol: 'BNB', … }
+ * await estimateCost(tronProvider, { from, to: USDT, data })     // { type: 'tron', energy: 64285, energyBurn: '6750000', totalFormatted: '7.0', … }
+ * ```
+ */
+export async function estimateCost(provider: Provider, call: CostCall, options: EstimateCostOptions = {}): Promise<CostEstimate> {
+  const chainId = await provider.getChainId()
+  const value = BigInt(call.value ?? 0)
+  if (isTronChain(chainId)) {
+    const { tronEstimateCost } = await import('./write/tron.js')
+    const c = await tronEstimateCost(provider, { from: call.from, to: call.to, ...(call.data ? { data: call.data } : {}), value })
+    const total = c.energyBurn + c.bandwidthBurn
+    return {
+      type: 'tron',
+      energy: c.energy,
+      bandwidth: c.bandwidth,
+      energyBurn: c.energyBurn.toString(),
+      bandwidthBurn: c.bandwidthBurn.toString(),
+      activates: c.activates,
+      energyPrice: c.energyPrice.toString(),
+      bandwidthPrice: c.bandwidthPrice.toString(),
+      total: total.toString(),
+      totalFormatted: formatUnits(total, 6),
+      symbol: 'TRX',
+    }
+  }
+  const { WriteRpc, l1Fee } = await import('./write/rpc.js')
+  const rpc = await WriteRpc.from(provider)
+  const tx = { from: call.from, to: call.to, data: call.data ?? '0x', value }
+  const [gasLimit, fees] = await Promise.all([rpc.estimateGas(tx), options.fees ? Promise.resolve(options.fees) : estimateFees(provider, options)])
+  const level = fees[options.level ?? 'normal']
+  const perGas = 'gasPrice' in level ? BigInt(level.gasPrice) : BigInt(fees.baseFee ?? '0') + BigInt(level.maxPriorityFeePerGas)
+  const maxPerGas = 'gasPrice' in level ? perGas : BigInt(level.maxFeePerGas)
+  const feeFields = 'gasPrice' in level ? { type: 0, gasPrice: perGas } : { type: 2, maxFeePerGas: maxPerGas, maxPriorityFeePerGas: BigInt(level.maxPriorityFeePerGas) }
+  const l1 = await l1Fee(rpc, { ...tx, from: undefined, gasLimit, ...feeFields })
+  const fee = gasLimit * perGas
+  const total = fee + l1
+  const native = getNativeCurrency(chainId)
+  return {
+    type: 'evm',
+    gasLimit: gasLimit.toString(),
+    gasPrice: perGas.toString(),
+    fee: fee.toString(),
+    maxFee: (gasLimit * maxPerGas).toString(),
+    l1Fee: l1.toString(),
+    total: total.toString(),
+    totalFormatted: formatUnits(total, native?.decimals ?? 18),
+    symbol: native?.symbol ?? null,
+  }
+}

package/src/http.ts

@@ -0,0 +1,34 @@
+/** HTTP 请求（代币列表、价格服务）：超时、状态码检查 */
+
+const REQUEST_TIMEOUT = 20_000
+
+export class HttpStatusError extends Error {
+  constructor(
+    readonly status: number,
+    target: string,
+  ) {
+    super(`HTTP ${status} from ${target}`)
+    this.name = 'HttpStatusError'
+  }
+}
+
+/**
+ * @param secret 请求里带的 Key：出错时错误信息只写域名，不写完整地址，避免 Key 出现在日志里
+ */
+export function fetchJson<T>(fetchFn: typeof fetch, url: string, init?: RequestInit, secret?: string): Promise<T> {
+  return fetchFn(url, { ...init, signal: AbortSignal.timeout(REQUEST_TIMEOUT) }).then(async (res) => {
+    if (!res.ok) {
+      throw new HttpStatusError(res.status, secret ? safeHost(url) : url)
+    }
+    return (await res.json()) as T
+  })
+}
+
+function safeHost(url: string): string {
+  try {
+    return new URL(url).host
+  } catch {
+    return 'request'
+  }
+}
+

package/src/lp.ts

@@ -3,7 +3,8 @@ import type { Call } from './call.js'
 import { formatUnits } from './erc20.js'
 import { getAmountsForLiquidity, getFeeGrowthInside, getFeesEarned, getSqrtRatioAtTick, sqrtPriceToPrice, tickToPrice } from './lpMath.js'
 import { v4Positions, type LpV4Options } from './lpV4.js'
-import { defillamaPrices, type PriceSource, type TokenSource } from './owner.js'
+import type { TokenSource } from './owner.js'
+import { defillamaPrices, type PriceSource } from './price.js'
 import type { Provider } from './provider.js'
 import { TRON_CHAIN_ID, isTronAddress, isTronChain, toEvmAddress, toTronAddress } from './tron.js'
 import { withSignal } from './util.js'
@@ -629,6 +630,7 @@ async function finalize(provider: Provider, chainId: number, raw: RawPosition[],
         tokens: addresses.filter((a) => !info.get(a)?.native).map((a) => (tron ? toTronAddress(a) : a)),
         nativeSymbol: nativeToken ? nativeToken.symbol : null,
         fetch: fetchFn,
+        provider,
       })
     } catch (err) {
       // 同步抛错和 reject 都在这里接住

package/src/multicall.ts

@@ -81,6 +81,9 @@ const MULTICALL3: Record<number, Multicall> = {
   80094: { address: CANONICAL, block: 0 }, // Berachain，创世预置
   534352: { address: CANONICAL, block: 14 }, // Scroll
   86233268: { address: CANONICAL, block: 10854614 }, // Winchain，部署区块未查到
+  1030: { address: CANONICAL, block: 159584122 }, // Conflux eSpace，部署区块未查到
+  1672: { address: CANONICAL, block: 20812125 }, // Pharos，部署区块未查到
+  1776: { address: CANONICAL, block: 188237272 }, // Injective EVM，部署区块未查到
   // 以下两条链不支持 deployless（合约创建式 eth_call 返回空 / 格式不对），只能用 Multicall3；
   // 早于部署区块的历史查询会失败
   42262: { address: CANONICAL, block: 22380155 }, // Oasis Emerald，部署区块未查到

package/src/names.ts

@@ -0,0 +1,141 @@
+/**
+ * 域名解析（子路径 `@w3lib/evm-batch-call/names`）：ENS（Ethereum）、SPACE ID（BSC 的 .bnb）、Basenames（Base 的 .base.eth），
+ * 名字 → 地址、地址 → 名字（反查后再正查核对）。都是 ENS 式的注册表合约，读取合成几次 multicall
+ */
+import { ensNormalize, namehash } from 'ethers'
+
+import type { Provider } from './provider.js'
+import { isTronChain } from './tron.js'
+
+export interface NameService {
+  id: string
+  name: string
+  chainId: number
+  /** ENS 式的注册表合约（resolver(node)） */
+  registry: string
+  /** 这个服务的名字后缀（如 ['bnb']）；null 表示任意名字都交给它（ENS 还支持导入的 DNS 域名） */
+  suffixes: readonly string[] | null
+  /** 反查用的节点后缀：ENS 是 addr.reverse，L2 上按 ENSIP-19 是 <coinType 十六进制>.reverse */
+  reverseSuffix: string
+}
+
+/** 内置的域名服务（2026-10 在链上核对过注册表和正查 / 反查） */
+export const NAME_SERVICES: readonly NameService[] = [
+  { id: 'ens', name: 'ENS', chainId: 1, registry: '0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e', suffixes: null, reverseSuffix: 'addr.reverse' },
+  { id: 'spaceid', name: 'SPACE ID', chainId: 56, registry: '0x08CEd32a7f3eeC915Ba84415e9C07a7286977956', suffixes: ['bnb'], reverseSuffix: 'addr.reverse' },
+  { id: 'basenames', name: 'Basenames', chainId: 8453, registry: '0xb94704422c2a1e396835a571837aa5ae53285a95', suffixes: ['base.eth'], reverseSuffix: '80002105.reverse' },
+]
+
+export interface NamesOptions {
+  /** 用哪些域名服务，默认 NAME_SERVICES 里 Provider 这条链的 */
+  services?: readonly NameService[]
+}
+
+export interface ResolvedName {
+  /** 传入的名字（原样） */
+  name: string
+  /** 规范化后的名字（ENSIP-15）；名字不合法时为 null */
+  normalized: string | null
+  /** 解析出的地址；没有注册、没有设置地址、名字不合法时为 null */
+  address: string | null
+  /** 解析这个名字的服务 id；没有服务认这个后缀时为 null */
+  service: string | null
+}
+
+export interface AddressName {
+  /** 传入的地址（原样） */
+  address: string
+  /** 反查到、并且正查回到同一个地址的名字；没有时为 null */
+  name: string | null
+  service: string | null
+}
+
+const REGISTRY_ABI = ['function resolver(bytes32 node) view returns (address)']
+const RESOLVER_ABI = ['function addr(bytes32 node) view returns (address)', 'function name(bytes32 node) view returns (string)']
+const ZERO = '0x0000000000000000000000000000000000000000'
+const present = (a: string | null | undefined): a is string => !!a && a.toLowerCase() !== ZERO
+
+function servicesOf(chainId: number, options: NamesOptions): readonly NameService[] {
+  return options.services ?? NAME_SERVICES.filter((s) => s.chainId === chainId)
+}
+
+/** 名字归哪个服务：后缀最长的匹配优先，其次是不限后缀的服务 */
+function serviceFor(name: string, services: readonly NameService[]): NameService | null {
+  let best: { s: NameService; len: number } | null = null
+  for (const s of services) {
+    for (const suffix of s.suffixes ?? []) {
+      if ((name === suffix || name.endsWith(`.${suffix}`)) && (!best || suffix.length > best.len)) best = { s, len: suffix.length }
+    }
+  }
+  return best?.s ?? services.find((s) => s.suffixes === null) ?? null
+}
+
+function normalize(name: string): string | null {
+  try {
+    const n = ensNormalize(name.trim())
+    return n.includes('.') ? n : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 名字 → 地址（读注册表的 resolver，再读 resolver 的 addr，两次 multicall）。
+ * 不支持通配解析（ENSIP-10）和链下解析（CCIP-Read，如 cb.id 等子域名），这些名字返回 null
+ *
+ * ```ts
+ * await resolveNames(new Provider(1), ['vitalik.eth', 'nick.eth'])
+ * // [{ name: 'vitalik.eth', normalized: 'vitalik.eth', address: '0xd8dA…6045', service: 'ens' }, …]
+ * ```
+ */
+export async function resolveNames(provider: Provider, names: readonly string[], options: NamesOptions = {}): Promise<ResolvedName[]> {
+  const chainId = await provider.getChainId()
+  const services = isTronChain(chainId) ? [] : servicesOf(chainId, options)
+  const items = names.map((name) => {
+    const normalized = normalize(name)
+    const service = normalized ? serviceFor(normalized, services) : null
+    return { name, normalized, service, node: normalized && service ? namehash(normalized) : null }
+  })
+  const todo = items.filter((x) => x.node && x.service)
+  const resolvers = todo.length ? await provider.tryAll<string>(todo.map((x) => provider.contract((x.service as NameService).registry, REGISTRY_ABI).resolver(x.node as string))) : []
+  const withResolver = todo.flatMap((x, i) => (present(resolvers[i]) ? [{ x, resolver: resolvers[i] as string }] : []))
+  const addresses = withResolver.length ? await provider.tryAll<string>(withResolver.map(({ x, resolver }) => provider.contract(resolver, RESOLVER_ABI).addr(x.node as string))) : []
+  const found = new Map(withResolver.map(({ x }, i) => [x, present(addresses[i]) ? (addresses[i] as string) : null]))
+  return items.map((x) => ({ name: x.name, normalized: x.normalized, address: found.get(x) ?? null, service: x.service?.id ?? null }))
+}
+
+/**
+ * 地址 → 名字：读反查记录（主名字），再正查核对名字确实指回这个地址（没有核对的反查记录可以随便设置，不能信）。
+ * 共四次 multicall；Tron 上没有域名服务，都返回 null
+ *
+ * ```ts
+ * await lookupAddresses(new Provider(56), [user])   // [{ address: user, name: 'alice.bnb', service: 'spaceid' }]
+ * ```
+ */
+export async function lookupAddresses(provider: Provider, addresses: readonly string[], options: NamesOptions = {}): Promise<AddressName[]> {
+  const chainId = await provider.getChainId()
+  const services = isTronChain(chainId) ? [] : servicesOf(chainId, options)
+  const queries = addresses.flatMap((address, i) =>
+    /^0x[0-9a-fA-F]{40}$/.test(address) ? services.map((s) => ({ i, s, node: namehash(`${address.slice(2).toLowerCase()}.${s.reverseSuffix}`) })) : [],
+  )
+  const resolvers = queries.length ? await provider.tryAll<string>(queries.map((q) => provider.contract(q.s.registry, REGISTRY_ABI).resolver(q.node))) : []
+  const withResolver = queries.flatMap((q, j) => (present(resolvers[j]) ? [{ q, resolver: resolvers[j] as string }] : []))
+  const names = withResolver.length ? await provider.tryAll<string>(withResolver.map(({ q, resolver }) => provider.contract(resolver, RESOLVER_ABI).name(q.node))) : []
+  const claimed = withResolver.flatMap(({ q }, j) => (typeof names[j] === 'string' && names[j] ? [{ q, name: names[j] as string }] : []))
+  // 正查核对：名字要由同一个服务解析回这个地址
+  const forward = await resolveNames(
+    provider,
+    claimed.map((c) => c.name),
+    { services },
+  )
+  const result: AddressName[] = addresses.map((address) => ({ address, name: null, service: null }))
+  claimed.forEach((c, j) => {
+    const f = forward[j]
+    const out = result[c.q.i] as AddressName
+    if (out.name === null && f?.address && f.service === c.q.s.id && f.address.toLowerCase() === out.address.toLowerCase()) {
+      out.name = f.normalized
+      out.service = c.q.s.id
+    }
+  })
+  return result
+}

package/src/owner.ts

@@ -1,8 +1,10 @@
 import type { CallOverrides } from './aggregate.js'
 import { NATIVE_TOKEN, formatUnits, type BalanceToken } from './erc20.js'
 import type { Provider } from './provider.js'
+import { HttpStatusError, fetchJson } from './http.js'
+import { defillamaPrices, type PriceSource } from './price.js'
 import { transferScan, type TransferScanOptions } from './scan.js'
-import { TRON_CHAIN_ID, isTronAddress, isTronChain, toTronAddress } from './tron.js'
+import { isTronAddress, isTronChain, toTronAddress } from './tron.js'
 
 // ---------------------------------------------------------------------------
 // 代币来源：负责“这个地址可能持有哪些代币”。余额和精度一律由本库用 multicall 在链上核对。
@@ -31,41 +33,10 @@ export interface TokenSource {
   discover(ctx: TokenSourceContext): Promise<DiscoveredToken[] | null>
 }
 
-const REQUEST_TIMEOUT = 20_000
 const LIST_TTL = 60 * 60 * 1000
 const MAX_CACHED_LISTS = 16
 const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000'
 
-export class HttpStatusError extends Error {
-  constructor(
-    readonly status: number,
-    target: string,
-  ) {
-    super(`HTTP ${status} from ${target}`)
-    this.name = 'HttpStatusError'
-  }
-}
-
-/**
- * @param secret 请求里带的 Key：出错时错误信息只写域名，不写完整地址，避免 Key 出现在日志里
- */
-function fetchJson<T>(fetchFn: typeof fetch, url: string, init?: RequestInit, secret?: string): Promise<T> {
-  return fetchFn(url, { ...init, signal: AbortSignal.timeout(REQUEST_TIMEOUT) }).then(async (res) => {
-    if (!res.ok) {
-      throw new HttpStatusError(res.status, secret ? safeHost(url) : url)
-    }
-    return (await res.json()) as T
-  })
-}
-
-function safeHost(url: string): string {
-  try {
-    return new URL(url).host
-  } catch {
-    return 'request'
-  }
-}
-
 // 公开代币列表：缓存“按链过滤、转换后”的结果（不缓存原始 JSON），1 小时；缓存 Promise，同时发起的请求共用，失败不缓存。
 // 公开列表与使用哪个 fetch 无关，所以缓存键只看列表和链
 const listCache = new Map<string, { at: number; promise: Promise<DiscoveredToken[] | null> }>()
@@ -410,111 +381,9 @@ function dedupe<T extends DiscoveredToken>(tokens: T[]): T[] {
   return [...seen.values()]
 }
 
-// ---------------------------------------------------------------------------
-// 价格来源
-// ---------------------------------------------------------------------------
-
-export interface PriceSourceContext {
-  chainId: number
-  /** 代币地址（不含主币） */
-  tokens: readonly string[]
-  /** 主币 symbol（需要主币价格时）；不需要时为 null */
-  nativeSymbol: string | null
-  fetch: typeof fetch
-}
-
-export interface PriceSource {
-  readonly name: string
-  /** 返回 去重键 → 美元价格：EVM 是小写 0x 地址；Tron 是 T 开头的 base58 地址（区分大小写）；主币用键 'native'。没有价格的不返回 */
-  prices(ctx: PriceSourceContext): Promise<Map<string, number>>
-}
-
-/** DefiLlama 的链标识：chainId → slug（2026-10 实测可用） */
-export const DEFILLAMA_CHAINS: Readonly<Record<number, string>> = {
-  1: 'ethereum',
-  10: 'optimism',
-  56: 'bsc',
-  130: 'unichain',
-  137: 'polygon',
-  143: 'monad',
-  196: 'xlayer',
-  204: 'op_bnb',
-  324: 'era',
-  999: 'hyperliquid',
-  1116: 'core',
-  2818: 'morph',
-  5000: 'mantle',
-  8453: 'base',
-  9745: 'plasma',
-  34443: 'mode',
-  42161: 'arbitrum',
-  43114: 'avax',
-  57073: 'ink',
-  59144: 'linea',
-  80094: 'berachain',
-  81457: 'blast',
-  534352: 'scroll',
-  [TRON_CHAIN_ID.mainnet]: 'tron',
-}
-
-/** 主币价格：按主币 symbol 对应 CoinGecko 的币种 id（DefiLlama 用 coingecko:<id> 查） */
-const NATIVE_PRICE_IDS: Readonly<Record<string, string>> = {
-  ETH: 'ethereum',
-  BNB: 'binancecoin',
-  POL: 'polygon-ecosystem-token',
-  AVAX: 'avalanche-2',
-  MNT: 'mantle',
-  OKB: 'okb',
-  HYPE: 'hyperliquid',
-  BERA: 'berachain-bera',
-  CORE: 'coredaoorg',
-  MON: 'monad',
-  XPL: 'plasma',
-  TRX: 'tron',
-}
-
-/**
- * DefiLlama 价格（免费、不需要 Key）。minConfidence：DefiLlama 给出的置信度下限（0~1），低于它视为没有价格，默认 0.9。
- * 注意：流动性很差的代币价格可能虚高，展示总资产时建议配合 minUsd 或自己的价格源。
- */
-export function defillamaPrices(options: { minConfidence?: number } = {}): PriceSource {
-  const minConfidence = options.minConfidence ?? 0.9
-  return {
-    name: 'defillama',
-    async prices({ chainId, tokens, nativeSymbol, fetch: fetchFn }) {
-      const result = new Map<string, number>()
-      const slug = DEFILLAMA_CHAINS[chainId]
-      const nativeId = nativeSymbol ? NATIVE_PRICE_IDS[nativeSymbol.toUpperCase()] : undefined
-      // 查询键 → 结果里用的去重键：EVM 地址小写；Tron 地址区分大小写，DefiLlama 要用原样的 base58（T…）地址
-      const resultKey = new Map<string, string>()
-      const tokenKeys = slug
-        ? tokens.map((t) => {
-            const tron = slug === 'tron'
-            const query = `${slug}:${tron ? toTronAddress(t) : t.toLowerCase()}`
-            resultKey.set(query.toLowerCase(), tron ? toTronAddress(t) : t.toLowerCase())
-            return query
-          })
-        : []
-      const keys = [...(nativeId ? [`coingecko:${nativeId}`] : []), ...tokenKeys]
-      const batches: string[][] = []
-      for (let i = 0; i < keys.length; i += 100) {
-        batches.push(keys.slice(i, i + 100))
-      }
-      const responses = await Promise.all(
-        batches.map((batch) => fetchJson<{ coins?: Record<string, { price?: number; confidence?: number }> }>(fetchFn, `https://coins.llama.fi/prices/current/${batch.join(',')}`)),
-      )
-      for (const res of responses) {
-        for (const [key, coin] of Object.entries(res.coins ?? {})) {
-          if (typeof coin.price !== 'number' || !Number.isFinite(coin.price) || (coin.confidence !== undefined && coin.confidence < minConfidence)) {
-            continue
-          }
-          result.set(key.startsWith('coingecko:') ? 'native' : (resultKey.get(key.toLowerCase()) ?? key.slice(key.indexOf(':') + 1).toLowerCase()), coin.price)
-        }
-      }
-      return result
-    },
-  }
-}
+// 价格来源在 price.ts（子路径 /price）；这里继续导出，旧的 import 不受影响
+export { DEFILLAMA_CHAINS, defillamaPrices, type PriceSource, type PriceSourceContext } from './price.js'
+export { HttpStatusError }
 
 // ---------------------------------------------------------------------------
 // ownerTokens
@@ -617,7 +486,7 @@ export async function ownerTokens(provider: Provider, owner: string, options: Ow
   // 价格源的键：Tron 上统一用 T 地址（代币来源给的可能是 0x 格式）
   const priceKey = (address: string) => (isTronChain(chainId) ? toTronAddress(address) : addressKey(address))
   const priceMap = priceSource
-    ? await priceSource.prices({ chainId, tokens: held.map((x) => (isTronChain(chainId) ? toTronAddress(x.meta.address) : x.meta.address)), nativeSymbol: nativeAddress ? (nativeInfo?.symbol ?? null) : null, fetch: fetchFn })
+    ? await priceSource.prices({ chainId, tokens: held.map((x) => (isTronChain(chainId) ? toTronAddress(x.meta.address) : x.meta.address)), nativeSymbol: nativeAddress ? (nativeInfo?.symbol ?? null) : null, fetch: fetchFn, provider })
     : new Map<string, number>()
   const valueOf = (formatted: string, price: number | undefined) => (price === undefined ? null : Number(formatted) * price)
 

package/src/portfolio.ts

@@ -0,0 +1,91 @@
+/**
+ * 资产总值（子路径 `@w3lib/evm-batch-call/price`）：已知代币的余额 × 价格，可选加上 LP 仓位的价值
+ */
+import { lpPositions, type LpPosition, type LpPositionsOptions } from './lp.js'
+import { combinePrices, defillamaPrices, onchainPrices, tokenPrices, type PriceSource } from './price.js'
+import type { Provider } from './provider.js'
+
+export interface PortfolioOptions {
+  /** 要计入的代币（含主币：NATIVE_TOKEN），余额用 multicall 一次读出 */
+  tokens: readonly string[]
+  /** 价格源，依次使用，默认 [defillamaPrices(), onchainPrices()] */
+  sources?: readonly PriceSource[]
+  /** 同时计入 LP 仓位（V2 LP 代币、V3 仓位 NFT；参数同 lpPositions，价格源用上面的 sources），默认不计入 */
+  lp?: boolean | Omit<LpPositionsOptions, 'prices'>
+  /** 价值低于它的代币不列出（不影响合计）；大于 0 时没有价格的代币也不列出（计入 unpriced），默认 0 */
+  minUsd?: number
+  /** 某个价格源出错时调用 */
+  onPriceError?: (err: unknown) => void
+  fetch?: typeof fetch
+}
+
+export interface PortfolioToken {
+  token: string
+  native: boolean
+  symbol: string | null
+  balance: string
+  decimals: number
+  formatted: string
+  price: number | null
+  /** 美元价值；没有价格时为 null */
+  value: number | null
+  /** 给出价格的价格源 */
+  priceSource: string | null
+}
+
+export interface Portfolio {
+  /** 合计（代币 + LP；没有价格的不计入） */
+  totalUsd: number
+  tokensUsd: number
+  lpUsd: number
+  /** 有余额的代币，按价值从高到低 */
+  tokens: PortfolioToken[]
+  /** LP 仓位（开启 lp 时） */
+  lp: LpPosition[]
+  /** 有余额但没有价格的代币数（LP 仓位里缺价格的也算） */
+  unpriced: number
+}
+
+/**
+ * 一个地址的资产总值：代币余额（只看传入的代币，EVM 不能只靠节点列出持仓）× 价格，可选加上 LP 仓位。
+ *
+ * ```ts
+ * const p = await portfolio(provider, user, { tokens: [NATIVE_TOKEN, USDT, USDC], lp: true })
+ * p.totalUsd  // 1234.5
+ * ```
+ */
+export async function portfolio(provider: Provider, owner: string, options: PortfolioOptions): Promise<Portfolio> {
+  const { tokens, sources = [defillamaPrices(), onchainPrices()], lp, minUsd = 0, onPriceError, fetch: fetchFn } = options
+  const onError = onPriceError ? (_: PriceSource, err: unknown) => onPriceError(err) : undefined
+  const [balances, positions] = await Promise.all([
+    tokens.length ? provider.balances(owner, tokens, { symbol: true }) : Promise.resolve([]),
+    lp ? lpPositions(provider, owner, { ...(lp === true ? {} : lp), prices: combinePrices(sources, { onError }), ...(fetchFn ? { fetch: fetchFn } : {}), ...(onPriceError ? { onPriceError } : {}) }) : Promise.resolve([]),
+  ])
+  const held = balances.filter((b) => b.success && BigInt(b.balance) > 0n)
+  const prices = held.length ? await tokenPrices(provider, held.map((b) => b.token), { sources, ...(onError ? { onError } : {}), ...(fetchFn ? { fetch: fetchFn } : {}) }) : []
+  const list: PortfolioToken[] = held.map((b, i) => {
+    const p = prices[i]
+    const price = p?.price ?? null
+    return {
+      token: b.token,
+      native: b.native,
+      symbol: b.symbol ?? null,
+      balance: b.balance,
+      decimals: b.decimals,
+      formatted: b.formatted,
+      price,
+      value: price === null ? null : Number(b.formatted) * price,
+      priceSource: p?.source ?? null,
+    }
+  })
+  const tokensUsd = list.reduce((sum, t) => sum + (t.value ?? 0), 0)
+  const lpUsd = positions.reduce((sum, p) => sum + (p.valueUsd ?? 0), 0)
+  return {
+    totalUsd: tokensUsd + lpUsd,
+    tokensUsd,
+    lpUsd,
+    tokens: list.filter((t) => (t.value ?? 0) >= minUsd || (minUsd === 0 && t.value === null)).sort((a, b) => (b.value ?? -1) - (a.value ?? -1)),
+    lp: positions,
+    unpriced: list.filter((t) => t.price === null).length + positions.filter((p) => p.valueUsd === null).length,
+  }
+}