@w3lib/evm-batch-call 0.6.0 → 0.8.0

package/src/smartAccount/userOp.ts

@@ -0,0 +1,180 @@
+import { AbiCoder, Interface, TypedDataEncoder, concat, getAddress, getBytes, keccak256, toBeHex, zeroPadValue, type Authorization } from 'ethers'
+
+/** ERC-4337 EntryPoint 的两个版本，各主流链上地址相同 */
+export const ENTRY_POINT_V07 = '0x0000000071727De22E5E9d8BAf0edAc6f37da032'
+export const ENTRY_POINT_V08 = '0x4337084D9E255Ff0702461CF8895CE9E3b5Ff108'
+
+export type EntryPointVersion = '0.7' | '0.8'
+
+export function entryPointAddress(version: EntryPointVersion): string {
+  return version === '0.8' ? ENTRY_POINT_V08 : ENTRY_POINT_V07
+}
+
+/** EntryPoint v0.8 把 initCode 以 0x7702 开头（至少 20 字节）的 UserOperation 当作 EIP-7702 账户 */
+export const EIP7702_MARKER = '0x7702000000000000000000000000000000000000'
+
+/** UserOperation（bundler JSON-RPC 的“拆开”格式，数值用 bigint） */
+export interface UserOperation {
+  sender: string
+  nonce: bigint
+  /** 账户还没部署时创建它的工厂 + calldata；EIP-7702 账户用 EIP7702_MARKER 作为 factory */
+  factory?: string
+  factoryData?: string
+  callData: string
+  callGasLimit: bigint
+  verificationGasLimit: bigint
+  preVerificationGas: bigint
+  maxFeePerGas: bigint
+  maxPriorityFeePerGas: bigint
+  paymaster?: string
+  paymasterVerificationGasLimit?: bigint
+  paymasterPostOpGasLimit?: bigint
+  paymasterData?: string
+  signature: string
+  /** EIP-7702 授权（账户还没委托时随 UserOperation 一起交给 bundler） */
+  eip7702Auth?: Authorization
+}
+
+/** 打包后的 UserOperation（EntryPoint.handleOps 的参数） */
+export interface PackedUserOperation {
+  sender: string
+  nonce: bigint
+  initCode: string
+  callData: string
+  accountGasLimits: string
+  preVerificationGas: bigint
+  gasFees: string
+  paymasterAndData: string
+  signature: string
+}
+
+const u128 = (value: bigint) => zeroPadValue(toBeHex(value), 16)
+
+export function initCodeOf(op: Pick<UserOperation, 'factory' | 'factoryData'>): string {
+  return op.factory ? concat([op.factory, op.factoryData ?? '0x']) : '0x'
+}
+
+export function paymasterAndDataOf(op: UserOperation): string {
+  if (!op.paymaster) {
+    return '0x'
+  }
+  return concat([op.paymaster, u128(op.paymasterVerificationGasLimit ?? 0n), u128(op.paymasterPostOpGasLimit ?? 0n), op.paymasterData ?? '0x'])
+}
+
+export function packUserOp(op: UserOperation): PackedUserOperation {
+  return {
+    sender: getAddress(op.sender),
+    nonce: op.nonce,
+    initCode: initCodeOf(op),
+    callData: op.callData,
+    accountGasLimits: concat([u128(op.verificationGasLimit), u128(op.callGasLimit)]),
+    preVerificationGas: op.preVerificationGas,
+    gasFees: concat([u128(op.maxPriorityFeePerGas), u128(op.maxFeePerGas)]),
+    paymasterAndData: paymasterAndDataOf(op),
+    signature: op.signature,
+  }
+}
+
+/** v0.8 的 EIP-712 类型（userOpHash 就是它的摘要，所以钱包可以直接 signTypedData 签） */
+export const USER_OP_TYPES = {
+  PackedUserOperation: [
+    { name: 'sender', type: 'address' },
+    { name: 'nonce', type: 'uint256' },
+    { name: 'initCode', type: 'bytes' },
+    { name: 'callData', type: 'bytes' },
+    { name: 'accountGasLimits', type: 'bytes32' },
+    { name: 'preVerificationGas', type: 'uint256' },
+    { name: 'gasFees', type: 'bytes32' },
+    { name: 'paymasterAndData', type: 'bytes' },
+  ],
+}
+
+/**
+ * v0.8 的 EIP-712 数据。EIP-7702 账户（initCode 以 0x7702 开头）：EntryPoint 算哈希时把 initCode 换成
+ * “账户当前委托的合约地址 ‖ initCode[20:]”，所以要传 delegate（账户将要委托 / 已委托的合约）
+ */
+export function userOpTypedData(op: UserOperation, entryPoint: string, chainId: number, delegate?: string) {
+  const packed = packUserOp(op)
+  let initCode = packed.initCode
+  if (initCode.toLowerCase().startsWith('0x7702') && getBytes(initCode).length >= 20) {
+    if (!delegate) {
+      throw new Error('delegate is required to hash an EIP-7702 UserOperation')
+    }
+    initCode = concat([getAddress(delegate), `0x${initCode.slice(2 + 40)}`])
+  }
+  const { signature: _signature, ...message } = packed
+  return {
+    domain: { name: 'ERC4337', version: '1', chainId, verifyingContract: getAddress(entryPoint) },
+    types: USER_OP_TYPES,
+    message: { ...message, initCode },
+  }
+}
+
+/** UserOperation 哈希（与 EntryPoint.getUserOpHash 一致） */
+export function getUserOpHash(op: UserOperation, entryPoint: string, chainId: number, version: EntryPointVersion, delegate?: string): string {
+  if (version === '0.8') {
+    const { domain, types, message } = userOpTypedData(op, entryPoint, chainId, delegate)
+    return TypedDataEncoder.hash(domain, types, message)
+  }
+  const p = packUserOp(op)
+  const coder = AbiCoder.defaultAbiCoder()
+  const inner = keccak256(
+    coder.encode(
+      ['address', 'uint256', 'bytes32', 'bytes32', 'bytes32', 'uint256', 'bytes32', 'bytes32'],
+      [p.sender, p.nonce, keccak256(p.initCode), keccak256(p.callData), p.accountGasLimits, p.preVerificationGas, p.gasFees, keccak256(p.paymasterAndData)],
+    ),
+  )
+  return keccak256(coder.encode(['bytes32', 'address', 'uint256'], [inner, getAddress(entryPoint), chainId]))
+}
+
+/** JSON-RPC 数值：0x 十六进制、没有前导零 */
+export const quantity = (v: bigint | number): string => `0x${v.toString(16)}`
+
+/** bundler JSON-RPC 的 UserOperation（数值为 0x 十六进制） */
+export function userOpToRpc(op: UserOperation): Record<string, unknown> {
+  const q = quantity
+  const rpc: Record<string, unknown> = { sender: getAddress(op.sender), nonce: q(op.nonce), callData: op.callData }
+  if (op.factory) {
+    rpc.factory = op.factory
+    rpc.factoryData = op.factoryData ?? '0x'
+  }
+  Object.assign(rpc, {
+    callGasLimit: q(op.callGasLimit),
+    verificationGasLimit: q(op.verificationGasLimit),
+    preVerificationGas: q(op.preVerificationGas),
+    maxFeePerGas: q(op.maxFeePerGas),
+    maxPriorityFeePerGas: q(op.maxPriorityFeePerGas),
+  })
+  if (op.paymaster) {
+    Object.assign(rpc, {
+      paymaster: op.paymaster,
+      paymasterVerificationGasLimit: q(op.paymasterVerificationGasLimit ?? 0n),
+      paymasterPostOpGasLimit: q(op.paymasterPostOpGasLimit ?? 0n),
+      paymasterData: op.paymasterData ?? '0x',
+    })
+  }
+  rpc.signature = op.signature
+  if (op.eip7702Auth) {
+    const a = op.eip7702Auth
+    rpc.eip7702Auth = { chainId: q(BigInt(a.chainId)), address: a.address, nonce: q(BigInt(a.nonce)), yParity: a.signature.yParity === 0 ? '0x0' : '0x1', r: a.signature.r, s: a.signature.s }
+  }
+  return rpc
+}
+
+/** 估算 gas 时用的占位签名（65 字节、格式合法的 ECDSA 签名，账户校验时不会因为长度 / 格式直接 revert） */
+export const DUMMY_SIGNATURE = `0x${'f'.repeat(31)}0${'0'.repeat(32)}7${'a'.repeat(63)}1c`
+
+export const entryPointInterface = new Interface([
+  'function handleOps((address sender, uint256 nonce, bytes initCode, bytes callData, bytes32 accountGasLimits, uint256 preVerificationGas, bytes32 gasFees, bytes paymasterAndData, bytes signature)[] ops, address beneficiary)',
+  'function getNonce(address sender, uint192 key) view returns (uint256)',
+  'function getUserOpHash((address sender, uint256 nonce, bytes initCode, bytes callData, bytes32 accountGasLimits, uint256 preVerificationGas, bytes32 gasFees, bytes paymasterAndData, bytes signature) userOp) view returns (bytes32)',
+  'error FailedOp(uint256 opIndex, string reason)',
+  'error FailedOpWithRevert(uint256 opIndex, string reason, bytes inner)',
+  'event UserOperationEvent(bytes32 indexed userOpHash, address indexed sender, address indexed paymaster, uint256 nonce, bool success, uint256 actualGasCost, uint256 actualGasUsed)',
+  'event UserOperationRevertReason(bytes32 indexed userOpHash, address indexed sender, uint256 nonce, bytes revertReason)',
+])
+
+/** 十六进制数值 → bigint（bundler 返回的字段） */
+export function hexToBigInt(value: unknown): bigint {
+  return value === undefined || value === null ? 0n : BigInt(value as string)
+}

