@w3lib/evm-batch-call 0.7.0 → 0.8.0

package/dist/simulate.d.ts

@@ -0,0 +1,186 @@
+/**
+ * 交易模拟（子路径 `@w3lib/evm-batch-call/simulate`）：发送前先看会发生什么——成不成功、花多少 gas、哪些资产进出、给了什么授权、风险提示。
+ *
+ * - EVM：`eth_simulateV1`（公共节点 publicnode / drpc / mainnet.base.org / bsc-dataseed 等都支持）：一次请求执行一串交易、状态逐笔延续，
+ *   `traceTransfers` 把主币转账也变成日志；资产变化和授权变化都从日志里算（ERC20 / 721 / 1155 Transfer、WETH Deposit / Withdrawal、Approval、
+ *   ApprovalForAll、Permit2 Approval）。不支持时退回 `eth_call` + `eth_estimateGas`：只能知道成不成功和 gas，资产变化只能按 calldata 估
+ * - Tron：`triggerconstantcontract`（能量、日志里的 TRC20 Transfer / Approval）；TRX 的变化只有 call_value
+ */
+import { type BigNumberish } from 'ethers';
+import type { BlockTag } from './aggregate.js';
+import type { Provider } from './provider.js';
+import { type DecodedCall } from './simulateDecode.js';
+export { decodeCalldata, decodeRevert, type DecodedCall, type DecodedType } from './simulateDecode.js';
+/** 要模拟的交易，字段与 buildSwap / buildRevokes / 流动性构建的 transactions 里的一致（多出来的字段忽略） */
+export interface SimulateTx {
+    from?: string;
+    to?: string;
+    data?: string;
+    /** 附带的主币（最小单位；Tron 是 sun） */
+    value?: BigNumberish;
+    gas?: BigNumberish;
+}
+/** 状态覆盖（eth_call / eth_simulateV1 的格式）：改余额、nonce、代码、存储 */
+export type StateOverrides = Record<string, {
+    balance?: string;
+    nonce?: string;
+    code?: string;
+    state?: Record<string, string>;
+    stateDiff?: Record<string, string>;
+}>;
+export interface SimulateOptions {
+    /** 发送者（交易里没有 from 时用），也是资产变化 / 授权变化的主体 */
+    from?: string;
+    /** 另外要统计资产变化、授权的地址（默认只有 from） */
+    watch?: readonly string[];
+    /** 按这个区块的状态模拟（默认最新） */
+    blockTag?: BlockTag;
+    stateOverrides?: StateOverrides;
+    /** 每笔交易的 gas 上限，默认 min(1000 万, 2500 万 / 笔数)：不同节点限制一个模拟里的总 gas */
+    gas?: bigint;
+    /** 估算手续费（gasUsed × 当前 gas 价格；不含 L1 数据费），默认 true */
+    fee?: boolean;
+    /** 给资产变化带美元价值（用 /price，按需加载）：true 用默认价格源，或传 tokenPrices 的 sources */
+    usd?: boolean | import('./price.js').TokenPricesOptions['sources'];
+    /** 对收到的代币做风险检查（用 /risk，按需加载，只支持 EVM 的 V2 池子能买卖的代币），有问题时加进 warnings */
+    risk?: boolean;
+    /** 不用 eth_simulateV1，直接 eth_call + estimateGas（调试 / 节点行为不一致时） */
+    forceCall?: boolean;
+}
+export type WarningSeverity = 'info' | 'warn' | 'danger';
+export interface SimulationWarning {
+    severity: WarningSeverity;
+    /**
+     * unlimited-approval / unknown-spender / approve-to-eoa / unlimited-nft-approval / no-code / large-value /
+     * token-risk / unknown-method / no-logs / no-state / reverted
+     */
+    code: string;
+    message: string;
+    /** 相关地址：授权类提示是被授权方，token-risk 是代币 */
+    address?: string;
+}
+export interface BalanceChange {
+    address: string;
+    /** 代币地址；主币是 'native' */
+    asset: string;
+    symbol: string | null;
+    decimals: number;
+    /** 带符号的最小单位数量 */
+    delta: string;
+    formatted: string;
+    usd?: number | null;
+    /** NFT（721 / 1155）：tokenId，数量是个数 */
+    tokenId?: string;
+    standard: 'native' | 'erc20' | 'erc721' | 'erc1155';
+}
+export interface ApprovalChange {
+    type: 'erc20' | 'permit2' | 'nft' | 'nft-token';
+    owner: string;
+    /** 代币 / NFT 合约 */
+    token: string;
+    symbol: string | null;
+    /** 被授权方（ERC20 的 spender、Permit2 的 spender、NFT 的 operator / approved） */
+    spender: string;
+    spenderName?: string;
+    /** 新的额度（最小单位）；NFT 的 ApprovalForAll 是 '1' / '0'，单个 NFT 是 tokenId */
+    amount: string;
+    unlimited: boolean;
+    /** 授权被取消（额度 0 / setApprovalForAll false） */
+    revoked: boolean;
+    /** Permit2：授权到期的时间（秒） */
+    expiration?: number;
+}
+/** 一条转账（所有地址之间的，不只是 from 的） */
+export interface SimulatedTransfer {
+    asset: string;
+    from: string;
+    to: string;
+    amount: string;
+    tokenId?: string;
+    standard: BalanceChange['standard'];
+}
+export interface SimulationResult {
+    success: boolean;
+    /** 失败原因：解码后的 revert 原因（Error / Panic / 常见自定义错误）或节点给的错误信息 */
+    error?: string;
+    /** revert 的原始数据 */
+    revertData?: string;
+    /** 消耗的 gas（Tron 是能量） */
+    gasUsed: string;
+    /** 估算的手续费（wei），不含 L1 数据费；Tron 没有 */
+    fee?: string;
+    balanceChanges: BalanceChange[];
+    approvalChanges: ApprovalChange[];
+    decoded: {
+        type: DecodedCall['type'];
+        protocol?: string;
+        method?: string;
+        summary: string;
+        args?: Record<string, unknown>;
+        calls?: DecodedCall[];
+    };
+    warnings: SimulationWarning[];
+    transfers: SimulatedTransfer[];
+    /** 原始日志 */
+    logs?: Array<{
+        address: string;
+        topics: string[];
+        data: string;
+    }>;
+    /** 用的模拟方式：'simulateV1'（有日志）、'eth_call'（只有成败和 gas）、'tron' */
+    mode: 'simulateV1' | 'eth_call' | 'tron';
+    returnData?: string;
+}
+export interface BatchSimulationResult {
+    /** 全部成功 */
+    success: boolean;
+    /** 每笔交易的结果，与输入一一对应 */
+    results: SimulationResult[];
+    /** 第一笔失败的下标 */
+    failedIndex?: number;
+    gasUsed: string;
+    fee?: string;
+    /** 汇总（同一个资产、同一个地址的变化相加；授权取最后的状态） */
+    balanceChanges: BalanceChange[];
+    approvalChanges: ApprovalChange[];
+    warnings: SimulationWarning[];
+    mode: SimulationResult['mode'];
+}
+/**
+ * 模拟一笔交易（不签名、不发送）。可以直接传 `buildSwap` / `buildRevokes` / 流动性构建里的交易。
+ *
+ * ```ts
+ * const plan = await buildSwap(provider, user, { tokenIn, tokenOut, amountInFormatted: '1' })
+ * const sim = await simulate(provider, plan.transactions[1], { from: user })      // 兑换这一笔（授权在前，没发出去时用 simulateBatch）
+ * if (!sim.success) throw new Error(sim.error)
+ * sim.balanceChanges   // [{ asset: 'native', delta: '-1000…', formatted: '-1', … }, { asset: USDC, formatted: '2300.5', … }]
+ * sim.warnings         // [{ severity: 'warn', code: 'unknown-spender', … }]
+ * ```
+ */
+export declare function simulate(provider: Provider, tx: SimulateTx, options?: SimulateOptions): Promise<SimulationResult>;
+/**
+ * 按顺序模拟一串依赖前一笔的交易（如先 approve 再兑换：`plan.transactions`）。eth_simulateV1 在同一个区块里依次执行，状态延续；
+ * 不支持的节点退回单笔 eth_call，后面的交易看不到前面的结果（结果里有 `no-state` 提示；Tron 同理）。
+ *
+ * ```ts
+ * const sim = await simulateBatch(provider, plan.transactions, { from: user, usd: true })
+ * sim.success; sim.balanceChanges   // 汇总：整个流程你付出 / 收到什么
+ * ```
+ */
+export declare function simulateBatch(provider: Provider, txs: readonly SimulateTx[] | {
+    transactions: readonly SimulateTx[];
+}, options?: SimulateOptions): Promise<BatchSimulationResult>;
+/**
+ * 模拟通过才发送的一行守卫：`simulate` 失败或有 danger 级别的提示时抛错，否则返回模拟结果，由调用方继续发送。
+ *
+ * ```ts
+ * await assertSimulation(simulate(provider, tx, { from }))
+ * await batchCall(provider, key, [{ to: tx.to, data: tx.data, value: tx.value }])
+ * ```
+ */
+export declare function assertSimulation<T extends Pick<SimulationResult, 'success' | 'error' | 'warnings'> | Pick<BatchSimulationResult, 'success' | 'warnings'> & {
+    results: Array<Pick<SimulationResult, 'error'>>;
+}>(simulation: Promise<T> | T, options?: {
+    allowDanger?: boolean;
+}): Promise<T>;
+//# sourceMappingURL=simulate.d.ts.map

package/dist/simulate.d.ts.map

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