@keplr-wallet/background 0.13.34 → 0.13.36

package/src/tx-executor/service.ts

@@ -1,4 +1,4 @@
-import { KVStore } from "@keplr-wallet/common";
+import { EventBusSubscriber, KVStore } from "@keplr-wallet/common";
 import { ChainsService } from "../chains";
 import { KeyRingCosmosService } from "../keyring-cosmos";
 import { KeyRingEthereumService } from "../keyring-ethereum";
@@ -20,6 +20,8 @@ import {
   TxExecutionResult,
   PendingTxExecutionResult,
   IBCSwapMinimalTrackingData,
+  TxExecutionDiagnostics,
+  TxExecutionEvent,
 } from "./types";
 import {
   action,
@@ -49,8 +51,12 @@ import {
 } from "./utils/cosmos";
 import { fillUnsignedEVMTx } from "./utils/evm";
 import { fetchWithRetry } from "./utils/fetch";
-import { EventBusSubscriber } from "@keplr-wallet/common";
-import { TxExecutionEvent } from "./types";
+import { getTxExecutionDiagnostics } from "./utils/diagnostics";
+
+type TraceTxResult = {
+  confirmed: boolean;
+  diagnostics?: TxExecutionDiagnostics;
+};
 
 export class BackgroundTxExecutorService {
   @observable
@@ -418,6 +424,7 @@ export class BackgroundTxExecutorService {
           return {
             status: TxExecutionStatus.FAILED,
             error: result.error,
+            diagnostics: result.diagnostics,
           };
         }
         case BackgroundTxStatus.BLOCKED: {
@@ -507,6 +514,7 @@ export class BackgroundTxExecutorService {
           status: BackgroundTxStatus.FAILED,
           txHash,
           error: e?.message || "Transaction signing failed",
+          diagnostics: getTxExecutionDiagnostics(e),
         };
       }
     }
@@ -531,9 +539,9 @@ export class BackgroundTxExecutorService {
     // trace the tx
     try {
       const txWithHash = { ...tx, txHash };
-      const confirmed = await this.traceTx(txWithHash);
+      const traceResult = await this.traceTx(txWithHash);
 
-      if (confirmed) {
+      if (traceResult.confirmed) {
         return { status: BackgroundTxStatus.CONFIRMED, txHash };
       }
 
@@ -541,6 +549,7 @@ export class BackgroundTxExecutorService {
         status: BackgroundTxStatus.FAILED,
         txHash,
         error: "Transaction confirmation failed",
+        diagnostics: traceResult.diagnostics,
       };
     } catch (e) {
       console.error(`[TxExecutor] tx trace failed:`, e);
@@ -548,6 +557,12 @@ export class BackgroundTxExecutorService {
         status: BackgroundTxStatus.FAILED,
         txHash,
         error: e?.message || "Transaction confirmation failed",
+        diagnostics: getTxExecutionDiagnostics(e) ?? {
+          confirmation_failure_reason:
+            tx.type === BackgroundTxType.EVM
+              ? "evm_trace_error"
+              : "cosmos_trace_error",
+        },
       };
     }
   }
@@ -820,7 +835,7 @@ export class BackgroundTxExecutorService {
     return Buffer.from(txHash).toString("hex");
   }
 
-  protected async traceTx(tx: BackgroundTx): Promise<boolean> {
+  protected async traceTx(tx: BackgroundTx): Promise<TraceTxResult> {
     switch (tx.type) {
       case BackgroundTxType.EVM: {
         return this.traceEvmTx(tx);
@@ -834,7 +849,7 @@ export class BackgroundTxExecutorService {
     }
   }
 
-  private async traceEvmTx(tx: EVMBackgroundTx): Promise<boolean> {
+  private async traceEvmTx(tx: EVMBackgroundTx): Promise<TraceTxResult> {
     if (!tx.txHash) {
       throw new KeplrError("direct-tx-executor", 133, "Tx hash not found");
     }
@@ -851,55 +866,95 @@ export class BackgroundTxExecutorService {
         tx.txHash
       );
     if (!txReceipt) {
-      return false;
+      return {
+        confirmed: false,
+        diagnostics: {
+          confirmation_failure_reason: "evm_receipt_missing",
+        },
+      };
     }
 
-    return txReceipt.status === EthTxStatus.Success;
+    if (txReceipt.status === EthTxStatus.Success) {
+      return { confirmed: true };
+    }
+
+    return {
+      confirmed: false,
+      diagnostics: {
+        confirmation_failure_reason: "evm_receipt_status_failed",
+      },
+    };
   }
 
-  private async traceCosmosTx(tx: CosmosBackgroundTx): Promise<boolean> {
+  private async traceCosmosTx(tx: CosmosBackgroundTx): Promise<TraceTxResult> {
     if (!tx.txHash) {
       throw new KeplrError("direct-tx-executor", 133, "Tx hash not found");
     }
 
     let txResult: any;
+    let traceErrored = false;
     try {
       txResult = await this.backgroundTxService.traceTx(tx.chainId, tx.txHash);
     } catch {
+      traceErrored = true;
       // WS retry 모두 실패 — REST fallback 시도
     }
 
     // WS에서 결과를 못 받은 경우, REST로 tx 존재 여부 확인
     // (tx가 온체인 성공했는데 WS 불안정으로 확인 못한 false positive 대응)
     if (!txResult) {
-      txResult = await this.queryTxByRestFallback(tx.chainId, tx.txHash);
+      const restFallback = await this.queryTxByRestFallback(
+        tx.chainId,
+        tx.txHash
+      );
+      if (restFallback.failed) {
+        return {
+          confirmed: false,
+          diagnostics: {
+            confirmation_failure_reason: "cosmos_rest_fallback_missing",
+          },
+        };
+      }
+      txResult = restFallback.txResult;
     }
 
     if (!txResult) {
-      return false;
+      return {
+        confirmed: false,
+        diagnostics: {
+          confirmation_failure_reason: traceErrored
+            ? "cosmos_trace_error"
+            : "cosmos_trace_missing",
+        },
+      };
     }
 
     // Tendermint/CometBFT omits the code field when tx is successful (code=0)
     // If code is present and non-zero, it's a failure
     if (txResult.code != null && txResult.code !== 0) {
-      return false;
+      return {
+        confirmed: false,
+        diagnostics: {
+          confirmation_failure_reason: "cosmos_code_nonzero",
+        },
+      };
     }
 
-    return true;
+    return { confirmed: true };
   }
 
   private async queryTxByRestFallback(
     chainId: string,
     txHash: string
-  ): Promise<{ code?: number } | undefined> {
+  ): Promise<{ txResult?: { code?: number }; failed: boolean }> {
     try {
       const chainInfo = this.chainsService.getChainInfoOrThrow(chainId);
       const { data } = await fetchWithRetry<{
         tx_response?: { code?: number; txhash?: string };
       }>(chainInfo.rest, `/cosmos/tx/v1beta1/txs/${txHash}`);
-      return data.tx_response;
+      return { txResult: data.tx_response, failed: false };
     } catch {
-      return undefined;
+      return { failed: true };
     }
   }
 

package/src/tx-executor/types.ts

@@ -1,5 +1,5 @@
 import { UnsignedTransaction } from "@ethersproject/transactions";
-import { StdFee } from "@keplr-wallet/types";
+import { EvmGasSimulationOutcome, StdFee } from "@keplr-wallet/types";
 import { Any } from "@keplr-wallet/proto-types/google/protobuf/any";
 import { Msg } from "@keplr-wallet/types";
 import { SwapV2HistoryData } from "../recent-send-history";
@@ -94,6 +94,45 @@ export enum TxExecutionType {
 
 export type BackgroundTxFeeType = "low" | "average" | "high";
 
+export type TxConfirmationFailureReason =
+  | "evm_receipt_missing"
+  | "evm_receipt_status_failed"
+  | "evm_trace_error"
+  | "cosmos_trace_missing"
+  | "cosmos_trace_error"
+  | "cosmos_rest_fallback_missing"
+  | "cosmos_code_nonzero";
+
+export type GasEstimateContext =
+  | "review_simulation"
+  | "pre_sign_simulation"
+  | "background_fill_unsigned_tx";
+
+export type GasEstimateErrorCategory =
+  | "allowance_insufficient"
+  | "native_balance_insufficient"
+  | "execution_reverted"
+  | "invalid_calldata"
+  | "rpc_unavailable"
+  | "unknown";
+
+export type TxRouteStepKind = "swap" | "bridge" | "ibc_transfer" | "unknown";
+
+export type TxRouteBridgeKind = "axelar" | "cctp" | "ibc" | "unknown";
+
+export interface TxExecutionDiagnostics {
+  confirmation_failure_reason?: TxConfirmationFailureReason;
+  gas_estimate_context?: GasEstimateContext;
+  gas_estimate_error_category?: GasEstimateErrorCategory;
+  has_required_erc20_approval?: boolean;
+  has_native_value?: boolean;
+  failed_tx_has_required_erc20_approval?: boolean;
+  failed_tx_has_native_value?: boolean;
+  route_step_kinds?: TxRouteStepKind[];
+  route_bridge_kinds?: TxRouteBridgeKind[];
+  evm_simulation_outcome?: EvmGasSimulationOutcome;
+}
+
 export interface TxExecutionBase {
   readonly id: string;
   status: TxExecutionStatus;
@@ -157,6 +196,7 @@ export interface PendingTxExecutionResult {
   status: BackgroundTxStatus;
   txHash?: string;
   error?: string;
+  diagnostics?: TxExecutionDiagnostics;
 }
 
 /**
@@ -166,4 +206,5 @@ export interface PendingTxExecutionResult {
 export interface TxExecutionResult {
   status: TxExecutionStatus;
   error?: string;
+  diagnostics?: TxExecutionDiagnostics;
 }

package/src/tx-executor/utils/diagnostics.spec.ts

@@ -0,0 +1,89 @@
+import {
+  classifyGasEstimateError,
+  createGasEstimateDiagnostics,
+  getTxExecutionDiagnostics,
+  hasEvmTxNativeValue,
+  sanitizeTxExecutionDiagnostics,
+  withTxExecutionDiagnostics,
+} from "./diagnostics";
+
+describe("tx execution diagnostics", () => {
+  it("classifies allowance failures without exposing the raw error", () => {
+    expect(
+      classifyGasEstimateError(
+        new Error(
+          "execution reverted: ERC20: transfer amount exceeds allowance"
+        )
+      )
+    ).toBe("allowance_insufficient");
+  });
+
+  it("classifies common gas estimate error families", () => {
+    expect(classifyGasEstimateError(new Error("insufficient funds"))).toBe(
+      "native_balance_insufficient"
+    );
+    expect(
+      classifyGasEstimateError(
+        new Error("execution reverted: panic: arithmetic underflow or overflow")
+      )
+    ).toBe("execution_reverted");
+    expect(
+      classifyGasEstimateError(
+        new Error("invalid argument 0: cannot unmarshal hex string")
+      )
+    ).toBe("invalid_calldata");
+    expect(classifyGasEstimateError(new Error("network error: timeout"))).toBe(
+      "rpc_unavailable"
+    );
+  });
+
+  it("detects native value on decimal and hex tx values", () => {
+    expect(hasEvmTxNativeValue("0")).toBe(false);
+    expect(hasEvmTxNativeValue("0x0")).toBe(false);
+    expect(hasEvmTxNativeValue("100")).toBe(true);
+    expect(hasEvmTxNativeValue("0x64")).toBe(true);
+  });
+
+  it("attaches sanitized gas estimate diagnostics to errors", () => {
+    const error = withTxExecutionDiagnostics(
+      new Error("execution reverted: ERC20: transfer amount exceeds allowance"),
+      createGasEstimateDiagnostics(
+        new Error(
+          "execution reverted: ERC20: transfer amount exceeds allowance"
+        ),
+        "background_fill_unsigned_tx",
+        {
+          value: "0x1",
+          requiredErc20Approvals: [{ tokenAddress: "0x1" }],
+        }
+      )
+    );
+
+    expect(error.message).toBe(
+      "execution reverted: ERC20: transfer amount exceeds allowance"
+    );
+    expect(getTxExecutionDiagnostics(error)).toEqual({
+      gas_estimate_context: "background_fill_unsigned_tx",
+      gas_estimate_error_category: "allowance_insufficient",
+      failed_tx_has_required_erc20_approval: true,
+      failed_tx_has_native_value: true,
+    });
+  });
+
+  it("drops unknown diagnostics keys and invalid enum values", () => {
+    expect(
+      sanitizeTxExecutionDiagnostics({
+        gas_estimate_context: "background_fill_unsigned_tx",
+        gas_estimate_error_category: "allowance_insufficient",
+        confirmation_failure_reason: "raw tx hash here",
+        route_step_kinds: ["swap", "raw-route-fingerprint"],
+        evm_simulation_outcome: "raw simulation outcome",
+        leaked_payload: "should not be logged",
+      })
+    ).toEqual({
+      gas_estimate_context: "background_fill_unsigned_tx",
+      gas_estimate_error_category: "allowance_insufficient",
+      route_step_kinds: ["swap"],
+    });
+  });
+});

package/src/tx-executor/utils/diagnostics.ts

@@ -0,0 +1,298 @@
+import { UnsignedTransaction } from "@ethersproject/transactions";
+import { EvmGasSimulationOutcome } from "@keplr-wallet/types";
+import {
+  GasEstimateContext,
+  GasEstimateErrorCategory,
+  TxConfirmationFailureReason,
+  TxExecutionDiagnostics,
+  TxRouteBridgeKind,
+  TxRouteStepKind,
+} from "../types";
+
+const CONFIRMATION_FAILURE_REASONS: readonly TxConfirmationFailureReason[] = [
+  "evm_receipt_missing",
+  "evm_receipt_status_failed",
+  "evm_trace_error",
+  "cosmos_trace_missing",
+  "cosmos_trace_error",
+  "cosmos_rest_fallback_missing",
+  "cosmos_code_nonzero",
+];
+
+const GAS_ESTIMATE_CONTEXTS: readonly GasEstimateContext[] = [
+  "review_simulation",
+  "pre_sign_simulation",
+  "background_fill_unsigned_tx",
+];
+
+const GAS_ESTIMATE_ERROR_CATEGORIES: readonly GasEstimateErrorCategory[] = [
+  "allowance_insufficient",
+  "native_balance_insufficient",
+  "execution_reverted",
+  "invalid_calldata",
+  "rpc_unavailable",
+  "unknown",
+];
+
+const ROUTE_STEP_KINDS: readonly TxRouteStepKind[] = [
+  "swap",
+  "bridge",
+  "ibc_transfer",
+  "unknown",
+];
+
+const ROUTE_BRIDGE_KINDS: readonly TxRouteBridgeKind[] = [
+  "axelar",
+  "cctp",
+  "ibc",
+  "unknown",
+];
+
+const EVM_SIMULATION_OUTCOMES: readonly EvmGasSimulationOutcome[] = [
+  EvmGasSimulationOutcome.TX_SIMULATED,
+  EvmGasSimulationOutcome.TX_BUNDLE_SIMULATED,
+  EvmGasSimulationOutcome.APPROVAL_ONLY_SIMULATED,
+];
+
+export class TxExecutionDiagnosticsError extends Error {
+  constructor(
+    message: string,
+    public readonly diagnostics: TxExecutionDiagnostics
+  ) {
+    super(message);
+    this.name = "TxExecutionDiagnosticsError";
+  }
+}
+
+export function getTxExecutionDiagnostics(
+  error: unknown
+): TxExecutionDiagnostics | undefined {
+  if (
+    error instanceof TxExecutionDiagnosticsError ||
+    (typeof error === "object" &&
+      error != null &&
+      "diagnostics" in error &&
+      typeof (error as { diagnostics?: unknown }).diagnostics === "object")
+  ) {
+    return sanitizeTxExecutionDiagnostics(
+      (error as { diagnostics: TxExecutionDiagnostics }).diagnostics
+    );
+  }
+}
+
+export function withTxExecutionDiagnostics(
+  error: unknown,
+  diagnostics: TxExecutionDiagnostics
+): TxExecutionDiagnosticsError {
+  const message =
+    typeof error === "object" &&
+    error != null &&
+    "message" in error &&
+    typeof (error as { message?: unknown }).message === "string"
+      ? (error as { message: string }).message
+      : String(error || "Unknown error");
+
+  return new TxExecutionDiagnosticsError(message, {
+    ...getTxExecutionDiagnostics(error),
+    ...sanitizeTxExecutionDiagnostics(diagnostics),
+  });
+}
+
+export function createGasEstimateDiagnostics(
+  error: unknown,
+  context: GasEstimateContext,
+  tx?: Pick<UnsignedTransaction, "value"> & {
+    requiredErc20Approvals?: unknown[];
+  }
+): TxExecutionDiagnostics {
+  return {
+    gas_estimate_context: context,
+    gas_estimate_error_category: classifyGasEstimateError(error),
+    ...(tx
+      ? {
+          failed_tx_has_required_erc20_approval:
+            (tx.requiredErc20Approvals?.length ?? 0) > 0,
+          failed_tx_has_native_value: hasEvmTxNativeValue(tx.value),
+        }
+      : {}),
+  };
+}
+
+export function classifyGasEstimateError(
+  error: unknown
+): GasEstimateErrorCategory {
+  const message = getErrorMessage(error).toLowerCase();
+
+  if (message.includes("allowance")) {
+    return "allowance_insufficient";
+  }
+
+  if (
+    matchesAny(message, [
+      "insufficient funds",
+      "insufficient balance",
+      "insufficient native",
+      "exceeds balance",
+      "not enough balance",
+      "not enough gas",
+    ])
+  ) {
+    return "native_balance_insufficient";
+  }
+
+  if (
+    matchesAny(message, [
+      "invalid argument",
+      "invalid calldata",
+      "invalid data",
+      "invalid hex",
+      "cannot unmarshal",
+      "missing value for required argument",
+    ])
+  ) {
+    return "invalid_calldata";
+  }
+
+  if (message.includes("execution reverted") || message.includes("revert")) {
+    return "execution_reverted";
+  }
+
+  if (
+    matchesAny(message, [
+      "failed to fetch",
+      "network error",
+      "timeout",
+      "timed out",
+      "too many requests",
+      "bad gateway",
+      "service unavailable",
+      "gateway timeout",
+    ])
+  ) {
+    return "rpc_unavailable";
+  }
+
+  return "unknown";
+}
+
+export function hasEvmTxNativeValue(value: unknown): boolean {
+  if (value == null) {
+    return false;
+  }
+
+  try {
+    return BigInt(value.toString()) > BigInt(0);
+  } catch {
+    return false;
+  }
+}
+
+export function sanitizeTxExecutionDiagnostics(
+  diagnostics: unknown
+): TxExecutionDiagnostics | undefined {
+  if (!diagnostics || typeof diagnostics !== "object") {
+    return undefined;
+  }
+
+  const source = diagnostics as Record<string, unknown>;
+  const sanitized: TxExecutionDiagnostics = {};
+  const confirmationFailureReason = source["confirmation_failure_reason"];
+  const gasEstimateContext = source["gas_estimate_context"];
+  const gasEstimateErrorCategory = source["gas_estimate_error_category"];
+  const hasRequiredErc20Approval = source["has_required_erc20_approval"];
+  const hasNativeValue = source["has_native_value"];
+  const failedTxHasRequiredErc20Approval =
+    source["failed_tx_has_required_erc20_approval"];
+  const failedTxHasNativeValue = source["failed_tx_has_native_value"];
+  const routeStepKindsValue = source["route_step_kinds"];
+  const routeBridgeKindsValue = source["route_bridge_kinds"];
+  const evmSimulationOutcome = source["evm_simulation_outcome"];
+
+  if (isOneOf(confirmationFailureReason, CONFIRMATION_FAILURE_REASONS)) {
+    sanitized.confirmation_failure_reason = confirmationFailureReason;
+  }
+
+  if (isOneOf(gasEstimateContext, GAS_ESTIMATE_CONTEXTS)) {
+    sanitized.gas_estimate_context = gasEstimateContext;
+  }
+
+  if (isOneOf(gasEstimateErrorCategory, GAS_ESTIMATE_ERROR_CATEGORIES)) {
+    sanitized.gas_estimate_error_category = gasEstimateErrorCategory;
+  }
+
+  if (typeof hasRequiredErc20Approval === "boolean") {
+    sanitized.has_required_erc20_approval = hasRequiredErc20Approval;
+  }
+
+  if (typeof hasNativeValue === "boolean") {
+    sanitized.has_native_value = hasNativeValue;
+  }
+
+  if (typeof failedTxHasRequiredErc20Approval === "boolean") {
+    sanitized.failed_tx_has_required_erc20_approval =
+      failedTxHasRequiredErc20Approval;
+  }
+
+  if (typeof failedTxHasNativeValue === "boolean") {
+    sanitized.failed_tx_has_native_value = failedTxHasNativeValue;
+  }
+
+  const routeStepKinds = sanitizeStringArray(routeStepKindsValue, [
+    ...ROUTE_STEP_KINDS,
+  ]);
+  if (routeStepKinds) {
+    sanitized.route_step_kinds = routeStepKinds;
+  }
+
+  const routeBridgeKinds = sanitizeStringArray(routeBridgeKindsValue, [
+    ...ROUTE_BRIDGE_KINDS,
+  ]);
+  if (routeBridgeKinds) {
+    sanitized.route_bridge_kinds = routeBridgeKinds;
+  }
+
+  if (isOneOf(evmSimulationOutcome, EVM_SIMULATION_OUTCOMES)) {
+    sanitized.evm_simulation_outcome = evmSimulationOutcome;
+  }
+
+  return Object.keys(sanitized).length > 0 ? sanitized : undefined;
+}
+
+function getErrorMessage(error: unknown): string {
+  if (
+    typeof error === "object" &&
+    error != null &&
+    "message" in error &&
+    typeof (error as { message?: unknown }).message === "string"
+  ) {
+    return (error as { message: string }).message;
+  }
+
+  return String(error || "");
+}
+
+function matchesAny(message: string, patterns: string[]): boolean {
+  return patterns.some((pattern) => message.includes(pattern));
+}
+
+function isOneOf<T extends string>(
+  value: unknown,
+  allowedValues: readonly T[]
+): value is T {
+  return typeof value === "string" && allowedValues.includes(value as T);
+}
+
+function sanitizeStringArray<T extends string>(
+  value: unknown,
+  allowedValues: readonly T[]
+): T[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+
+  const sanitized = value.filter((item): item is T =>
+    isOneOf(item, allowedValues)
+  );
+
+  return sanitized.length > 0 ? [...new Set(sanitized)] : undefined;
+}