package/src/subpaths/approvals.ts

@@ -0,0 +1,48 @@
+/**
+ * 授权管理（子路径 `@w3lib/evm-batch-call/approvals`）：批量查地址给出的授权（ERC20、Permit2、NFT 的 setApprovalForAll），
+ * 按 Approval 事件发现授权过的代币，批量撤销。不放在主入口，不用时打包不会带上这部分代码；发送的代码按需加载。
+ *
+ * ```ts
+ * import { getApprovals, revokeApprovals } from '@w3lib/evm-batch-call/approvals'
+ *
+ * const list = await getApprovals(user, { chainId: 56, tokens: [USDT, CAKE] })
+ * await revokeApprovals(provider, key, list.filter((a) => a.type !== 'nft' && a.unlimited))
+ * ```
+ */
+import { approvals, type Approval, type ApprovalsQuery } from '../approvals.js'
+import { resolve, type ShortcutProviderOptions } from '../shortcuts.js'
+
+export {
+  PERMIT2_ADDRESS,
+  approvals,
+  buildRevokes,
+  knownSpenders,
+  revokeApprovals,
+  scanApprovals,
+  type Approval,
+  type ApprovalScanOptions,
+  type ApprovalScanProgress,
+  type ApprovalScanResult,
+  type ApprovalsQuery,
+  type Erc20Approval,
+  type KnownSpender,
+  type NftApproval,
+  type Permit2Approval,
+  type RevokeResult,
+  type RevokeTx,
+} from '../approvals.js'
+
+export interface GetApprovalsOptions extends ApprovalsQuery, ShortcutProviderOptions {}
+
+/**
+ * 查地址给出的授权，节点参数与 getBalances 相同。默认检查已知的 Router / 聚合器 / NFT 市场。
+ *
+ * ```ts
+ * await getApprovals(user, { chainId: 56, tokens: [USDT, CAKE] })
+ * // [{ type: 'erc20', token: USDT, symbol: 'USDT', spender: '0x1111…', spenderName: '1inch Router v6', amount: '…', unlimited: true }, …]
+ * ```
+ */
+export function getApprovals(owner: string, options: GetApprovalsOptions): Promise<Approval[]> {
+  const { provider, own } = resolve(options, ['tokens', 'spenders', 'pairs', 'permit2', 'nfts', 'operators', 'nftPairs', 'includeZero'])
+  return approvals(provider, owner, own)
+}

