@tuwaio/pulsar-evm 0.6.0 → 0.7.1

package/dist/index.d.mts

@@ -1,172 +1,301 @@
-import { Transaction, TxAdapter, ITxTrackingStore, TrackerCallbacks, PollingTrackerConfig, TransactionTracker, CheckTxTracker } from '@tuwaio/pulsar-core';
+import { Transaction, TxAdapter, EvmTransaction, ITxTrackingStore, TrackerCallbacks, PollingFetcherParams, TransactionTracker, CheckTxTracker } from '@tuwaio/pulsar-core';
 import { Config } from '@wagmi/core';
 import { Chain, Hex, GetTransactionReturnType, TransactionReceipt, Client, ReplacementReturnType, WaitForTransactionReceiptParameters, Transport, HttpTransportConfig } from 'viem';
 import { GetUserOperationReceiptReturnType } from 'viem/account-abstraction';
 
 /**
- * @file This file contains the factory function for creating the EVM (Ethereum Virtual Machine) transaction adapter.
- * This adapter encapsulates all the logic required to interact with EVM-based chains using wagmi.
+ * @file The EVM adapter that plugs `@wagmi/core` and `viem` into the Pulsar store.
  */
 
 /**
- * Creates an EVM-specific transaction adapter.
+ * Creates the EVM adapter for `createPulsarStore` from `@tuwaio/pulsar-core`. Pass it alone or in the adapter array.
+ *
+ * The adapter implements `TxAdapter` from `@tuwaio/pulsar-core`:
+ * - `getConnectorInfo` returns the address of the active wagmi connection (or, without one, the last connected address
+ *   saved in `localStorage` by `@tuwaio/orbit-core`, then the zero address) and the connector type, e.g. `evm:metamask`.
+ * - `checkChainForTx` runs `checkAndSwitchChain` from `@tuwaio/orbit-evm`: when the wallet is on another chain, it asks
+ *   the wallet to switch and rejects if the user declines.
+ * - `checkTransactionsTracker` and `checkAndInitializeTrackerInStore` are {@link checkTransactionsTracker} and
+ *   {@link checkAndInitializeTrackerInStore}.
+ * - `getExplorerUrl(path, chainId)` appends a path to the default block explorer of `chainId` (looked up in
+ *   `appChains`), or of the chain the wallet is connected to when `chainId` is omitted. It returns `undefined` when that
+ *   chain has no block explorer. `getExplorerTxUrl` is {@link selectEvmTxExplorerLink} with `appChains`.
+ * - `cancelTxAction` and `speedUpTxAction` are {@link cancelTxAction} and {@link speedUpTxAction}; both open a wallet
+ *   prompt.
+ * - `retryTxAction` closes the modal and runs `executeTxAction` again with
+ *   `tx.actionFunction({ config, ...tx.payload })`; it logs an error and does nothing without `executeTxAction`.
+ *
+ * @template T - The application transaction type.
+ * @param config - The wagmi config of the app.
+ * @param appChains - The viem chains of the app, used to build explorer links.
+ * @returns The EVM adapter.
+ * @throws `Error` when `config` is not provided.
  *
- * This function acts as a constructor for the EVM adapter, bundling all the necessary
- * chain-specific utilities (like checking chain, ENS resolution, speeding up transactions, etc.)
- * into a single object that conforms to the `TxAdapter` interface.
- *
- * @template T - The application-specific transaction type.
- * @param {Config} config - The wagmi configuration object.
- * @param {Chain[]} appChains - An array of viem `Chain` objects supported by the application.
- *
- * @returns {TxAdapter<T>} The configured EVM transaction adapter.
+ * @example
+ * ```ts
+ * import { createPulsarStore } from '@tuwaio/pulsar-core';
+ * import { pulsarEvmAdapter } from '@tuwaio/pulsar-evm';
+ * import { mainnet, sepolia } from 'viem/chains';
  *
- * @throws {Error} Throws an error if the wagmi `config` is not provided.
+ * const pulsarStore = createPulsarStore({
+ *   name: 'transactions-tracking-storage',
+ *   adapter: pulsarEvmAdapter(wagmiConfig, [mainnet, sepolia]),
+ * });
+ * ```
  */
 declare function pulsarEvmAdapter<T extends Transaction>(config: Config, appChains: readonly [Chain, ...Chain[]]): TxAdapter<T>;
 
 /**
- * @file This file implements transaction tracking for ERC-4337 UserOperations.
- * It uses a polling mechanism against a Bundler RPC endpoint (e.g., Pimlico)
- * to check the status of a UserOperation via `eth_getUserOperationReceipt`.
+ * @file The tracker for ERC-4337 UserOperations. It polls `eth_getUserOperationReceipt` on a bundler RPC (a custom
+ * `bundlerUrl` or Pimlico) and, once the UserOperation is bundled, tracks the bundle transaction on-chain.
  */
 
 /**
- * The receipt returned by `getUserOperationReceipt`.
+ * The UserOperation receipt returned by viem's `getUserOperationReceipt`.
  */
 type Erc4337UserOpReceipt = GetUserOperationReceiptReturnType;
 /**
- * Result structure produced by `erc4337Fetcher` on each polling cycle.
+ * The result {@link erc4337Fetcher} reports on each polling tick.
  */
 type Erc4337FetchResult = {
+    /** The UserOperation receipt, or `null` while it is not available. */
     receipt: Erc4337UserOpReceipt | null;
+    /** `pending` while the UserOperation is not bundled, then `success` or `failed`. */
     status: 'pending' | 'success' | 'failed';
+    /** The hash of the bundle transaction that included the UserOperation, once known. */
     hash?: Hex;
+    /** The failure reason: the revert reason of the receipt, or a validation message. */
     reason?: string;
 };
-type Erc4337FetcherParams<T extends Transaction> = Parameters<PollingTrackerConfig<Erc4337FetchResult, T>['fetcher']>[0];
 /**
- * Low-level fetcher for ERC-4337 UserOperation status.
- * Queries `eth_getUserOperationReceipt` on the configured Bundler client.
+ * The transaction fields {@link erc4337Fetcher} reads: the `userOpHash` as `txKey`, the numeric `chainId`, and either a
+ * custom `bundlerUrl` or a `pimlicoApiKey` (without both, the public Pimlico endpoint is used).
+ */
+type Erc4337FetcherTx = Pick<Transaction, 'txKey' | 'chainId'> & Pick<EvmTransaction, 'pimlicoApiKey' | 'bundlerUrl'>;
+/**
+ * A fetcher for `initializePollingTracker` from `@tuwaio/pulsar-core` that checks a UserOperation once through
+ * `eth_getUserOperationReceipt`.
+ *
+ * The bundler client comes from `createBundlerRpcClient` of `@tuwaio/orbit-evm`, which caches it in memory and
+ * contacts `tx.bundlerUrl`, else `api.pimlico.io` with `tx.pimlicoApiKey`, else the rate-limited `public.pimlico.io`.
+ *
+ * - Invalid `chainId`: stops polling (keeping the transaction) and calls `onFailure` with a reason.
+ * - Receipt not available yet: calls `onIntervalTick` with `status: 'pending'`.
+ * - Receipt with `success: true`: stops polling (keeping the transaction) and calls `onSuccess` with the bundle `hash`.
+ * - Receipt with `success: false`: stops polling (keeping the transaction) and calls `onFailure` with the revert reason.
+ * - Any other error is rethrown, so the polling tracker counts it as a failed attempt.
  *
- * @param params - The fetcher parameters provided by the polling tracker.
+ * @template T - The tracked transaction type.
+ * @param params - The fetcher parameters provided by `initializePollingTracker`.
+ * @returns A promise that resolves when the check is done.
  */
