hermes-swap 0.6.9 → 0.6.10

package/dist/cjs/aggregator.cjs

@@ -90,6 +90,20 @@ var _Aggregator = class {
       return "unknown";
     }
   }
+  emitTrace(txReq, chain, level, stage, message) {
+    var _a;
+    (_a = txReq == null ? void 0 : txReq.trace) == null ? void 0 : _a.call(txReq, {
+      ts: Date.now(),
+      chain,
+      level,
+      stage,
+      message
+    });
+  }
+  trace(chain, txReq, level, stage, message) {
+    _Aggregator.traceLog(chain, level, message);
+    this.emitTrace(txReq, chain, level, stage, message);
+  }
   getAggregator(chain) {
     if (!this.aggregatorMap.has(chain)) {
       throw new Error(`Aggregator not found for chain: ${chain}`);
@@ -311,10 +325,13 @@ var _Aggregator = class {
   }
   async swapAndBridge(params, txReq = {}) {
     var _a, _b;
+    const traceReq = txReq;
     const useBundle = this.shouldUseBundle(params.chain, txReq);
-    _Aggregator.traceLog(
+    this.trace(
       params.chain,
+      traceReq,
       "log",
+      "hermes-swapAndBridge-开始",
       `swapAndBridge开始, user=${params.user}, amountInWeis=[${params.amountInWeis.join(",")}], bridgeType=${params.bridgeType}, destChain=${params.destChain}, useBundle=${useBundle}`
     );
     const startTs = Date.now();
@@ -357,14 +374,26 @@ var _Aggregator = class {
       const { gasLimit: _ignore, ...estimationOverrides } = txReq;
       const args = [params.user, params.amountInWeis, swapParamsList, params.minAmountOutLists, bridgeArgs, params.totalMinAmountOut];
       try {
+        this.trace(params.chain, traceReq, "log", "hermes-swapAndBridge-estimateGas-开始", "swapAndBridge estimateGas 开始");
         estimateGas = await aggregator.multiSwapAndBridge.estimateGas(...args, estimationOverrides);
+        this.trace(params.chain, traceReq, "log", "hermes-swapAndBridge-estimateGas-完成", `swapAndBridge estimateGas 完成, estimateGas=${estimateGas}`);
       } catch (error) {
-        _Aggregator.traceLog(params.chain, "error", `swapAndBridge estimateGas失败, rpcUrl=${this.getRpcUrl(params.chain)}, error=${error}`);
+        this.trace(params.chain, traceReq, "error", "hermes-swapAndBridge-estimateGas-失败", `swapAndBridge estimateGas失败, rpcUrl=${this.getRpcUrl(params.chain)}, error=${error}`);
         throw error;
       }
       txReq = this.resolveGasLimit(txReq, estimateGas);
+      this.trace(params.chain, traceReq, "log", "hermes-resolveNonce-开始", "swapAndBridge resolveNonce 开始");
       txReq = await this.resolveNonce(wallet.provider, wallet.address, txReq);
+      this.trace(params.chain, traceReq, "log", "hermes-resolveNonce-完成", `swapAndBridge resolveNonce 完成, nonce=${txReq.nonce}`);
+      this.trace(params.chain, traceReq, "log", "hermes-resolvePricing-开始", "swapAndBridge resolvePricing 开始");
       txReq = await this.resolvePricing(wallet.provider, txReq);
+      this.trace(
+        params.chain,
+        traceReq,
+        "log",
+        "hermes-resolvePricing-完成",
+        `swapAndBridge resolvePricing 完成, gasPrice=${txReq.gasPrice ?? "n/a"}, maxFeePerGas=${txReq.maxFeePerGas ?? "n/a"}, maxPriorityFeePerGas=${txReq.maxPriorityFeePerGas ?? "n/a"}`
+      );
       const iface = new import_ethers.ethers.Interface(import_aggregator.default);
       let receipt;
       if (useBundle) {
@@ -373,7 +402,7 @@ var _Aggregator = class {
           receipt: flashbotsReceipt,
           txHash: bundleTxHash,
           targetBlocks
-        } = await this.submitBundleTx(params.chain, wallet, txReq, aggregatorAddress, calldata, txReq.value ?? 0n, bundleBlockCount);
+        } = await this.submitBundleTx(params.chain, wallet, txReq, aggregatorAddress, calldata, txReq.value ?? 0n, bundleBlockCount, traceReq);
         txHash = bundleTxHash;
         if (!flashbotsReceipt) {
           throw new import_types.BundleNotIncludedError(`Bundle 未在目标区块上链, txHash=${bundleTxHash}, targetBlocks=[${targetBlocks.join(",")}]`, bundleTxHash);
@@ -383,7 +412,7 @@ var _Aggregator = class {
         }
         receipt = flashbotsReceipt;
       } else {
-        receipt = await this.sendContractTx(params.chain, aggregator, "multiSwapAndBridge", args, txReq);
+        receipt = await this.sendContractTx(params.chain, aggregator, "multiSwapAndBridge", args, txReq, traceReq);
         txHash = receipt.hash;
       }
       let receiptUser = null;
@@ -411,7 +440,13 @@ var _Aggregator = class {
       const fromTokenAddress = ((_a = pathStart == null ? void 0 : pathStart[0]) == null ? void 0 : _a.fromCoinAddress) ?? "";
       const toTokenAddress = ((_b = pathEnd == null ? void 0 : pathEnd[pathEnd.length - 1]) == null ? void 0 : _b.toCoinAddress) ?? "";
       const totalAmountInFromEvent = amountInList.reduce((sum, amount) => sum + amount, 0n);
-      _Aggregator.traceLog(params.chain, "log", `swapAndBridge完成, txHash=${receipt.hash}, amountOut=${amountOut}, useBundle=${useBundle}, 总耗时=${Date.now() - startTs}ms`);
+      this.trace(
+        params.chain,
+        traceReq,
+        "log",
+        "hermes-swapAndBridge-完成",
+        `swapAndBridge完成, txHash=${receipt.hash}, amountOut=${amountOut}, useBundle=${useBundle}, 总耗时=${Date.now() - startTs}ms`
+      );
       return {
         hash: receipt.hash,
         from: receipt.from,
@@ -420,14 +455,27 @@ var _Aggregator = class {
         receipt
       };
     } catch (error) {
-      _Aggregator.traceLog(params.chain, "error", `swapAndBridge异常, rpcUrl=${this.getRpcUrl(params.chain)}, txHash=${txHash ?? "N/A"}, 总耗时=${Date.now() - startTs}ms, error=${error}`);
+      this.trace(
+        params.chain,
+        traceReq,
+        "error",
+        "hermes-swapAndBridge-异常",
+        `swapAndBridge异常, rpcUrl=${this.getRpcUrl(params.chain)}, txHash=${txHash ?? "N/A"}, 总耗时=${Date.now() - startTs}ms, error=${error}`
+      );
       throw error;
     }
   }
   async multiSwap(params, txReq = {}) {
     var _a;
+    const traceReq = txReq;
     const useBundle = this.shouldUseBundle(params.chain, txReq);
-    _Aggregator.traceLog(params.chain, "log", `multiSwap开始, user=${params.user}, pathsCount=${params.paths.length}, amountInWeis=[${params.amountInWeis.join(",")}], useBundle=${useBundle}`);
+    this.trace(
+      params.chain,
+      traceReq,
+      "log",
+      "hermes-multiSwap-开始",
+      `multiSwap开始, user=${params.user}, pathsCount=${params.paths.length}, amountInWeis=[${params.amountInWeis.join(",")}], useBundle=${useBundle}`
+    );
     const startTs = Date.now();
     let txHash;
     try {
@@ -469,14 +517,26 @@ var _Aggregator = class {
       let estimateGas;
       const { gasLimit: _ignore, ...estimationOverrides } = txReq;
       try {
+        this.trace(params.chain, traceReq, "log", "hermes-multiSwap-estimateGas-开始", "multiSwap estimateGas 开始");
         estimateGas = await aggregator.multiSwap.estimateGas(params.user, params.amountInWeis, swapParamsList, params.minAmountOutLists, params.totalMinAmountOut, estimationOverrides);
+        this.trace(params.chain, traceReq, "log", "hermes-multiSwap-estimateGas-完成", `multiSwap estimateGas 完成, estimateGas=${estimateGas}`);
       } catch (error) {
-        _Aggregator.traceLog(params.chain, "error", `multiSwap estimateGas失败, rpcUrl=${this.getRpcUrl(params.chain)}, error=${error}`);
+        this.trace(params.chain, traceReq, "error", "hermes-multiSwap-estimateGas-失败", `multiSwap estimateGas失败, rpcUrl=${this.getRpcUrl(params.chain)}, error=${error}`);
         throw error;
       }
       txReq = this.resolveGasLimit(txReq, estimateGas);
+      this.trace(params.chain, traceReq, "log", "hermes-resolveNonce-开始", "multiSwap resolveNonce 开始");
       txReq = await this.resolveNonce(wallet.provider, wallet.address, txReq);
+      this.trace(params.chain, traceReq, "log", "hermes-resolveNonce-完成", `multiSwap resolveNonce 完成, nonce=${txReq.nonce}`);
+      this.trace(params.chain, traceReq, "log", "hermes-resolvePricing-开始", "multiSwap resolvePricing 开始");
       txReq = await this.resolvePricing(wallet.provider, txReq);
+      this.trace(
+        params.chain,
+        traceReq,
+        "log",
+        "hermes-resolvePricing-完成",
+        `multiSwap resolvePricing 完成, gasPrice=${txReq.gasPrice ?? "n/a"}, maxFeePerGas=${txReq.maxFeePerGas ?? "n/a"}, maxPriorityFeePerGas=${txReq.maxPriorityFeePerGas ?? "n/a"}`
+      );
       const iface = new import_ethers.ethers.Interface(import_aggregator.default);
       let receipt;
       if (useBundle) {
@@ -485,7 +545,7 @@ var _Aggregator = class {
           receipt: flashbotsReceipt,
           txHash: bundleTxHash,
           targetBlocks
-        } = await this.submitBundleTx(params.chain, wallet, txReq, aggregatorAddress, calldata, txReq.value ?? 0n, bundleBlockCount);
+        } = await this.submitBundleTx(params.chain, wallet, txReq, aggregatorAddress, calldata, txReq.value ?? 0n, bundleBlockCount, traceReq);
         txHash = bundleTxHash;
         if (!flashbotsReceipt) {
           throw new import_types.BundleNotIncludedError(`Bundle 未在目标区块上链, txHash=${bundleTxHash}, targetBlocks=[${targetBlocks.join(",")}]`, bundleTxHash);
@@ -495,7 +555,7 @@ var _Aggregator = class {
         }
         receipt = flashbotsReceipt;
       } else {
-        receipt = await this.sendContractTx(params.chain, aggregator, "multiSwap", [params.user, params.amountInWeis, swapParamsList, params.minAmountOutLists, params.totalMinAmountOut], txReq);
+        receipt = await this.sendContractTx(params.chain, aggregator, "multiSwap", [params.user, params.amountInWeis, swapParamsList, params.minAmountOutLists, params.totalMinAmountOut], txReq, traceReq);
         txHash = receipt.hash;
       }
       let amountOutList = null;
@@ -513,7 +573,13 @@ var _Aggregator = class {
       }
       if (!amountOutList)
         throw new Error(`MultiSwapped event not found: ${receipt.hash}`);
-      _Aggregator.traceLog(params.chain, "log", `multiSwap完成, txHash=${receipt.hash}, amountOutList=[${amountOutList.join(",")}], useBundle=${useBundle}, 总耗时=${Date.now() - startTs}ms`);
+      this.trace(
+        params.chain,
+        traceReq,
+        "log",
+        "hermes-multiSwap-完成",
+        `multiSwap完成, txHash=${receipt.hash}, amountOutList=[${amountOutList.join(",")}], useBundle=${useBundle}, 总耗时=${Date.now() - startTs}ms`
+      );
       return {
         hash: receipt.hash,
         from: receipt.from,
@@ -531,7 +597,13 @@ var _Aggregator = class {
         receipt
       };
     } catch (error) {
-      _Aggregator.traceLog(params.chain, "error", `multiSwap异常, rpcUrl=${this.getRpcUrl(params.chain)}, txHash=${txHash ?? "N/A"}, 总耗时=${Date.now() - startTs}ms, error=${error}`);
+      this.trace(
+        params.chain,
+        traceReq,
+        "error",
+        "hermes-multiSwap-异常",
+        `multiSwap异常, rpcUrl=${this.getRpcUrl(params.chain)}, txHash=${txHash ?? "N/A"}, 总耗时=${Date.now() - startTs}ms, error=${error}`
+      );
       throw error;
     }
   }
@@ -1030,22 +1102,22 @@ var _Aggregator = class {
       );
     });
   }
-  async sendSignedTxToChannels(chain, signedTx, txHash, channels) {
+  async sendSignedTxToChannels(chain, signedTx, txHash, channels, traceReq) {
     const results = await Promise.all(
       channels.map(async ({ label, send }) => {
         var _a, _b, _c, _d, _e;
         const sendTs = Date.now();
         try {
           await send();
-          _Aggregator.traceLog(chain, "log", `广播${label} OK, txHash=${txHash}, 耗时=${Date.now() - sendTs}ms`);
+          this.trace(chain, traceReq, "log", "hermes-broadcast-channel-成功", `广播${label} OK, txHash=${txHash}, 耗时=${Date.now() - sendTs}ms`);
           return { label, ok: true };
         } catch (err) {
           const msg = ((_c = (_b = (_a = err == null ? void 0 : err.response) == null ? void 0 : _a.data) == null ? void 0 : _b.error) == null ? void 0 : _c.message) ?? ((_e = (_d = err == null ? void 0 : err.response) == null ? void 0 : _d.data) == null ? void 0 : _e.message) ?? (err == null ? void 0 : err.message) ?? String(err);
           if (_Aggregator.isBenignBroadcastError(msg)) {
-            _Aggregator.traceLog(chain, "log", `广播${label} already-known, txHash=${txHash}, 耗时=${Date.now() - sendTs}ms`);
+            this.trace(chain, traceReq, "log", "hermes-broadcast-channel-已存在", `广播${label} already-known, txHash=${txHash}, 耗时=${Date.now() - sendTs}ms`);
             return { label, ok: true };
           }
-          _Aggregator.traceLog(chain, "warn", `广播${label} 失败: ${msg}, txHash=${txHash}, 耗时=${Date.now() - sendTs}ms`);
+          this.trace(chain, traceReq, "warn", "hermes-broadcast-channel-失败", `广播${label} 失败: ${msg}, txHash=${txHash}, 耗时=${Date.now() - sendTs}ms`);
           return { label, ok: false, msg };
         }
       })
@@ -1056,7 +1128,7 @@ var _Aggregator = class {
     const detail = results.map((result) => `${result.label}: ${result.msg ?? "unknown error"}`).join("; ");
     throw new Error(`All broadcast channels failed for ${txHash}: ${detail}`);
   }
-  raceForReceipt(chain, txHash, providers, ownedProviders = [], timeoutMs = _Aggregator.TX_CONFIRM_TIMEOUT_MS) {
+  raceForReceipt(chain, txHash, providers, ownedProviders = [], timeoutMs = _Aggregator.TX_CONFIRM_TIMEOUT_MS, traceReq) {
     return new Promise((resolve, reject) => {
       let settled = false;
       const blockHandlers = [];
@@ -1077,7 +1149,7 @@ var _Aggregator = class {
         settled = true;
         clearTimeout(timer);
         cleanup();
-        _Aggregator.traceLog(chain, "log", `${label} 先查到receipt, txHash=${txHash}, block=${receipt.blockNumber}`);
+        this.trace(chain, traceReq, "log", "hermes-raceForReceipt-命中receipt", `${label} 先查到receipt, txHash=${txHash}, block=${receipt.blockNumber}`);
         resolve(receipt);
       };
       const checkReceipt = (provider, label) => {
@@ -1103,6 +1175,7 @@ var _Aggregator = class {
           return;
         settled = true;
         cleanup();
+        this.trace(chain, traceReq, "warn", "hermes-raceForReceipt-超时", `Transaction not confirmed within ${timeoutMs}ms: ${txHash}`);
         reject(new Error(`Transaction not confirmed within ${timeoutMs}ms: ${txHash}`));
       }, timeoutMs);
     });
@@ -1123,26 +1196,35 @@ var _Aggregator = class {
       }
     };
   }
-  async sendContractTx(chain, contract, method, args, txReq) {
+  async sendContractTx(chain, contract, method, args, txReq, traceReq) {
     const extraUrls = this.broadcastRpcsMap.get(chain);
     const hasSequencer = _Aggregator.SEQUENCER_CHAINS.has(chain) && this.sequencerRpcsMap.has(chain);
     if (!extraUrls || extraUrls.length === 0) {
       if (!hasSequencer) {
-        _Aggregator.traceLog(chain, "log", `渠道=单RPC直发, method=${method}, nonce=${txReq.nonce}, gasLimit=${txReq.gasLimit}`);
+        this.trace(chain, traceReq, "log", "hermes-sendContractTx-发出前", `渠道=单RPC直发, method=${method}, nonce=${txReq.nonce}, gasLimit=${txReq.gasLimit}`);
         const sendTs = Date.now();
+        this.trace(chain, traceReq, "log", "hermes-sendContractTx-RPC发送前", `单RPC准备发送, method=${method}`);
         const txResponse = await contract[method](...args, txReq);
-        _Aggregator.traceLog(chain, "log", `单RPC已发送, txHash=${txResponse.hash}, 耗时=${Date.now() - sendTs}ms`);
+        this.trace(chain, traceReq, "log", "hermes-sendContractTx-RPC已发送", `单RPC已发送, txHash=${txResponse.hash}, 耗时=${Date.now() - sendTs}ms`);
+        this.trace(chain, traceReq, "log", "hermes-sendContractTx-等待确认", `单RPC开始等待上链确认, txHash=${txResponse.hash}`);
         const receipt3 = await txResponse.wait();
         const singleProvider = this.providerClient.getProvider(chain);
         const blockTs3 = await this.getBlockTimestampStr(singleProvider, receipt3.blockNumber);
-        _Aggregator.traceLog(chain, "log", `单RPC上链确认, txHash=${receipt3.hash}, blockNumber=${receipt3.blockNumber}, 出块时间=${blockTs3}, gasUsed=${receipt3.gasUsed}, status=${receipt3.status}`);
+        this.trace(
+          chain,
+          traceReq,
+          "log",
+          "hermes-sendContractTx-确认完成",
+          `单RPC上链确认, txHash=${receipt3.hash}, blockNumber=${receipt3.blockNumber}, 出块时间=${blockTs3}, gasUsed=${receipt3.gasUsed}, status=${receipt3.status}`
+        );
         if (receipt3.status === 0) {
           throw new import_types.TransactionRevertedError(receipt3.hash, receipt3.gasUsed);
         }
         return receipt3;
       }
-      _Aggregator.traceLog(chain, "log", `渠道=单RPC+排序器直发, method=${method}, nonce=${txReq.nonce}, gasLimit=${txReq.gasLimit}`);
+      this.trace(chain, traceReq, "log", "hermes-sendContractTx-发出前", `渠道=单RPC+排序器直发, method=${method}, nonce=${txReq.nonce}, gasLimit=${txReq.gasLimit}`);
       const wallet2 = this.providerClient.getWallet(chain);
+      this.trace(chain, traceReq, "log", "hermes-sendContractTx-构建交易", `开始 populateTransaction, method=${method}`);
       const populated2 = await contract[method].populateTransaction(...args, txReq);
       delete populated2.from;
       const network2 = await wallet2.provider.getNetwork();
@@ -1150,18 +1232,21 @@ var _Aggregator = class {
       const signedTx2 = await wallet2.signTransaction(populated2);
       const txHash2 = import_ethers.ethers.keccak256(signedTx2);
       const mainProvider2 = wallet2.provider;
-      _Aggregator.traceLog(chain, "log", `单RPC+排序器并行广播, txHash=${txHash2}`);
+      this.trace(chain, traceReq, "log", "hermes-sendContractTx-RPC发送前", `单RPC+排序器并行广播, txHash=${txHash2}`);
       const broadcastTs2 = Date.now();
       const providers = [{ provider: mainProvider2, label: "RPC[0/主]" }];
       const sequencerChannel2 = this.buildSequencerChannel(chain, signedTx2);
       const channels2 = [...providers.map(({ provider, label }) => ({ label, send: () => provider.broadcastTransaction(signedTx2) })), ...sequencerChannel2 ? [sequencerChannel2] : []];
-      const receiptPromise2 = this.raceForReceipt(chain, txHash2, providers);
-      await this.sendSignedTxToChannels(chain, signedTx2, txHash2, channels2);
+      const receiptPromise2 = this.raceForReceipt(chain, txHash2, providers, [], _Aggregator.TX_CONFIRM_TIMEOUT_MS, traceReq);
+      await this.sendSignedTxToChannels(chain, signedTx2, txHash2, channels2, traceReq);
+      this.trace(chain, traceReq, "log", "hermes-sendContractTx-等待确认", `并行广播后开始等待确认, txHash=${txHash2}`);
       const receipt2 = await receiptPromise2;
       const blockTs2 = await this.getBlockTimestampStr(mainProvider2, receipt2.blockNumber);
-      _Aggregator.traceLog(
+      this.trace(
         chain,
+        traceReq,
         "log",
+        "hermes-sendContractTx-确认完成",
         `单RPC+排序器上链确认, txHash=${receipt2.hash}, blockNumber=${receipt2.blockNumber}, 出块时间=${blockTs2}, gasUsed=${receipt2.gasUsed}, status=${receipt2.status}, 总耗时=${Date.now() - broadcastTs2}ms`
       );
       if (receipt2.status === 0) {
@@ -1184,21 +1269,27 @@ var _Aggregator = class {
     }));
     const allProviders = [{ provider: mainProvider, label: "RPC[0/主]" }, ...extraProviders];
     const ownedProviders = extraProviders.map((e) => e.provider);
-    _Aggregator.traceLog(
+    this.trace(
       chain,
+      traceReq,
       "log",
+      "hermes-sendContractTx-发出前",
       `渠道=多RPC广播, method=${method}, nonce=${txReq.nonce}, gasLimit=${txReq.gasLimit}, 当前区块=${currentBlock}, 期望上链区块=${currentBlock + 1}, txHash=${txHash}, RPC数量=${allProviders.length}(主1+副${extraUrls.length})${hasSequencer ? ", +排序器直发" : ""}`
     );
     const broadcastTs = Date.now();
     const sequencerChannel = this.buildSequencerChannel(chain, signedTx);
     const channels = [...allProviders.map(({ provider, label }) => ({ label, send: () => provider.broadcastTransaction(signedTx) })), ...sequencerChannel ? [sequencerChannel] : []];
-    const receiptPromise = this.raceForReceipt(chain, txHash, allProviders, ownedProviders);
-    await this.sendSignedTxToChannels(chain, signedTx, txHash, channels);
+    const receiptPromise = this.raceForReceipt(chain, txHash, allProviders, ownedProviders, _Aggregator.TX_CONFIRM_TIMEOUT_MS, traceReq);
+    this.trace(chain, traceReq, "log", "hermes-sendContractTx-RPC发送前", `多RPC广播准备发送, txHash=${txHash}`);
+    await this.sendSignedTxToChannels(chain, signedTx, txHash, channels, traceReq);
+    this.trace(chain, traceReq, "log", "hermes-sendContractTx-等待确认", `多RPC广播后开始等待确认, txHash=${txHash}`);
     const receipt = await receiptPromise;
     const blockTs = await this.getBlockTimestampStr(mainProvider, receipt.blockNumber);
-    _Aggregator.traceLog(
+    this.trace(
       chain,
+      traceReq,
       "log",
+      "hermes-sendContractTx-确认完成",
       `多RPC广播上链确认, txHash=${receipt.hash}, blockNumber=${receipt.blockNumber}, 出块时间=${blockTs}, gasUsed=${receipt.gasUsed}, status=${receipt.status}, 总耗时=${Date.now() - broadcastTs}ms`
     );
     if (receipt.status === 0) {
@@ -1206,7 +1297,7 @@ var _Aggregator = class {
     }
     return receipt;
   }
-  async submitBundleTx(chain, wallet, txReq, to, data, value, bundleBlockCount) {
+  async submitBundleTx(chain, wallet, txReq, to, data, value, bundleBlockCount, traceReq) {
     if (bundleBlockCount == null) {
       bundleBlockCount = this.builderConfigMap.has(chain) ? 3 : 1;
     }
@@ -1240,9 +1331,11 @@ var _Aggregator = class {
     const targetBlocks = Array.from({ length: normalizedBundleBlockCount }, (_, i) => currentBlock + 1 + i);
     const builderNames = Object.keys(builderCfg.urls);
     const builderEntries = Object.entries(builderCfg.urls);
-    _Aggregator.traceLog(
+    this.trace(
       chain,
+      traceReq,
       "log",
+      "hermes-submitBundleTx-发出前",
       `渠道=Builder Bundle, authType=${builderCfg.authType}, method=${builderCfg.method ?? "eth_sendBundle"}, nonce=${txReq.nonce}, gasLimit=${txReq.gasLimit}, chainId=${network.chainId}, 当前区块=${currentBlock}, 目标区块=[${targetBlocks.join(",")}], builders=[${builderNames.join(",")}](${builderNames.length}个), txHash=${txHash}`
     );
     const sendBundleTs = Date.now();
@@ -1262,11 +1355,11 @@ var _Aggregator = class {
             try {
               const response = await import_axios.default.post(url, body, { headers, timeout: 3e3 });
               totalSent++;
-              _Aggregator.traceLog(chain, "log", `Builder[${name}] mev_sendBundle 发送成功, targetBlocks=[${targetBlocks.join(",")}], 耗时=${Date.now() - ts}ms, resp=${JSON.stringify(response.data)}`);
+              this.trace(chain, traceReq, "log", "hermes-submitBundleTx-builder-成功", `Builder[${name}] mev_sendBundle 发送成功, targetBlocks=[${targetBlocks.join(",")}], 耗时=${Date.now() - ts}ms, resp=${JSON.stringify(response.data)}`);
             } catch (error) {
               totalFailed++;
               const msg = (error == null ? void 0 : error.response) ? JSON.stringify(error.response.data) : (error == null ? void 0 : error.message) ?? String(error);
-              _Aggregator.traceLog(chain, "error", `Builder[${name}] mev_sendBundle 发送失败, targetBlocks=[${targetBlocks.join(",")}], 耗时=${Date.now() - ts}ms, error=${msg}`);
+              this.trace(chain, traceReq, "error", "hermes-submitBundleTx-builder-失败", `Builder[${name}] mev_sendBundle 发送失败, targetBlocks=[${targetBlocks.join(",")}], 耗时=${Date.now() - ts}ms, error=${msg}`);
             }
           })()
         ];
@@ -1281,34 +1374,49 @@ var _Aggregator = class {
         try {
           const response = await import_axios.default.post(url, body, { headers, timeout: 3e3 });
           totalSent++;
-          _Aggregator.traceLog(chain, "log", `Builder[${name}] 发送成功, targetBlock=${block}, 耗时=${Date.now() - ts}ms, resp=${JSON.stringify(response.data)}`);
+          this.trace(chain, traceReq, "log", "hermes-submitBundleTx-builder-成功", `Builder[${name}] 发送成功, targetBlock=${block}, 耗时=${Date.now() - ts}ms, resp=${JSON.stringify(response.data)}`);
         } catch (error) {
           totalFailed++;
           const msg = (error == null ? void 0 : error.response) ? JSON.stringify(error.response.data) : (error == null ? void 0 : error.message) ?? String(error);
-          _Aggregator.traceLog(chain, "error", `Builder[${name}] 发送失败, targetBlock=${block}, 耗时=${Date.now() - ts}ms, error=${msg}`);
+          this.trace(chain, traceReq, "error", "hermes-submitBundleTx-builder-失败", `Builder[${name}] 发送失败, targetBlock=${block}, 耗时=${Date.now() - ts}ms, error=${msg}`);
         }
       });
     });
     const abortController = new AbortController();
     const inclusionPromise = this.waitForBundleInclusion(provider, txHash, targetBlocks, abortController.signal);
     const waitTs = Date.now();
+    this.trace(chain, traceReq, "log", "hermes-submitBundleTx-RPC发送前", `Bundle 请求开始发送, txHash=${txHash}, targetBlocks=[${targetBlocks.join(",")}]`);
     const [receipt] = await Promise.all([
       inclusionPromise,
       Promise.all(fireAndForget).then(() => {
-        _Aggregator.traceLog(chain, "log", `Bundle发送完成, 成功=${totalSent}, 失败=${totalFailed}, 总请求=${fireAndForget.length}, 耗时=${Date.now() - sendBundleTs}ms, txHash=${txHash}`);
+        this.trace(
+          chain,
+          traceReq,
+          "log",
+          "hermes-submitBundleTx-RPC已发送",
+          `Bundle发送完成, 成功=${totalSent}, 失败=${totalFailed}, 总请求=${fireAndForget.length}, 耗时=${Date.now() - sendBundleTs}ms, txHash=${txHash}`
+        );
         if (totalSent === 0)
           abortController.abort();
       })
     ]);
     if (receipt) {
       const blockTs = await this.getBlockTimestampStr(provider, receipt.blockNumber);
-      _Aggregator.traceLog(
+      this.trace(
         chain,
+        traceReq,
         "log",
+        "hermes-submitBundleTx-确认完成",
         `Bundle上链确认, txHash=${receipt.hash}, blockNumber=${receipt.blockNumber}, 出块时间=${blockTs}, gasUsed=${receipt.gasUsed}, 等待耗时=${Date.now() - waitTs}ms`
       );
     } else {
-      _Aggregator.traceLog(chain, "warn", `Bundle未在目标区块上链, txHash=${txHash}, 目标区块=[${targetBlocks.join(",")}], 等待耗时=${Date.now() - waitTs}ms`);
+      this.trace(
+        chain,
+        traceReq,
+        "warn",
+        "hermes-submitBundleTx-等待结束",
+        `Bundle未在目标区块上链, txHash=${txHash}, 目标区块=[${targetBlocks.join(",")}], 等待耗时=${Date.now() - waitTs}ms`
+      );
     }
     return { receipt, txHash, targetBlocks };
   }
@@ -1410,7 +1518,7 @@ var _Aggregator = class {
   }
   stripCustomFields(txReq, chain) {
     const defaultBlockCount = chain && this.builderConfigMap.has(chain) ? 3 : 1;
-    const { useBundle, bundleBlockCount = defaultBlockCount, ...pureTxReq } = txReq;
+    const { useBundle, bundleBlockCount = defaultBlockCount, trace, ...pureTxReq } = txReq;
     return { pureTxReq, bundleBlockCount: this.normalizeBundleBlockCount(bundleBlockCount) };
   }
   normalizeBundleBlockCount(bundleBlockCount) {

package/dist/cjs/aggregator.d.ts

@@ -16,6 +16,8 @@ declare class Aggregator {
     private static traceLog;
     private static formatBlockTimestamp;
     private getBlockTimestampStr;
+    private emitTrace;
+    private trace;
     private static readonly DEFAULT_ETH_BUILDERS;
     private static readonly DEFAULT_SEQUENCER_RPC_BY_CHAIN;
     private static readonly SEQUENCER_CHAINS;

package/dist/cjs/index.d.ts

@@ -1,7 +1,7 @@
-import type { HermesTxRequest, IBatchMultiSwapParams, IBatchExpectParams, ISwapByPathParams, IExpectSplitOrderParams, IExpectSplitOrderResp, IBridgeParams, IBatchReceipt, IMultiSwapParams, IBatchMultiSwapAndBridgeParams, ISwapAndBridgeParams, IReceipt, IConfig, IBuilderConfig, IExpectPayload, IRouterPath, SupportContracts, IExpectByPathParams, IHermesSignalResponse, IHermesSignalQuoteBestData, IHermesSignalRoute } from './types.js';
+import type { HermesTxRequest, IHermesExecutionTrace, IBatchMultiSwapParams, IBatchExpectParams, ISwapByPathParams, IExpectSplitOrderParams, IExpectSplitOrderResp, IBridgeParams, IBatchReceipt, IMultiSwapParams, IBatchMultiSwapAndBridgeParams, ISwapAndBridgeParams, IReceipt, IConfig, IBuilderConfig, IExpectPayload, IRouterPath, SupportContracts, IExpectByPathParams, IHermesSignalResponse, IHermesSignalQuoteBestData, IHermesSignalRoute } from './types.js';
 import { ChainNameEnum, AddressConst, DexType, BridgeType, IEstimateType, LayerZeroV1ChainIdMap, LayerZeroV1ChainNameMap, LayerZeroV2ChainIdMap, LayerZeroV2ChainNameMap } from './types.js';
 import { TransactionRequest } from 'ethers';
-export type { HermesTxRequest, IBatchMultiSwapAndBridgeParams, IExpectSplitOrderParams, IExpectSplitOrderResp, IMultiSwapParams, IBatchMultiSwapParams, IBatchExpectParams, IBatchReceipt, ISwapByPathParams as ISwapParams, IBridgeParams, ISwapAndBridgeParams, IReceipt, IConfig, IBuilderConfig, IExpectPayload, IRouterPath, SupportContracts, IHermesSignalResponse, IHermesSignalQuoteBestData, IHermesSignalRoute, };
+export type { HermesTxRequest, IHermesExecutionTrace, IBatchMultiSwapAndBridgeParams, IExpectSplitOrderParams, IExpectSplitOrderResp, IMultiSwapParams, IBatchMultiSwapParams, IBatchExpectParams, IBatchReceipt, ISwapByPathParams as ISwapParams, IBridgeParams, ISwapAndBridgeParams, IReceipt, IConfig, IBuilderConfig, IExpectPayload, IRouterPath, SupportContracts, IHermesSignalResponse, IHermesSignalQuoteBestData, IHermesSignalRoute, };
 import { BundleNotIncludedError, TransactionRevertedError } from './types.js';
 export { ChainNameEnum, AddressConst, DexType, BridgeType, IEstimateType, LayerZeroV1ChainIdMap, LayerZeroV1ChainNameMap, LayerZeroV2ChainIdMap, LayerZeroV2ChainNameMap, BundleNotIncludedError, TransactionRevertedError };
 declare class Hermes {

package/dist/cjs/types.d.ts

@@ -377,10 +377,18 @@ export interface IRpcConfig {
     url: string;
     privateKey?: string;
 }
+export interface IHermesExecutionTrace {
+    ts: number;
+    chain?: ChainNameEnum;
+    level: 'log' | 'warn' | 'error';
+    stage: string;
+    message: string;
+}
 export type HermesTxRequest = TransactionRequest & {
     useBundle?: boolean;
     /** 尝试的区块数量（1-3），默认1（即仅 +1 区块）。传2则尝试 +1/+2 区块，传3则尝试 +1/+2/+3 区块 */
     bundleBlockCount?: number;
+    trace?: (event: IHermesExecutionTrace) => void;
 };
 export declare const AddressConst: {
     weth: {

package/dist/esm/aggregator.d.ts

@@ -16,6 +16,8 @@ declare class Aggregator {
     private static traceLog;
     private static formatBlockTimestamp;
     private getBlockTimestampStr;
+    private emitTrace;
+    private trace;
     private static readonly DEFAULT_ETH_BUILDERS;
     private static readonly DEFAULT_SEQUENCER_RPC_BY_CHAIN;
     private static readonly SEQUENCER_CHAINS;