package/src/subpaths/dividends.ts

@@ -0,0 +1,47 @@
+/**
+ * Flap 分红（子路径 `@w3lib/evm-batch-call/dividends`）：查持有人在 Flap（flap.sh，BNB Chain 发币平台）税收代币上累计的分红
+ * （可领取 / 已领取、分红资产、美元价值），批量领取（可用 7702 / 4337 / 5792 合成一笔原子交易）。
+ * 不放在主入口，不用时打包不会带上这部分代码；发送和模拟的代码按需加载。只支持 BSC，合约形态和核实范围见 README「Flap 分红」。
+ *
+ * ```ts
+ * import { getDividends, claimDividends } from '@w3lib/evm-batch-call/dividends'
+ *
+ * const { items } = await getDividends(user, { chainId: 56, discover: true })   // 或 tokens: [flapToken]
+ * await claimDividends(provider, key, items, { mode: '7702', simulate: true })
+ * ```
+ */
+import { dividends, type DividendsOptions, type DividendsResult } from '../dividends.js'
+import { resolve, type ShortcutProviderOptions } from '../shortcuts.js'
+
+export {
+  FLAP_DIVIDEND_CHAINS,
+  FLAP_TOKEN_SUFFIXES,
+  buildClaimDividends,
+  claimDividends,
+  dividends,
+  scanDividendTokens,
+  type ClaimDividendResult,
+  type ClaimDividendTx,
+  type ClaimDividendsOptions,
+  type DividendItem,
+  type DividendScanOptions,
+  type DividendUnsupported,
+  type DividendsOptions,
+  type DividendsResult,
+} from '../dividends.js'
+
+export interface GetDividendsOptions extends DividendsOptions, ShortcutProviderOptions {}
+
+/**
+ * 查持有人在 Flap 代币上的分红，节点参数与 getBalances 相同（chainId 只能是 56）。
+ * tokens 给定要查的代币；discover 从收到过的 Transfer 事件里发现（卖光的代币上之前累计的分红也能领）。
+ *
+ * ```ts
+ * const { items, unsupported } = await getDividends(user, { chainId: 56, tokens: [flapToken] })
+ * // [{ token, symbol, balance, claimable: '88823258714382840', asset: '0x9b8E…', assetSymbol: 'FXIon', usd: null, dividendContract, … }]
+ * ```
+ */
+export function getDividends(owner: string, options: GetDividendsOptions = {}): Promise<DividendsResult> {
+  const { provider, own } = resolve(options, ['tokens', 'discover', 'prices', 'fetch', 'includeZero'])
+  return dividends(provider, owner, own as DividendsOptions)
+}