-declare function erc4337Fetcher<T extends Transaction>({ tx, stopPolling, onSuccess, onFailure, onIntervalTick, }: Erc4337FetcherParams<T>): Promise<void>;
+declare function erc4337Fetcher<T extends Erc4337FetcherTx>({ tx, stopPolling, onSuccess, onFailure, onIntervalTick, }: PollingFetcherParams<Erc4337FetchResult, T>): Promise<void>;
 /**
- * Configuration options for the low-level ERC-4337 tracker.
+ * The configuration of {@link erc4337Tracker}.
+ *
+ * @template T - The tracked transaction type.
  */
-type Erc4337TrackerConfig<T extends Transaction> = {
-    tx: T & Pick<Transaction, 'txKey' | 'pending'>;
+type Erc4337TrackerConfig<T extends Erc4337FetcherTx & Pick<Transaction, 'pending'>> = {
+    /** The UserOperation to track (see {@link Erc4337FetcherTx}); polling starts only if `pending` is `true`. */
+    tx: T;
+    /**
+     * Called when the UserOperation succeeded.
+     * @param result - The result; `hash` is the bundle transaction hash.
+     */
     onSuccess: (result: Erc4337FetchResult) => void;
+    /**
+     * Called when the UserOperation reverted or the chain ID is invalid, and without arguments after `maxRetries`
+     * consecutive failed attempts.
+     * @param result - The result with the failure `reason`, if any.
+     */
     onFailure: (result?: Erc4337FetchResult) => void;
+    /**
+     * Called on every tick while the UserOperation is not bundled.
+     * @param result - The pending result.
+     */
     onIntervalTick?: (result: Erc4337FetchResult) => void;
+    /**
+     * Called when polling stops after `maxRetries` consecutive failed attempts.
+     * @param txKey - The `userOpHash`.
+     */
     removeTxFromPool?: (txKey: string) => void;
+    /** The delay before each attempt, in milliseconds. Defaults to 2000. */
     pollingInterval?: number;
+    /** The number of consecutive failed attempts after which polling stops. Defaults to 60. */
     maxRetries?: number;
 };
 /**
- * Initializes a low-level polling tracker for ERC-4337 UserOperations.
+ * Starts polling a UserOperation in the background with {@link erc4337Fetcher}, without a store: every 2 s by default,
+ * giving up after 60 consecutive failed attempts. It only follows the bundler; it does not wait for block
+ * confirmations of the bundle transaction (pass `onSuccess`'s `hash` to {@link evmTracker} for that).
+ *
+ * @template T - The tracked transaction type.
+ * @param config - The UserOperation and the callbacks.
  *
- * @param config - The tracker configuration options.
+ * @example
+ * ```ts
+ * erc4337Tracker({
+ *   tx: { txKey: userOpHash, chainId: 11155111, pimlicoApiKey, pending: true },
+ *   onSuccess: ({ hash }) => console.log('Bundled in', hash),
+ *   onFailure: (result) => console.error('UserOperation failed', result?.reason),
+ * });
+ * ```
  */
-declare function erc4337Tracker<T extends Transaction>(config: Erc4337TrackerConfig<T>): void;
+declare function erc4337Tracker<T extends Erc4337FetcherTx & Pick<Transaction, 'pending'>>(config: Erc4337TrackerConfig<T>): void;
 /**
- * Parameters for the store-connected ERC-4337 tracker.
+ * The parameters of {@link erc4337TrackerForStore}: the transaction, an optional wagmi config, the store members used
+ * by trackers and the callbacks.
+ *
+ * @template T - The application transaction type.
  */
 type Erc4337TrackerForStoreParams<T extends Transaction> = Pick<ITxTrackingStore<T>, 'updateTxParams' | 'removeTxFromPool' | 'transactionsPool'> & {
+    /** The transaction to track; `txKey` is the `userOpHash`. */
     tx: T;
+    /** The wagmi config, used for the on-chain stage. Without it, the transaction succeeds as soon as it is bundled. */
     config?: Config;
 } & TrackerCallbacks<T>;
 /**
- * High-level two-stage tracker for ERC-4337 UserOperations integrated with the Pulsar store.
+ * Tracks an ERC-4337 UserOperation of the Pulsar store in two stages and writes the results to the store:
  *
- * - Stage 1 (Bundler Mempool): Polls `eth_getUserOperationReceipt` against the Bundler RPC.
- *   As soon as the UserOp is bundled on-chain, writes `tx.hash` to the store and stops Bundler polling
- *   without evicting the transaction from the pool.
- * - Stage 2 (EVM On-Chain Finality): Hands off tracking to `evmTracker` for on-chain block confirmations,
- *   block timestamp resolution, and final terminal status update.
+ * 1. Bundler: polls {@link erc4337Fetcher} every 2 s (up to 60 consecutive failed attempts). When the UserOperation
+ *    is bundled, writes the bundle transaction `hash`. A reverted UserOperation, or 60 failed attempts, marks the
+ *    transaction `Failed`.
+ * 2. On-chain: runs {@link evmTracker} for the bundle transaction and writes the details, confirmations and the final
+ *    `Success`, `Failed` or `Replaced` status. Without `config`, the transaction is marked `Success` as soon as it is
+ *    bundled.
  *
- * Supports seamless session restoration across page reloads: if `tx.hash` is already populated,
- * Stage 1 is bypassed and tracking resumes directly at Stage 2.
+ * If `tx.hash` is already set (tracking resumed after a reload), stage 1 is skipped. The transaction is never removed
+ * from the pool. The callbacks receive the transaction with every update written by the tracker.
  *
- * @param params - The store actions, Wagmi config, and transaction object to track.
+ * @template T - The application transaction type.
+ * @param params - The transaction, the wagmi config, the store members and the callbacks.
+ * @returns A promise that resolves once stage 1 has started, or when stage 2 has finished if it started directly.
  */
 declare function erc4337TrackerForStore<T extends Transaction>({ tx, config, updateTxParams, transactionsPool, onSuccess, onError, onReplaced, }: Erc4337TrackerForStoreParams<T>): Promise<void>;
 
 /**
- * @file This file contains the tracker implementation for standard EVM transactions.
- * It uses viem's public actions (`getTransaction`, `waitForTransactionReceipt`) to monitor
- * a transaction's lifecycle from submission to finality with robust timeout handling.
+ * @file The tracker for standard EVM transactions. It uses viem actions (`getTransaction`,
+ * `waitForTransactionReceipt`, `getTransactionConfirmations`, `getBlock`) through the wagmi client of the chain.
  */
 
 /**
- * Checks whether an error during receipt polling is transient (RPC network glitch, timeout, or unindexed tx).
- * Recursively inspects nested error causes to handle wrapped Viem transport errors.
+ * Checks whether an error thrown while waiting for a receipt is transient: a receipt timeout or "not found" error, an
+ * HTTP or WebSocket transport error, or a message about a timeout, rate limit, connection reset or a 502/503/504
+ * status. Nested `cause` errors are checked too.
  *
- * @param error - The caught error object.
- * @returns `true` if the error is considered transient and retryable; otherwise `false`.
+ * @param error - The caught error.
+ * @returns `true` if waiting for the receipt should be retried.
  */
 declare function isRetryableReceiptError(error: unknown): boolean;
 /**
- * Defines the parameters for the low-level EVM transaction tracker.
+ * The configuration of {@link evmTracker}.
  */
 type EVMTrackerParams = {
-    /** The transaction identity parameters (chainId, txKey, requiredConfirmations). */
+    /**
+     * The transaction: its hash (`txKey`), its numeric `chainId` (which must be configured in `config`) and, optionally,
+     * the number of confirmations to wait for.
+     */
     tx: Pick<Transaction, 'chainId' | 'txKey' | 'requiredConfirmations'>;
-    /** The `@wagmi/core` configuration instance used to resolve network clients. */
+    /** The wagmi config; the tracker uses its client for `tx.chainId`. */
     config: Config;
-    /** Callback fired once transaction details (nonce, input, values) are successfully fetched. */
+    /**
+     * Called once with the result of `getTransaction`.
+     * @param txDetails - The transaction: nonce, fees, `to`, `value`, `input`.
+     */
     onTxDetailsFetched: (txDetails: GetTransactionReturnType) => void;
-    /** Callback fired when the transaction is mined successfully (or reverted on-chain). */
+    /**
+     * Called and awaited once the receipt is available and the required confirmations are reached. Also called for
+     * reverted transactions: check `receipt.status`.
+     * @param txDetails - The result of `getTransaction`.
+     * @param receipt - The transaction receipt.
+     * @param client - The viem client of the chain, for further RPC calls.
+     */
     onSuccess: (txDetails: GetTransactionReturnType, receipt: TransactionReceipt, client: Client) => Promise<void>;
-    /** Callback fired when the transaction has been replaced (repriced or cancelled). */
+    /**
+     * Called when viem detects that another transaction with the same nonce replaced this one (speed-up or cancel).
+     * @param replacement - viem's replacement data: the `reason` and the replacing `transaction`.
+     */
     onReplaced: (replacement: ReplacementReturnType) => void;
-    /** Callback fired when tracking fails fatally or exceeds all retry attempts. */
+    /**
+     * Called once when tracking gives up (see {@link evmTracker}).
+     * @param error - The last error.
+     */
     onFailure: (error?: unknown) => void;
-    /** Optional callback fired when tracker initialization starts. */
+    /** Called once, before anything else. */
     onInitialize?: () => void;
-    /** Number of retries for the initial `getTransaction` fetch step. Defaults to 10. */
+    /** Number of `getTransaction` attempts. Defaults to 10. */
     retryCount?: number;
-    /** Timeout in milliseconds between `getTransaction` retry attempts. Defaults to 3000ms. */
+    /** Delay between `getTransaction` attempts, in milliseconds. Defaults to 3000. */
     retryTimeout?: number;
-    /** Optional callback fired whenever required block confirmation count updates. */
+    /**
+     * Called while waiting for `requiredConfirmations` (only when it is above 1).
+     * @param confirmations - The current number of confirmations.
+     */
     onConfirmationsUpdate?: (confirmations: number) => void;
-    /** Optional custom parameters passed directly to viem's `waitForTransactionReceipt`. */
+    /**
+     * Options for viem's `waitForTransactionReceipt`, merged over the defaults (`retryCount: 10`, `retryDelay: 3000`,
+     * `timeout: 60000`).
+     */
     waitForTransactionReceiptParams?: WaitForTransactionReceiptParameters;
 };
 /**
- * A low-level tracker for monitoring a standard EVM transaction by its hash.
- * Retries fetching transaction details and gracefully polls for transaction receipt,
- * recovering automatically from RPC network glitches and timeout errors.
+ * Tracks a standard EVM transaction by its hash, without a store. Use it to track transactions in your own state or on
+ * a server.
+ *
+ * Steps (all RPC calls go through the wagmi client of `tx.chainId`):
+ * 1. Calls `onInitialize`. Fails at once for the zero hash or when there is no client for the chain.
+ * 2. Calls `getTransaction` up to `retryCount` times, `retryTimeout` ms apart, so a transaction the node has not
+ *    indexed yet is still found; then calls `onTxDetailsFetched`.
+ * 3. Waits for the receipt with `waitForTransactionReceipt`, retrying up to 5 times (5, 10, 15, 20 and 25 s apart) when
+ *    {@link isRetryableReceiptError} matches. If viem reports a replacement, calls `onReplaced` and stops.
+ * 4. If `requiredConfirmations` is above 1, polls `getTransactionConfirmations` every 5 s until it is reached.
+ * 5. Awaits `onSuccess`, also for reverted transactions.
  *
- * @param params - The configuration parameters and lifecycle callbacks for the EVM tracker.
- * @returns A promise that resolves when tracking completes or fails fatally.
+ * Any other error, including one thrown by `onSuccess`, is passed to `onFailure`.
+ *
+ * @param params - The transaction, the wagmi config and the callbacks.
+ * @returns A promise that resolves when tracking has finished.
+ *
+ * @example
+ * ```ts
+ * await evmTracker({
+ *   config: wagmiConfig,
+ *   tx: { txKey: hash, chainId: 1, requiredConfirmations: 2 },
+ *   onTxDetailsFetched: (details) => console.log('Nonce', details.nonce),
+ *   onSuccess: async (_details, receipt) => console.log('Mined with status', receipt.status),
+ *   onReplaced: (replacement) => console.log('Replaced by', replacement.transaction.hash),
+ *   onFailure: (error) => console.error('Tracking failed', error),
+ * });
+ * ```
  */
 declare function evmTracker(params: EVMTrackerParams): Promise<void>;
 /**
- * A higher-level wrapper for `evmTracker` that integrates directly with the Pulsar store.
- * Updates transaction lifecycle states (pending, success, failed, replaced) in the Zustand store.
+ * Runs {@link evmTracker} for a transaction of the Pulsar store and writes the results to it through
+ * `updateTxParams`: `hash` at start, the transaction details, `confirmations`, and finally `status` `Success`/`Failed`
+ * with `pending: false` and the block timestamp, `Replaced` with `replacedTxHash`, or `Failed` with the normalized
+ * error. The transaction is never removed from the pool.
  *
- * @template T - The application-specific transaction state structure extending `Transaction`.
- * @param params - Configuration connecting `@wagmi/core`, store mutation methods, target transaction, and callbacks.
- * @returns A promise that resolves when transaction tracking finishes and store state is committed.
+ * The callbacks receive the transaction with every update written by the tracker (`createTxUpdater` from
+ * `@tuwaio/pulsar-core`). A reverted transaction calls `onError` with `Error('Transaction reverted')`.
+ *
+ * @template T - The application transaction type.
+ * @param params - The transaction, the wagmi config, the store members and the callbacks.
+ * @returns A promise that resolves when tracking has finished.
  */
 declare function evmTrackerForStore<T extends Transaction>(params: Pick<EVMTrackerParams, 'config'> & Pick<ITxTrackingStore<T>, 'updateTxParams' | 'transactionsPool'> & {
     tx: T;
 } & TrackerCallbacks<T>): Promise<void>;
 
 /**
- * @file This file implements the transaction tracking logic for meta-transactions relayed via the Gelato Network.
- * It uses a polling mechanism to check the status of a Gelato task via the authenticated Gelato RPC client.
- *
- * The fetcher calls `relayer_getStatus` on the Gelato RPC endpoint and interprets the numeric
- * status codes to determine whether a task is still pending, succeeded, was rejected, or reverted.
+ * @file The deprecated tracker for Gelato relay tasks. It polls `relayer_getStatus` on the Gelato RPC endpoint and maps
+ * the numeric status codes to Pulsar statuses.
  */
 
 /**
  * Numeric status codes returned by the Gelato `relayer_getStatus` RPC method.
  *
- * @see https://docs.gelato.cloud/
+ * @deprecated Gelato relay is deprecated. Use `TransactionTracker.ERC4337` instead.
+ * @see {@link https://docs.gelato.cloud/ Gelato documentation}
  */
 declare enum GelatoStatusCode {
     /** The task has been received and is awaiting execution. */
@@ -181,7 +310,9 @@ declare enum GelatoStatusCode {
     Reverted = 500
 }
 /**
- * Common fields shared by all Gelato task status responses.
+ * Fields shared by every Gelato task status response.
+ *
+ * @deprecated Gelato relay is deprecated. Use `TransactionTracker.ERC4337` instead.
  */
 type GelatoBaseStatus = {
     /** The chain ID on which the task was submitted. */
@@ -192,8 +323,9 @@ type GelatoBaseStatus = {
     id: string;
 };
 /**
- * Discriminated union representing all possible Gelato task status responses.
- * Each variant corresponds to a specific {@link GelatoStatusCode}.
+ * A Gelato task status response, discriminated by `status` ({@link GelatoStatusCode}).
+ *
+ * @deprecated Gelato relay is deprecated. Use `TransactionTracker.ERC4337` instead.
  */
 type GelatoTaskStatus = (GelatoBaseStatus & {
     status: GelatoStatusCode.Pending;
@@ -218,114 +350,148 @@ type GelatoTaskStatus = (GelatoBaseStatus & {
     };
 });
 /**
- * Creates a reusable fetcher function for `initializePollingTracker` that queries the
- * Gelato RPC endpoint (`relayer_getStatus`) for a task's status using an authenticated client.
+ * Creates a fetcher for `initializePollingTracker` from `@tuwaio/pulsar-core` that checks a Gelato task (`tx.txKey`)
+ * once through `relayer_getStatus`.
  *
- * The fetcher interprets the numeric status codes and calls the appropriate polling callbacks:
- * - {@link GelatoStatusCode.Success} → `onSuccess`
- * - {@link GelatoStatusCode.Rejected} / {@link GelatoStatusCode.Reverted} → `onFailure`
- * - {@link GelatoStatusCode.Submitted} → `onIntervalTick` (to update the tx hash)
+ * On every tick it calls `onIntervalTick` with the status. {@link GelatoStatusCode.Success} calls `onSuccess`;
+ * {@link GelatoStatusCode.Rejected} and {@link GelatoStatusCode.Reverted} call `onFailure`; both stop polling and keep
+ * the transaction. A task still pending one hour after `createdAt` calls `onFailure` with its status and stops polling,
+ * keeping the transaction. Request errors are thrown, so the polling tracker counts them as failed attempts.
  *
- * @deprecated Gelato relay is deprecated. Use TransactionTracker.ERC4337 and erc4337Fetcher instead.
- * @param {ReturnType<Transport>} client - A viem transport client configured for the Gelato API.
- * @returns {PollingTrackerConfig<GelatoTaskStatus, Transaction>['fetcher']} The fetcher function.
+ * @deprecated Gelato relay is deprecated. Use `TransactionTracker.ERC4337` and {@link erc4337Fetcher} instead.
+ * @param client - A transport created by {@link createGelatoClient}.
+ * @returns The fetcher.
  */
-declare function gelatoFetcher(client: ReturnType<Transport>): PollingTrackerConfig<GelatoTaskStatus, Transaction>['fetcher'];
+declare function gelatoFetcher(client: ReturnType<Transport>): (params: PollingFetcherParams<GelatoTaskStatus, Pick<Transaction, 'txKey'>>) => Promise<void>;
 /**
- * @deprecated Gelato relay is deprecated. Use TransactionTracker.ERC4337 and erc4337TrackerForStore instead.
- * A higher-level wrapper that integrates the Gelato polling logic with the Pulsar store.
- * It creates an authenticated Gelato RPC client and uses {@link gelatoFetcher} to
- * build the fetcher, then delegates to `initializePollingTracker` with store-specific callbacks.
+ * Tracks a Gelato task of the Pulsar store with {@link gelatoFetcher} (every 5 s, up to 10 consecutive failed
+ * attempts) and writes the results to the store: the transaction `hash` once the task is submitted, then `Success` or
+ * `Failed` with the local time as `finishedTimestamp`.
  *
- * @template T - The application-specific transaction type.
+ * When tracking gives up (10 consecutive failed attempts, or the task still pending after one hour), the transaction
+ * is marked `Failed` and stays in the pool.
  *
- * @param params.tx - The transaction to track.
- * @param params.gelatoApiKey - The Gelato API key for authenticating RPC requests.
- * @param params.updateTxParams - Store action to update transaction fields.
- * @param params.removeTxFromPool - Store action to remove a transaction from the pool.
- * @param params.transactionsPool - The current pool of tracked transactions.
- * @param params.onSuccess - Optional callback invoked when the transaction succeeds.
- * @param params.onError - Optional callback invoked when the transaction fails.
+ * Side effects: sends requests to the Gelato API with `gelatoApiKey` (see {@link createGelatoClient}). The callbacks
+ * receive the transaction with every update written by the tracker.
+ *
+ * @deprecated Gelato relay is deprecated. Use `TransactionTracker.ERC4337` and {@link erc4337TrackerForStore} instead.
+ * @template T - The application transaction type.
+ * @param params - The transaction, the Gelato API key, the store members and the callbacks.
+ * @param params.tx - The transaction to track; `txKey` is the Gelato task ID.
+ * @param params.gelatoApiKey - The Gelato API key.
+ * @param params.updateTxParams - The store's `updateTxParams`.
+ * @param params.removeTxFromPool - Not used: failed transactions stay in the pool.
+ * @param params.transactionsPool - The store's pool when tracking starts.
+ * @param params.onSuccess - Called when the task succeeded.
+ * @param params.onError - Called when the task failed or tracking gave up.
  */
-declare function gelatoTrackerForStore<T extends Transaction>({ tx, gelatoApiKey, updateTxParams, removeTxFromPool, transactionsPool, onSuccess, onError, }: Pick<ITxTrackingStore<T>, 'updateTxParams' | 'removeTxFromPool' | 'transactionsPool'> & {
+declare function gelatoTrackerForStore<T extends Transaction>({ tx, gelatoApiKey, updateTxParams, transactionsPool, onSuccess, onError, }: Pick<ITxTrackingStore<T>, 'updateTxParams' | 'removeTxFromPool' | 'transactionsPool'> & {
     tx: T;
     gelatoApiKey: string;
 } & TrackerCallbacks<T>): void;
 /**
- * @deprecated Gelato relay is deprecated. Use TransactionTracker.ERC4337 and erc4337Tracker instead.
+ * Alias of {@link gelatoTrackerForStore}.
+ *
+ * @deprecated Gelato relay is deprecated. Use `TransactionTracker.ERC4337` and {@link erc4337TrackerForStore} instead.
  */
 declare const gelatoTracker: typeof gelatoTrackerForStore;
 
 /**
- * @file This file implements the transaction tracking logic for Safe (formerly Gnosis Safe) multisig transactions.
- * It uses a polling mechanism to query the Safe Transaction Service API for the status of a `safeTxHash`.
+ * @file The tracker for Safe multisig transactions. It polls the Safe Transaction Service API for the status of a
+ * `safeTxHash`.
  */
 
 /**
- * Defines the shape of the primary response for a single transaction from the Safe Transaction Service API.
+ * The fields of a multisig transaction returned by the Safe Transaction Service API that the Safe tracker reads.
  */
 type SafeTxStatusResponse = {
+    /** The hash of the executed on-chain transaction, or `null` before execution. */
     transactionHash: Hex | null;
+    /** The Safe transaction hash (the `txKey` of the tracked transaction). */
     safeTxHash: Hex;
+    /** `true` once the multisig transaction has been executed on-chain. */
     isExecuted: boolean;
+    /** Whether the execution succeeded; `null` before execution. */
     isSuccessful: boolean | null;
+    /** ISO date of the execution, or `null` before execution. */
     executionDate: string | null;
+    /** ISO date when the transaction was proposed to the service. */
     submissionDate: string;
+    /** ISO date of the last change. */
     modified: string;
+    /** The Safe nonce of the transaction. */
     nonce: number;
 };
 /**
- * A reusable fetcher for `initializePollingTracker` that queries the Safe Transaction Service API.
- * It handles the complex logic of detecting executed, failed, and replaced multisig transactions.
+ * A fetcher for `initializePollingTracker` from `@tuwaio/pulsar-core` that checks a Safe multisig transaction once
+ * through the Safe Transaction Service API of `tx.chainId` ({@link SafeTransactionServiceUrls}). `tx.txKey` is the
+ * `safeTxHash` and `tx.from` the Safe address.
+ *
+ * Requests: `GET <service>/multisig-transactions/<safeTxHash>/`, and while it is not executed,
+ * `GET <service>/safes/<from>/multisig-transactions/?nonce=<nonce>`.
+ *
+ * - Executed: calls `onSuccess` or `onFailure` (by `isSuccessful`) and stops polling, keeping the transaction.
+ * - Another transaction with the same nonce was executed: calls `onReplaced` with it and stops polling, keeping the
+ *   transaction.
+ * - Still pending one day after `submissionDate`: calls `onFailure` with the status and stops polling, keeping the
+ *   transaction.
+ * - The service returns 404: calls `onFailure()` without a response and stops polling, keeping the transaction.
+ * - An unsupported chain or another failed request throws, so the polling tracker counts it as a failed attempt.
+ *
+ * @param params - The fetcher parameters provided by `initializePollingTracker`.
+ * @returns A promise that resolves when the check is done.
  */
-declare const safeFetcher: PollingTrackerConfig<SafeTxStatusResponse, Transaction>['fetcher'];
+declare const safeFetcher: ({ tx, stopPolling, onSuccess, onFailure, onReplaced, onIntervalTick, }: PollingFetcherParams<SafeTxStatusResponse, Pick<Transaction, "txKey" | "chainId" | "from">>) => Promise<void>;
 /**
- * A higher-level wrapper that integrates the Safe polling logic with the Pulsar store.
- * It uses the generic `safeFetcher` and provides store-specific callbacks.
+ * Tracks a Safe multisig transaction of the Pulsar store with {@link safeFetcher} (every 5 s, up to 10 consecutive
+ * failed attempts) and writes the results to the store: the executed transaction `hash`, then `Success`, `Failed` or
+ * `Replaced` (with the `safeTxHash` of the executed transaction as `replacedTxHash`) and the execution date as
+ * `finishedTimestamp`.
+ *
+ * When tracking gives up (10 consecutive failed attempts, a 404 response, or still pending one day after it was
+ * proposed), the transaction is marked `Failed` with an error that says why, and it stays in the pool.
  *
- * @template T - The application-specific transaction type.
+ * Side effects: sends requests to the Safe Transaction Service. The callbacks receive the transaction with every update
+ * written by the tracker.
+ *
+ * @template T - The application transaction type.
+ * @param params - The transaction, the store members and the callbacks.
+ * @param params.tx - The transaction to track; `txKey` is the `safeTxHash` and `from` the Safe address.
+ * @param params.updateTxParams - The store's `updateTxParams`.
+ * @param params.removeTxFromPool - Not used: failed transactions stay in the pool.
+ * @param params.transactionsPool - The store's pool when tracking starts.
+ * @param params.onSuccess - Called when the transaction was executed successfully.
+ * @param params.onError - Called when the execution failed or tracking gave up.
+ * @param params.onReplaced - Called when another transaction with the same nonce was executed.
  */
-declare function safeTrackerForStore<T extends Transaction>({ tx, updateTxParams, removeTxFromPool, transactionsPool, onSuccess, onError, onReplaced, }: Pick<ITxTrackingStore<T>, 'updateTxParams' | 'removeTxFromPool' | 'transactionsPool'> & {
+declare function safeTrackerForStore<T extends Transaction>({ tx, updateTxParams, transactionsPool, onSuccess, onError, onReplaced, }: Pick<ITxTrackingStore<T>, 'updateTxParams' | 'removeTxFromPool' | 'transactionsPool'> & {
     tx: T;
 } & TrackerCallbacks<T>): void;
 
 /**
- * @file This file contains a utility function for canceling a pending EVM transaction.
+ * @file Cancels a pending EVM transaction by replacing it with a zero-value transaction.
  */
 
 /**
- * Cancels a pending EVM transaction by sending a new, zero-value transaction to oneself
- * with the same nonce but higher gas fees. This effectively replaces the original transaction.
- *
- * @template T - The transaction type, which must be a valid EVM transaction.
- *
- * @param {object} params - The parameters required to cancel the transaction.
- * @param {Config} params.config - The wagmi configuration object.
- * @param {T} params.tx - The original transaction object to be canceled. It must contain the nonce and gas fee fields.
+ * Cancels a pending EVM transaction: asks the connected wallet to send a zero-value transaction to its own address with
+ * the same nonce and both EIP-1559 fees raised by 15%. When it is mined, the tracker of the original transaction
+ * reports it as `Replaced`; the cancellation transaction itself is not added to the pool.
  *
- * @returns {Promise<Hex>} A promise that resolves with the hash of the new cancellation transaction.
+ * Side effects: opens a wallet prompt and broadcasts a transaction.
  *
- * @throws {Error} Throws an error if:
- * - The transaction is not an EVM transaction.
- * - The transaction is missing required fields (`nonce`, `maxFeePerGas`, etc.).
- * - The wagmi config is not provided.
- * - No connected account is found.
- * - The `sendTransaction` call fails.
+ * @template T - The application transaction type.
+ * @param params - The wagmi config and the transaction.
+ * @param params.config - The wagmi config of the app.
+ * @param params.tx - The pending transaction. It must be an EVM transaction with `nonce`, `maxFeePerGas` and
+ * `maxPriorityFeePerGas` (set by the EVM tracker once the transaction details are fetched).
+ * @returns The hash of the cancellation transaction.
+ * @throws `Error` when the transaction is not an EVM transaction or lacks the nonce and fee fields, and
+ * `Error('Failed to cancel transaction: …')` (with the original error as `cause`) when no account is connected or the
+ * wallet rejects or fails to send the transaction.
  *
  * @example
  * ```ts
- * const handleCancel = async (stuckTransaction) => {
- * try {
- * const cancelTxHash = await cancelTxAction({
- * config: wagmiConfig,
- * tx: stuckTransaction,
- * });
- * console.log('Cancellation transaction sent with hash:', cancelTxHash);
- * // You should now update your state to track this new transaction.
- * } catch (error) {
- * console.error('Failed to cancel transaction:', error);
- * }
- * };
+ * const hash = await cancelTxAction({ config: wagmiConfig, tx: pendingTx });
  * ```
  */
 declare function cancelTxAction<T extends Transaction>({ config, tx }: {
@@ -334,179 +500,192 @@ declare function cancelTxAction<T extends Transaction>({ config, tx }: {
 }): Promise<Hex>;
 
 /**
- * @file This file contains a utility function that acts as a router to initialize the correct transaction tracker.
- * Based on a transaction's `tracker` property, it delegates the tracking task to the appropriate implementation.
+ * @file Routes an EVM transaction of the Pulsar store to the tracker named by its `tracker` field.
  */
 
 /**
- * The parameters required to initialize a tracker.
- * @template T - The application-specific transaction type.
+ * The parameters of {@link checkAndInitializeTrackerInStore}.
+ *
+ * @template T - The application transaction type.
  */
 type InitializeTrackerParams<T extends Transaction> = Pick<ITxTrackingStore<T>, 'updateTxParams' | 'removeTxFromPool' | 'transactionsPool'> & {
+    /** The wagmi config of the app. */
     config: Config;
+    /** The transaction to track. */
     tx: T;
+    /** The tracker to run, usually `tx.tracker`. */
     tracker: TransactionTracker;
+    /** @deprecated Gelato API key; required to run the Gelato tracker. */
     gelatoApiKey?: string;
 } & TrackerCallbacks<T>;
 /**
- * Initializes the appropriate tracker for a given transaction based on its `tracker` type.
- * This function acts as a central router, delegating to the specific tracker implementation
- * (e.g., standard EVM, Gelato, Safe, or ERC-4337).
+ * Starts the tracker named by `tracker` for a transaction of the Pulsar store: {@link evmTrackerForStore},
+ * {@link erc4337TrackerForStore}, {@link safeTrackerForStore} or {@link gelatoTrackerForStore}. A Gelato transaction
+ * without `gelatoApiKey`, or an unknown tracker, falls back to the standard EVM tracker with a console warning.
+ * `pulsarEvmAdapter` uses it as `checkAndInitializeTrackerInStore`.
  *
- * @template T - The application-specific transaction type, extending the base `Transaction`.
- * @param {InitializeTrackerParams<T>} params - The parameters for initializing the tracker.
- * @returns {Promise<void>} A promise that resolves once the tracking process has been successfully initiated.
+ * @template T - The application transaction type.
+ * @param params - The tracker, the transaction, the wagmi config, the store members and the callbacks.
+ * @returns The promise of the started tracker. For the standard EVM tracker it resolves only when tracking has
+ * finished; polling trackers resolve once polling has started.
  */
 declare function checkAndInitializeTrackerInStore<T extends Transaction>({ tracker, tx, config, transactionsPool, onSuccess, onError, onReplaced, gelatoApiKey, ...rest }: InitializeTrackerParams<T>): Promise<void>;
 
 /**
- * @file This file contains a utility to check if the Gelato Relay service is available for a specific chain.
- * It uses the authenticated Gelato RPC client to fetch relay capabilities and caches the result.
+ * @file Checks whether Gelato Relay supports a chain, using the `relayer_getCapabilities` RPC method.
  */
 /**
- * Represents the per-chain capabilities returned by the Gelato `relayer_getCapabilities` RPC method.
+ * The Gelato Relay capabilities of one chain, as returned by `relayer_getCapabilities`.
  *
- * @property {string} feeCollector - The address of the fee collector contract on this chain.
- * @property {GelatoToken[]} tokens - The list of ERC-20 tokens accepted for fee payment on this chain.
+ * @deprecated Gelato relay is deprecated. Use `TransactionTracker.ERC4337` instead.
  */
 type GelatoCapabilitiesByChain = {
+    /** The address of the fee collector contract on this chain. */
     feeCollector: string;
+    /** The ERC-20 tokens accepted for fee payment on this chain. */
     tokens: GelatoToken[];
 };
 /**
- * Represents a token accepted for fee payment by the Gelato Relay on a given chain.
+ * A token accepted for fee payment by Gelato Relay.
  *
- * @property {string} address - The ERC-20 token contract address.
- * @property {number} decimals - The number of decimals for the token.
+ * @deprecated Gelato relay is deprecated. Use `TransactionTracker.ERC4337` instead.
  */
 type GelatoToken = {
+    /** The ERC-20 token contract address. */
     address: string;
+    /** The number of decimals of the token. */
     decimals: number;
 };
 /**
- * A record of Gelato relay capabilities keyed by numeric chain ID.
+ * Gelato Relay capabilities by numeric chain ID.
+ *
+ * @deprecated Gelato relay is deprecated. Use `TransactionTracker.ERC4337` instead.
  */
 type GelatoCapabilities = Record<number, GelatoCapabilitiesByChain>;
 /**
- * Checks if the Gelato Relay service supports a given chain ID.
+ * Checks whether Gelato Relay supports a chain.
  *
- * This function fetches the relay capabilities via the authenticated Gelato RPC client
- * (`relayer_getCapabilities`) and checks whether the specified chain is present in the response.
- * Results are cached in memory per API key for the lifetime of the application to minimize network requests.
+ * Side effects: the first call for an API key sends `relayer_getCapabilities` to the Gelato API (see
+ * {@link createGelatoClient}); the result is cached in memory per API key until the page is reloaded. A failed request
+ * is logged, is not cached, and returns `false`.
  *
- * @deprecated Gelato relay is deprecated. Use TransactionTracker.ERC4337 instead.
- * @param {number} chainId - The chain identifier to check.
- * @param {string} gelatoApiKey - The Gelato API key used for authentication.
- * @returns {Promise<boolean>} A promise that resolves to `true` if Gelato supports the chain, `false` otherwise.
+ * @deprecated Gelato relay is deprecated. Use `TransactionTracker.ERC4337` instead.
+ * @param chainId - The chain ID to check.
+ * @param gelatoApiKey - The Gelato API key.
+ * @returns `true` if the chain is supported; `false` if it is not or the request failed. Never rejects.
  */
 declare function checkIsGelatoAvailable(chainId: number, gelatoApiKey: string): Promise<boolean>;
 
 /**
- * @file This file contains a utility function to determine the correct tracker for a transaction
- * based on the key returned by the submission function and the connector type.
+ * @file Picks the EVM tracker for the key returned by an `actionFunction`.
  */
 
 /**
- * Determines which transaction tracker to use based on the format of the transaction key and the connector type.
+ * Picks the tracker for the key returned by an `actionFunction`. The key is always used as `txKey`. Rules, in order:
+ * 1. `tracker` is `Gelato` and `gelatoApiKey` is set: `Gelato` (the key is a task ID).
+ * 2. The key must be a hex string; otherwise it throws.
+ * 3. `tracker` is `ERC4337`: `ERC4337` (the key is a `userOpHash`). ERC-4337 is never detected automatically.
+ * 4. The connector type ends with `safe` or `safewallet` (for example `evm:safe`): `Safe` (the key is a `safeTxHash`).
+ * 5. Otherwise: `Ethereum`.
  *
- * This function is a critical routing step after a transaction is submitted. It inspects
- * the key returned by the `actionFunction` and the connector type to decide the tracking strategy.
- * The logic follows a specific priority:
- * 1. Checks for a Gelato Task ID structure.
- * 2. Checks if the connector type indicates a Safe transaction.
- * 3. Defaults to the standard on-chain EVM hash tracker.
+ * `bundlerUrl` and `pimlicoApiKey` are not used here. `pulsarEvmAdapter` uses this function as
+ * `checkTransactionsTracker`.
  *
- * @param {ActionTxKey} actionTxKey - The key returned from the transaction submission function (e.g., a hash or a Gelato task object).
- * @param {string} connectorType - The type of the connector that initiated the action (e.g., 'safe', 'injected').
- * @param {TransactionTracker} tracker - The type of transaction tracker to use.
- * @param {string} gelatoApiKey - Gelato API key for Gelato relayer integration.
- * @returns {{ tracker: TransactionTracker; txKey: string }} An object containing the determined tracker type and the final string-based transaction key.
+ * @param params - The returned key and its context (`CheckTxTracker` from `@tuwaio/pulsar-core`).
+ * @param params.actionTxKey - The key returned by `actionFunction`.
+ * @param params.connectorType - The connector that signed the transaction.
+ * @param params.tracker - The tracker requested in the transaction params, if any.
+ * @param params.gelatoApiKey - Deprecated Gelato API key.
+ * @returns The tracker and the `txKey`.
+ * @throws `Error` when the key is not a hex string and the Gelato rule does not apply.
  *
- * @throws {Error} Throws an error if the `actionTxKey` is not a valid Hex string after failing the Gelato check.
+ * @example
+ * ```ts
+ * checkTransactionsTracker({ actionTxKey: '0xabc123', connectorType: 'evm:metamask' });
+ * // { tracker: TransactionTracker.Ethereum, txKey: '0xabc123' }
+ * ```
  */
 declare function checkTransactionsTracker({ actionTxKey, connectorType, tracker, gelatoApiKey }: CheckTxTracker): {
+    /** The tracker to use. */
     tracker: TransactionTracker;
+    /** The key to store the transaction under: always `actionTxKey`. */
     txKey: string;
 };
 
 /**
- * @file This file contains a utility function for creating a cached viem HTTP transport
- * client configured for the Gelato Relay API.
+ * @file Creates a cached viem HTTP transport for the Gelato Relay RPC API.
  */
 
 /**
- * Configuration options for creating a Gelato API client.
+ * The configuration of {@link createGelatoClient}.
  *
- * @property {string} apiKey - The Gelato API key used for authentication.
- * @property {number} [timeout] - Optional custom HTTP timeout in milliseconds. Defaults to 15000ms.
- * @property {string} [baseUrl] - Optional custom base URL for the Gelato API. Defaults to `https://api.gelato.cloud/rpc`.
- * @property {HttpTransportConfig} [httpTransportConfig] - Optional additional viem HTTP transport configuration overrides.
+ * @deprecated Gelato relay is deprecated. Use `TransactionTracker.ERC4337` instead.
  */
 type GelatoClientConfig = {
+    /** The Gelato API key, sent as a `Bearer` token. */
     apiKey: string;
+    /** HTTP timeout in milliseconds. Defaults to 15000. */
     timeout?: number;
+    /** The base URL of the Gelato API; `/rpc` is appended. Defaults to `https://api.gelato.cloud`. */
     baseUrl?: string;
+    /** Additional options for viem's `http` transport. Its `timeout` overrides `timeout`. */
     httpTransportConfig?: HttpTransportConfig;
 };
 /**
- * Creates or retrieves a cached viem HTTP transport client configured for the Gelato Relay API.
+ * Creates a viem HTTP transport for `<baseUrl>/rpc` of the Gelato Relay API, authenticated with `apiKey`. The default
+ * timeout is 15 s because Gelato's synchronous relay methods can take up to 10 s.
  *
- * The client is cached by a composite key of `apiKey` and `baseUrl` to avoid
- * creating redundant transport instances for identical configurations.
+ * Side effects: the transport is cached in memory by `apiKey` and `baseUrl` until the page is reloaded; later calls
+ * with the same pair return the cached transport and ignore the other options. Creating it sends no request.
  *
- * The default HTTP timeout is set to 15 seconds (instead of viem's default) because
- * Gelato's synchronous relay methods may take up to 10 seconds on the server side,
- * and the client should not time out before the server does.
- *
- * @deprecated Gelato relay is deprecated. Use TransactionTracker.ERC4337 and createBundlerRpcClient instead.
- * @param {GelatoClientConfig} parameters - The configuration for the Gelato client.
- * @returns {ReturnType<Transport>} A viem transport instance configured for the Gelato API.
+ * @deprecated Gelato relay is deprecated. Use `TransactionTracker.ERC4337` and `createBundlerRpcClient` from
+ * `@tuwaio/orbit-evm` instead.
+ * @param parameters - The API key and transport options.
+ * @returns The transport; use its `request` method to call the Gelato RPC API.
  */
 declare const createGelatoClient: (parameters: GelatoClientConfig) => ReturnType<Transport>;
 
 /**
- * @file This file contains constants related to Safe (formerly Gnosis Safe) configuration,
- * including SDK options, web app URLs, and transaction service API endpoints for various chains.
+ * @file Safe (formerly Gnosis Safe) constants: Safe Apps SDK options, Safe web app URLs and Safe Transaction Service
+ * endpoints by chain.
  */
 /**
- * Configuration options for the Safe Apps SDK.
- * This is typically used when integrating with the Safe environment.
+ * Options for the Safe Apps SDK (`@safe-global/safe-apps-sdk`), for apps that run inside the Safe web app. Pulsar does
+ * not use them itself.
  */
 declare const safeSdkOptions: {
+    /** Domains of Safe web apps the SDK accepts messages from. */
     allowedDomains: RegExp[];
+    /** Whether the SDK logs debug messages. */
     debug: boolean;
 };
 /**
- * A mapping of chain IDs to their corresponding Safe web application URL prefixes.
- * Used by selectors like `selectTxExplorerLink` to build correct links for Safe transactions.
- * The prefixes (e.g., 'eth:', 'gor:') are part of the Safe URL scheme.
- * @type {Record<number, string>}
+ * Safe web app URL prefixes by chain ID, such as `https://app.safe.global/eth:`. The Safe address follows the prefix.
+ * Used by {@link selectEvmTxExplorerLink} to link Safe transactions.
  */
 declare const gnosisSafeLinksHelper: Record<number, string>;
 /**
- * A comprehensive mapping of chain IDs to their corresponding Safe Transaction Service API endpoints.
- * This is used by the `safeTracker` to fetch the status of multisig transactions from the correct service.
- * @type {Record<number, string>}
+ * Safe Transaction Service API base URLs by chain ID. {@link safeFetcher} uses them; chains that are not listed cannot be
+ * tracked with the Safe tracker.
  */
 declare const SafeTransactionServiceUrls: Record<number, string>;
 
 /**
- * @file This file contains a selector utility for generating a block explorer URL for a given EVM transaction.
+ * @file Builds the explorer URL of an EVM transaction.
  */
 
 /**
- * Generates a URL to a block explorer or Safe UI for a given transaction.
- * It handles different URL structures for standard EVM transactions, Safe multi-sig, and ERC-4337 UserOperations.
- * Both standard transactions and ERC-4337 UserOperations link to the native block explorer (e.g., Etherscan).
- *
- * @template T - The transaction type, extending the base `Transaction`.
- *
- * @param {object} params - The parameters for the selection.
- * @param {Chain[]} params.chains - An array of supported chain objects, typically from `viem/chains`.
- * @param {T} params.tx - The transaction object for which to generate the link.
+ * Builds the URL of a transaction page:
+ * - Safe transactions link to the transaction in the Safe web app ({@link gnosisSafeLinksHelper}).
+ * - Other transactions link to `<explorer>/tx/<hash>` on the default block explorer of the chain in `chains`, where
+ *   `<hash>` is `replacedTxHash`, else `hash`, else `txKey`. Before an ERC-4337 UserOperation is bundled, this is the
+ *   `userOpHash`, which block explorers do not know.
  *
- * @returns {string} The full URL to the transaction on the corresponding block explorer or Safe app,
- * or an empty string if the transaction or required chain configuration is not found.
+ * @template T - The application transaction type.
+ * @param params - The chains and the transaction.
+ * @param params.chains - The viem chains of the app.
+ * @param params.tx - The transaction.
+ * @returns The URL, or an empty string when the chain or its explorer is not configured.
  */
 declare const selectEvmTxExplorerLink: <T extends Transaction>({ chains, tx, }: {
     chains: readonly [Chain, ...Chain[]];
@@ -514,42 +693,29 @@ declare const selectEvmTxExplorerLink: <T extends Transaction>({ chains, tx, }:
 }) => string;
 
 /**
- * @file This file contains a utility function for speeding up a pending EVM transaction.
+ * @file Speeds up a pending EVM transaction by resending it with higher fees.
  */
 
 /**
- * Speeds up a pending EVM transaction by resubmitting it with the same nonce but higher gas fees.
- * This function is designed to work with wagmi's configuration and actions.
+ * Speeds up a pending EVM transaction: asks the connected wallet to resend it (same `to`, `value`, `input` and nonce)
+ * with both EIP-1559 fees raised by 15%. When it is mined, the tracker of the original transaction reports it as
+ * `Replaced`; the new transaction itself is not added to the pool.
  *
- * @template T - The transaction type, which must be a valid EVM transaction.
+ * Side effects: opens a wallet prompt and broadcasts a transaction.
  *
- * @param {object} params - The parameters required to speed up the transaction.
- * @param {Config} params.config - The wagmi configuration object.
- * @param {T} params.tx - The original transaction object that needs to be sped up. It must contain all necessary EVM fields.
- *
- * @returns {Promise<Hex>} A promise that resolves with the hash of the new, speed-up transaction.
- *
- * @throws {Error} Throws an error if:
- * - The transaction is not an EVM transaction.
- * - The transaction is missing required fields (`nonce`, `from`, `to`, `value`, `maxFeePerGas`, etc.).
- * - The wagmi config is not provided.
- * - No connected account is found.
- * - The `sendTransaction` call fails for any reason.
+ * @template T - The application transaction type.
+ * @param params - The wagmi config and the transaction.
+ * @param params.config - The wagmi config of the app.
+ * @param params.tx - The pending transaction. It must be an EVM transaction with `nonce`, `from`, `to`, `value`,
+ * `maxFeePerGas` and `maxPriorityFeePerGas` (set by the EVM tracker once the transaction details are fetched).
+ * @returns The hash of the replacement transaction.
+ * @throws `Error` when the transaction is not an EVM transaction or lacks the required fields, and
+ * `Error('Failed to speed up transaction: …')` (with the original error as `cause`) when no account is connected or
+ * the wallet rejects or fails to send the transaction.
  *
  * @example
  * ```ts
- * const handleSpeedUp = async (stuckTransaction) => {
- * try {
- * const newTxHash = await speedUpTxAction({
- * config: wagmiConfig,
- * tx: stuckTransaction,
- * });
- * console.log('Transaction sped up with new hash:', newTxHash);
- * // You should now update your state to track this new transaction hash.
- * } catch (error) {
- * console.error('Failed to speed up transaction:', error);
- * }
- * };
+ * const hash = await speedUpTxAction({ config: wagmiConfig, tx: pendingTx });
  * ```
  */
 declare function speedUpTxAction<T extends Transaction>({ config, tx }: {
@@ -557,4 +723,4 @@ declare function speedUpTxAction<T extends Transaction>({ config, tx }: {
     tx: T;
 }): Promise<Hex>;
 
-export { type EVMTrackerParams, type Erc4337FetchResult, type Erc4337TrackerConfig, type Erc4337TrackerForStoreParams, type Erc4337UserOpReceipt, type GelatoCapabilities, type GelatoCapabilitiesByChain, type GelatoClientConfig, GelatoStatusCode, type GelatoTaskStatus, type GelatoToken, SafeTransactionServiceUrls, type SafeTxStatusResponse, cancelTxAction, checkAndInitializeTrackerInStore, checkIsGelatoAvailable, checkTransactionsTracker, createGelatoClient, erc4337Fetcher, erc4337Tracker, erc4337TrackerForStore, evmTracker, evmTrackerForStore, gelatoFetcher, gelatoTracker, gelatoTrackerForStore, gnosisSafeLinksHelper, isRetryableReceiptError, pulsarEvmAdapter, safeFetcher, safeSdkOptions, safeTrackerForStore, selectEvmTxExplorerLink, speedUpTxAction };
+export { type EVMTrackerParams, type Erc4337FetchResult, type Erc4337FetcherTx, type Erc4337TrackerConfig, type Erc4337TrackerForStoreParams, type Erc4337UserOpReceipt, type GelatoBaseStatus, type GelatoCapabilities, type GelatoCapabilitiesByChain, type GelatoClientConfig, GelatoStatusCode, type GelatoTaskStatus, type GelatoToken, type InitializeTrackerParams, SafeTransactionServiceUrls, type SafeTxStatusResponse, cancelTxAction, checkAndInitializeTrackerInStore, checkIsGelatoAvailable, checkTransactionsTracker, createGelatoClient, erc4337Fetcher, erc4337Tracker, erc4337TrackerForStore, evmTracker, evmTrackerForStore, gelatoFetcher, gelatoTracker, gelatoTrackerForStore, gnosisSafeLinksHelper, isRetryableReceiptError, pulsarEvmAdapter, safeFetcher, safeSdkOptions, safeTrackerForStore, selectEvmTxExplorerLink, speedUpTxAction };