package/src/subpaths/fees.ts

@@ -0,0 +1,43 @@
+/**
+ * 手续费估算（子路径 `@w3lib/evm-batch-call/fees`）：EIP-1559 的三档费用建议、一笔交易的手续费（含 L1 数据费），
+ * Tron 按能量 / 带宽和账户剩余的资源算要烧的 TRX。不放在主入口，不用时打包不会带上这部分代码。
+ *
+ * ```ts
+ * import { getCostEstimate, getFeeEstimate } from '@w3lib/evm-batch-call/fees'
+ *
+ * await getFeeEstimate({ chainId: 1 })
+ * await getCostEstimate({ from: user, to: USDT, data }, { chainId: 728126428 })
+ * ```
+ */
+import { estimateCost, estimateFees, type CostCall, type CostEstimate, type EstimateCostOptions, type EstimateFeesOptions, type FeeEstimate } from '../fees.js'
+import { resolve, type ShortcutProviderOptions } from '../shortcuts.js'
+
+export {
+  estimateCost,
+  estimateFees,
+  type CostCall,
+  type CostEstimate,
+  type EstimateCostOptions,
+  type EstimateFeesOptions,
+  type EvmCostEstimate,
+  type FeeEstimate,
+  type FeeLevel,
+  type FeeLevelEstimate,
+  type TronCost,
+} from '../fees.js'
+
+export interface GetFeeEstimateOptions extends EstimateFeesOptions, ShortcutProviderOptions {}
+
+/** 当前的三档手续费建议（EVM 链），节点参数与 getBalances 相同 */
+export function getFeeEstimate(options: GetFeeEstimateOptions = {}): Promise<FeeEstimate> {
+  const { provider, own } = resolve(options, ['blocks', 'percentiles', 'baseFeeMultiplier'])
+  return estimateFees(provider, own)
+}
+
+export interface GetCostEstimateOptions extends EstimateCostOptions, ShortcutProviderOptions {}
+
+/** 一笔交易的手续费（EVM：gas × 价格 + L1 数据费；Tron：要烧的 TRX） */
+export function getCostEstimate(call: CostCall, options: GetCostEstimateOptions = {}): Promise<CostEstimate> {
+  const { provider, own } = resolve(options, ['blocks', 'percentiles', 'baseFeeMultiplier', 'level', 'fees'])
+  return estimateCost(provider, call, own)
+}

package/src/subpaths/history.ts

@@ -0,0 +1,41 @@
+/**
+ * 交易历史（子路径 `@w3lib/evm-batch-call/history`）：一个地址的转账 / 兑换 / 授权 / 流动性 / 铸造记录，带解码后的类型、资产变化和手续费。
+ * 数据来源可替换、可故障切换：Blockscout（免 Key，默认）、Etherscan v2（传 apiKey）、纯 RPC 日志、Tron 的 TronGrid。
+ * 不放在主入口，不用时打包不会带上这部分代码。
+ *
+ * ```ts
+ * import { getHistory } from '@w3lib/evm-batch-call/history'
+ *
+ * const page = await getHistory(user, { chainId: 1, limit: 20 })
+ * const more = await getHistory(user, { chainId: 1, cursor: page.nextCursor, types: ['swap'] })
+ * await getHistory(user, { chainId: 56, source: ['etherscan', 'rpc'], apiKey })
+ * ```
+ */
+import { history, type HistoryOptions, type HistoryResult } from '../history.js'
+import { resolve, type ShortcutProviderOptions } from '../shortcuts.js'
+
+export {
+  HistorySourceError,
+  buildActivities,
+  history,
+  type Activity,
+  type ActivityChange,
+  type ActivityType,
+  type HistoryAdapter,
+  type HistoryOptions,
+  type HistoryQuery,
+  type HistoryResult,
+  type HistorySource,
+  type RawMove,
+  type RawPage,
+  type RawTx,
+} from '../history.js'
+export { BLOCKSCOUT_APIS, blockscoutSource, etherscanSource, explorerSource, rpcSource, trongridSource, type RpcSourceOptions, type TrongridSourceOptions } from '../historySources.js'
+
+export interface GetHistoryOptions extends HistoryOptions, ShortcutProviderOptions {}
+
+/** 查一个地址的历史活动，节点参数与 getBalances 相同（只有 rpc 来源会用到节点） */
+export function getHistory(address: string, options: GetHistoryOptions = {}): Promise<HistoryResult> {
+  const { provider, own } = resolve(options, ['source', 'apiKey', 'limit', 'cursor', 'types', 'before', 'after', 'nft', 'maxPages', 'fetch'])
+  return history(provider, address, own)
+}

package/src/subpaths/names.ts

@@ -0,0 +1,43 @@
+/**
+ * 域名解析（子路径 `@w3lib/evm-batch-call/names`）：ENS、SPACE ID（.bnb）、Basenames（.base.eth），名字 → 地址、地址 → 名字。
+ * 不放在主入口，不用时打包不会带上这部分代码。
+ *
+ * ```ts
+ * import { getAddressNames, getNameAddresses } from '@w3lib/evm-batch-call/names'
+ *
+ * await getNameAddresses(['vitalik.eth'], { chainId: 1 })
+ * await getAddressNames([user], { chainId: 56 })
+ * ```
+ */
+import { lookupAddresses, resolveNames, type AddressName, type NamesOptions, type ResolvedName } from '../names.js'
+import { resolve, type ShortcutProviderOptions } from '../shortcuts.js'
+
+export { NAME_SERVICES, lookupAddresses, resolveNames, type AddressName, type NameService, type NamesOptions, type ResolvedName } from '../names.js'
+
+export interface GetNamesOptions extends NamesOptions, ShortcutProviderOptions {}
+
+/**
+ * 名字 → 地址，节点参数与 getBalances 相同（用这条链的域名服务：Ethereum 是 ENS，BSC 是 SPACE ID，Base 是 Basenames）。
+ *
+ * ```ts
+ * await getNameAddresses(['vitalik.eth', 'nick.eth'], { chainId: 1 })
+ * // [{ name: 'vitalik.eth', normalized: 'vitalik.eth', address: '0xd8dA…6045', service: 'ens' }, …]
+ * ```
+ */
+export function getNameAddresses(names: readonly string[], options: GetNamesOptions = {}): Promise<ResolvedName[]> {
+  const { provider, own } = resolve(options, ['services'])
+  return resolveNames(provider, names, own)
+}
+
+/**
+ * 地址 → 名字（反查的主名字，正查核对过）。
+ *
+ * ```ts
+ * await getAddressNames(['0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'], { chainId: 1 })
+ * // [{ address: '0xd8dA…', name: 'vitalik.eth', service: 'ens' }]
+ * ```
+ */
+export function getAddressNames(addresses: readonly string[], options: GetNamesOptions = {}): Promise<AddressName[]> {
+  const { provider, own } = resolve(options, ['services'])
+  return lookupAddresses(provider, addresses, own)
+}

package/src/subpaths/permit.ts

@@ -0,0 +1,39 @@
+/**
+ * 免 gas 授权（子路径 `@w3lib/evm-batch-call/permit`）：EIP-2612 permit、DAI 风格 permit、Permit2（PermitSingle / PermitBatch / permitTransferFrom）。
+ * 构建 EIP-712 数据 → 用 ethers Signer 签名 → 本地验证 → 生成上链的 calldata。不放在主入口，不用时打包不会带上。
+ *
+ * ```ts
+ * import { buildPermit, signPermit, permitCalldata } from '@w3lib/evm-batch-call/permit'
+ *
+ * const permit = await buildPermit(provider, { token: USDC, owner, spender: router, value: 100_000_000n }) // 精确额度，30 分钟有效
+ * const signed = await signPermit(signer, permit)      // signer：Wallet / 浏览器钱包的 JsonRpcSigner
+ * const data = permitCalldata(signed)                  // token.permit(...) 的 calldata，谁都可以提交
+ * ```
+ */
+export {
+  DEFAULT_PERMIT_DEADLINE,
+  MAX_PERMIT_DEADLINE,
+  MAX_UINT160,
+  PERMIT2_ADDRESS,
+  assertPermitSafe,
+  buildPermit,
+  buildPermit2Batch,
+  buildPermit2Single,
+  buildPermit2Transfer,
+  detectPermit,
+  permit2Calldata,
+  permitCalldata,
+  permitTransferFromCalldata,
+  signPermit,
+  verifyPermitSignature,
+  type BuildPermitParams,
+  type Permit,
+  type Permit2AllowanceParams,
+  type Permit2BatchParams,
+  type Permit2TransferParams,
+  type PermitKind,
+  type PermitOptions,
+  type PermitSupport,
+  type SignedPermit,
+  type TypedData,
+} from '../permit.js'

package/src/subpaths/price.ts

@@ -0,0 +1,60 @@
+/**
+ * 价格（子路径 `@w3lib/evm-batch-call/price`）：代币的美元价格（DefiLlama 当前 / 历史价格，没有收录的从链上 V2 / V3 池子算）、
+ * 组合价格源、地址的资产总值。不放在主入口，不用时打包不会带上这部分代码。
+ *
+ * ```ts
+ * import { getTokenPrices, getPortfolio } from '@w3lib/evm-batch-call/price'
+ *
+ * await getTokenPrices([NATIVE_TOKEN, USDT, newToken], { chainId: 56 })
+ * await getPortfolio(user, { chainId: 56, tokens: [NATIVE_TOKEN, USDT], lp: true })
+ * ```
+ */
+import { portfolio, type Portfolio, type PortfolioOptions } from '../portfolio.js'
+import { tokenPrices, type TokenPrice, type TokenPricesOptions } from '../price.js'
+import { resolve, type ShortcutProviderOptions } from '../shortcuts.js'
+
+export { portfolio, type Portfolio, type PortfolioOptions, type PortfolioToken } from '../portfolio.js'
+export {
+  DEFILLAMA_CHAINS,
+  STABLECOINS,
+  combinePrices,
+  defillamaPrices,
+  onchainPrices,
+  priceKeyOf,
+  tokenPrices,
+  type DefillamaPriceOptions,
+  type OnchainPriceOptions,
+  type PriceSource,
+  type PriceSourceContext,
+  type TokenPrice,
+  type TokenPricesOptions,
+} from '../price.js'
+
+export interface GetTokenPricesOptions extends TokenPricesOptions, ShortcutProviderOptions {}
+
+/**
+ * 查代币的美元价格（主币用 NATIVE_TOKEN），节点参数与 getBalances 相同。
+ *
+ * ```ts
+ * await getTokenPrices([NATIVE_TOKEN, USDT], { chainId: 56 })
+ * // [{ token: '0xEeee…', native: true, price: 612.3, source: 'defillama' }, { token: USDT, …, price: 1, source: 'defillama' }]
+ * ```
+ */
+export function getTokenPrices(tokens: readonly string[], options: GetTokenPricesOptions = {}): Promise<TokenPrice[]> {
+  const { provider, own } = resolve(options, ['sources', 'onError', 'fetch'])
+  return tokenPrices(provider, tokens, own)
+}
+
+export interface GetPortfolioOptions extends PortfolioOptions, ShortcutProviderOptions {}
+
+/**
+ * 地址的资产总值：传入代币的余额 × 价格，可选加上 LP 仓位（lp: true）。
+ *
+ * ```ts
+ * const p = await getPortfolio(user, { chainId: 56, tokens: [NATIVE_TOKEN, USDT, CAKE], lp: true })
+ * ```
+ */
+export function getPortfolio(owner: string, options: GetPortfolioOptions): Promise<Portfolio> {
+  const { provider, overrides, own } = resolve(options, ['tokens', 'sources', 'lp', 'minUsd', 'onPriceError', 'fetch'])
+  return portfolio(provider, owner, { ...(own as PortfolioOptions), ...(overrides.signal ? { signal: overrides.signal } : {}) })
+}

package/src/subpaths/rewards.ts

@@ -0,0 +1,46 @@
+/**
+ * 一键领取手续费和挖矿奖励（子路径 `@w3lib/evm-batch-call/rewards`）：V3 / V4 仓位（含 Tron 的 SunSwap V3）未领取的手续费、
+ * PancakeSwap V3 MasterChef 的 CAKE（和质押仓位的手续费）、Aerodrome / Velodrome Slipstream gauge 的奖励。
+ * 不放在主入口，不用时打包不会带上这部分代码。
+ *
+ * - getClaimable：只读，列出每个仓位能领什么（数量 + 美元价值）
+ * - buildClaimAll：合并成尽量少的交易（V3 multicall、V4 一次 modifyLiquidities、MasterChef multicall），先模拟、剔除会失败的项
+ * - claimAll：构建后签名发送；`mode: '7702' | '4337' | '5792'` 时合成一笔原子交易
+ *
+ * ```ts
+ * import { claimAll, getClaimable } from '@w3lib/evm-batch-call/rewards'
+ *
+ * const c = await getClaimable(user, { chainId: 56, prices: true })   // c.items、c.totals、c.usd
+ * const { status, claimed } = await claimAll(multi, privateKey, { minUsd: 1 })
+ * ```
+ */
+import { resolve, type ShortcutProviderOptions } from '../shortcuts.js'
+import { claimable } from '../rewards/index.js'
+import type { Claimable, ClaimableOptions } from '../rewards/types.js'
+
+export { FARM_PROTOCOLS, buildClaimAll, claimAll, claimable } from '../rewards/index.js'
+export type {
+  ClaimAllOptions,
+  ClaimAllSendOptions,
+  ClaimAmount,
+  ClaimItem,
+  ClaimKind,
+  ClaimPlan,
+  ClaimResult,
+  ClaimSkipped,
+  ClaimTx,
+  ClaimTxResult,
+  Claimable,
+  ClaimableOptions,
+  FarmProtocol,
+} from '../rewards/types.js'
+export type { LpProtocol } from '../lp.js'
+export type { SignerInput, WriteResult, WriteStatus } from '../subpaths/write.js'
+
+export interface GetClaimableOptions extends ClaimableOptions, ShortcutProviderOptions {}
+
+/** 查一个地址能领取的手续费和挖矿奖励，节点参数与 getBalances 相同 */
+export function getClaimable(owner: string, options: GetClaimableOptions = {}): Promise<Claimable> {
+  const { provider, overrides, own } = resolve(options, ['protocols', 'fees', 'rewards', 'v4', 'farms', 'gauges', 'maxPositions', 'prices', 'onPriceError', 'fetch'])
+  return claimable(provider, owner, { ...overrides, ...own })
+}

package/src/subpaths/risk.ts

@@ -0,0 +1,23 @@
+/**
+ * 代币风险检查（子路径 `@w3lib/evm-batch-call/risk`）：模拟买入 / 转账 / 卖出，算出买卖税、判断貔貅盘，看是不是可升级代理、owner 有没有放弃。
+ * 不放在主入口，不用时打包不会带上这部分代码（含约 2.7KB 的探测合约字节码）。
+ *
+ * ```ts
+ * import { getTokenRisks } from '@w3lib/evm-batch-call/risk'
+ *
+ * const [risk] = await getTokenRisks([token], { chainId: 56 })
+ * if (risk.honeypot) alert('卖不出')
+ * ```
+ */
+import { tokenRisks, type TokenRisk, type TokenRiskOptions } from '../risk.js'
+import { resolve, type ShortcutProviderOptions } from '../shortcuts.js'
+
+export { tokenRisks, type ProbeStage, type TokenRisk, type TokenRiskOptions } from '../risk.js'
+
+export interface GetTokenRisksOptions extends TokenRiskOptions, ShortcutProviderOptions {}
+
+/** 检查代币的风险，节点参数与 getBalances 相同 */
+export function getTokenRisks(tokens: readonly string[], options: GetTokenRisksOptions = {}): Promise<TokenRisk[]> {
+  const { provider, own } = resolve(options, ['amount', 'protocols'])
+  return tokenRisks(provider, tokens, own)
+}

package/src/subpaths/simulate.ts

@@ -0,0 +1,51 @@
+/**
+ * 交易模拟（子路径 `@w3lib/evm-batch-call/simulate`）：发送前先看一笔（或一串依赖的）交易会发生什么——成不成功、gas、
+ * 哪些资产进出（含美元价值）、给了什么授权、calldata 解码、风险提示。可以直接传 `buildSwap` / `buildRevokes` / 流动性构建的交易。
+ * 不放在主入口，不用时打包不会带上这部分代码。EVM 用 `eth_simulateV1`（不支持时退回 `eth_call`），Tron 用 `triggerconstantcontract`。
+ *
+ * ```ts
+ * import { getSimulation, getBatchSimulation } from '@w3lib/evm-batch-call/simulate'
+ *
+ * const sim = await getSimulation({ to: router, data, value }, { chainId: 1, from: user, usd: true })
+ * if (sim.warnings.some((w) => w.severity === 'danger')) alert(sim.warnings[0].message)
+ * const flow = await getBatchSimulation(plan.transactions, { chainId: 1, from: user }) // approve + swap，状态延续
+ * ```
+ */
+import { simulate, simulateBatch, type BatchSimulationResult, type SimulateOptions, type SimulateTx, type SimulationResult } from '../simulate.js'
+import { resolve, type ShortcutProviderOptions } from '../shortcuts.js'
+
+export {
+  assertSimulation,
+  decodeCalldata,
+  decodeRevert,
+  simulate,
+  simulateBatch,
+  type ApprovalChange,
+  type BalanceChange,
+  type BatchSimulationResult,
+  type DecodedCall,
+  type DecodedType,
+  type SimulatedTransfer,
+  type SimulateOptions,
+  type SimulateTx,
+  type SimulationResult,
+  type SimulationWarning,
+  type StateOverrides,
+  type WarningSeverity,
+} from '../simulate.js'
+
+const OWN = ['from', 'watch', 'stateOverrides', 'gas', 'fee', 'usd', 'risk', 'forceCall'] as const
+
+export interface GetSimulationOptions extends SimulateOptions, ShortcutProviderOptions {}
+
+/** 模拟一笔交易，节点参数与 getBalances 相同 */
+export function getSimulation(tx: SimulateTx, options: GetSimulationOptions = {}): Promise<SimulationResult> {
+  const { provider, overrides, own } = resolve(options, OWN)
+  return simulate(provider, tx, { ...own, ...(overrides.blockTag === undefined ? {} : { blockTag: overrides.blockTag }) })
+}
+
+/** 按顺序模拟一串依赖前一笔的交易（也可以直接传 buildSwap 等的结果），节点参数与 getBalances 相同 */
+export function getBatchSimulation(txs: readonly SimulateTx[] | { transactions: readonly SimulateTx[] }, options: GetSimulationOptions = {}): Promise<BatchSimulationResult> {
+  const { provider, overrides, own } = resolve(options, OWN)
+  return simulateBatch(provider, txs, { ...own, ...(overrides.blockTag === undefined ? {} : { blockTag: overrides.blockTag }) })
+}