@tuwaio/pulsar-core 0.7.0 → 0.8.0

package/dist/index.d.ts

@@ -4,326 +4,411 @@ import { StoreApi } from 'zustand';
 import { PersistOptions } from 'zustand/middleware';
 
 /**
- * A utility type for creating modular Zustand store slices, enabling composable state management.
- * @template T The state slice being defined.
- * @template S The full store state that includes the slice `T`.
+ * @file Core types of Pulsar: transaction shapes, the adapter contract that chain packages implement, and the state
+ * and actions of the transaction stores.
+ */
+
+/**
+ * A Zustand slice creator: receives the store's `set` and `get` and returns the slice state and actions.
+ *
+ * @template T - The state slice being defined.
+ * @template S - The full store state that includes the slice `T`.
  */
 type StoreSlice<T extends object, S extends object = T> = (set: StoreApi<S extends T ? S : S & T>['setState'], get: StoreApi<S extends T ? S : S & T>['getState']) => T;
 /**
- * Enum representing the different tracking strategies available for transactions.
- * Each tracker corresponds to a specific method of monitoring a transaction's lifecycle.
+ * Tracking strategy of a transaction. The chain adapter picks it after the action returns (see
+ * `TxAdapter.checkTransactionsTracker`) and routes the transaction to the matching tracker.
  */
 declare enum TransactionTracker {
-    /** For standard on-chain EVM transactions tracked by their hash. */
+    /** A standard EVM transaction, tracked by its hash through RPC (`@tuwaio/pulsar-evm`). */
     Ethereum = "ethereum",
-    /** For multi-signature transactions managed and executed via a Safe contract. */
+    /** A Safe multisig transaction, tracked by its `safeTxHash` through the Safe Transaction Service API. */
     Safe = "safe",
     /**
-     * For meta-transactions relayed and executed by the Gelato Network.
-     * @deprecated Gelato gasless relay is deprecated. Use TransactionTracker.ERC4337 instead.
+     * A meta-transaction relayed by Gelato, tracked by its task ID through the Gelato API.
+     * @deprecated Gelato relay is deprecated. Use `TransactionTracker.ERC4337` instead.
      */
     Gelato = "gelato",
-    /** The tracker for monitoring standard Solana transaction signatures. */
+    /** A Solana transaction, tracked by its signature through RPC (`@tuwaio/pulsar-solana`). */
     Solana = "solana",
-    /** For native ERC-4337 UserOperation transactions tracked via bundler RPC. */
+    /** An ERC-4337 UserOperation, tracked by its `userOpHash` through a bundler RPC and then on-chain. */
     ERC4337 = "erc4337"
 }
 /**
- * Represents the terminal status of a transaction after it has been processed.
+ * Terminal status of a transaction. Trackers set it together with `pending: false`.
  */
 declare enum TransactionStatus {
-    /** The transaction failed to execute due to an on-chain error or rejection. */
+    /** The transaction reverted, was rejected, or tracking failed (for example, it was not found in time). */
     Failed = "Failed",
-    /** The transaction was successfully mined and included in a block. */
+    /** The transaction was included on-chain and executed successfully. */
     Success = "Success",
-    /** The transaction was replaced by another with the same nonce (e.g., a speed-up or cancel). */
+    /** Another transaction with the same nonce was mined instead (a wallet speed-up or cancel). */
     Replaced = "Replaced"
 }
 /**
- * A union type representing the unique identifier returned by an `actionFunction`
- * after a transaction is submitted to the network or a relay service.
- *
- * This key is crucial for the adapter to determine which tracker should
- * monitor the transaction.
- *
- * It can be one of the following:
- * - A standard `0x...` transaction hash (`Hex`).
- * - A Solana transaction signature (string).
+ * The identifier returned by an `actionFunction` once the transaction is submitted: an EVM transaction hash, an
+ * ERC-4337 `userOpHash`, a Safe `safeTxHash`, a Gelato task ID or a Solana signature. The adapter uses it to pick the
+ * tracker and the `txKey` of the transaction.
  */
 type ActionTxKey = `0x${string}` | string;
 /**
- * The fundamental structure for any transaction being tracked by Pulsar.
- * This serves as the base upon which chain-specific transaction types are built.
+ * Fields shared by every tracked transaction. Chain-specific transaction types extend it.
  */
 type BaseTransaction = {
-    /** The chain identifier (e.g., 1 for Ethereum Mainnet, 'SN_MAIN' for Starknet). */
+    /**
+     * The chain of the transaction: the numeric chain ID for EVM (for example `1`), or `solana:<cluster>` for Solana
+     * (for example `solana:devnet`). `executeTxAction` derives it from `desiredChainID`.
+     */
     chainId: number | string;
     /**
-     * User-facing description. Can be a single string for all states, or a tuple for specific states.
-     * Each string is validated before execution and persistence. It must be 300 characters or less and must not contain
-     * executable-like patterns such as `eval(` or `javascript:`.
+     * User-facing description: one string for every state, or a tuple for the `[pending, success, error, replaced]`
+     * states. Each string must be 300 characters or less and must not contain executable-like patterns such as `eval(`
+     * or `javascript:`; `executeTxAction`, `addTxToPool` and the pool restore functions reject or drop transactions that
+     * break these rules.
      * @example
-     * // A single description for all states
-     * description: 'Swap 1 ETH for 1,500 USDC'
-     * // Specific descriptions for each state in order: [pending, success, error, replaced]
-     * description: ['Swapping...', 'Swapped Successfully', 'Swap Failed', 'Swap Replaced']
+     * ```ts
+     * description: 'Swap 1 ETH for 1,500 USDC';
+     * description: ['Swapping...', 'Swapped successfully', 'Swap failed', 'Swap replaced'];
+     * ```
      */
     description?: string | [string, string, string, string];
-    /** The error state if the transaction failed, containing message and raw error details. */
+    /** The normalized error of a failed transaction (`normalizeError` from `@tuwaio/orbit-core`). */
     error?: TuwaErrorState;
-    /** The on-chain timestamp (in seconds) when the transaction was finalized. */
+    /**
+     * Unix timestamp (seconds) of the terminal state: the block timestamp for EVM and ERC-4337 transactions confirmed
+     * on-chain, the execution date for Safe, and the local time otherwise.
+     */
     finishedTimestamp?: number;
-    /** The sender's wallet address. */
+    /** The address of the wallet that sent the transaction, as reported by the adapter's `getConnectorInfo`. */
     from: string;
-    /** A flag indicating if the transaction is in a failed state. */
+    /** `true` when the transaction failed; set by trackers together with `status: Failed`. */
     isError?: boolean;
-    /** A UI flag to control the visibility of a detailed tracking modal for this transaction. */
+    /** UI flag for a detailed tracking modal. Set from `withTrackedModal`; `closeTxTrackedModal` sets it to `false`. */
     isTrackedModalOpen?: boolean;
-    /** The local timestamp (in seconds) when the transaction was initiated by the user. */
+    /** Unix timestamp (seconds) when `executeTxAction` started. The pool is ordered and evicted by this value. */
     localTimestamp: number;
     /**
-     * Custom JSON-serializable data (strings or numbers) to associate with the transaction.
-     * The serialized UTF-8 payload must be 10KB or less and string values must not contain executable-like patterns.
+     * Custom JSON data of the application. The UTF-8 JSON must be 10 KB or less, and string keys and values must not
+     * contain executable-like patterns.
      */
     payload?: Record<string, string | number>;
-    /** A flag indicating if the transaction is still awaiting on-chain confirmation. */
+    /** `true` while the transaction is tracked; trackers set it to `false` when it reaches a terminal status. */
     pending: boolean;
-    /** The final on-chain status of the transaction. */
+    /** The terminal status, set together with `pending: false`. */
     status?: TransactionStatus;
     /**
-     * User-facing title. Can be a single string for all states, or a tuple for specific states.
-     * Each string is validated before execution and persistence. It must be 100 characters or less and must not contain
-     * executable-like patterns such as `eval(` or `javascript:`.
+     * User-facing title: one string for every state, or a tuple for the `[pending, success, error, replaced]` states.
+     * Each string must be 100 characters or less and must not contain executable-like patterns such as `eval(` or
+     * `javascript:`.
      * @example
-     * // A single title for all states
-     * title: 'ETH/USDC Swap'
-     * // Specific titles for each state in order: [pending, success, error, replaced]
-     * title: ['Processing Swap', 'Swap Complete', 'Swap Error', 'Swap Replaced']
+     * ```ts
+     * title: 'ETH/USDC swap';
+     * title: ['Processing swap', 'Swap complete', 'Swap error', 'Swap replaced'];
+     * ```
      */
     title?: string | [string, string, string, string];
-    /** The specific tracker responsible for monitoring this transaction's status. */
+    /** The tracker that monitors the transaction. */
     tracker: TransactionTracker;
-    /** The unique identifier for the transaction (e.g., EVM hash, Solana signature, or Gelato task ID). */
+    /**
+     * The key of the transaction in the pool: the transaction hash, `userOpHash` (ERC-4337), `safeTxHash` (Safe), Gelato
+     * task ID or Solana signature.
+     */
     txKey: string;
-    /** The application-specific type or category of the transaction (e.g., 'SWAP', 'APPROVE'). */
+    /** Application-specific type of the transaction, for example `'SWAP'` or `'APPROVE'`. */
     type: string;
-    /** The type of connector used to sign the transaction (e.g., 'injected', 'walletConnect'). */
+    /** The connector that signed the transaction, for example `evm:metamask` or `solana:phantom`. */
     connectorType: string;
-    /** The number of confirmations required for the transaction to be considered confirmed. */
+    /**
+     * Number of block confirmations the EVM trackers wait for before marking the transaction successful. Defaults to 1.
+     * The Solana tracker always waits for the `finalized` commitment instead.
+     */
     requiredConfirmations?: number;
-    /** The number of confirmations received. A string value indicates a confirmed transaction, while `null` means it's pending. */
+    /**
+     * Confirmations reported by the tracker while the transaction is pending. The Solana tracker sets it to `'MAX'` when
+     * the transaction is finalized.
+     */
     confirmations?: number | string | null;
-    /** The RPC URL to use for the transaction. Required for Solana transactions. */
+    /**
+     * RPC endpoint used by the Solana tracker, also after a page reload. Without it, the tracker uses the public
+     * endpoint of the cluster in `chainId`.
+     */
     rpcUrl?: string;
-    /** Indicates the synchronization status of the transaction with the remote backend (Quasar). */
+    /**
+     * Remote sync state, set only when the store has an `onRemoteCreate` callback: `'pending-sync'` from the moment the
+     * transaction is added until `onRemoteCreate` resolves (the key is listed in `unsyncedTxKeys` meanwhile and retried
+     * if the call fails), then `'synced'`.
+     */
     syncStatus?: 'synced' | 'pending-sync';
 };
 /**
- * Represents an EVM-specific transaction, extending the base properties with EVM fields.
+ * An EVM transaction. Trackers fill the on-chain fields (`hash`, `nonce`, fees, `to`, `value`, `input`) once the
+ * transaction details are available.
  */
 type EvmTransaction = BaseTransaction & {
-    /** The adapter type for EVM transactions. */
+    /** Always `OrbitAdapter.EVM`. */
     adapter: OrbitAdapter.EVM;
-    /** The on-chain transaction hash, available after submission. */
+    /**
+     * The on-chain transaction hash: the `txKey` for standard transactions, and the hash of the mined transaction for
+     * ERC-4337, Safe and Gelato once it is known.
+     */
     hash?: `0x${string}`;
-    /** The data payload for the transaction, typically for smart contract interactions. */
+    /** The calldata of the transaction. */
     input?: `0x${string}`;
-    /** The maximum fee per gas for an EIP-1559 transaction (in wei). */
+    /** EIP-1559 max fee per gas, in wei, as a decimal string. */
     maxFeePerGas?: string;
-    /** The maximum priority fee per gas for an EIP-1559 transaction (in wei). */
+    /** EIP-1559 max priority fee per gas, in wei, as a decimal string. */
     maxPriorityFeePerGas?: string;
-    /** The transaction nonce, a sequential number for the sender's account. */
+    /** The nonce of the sender account. */
     nonce?: number;
-    /** The hash of a transaction that this one replaced. */
+    /**
+     * The hash of the transaction that replaced this one (set with `status: Replaced`). For Safe transactions it is the
+     * `safeTxHash` of the transaction executed instead.
+     */
     replacedTxHash?: `0x${string}`;
-    /** The recipient's address or contract address. */
+    /** The recipient or contract address. */
     to?: `0x${string}`;
-    /** The amount of native currency (in wei) being sent. */
+    /** The native value sent, in wei, as a decimal string. */
     value?: string;
-    /** Optional custom bundler RPC URL for ERC-4337 UserOperation tracking. */
+    /**
+     * Custom bundler RPC URL used to track an ERC-4337 UserOperation. Stored with the transaction, so it is persisted to
+     * `localStorage` and passed to `onRemoteCreate` (a backend can track through the same bundler). Keep API keys out of
+     * this URL; pass them as `pimlicoApiKey`.
+     */
     bundlerUrl?: string;
-    /** Optional Pimlico API key for ERC-4337 UserOperation tracking. */
+    /**
+     * Pimlico API key used to track an ERC-4337 UserOperation when no `bundlerUrl` is set. Persisted to `localStorage`
+     * with the transaction, so tracking can resume after a reload, but never passed to `onRemoteCreate`.
+     */
     pimlicoApiKey?: string;
 };
 /**
- * Represents a Solana-specific transaction, extending the base properties.
+ * A Solana transaction. The Solana tracker fills the on-chain fields once the transaction is found.
  */
 type SolanaTransaction = BaseTransaction & {
-    /** The adapter type for Solana transactions. */
+    /** Always `OrbitAdapter.SOLANA`. */
     adapter: OrbitAdapter.SOLANA;
-    /** The transaction fee in lamports. */
+    /** The transaction fee, in lamports. */
     fee?: number;
-    /** The instructions included in the transaction. */
+    /** The instructions of the transaction, as returned by the `getTransaction` RPC method. */
     instructions?: unknown[];
-    /** The recent blockhash used for the transaction. */
+    /** The blockhash the transaction was signed with. */
     recentBlockhash?: string;
     /** The slot in which the transaction was processed. */
     slot?: number;
 };
 /**
- * Represents a Starknet-specific transaction, extending the base properties.
+ * A Starknet transaction. Reserved for a Starknet adapter; Pulsar does not ship one.
  */
 type StarknetTransaction = BaseTransaction & {
-    /** The adapter type for Starknet transactions. */
+    /** Always `OrbitAdapter.Starknet`. */
     adapter: OrbitAdapter.Starknet;
     /** The actual fee paid for the transaction. */
     actualFee?: {
+        /** The fee amount. */
         amount: string;
+        /** The fee unit. */
         unit: string;
     };
     /** The address of the contract being interacted with. */
     contractAddress?: string;
 };
-/** A union type representing any possible transaction structure that Pulsar can handle. */
+/** Any transaction Pulsar can track. Application transaction types extend one of its members. */
 type Transaction = EvmTransaction | SolanaTransaction | StarknetTransaction;
 /**
- * Represents the parameters required to initiate a new transaction tracking flow.
+ * The metadata of a transaction passed to `executeTxAction` (as `params`, without `actionFunction`) and kept in
+ * `initialTx`.
  */
 type InitialTransactionParams = Pick<BaseTransaction, 'description' | 'title' | 'type' | 'requiredConfirmations' | 'rpcUrl' | 'payload'> & Pick<EvmTransaction, 'bundlerUrl' | 'pimlicoApiKey'> & {
-    /** The specific blockchain adapter for this transaction. */
+    /** The adapter that handles the transaction. When no configured adapter has this key, the first one is used. */
     adapter: OrbitAdapter;
-    /** The function that executes the on-chain action (e.g., sending a transaction) and returns a preliminary identifier like a hash. */
-    actionFunction: (...args: any[]) => Promise<ActionTxKey | undefined>;
-    /** The target chain ID for the transaction. */
+    /**
+     * Signs and submits the transaction and returns its `ActionTxKey`, or `undefined` when the user cancelled.
+     * `executeTxAction` calls it without arguments. The adapters' `retryTxAction` call it with
+     * `{ config, ...payload }` (EVM) or `{ client, ...payload }` (Solana).
+     * @param args - No arguments from `executeTxAction`; one object from `retryTxAction`.
+     */
+    actionFunction: (...args: unknown[]) => Promise<ActionTxKey | undefined>;
+    /**
+     * The chain the transaction must be sent on: a numeric chain ID for EVM (the wallet is asked to switch if needed),
+     * or a cluster moniker such as `'devnet'` for Solana (compared with the cluster of the connected wallet).
+     */
     desiredChainID: number | string;
-    /** If true, the detailed tracking modal will open automatically upon initiation. */
+    /** When `true`, the transaction is created with `isTrackedModalOpen: true`. */
     withTrackedModal?: boolean;
-    /** The specific tracker responsible for monitoring this transaction's status. Required for Gelato / ERC-4337 tracker. */
+    /**
+     * Forces a tracker. Required for ERC-4337 (`TransactionTracker.ERC4337`) and Gelato; otherwise the adapter picks
+     * one from the returned key and the connector.
+     */
     tracker?: TransactionTracker;
-    /** @deprecated Gelato relay is deprecated. */
+    /**
+     * Stored with the transaction and persisted to `localStorage`, but never passed to `onRemoteCreate`.
+     * @deprecated Gelato relay is deprecated. Use ERC-4337 with `bundlerUrl` or `pimlicoApiKey` instead.
+     */
     gelatoApiKey?: string;
 };
 /**
- * Represents a transaction in its temporary, pre-submission state.
- * This is used for UI feedback while the transaction is being signed and sent.
+ * The state of a transaction while `executeTxAction` runs, before it is added to the pool. UI layers use it for
+ * immediate feedback (signature prompts, preflight errors).
  */
 type InitialTransaction = InitialTransactionParams & {
-    /** Normalized error if the initialization fails (e.g., user rejects signature). */
+    /** The normalized error when the flow failed before tracking started, for example a rejected signature. */
     error?: TuwaErrorState;
-    /** A flag indicating if the transaction is being processed (e.g., waiting for signature). */
+    /** `true` from the start of `executeTxAction` until the transaction is added to the pool or the flow fails. */
     isInitializing: boolean;
-    /** The `txKey` of the on-chain transaction that this action produced, used for linking the states. */
+    /** The `txKey` of the transaction this action added to the pool. */
     lastTxKey?: string;
-    /** The local timestamp when the user initiated the action. */
+    /** Unix timestamp (seconds) when `executeTxAction` started. */
     localTimestamp: number;
 };
 /**
- * Defines the standard callback structure for transaction events.
- * @template T The specific transaction type, extending `Transaction`.
+ * Callbacks passed to `executeTxAction` and forwarded to the tracker of that transaction. They are not stored:
+ * trackers restarted by `initializeTransactionsPool` or `injectExternalPendingTxs` (for example after a page reload)
+ * run without them. Their return values are not awaited.
+ *
+ * @template T - The application transaction type.
  */
 interface TrackerCallbacks<T extends Transaction> {
+    /**
+     * Called when the tracker marks the transaction `Success`.
+     * @param tx - The transaction after the update.
+     */
     onSuccess?: (tx: T) => Promise<void> | void;
+    /**
+     * Called when the transaction fails: it reverted, was rejected, or tracking gave up.
+     * @param error - The raw error, or a generated `Error`.
+     * @param tx - The transaction after the update.
+     */
     onError?: (error: unknown, tx?: T) => Promise<void> | void;
+    /**
+     * Called when the transaction is replaced by another one with the same nonce.
+     * @param newTx - The tracked transaction after the update (`status: Replaced`, `replacedTxHash` set).
+     * @param oldTx - The transaction as tracking started.
+     */
     onReplaced?: (newTx: T, oldTx: T) => Promise<void> | void;
 }
 /**
- * Callbacks for synchronizing local transaction state with a remote backend.
- * These are injected into the store at creation time.
+ * Callbacks that synchronize the local pool with a remote backend (for example Quasar). Passed to
+ * `createPulsarStore`.
+ *
+ * @template T - The application transaction type.
  */
 interface SyncCallbacks<T extends Transaction> {
     /**
-     * Called immediately after a transaction is created locally (added to pool).
-     * Use this to POST the active pending transaction to the backend.
+     * Called in the background with every new transaction, right after `addTxToPool` has written it to the pool with
+     * `syncStatus: 'pending-sync'` and listed its key in `unsyncedTxKeys`. It never delays or blocks tracking. Resolving
+     * marks the transaction `'synced'` and removes the key; rejecting logs a warning and leaves the key for
+     * `reconcileUnsyncedTransactions`, also across reloads. Reject (throw) on failure: a resolved promise counts as
+     * synced. A transaction is never sent twice at the same time.
+     * @param tx - A copy of the pooled transaction without `pimlicoApiKey` and `gelatoApiKey`.
      */
     onRemoteCreate?: (tx: T) => Promise<void>;
 }
 /**
- * Callback executed before Pulsar initializes or submits a transaction.
+ * Preflight callback run by `executeTxAction` after metadata validation and the chain check (which can ask the wallet
+ * to switch networks), before `actionFunction` asks the wallet to sign. It receives no transaction data.
  *
- * Throw an error from this function to block the transaction before `initialTx`, wallet interaction,
- * persistence, or remote synchronization starts.
+ * Throw to block the transaction: with `abortOnTxError` (default `true`), `initialTx.error` is set and
+ * `executeTxAction` rejects with the thrown error. With `abortOnTxError: false`, the error is logged and the flow
+ * continues.
  */
 type BeforeTxProcess = () => Promise<void> | void;
 /**
- * The configuration object containing one or more transaction adapters.
- * @template T The specific transaction type.
+ * The configuration of `createPulsarStore`: one or more chain adapters and the store options.
+ *
+ * @template T - The application transaction type.
  */
 type PulsarAdapter<T extends Transaction> = OrbitGenericAdapter<TxAdapter<T>> & {
-    /** Optional global preflight callback executed before every transaction unless locally overridden. */
+    /** Global preflight callback run before every transaction. A `beforeTxProcess` passed to `executeTxAction` replaces it. */
     beforeTxProcess?: BeforeTxProcess;
+    /** Maximum number of transactions in the pool. When it is full, the oldest one (by `localTimestamp`) is evicted. Defaults to 50. */
     maxTransactions?: number;
+    /** @deprecated Gelato relay is deprecated. Gelato API key used to track `TransactionTracker.Gelato` transactions. */
     gelatoApiKey?: string;
-    /** Optional setting to abort the transaction if the beforeTxProcess hook or remote creation fails. Defaults to true. */
+    /**
+     * Whether an error thrown by `beforeTxProcess` aborts the transaction. Defaults to `true`. It does not apply to
+     * `onRemoteCreate`, whose errors never abort the transaction.
+     */
     abortOnTxError?: boolean;
 } & SyncCallbacks<T>;
 /**
- * Represents a tracker for a specific transaction tied to an action and a connector.
- *
- * @typedef {Object} CheckTxTracker
- * @property {ActionTxKey} actionTxKey - The key identifying the specific action related to the transaction.
- * @property {string} connectorType - The type of connector used for the transaction (e.g., wallet provider, blockchain interface).
- * @property {TransactionTracker} [tracker] - An optional tracker object that monitors the status and progress of the transaction.
- * @property {string} [gelatoApiKey] - @deprecated Gelato API key for Gelato relayer integration.
- * @property {string} [bundlerUrl] - Optional custom bundler RPC URL for ERC-4337 UserOperation tracking.
- * @property {string} [pimlicoApiKey] - Optional Pimlico API key for ERC-4337 UserOperation tracking.
+ * The input of `TxAdapter.checkTransactionsTracker`: the key returned by the action and the context needed to pick a
+ * tracker.
  */
 type CheckTxTracker = {
+    /** The key returned by `actionFunction`. */
     actionTxKey: ActionTxKey;
+    /** The connector that signed the transaction, for example `evm:safe` for a Safe wallet. */
     connectorType: string;
+    /** The tracker requested in `executeTxAction` params, if any. */
     tracker?: TransactionTracker;
-    /** @deprecated Gelato relay is deprecated. Use bundlerUrl / pimlicoApiKey with ERC-4337 instead. */
+    /** @deprecated Gelato relay is deprecated. Use `bundlerUrl` / `pimlicoApiKey` with ERC-4337 instead. */
     gelatoApiKey?: string;
-    /** Optional custom bundler RPC URL for ERC-4337 UserOperation tracking. */
+    /** Custom bundler RPC URL for ERC-4337 UserOperation tracking. */
     bundlerUrl?: string;
-    /** Optional Pimlico API key for ERC-4337 UserOperation tracking. */
+    /** Pimlico API key for ERC-4337 UserOperation tracking. */
     pimlicoApiKey?: string;
 };
 /**
- * Defines the interface for a transaction adapter, which provides chain-specific logic and utilities.
- * @template T The specific transaction type, extending `Transaction`.
+ * The contract a chain adapter implements to plug into the Pulsar store. `@tuwaio/pulsar-evm` and
+ * `@tuwaio/pulsar-solana` provide implementations.
+ *
+ * @template T - The application transaction type.
  */
 type TxAdapter<T extends Transaction> = Pick<BaseAdapter, 'getExplorerUrl'> & {
-    /** The unique key identifying this adapter. */
+    /** The chain family handled by the adapter. */
     key: OrbitAdapter;
-    /** Returns information about the currently connected connector. */
+    /** Returns the connected wallet. Called by `executeTxAction` before the chain check. */
     getConnectorInfo: () => {
-        /** The currently connected wallet address. */
+        /** The address of the connected wallet. */
         walletAddress: string;
-        /** The type of the connector (e.g., 'metamask', 'phantom'). */
+        /** The connector type, for example `evm:metamask`. */
         connectorType: string;
     };
     /**
-     * Ensures the connected wallet is on the correct network for the transaction.
-     *
-     * This method should throw an error if the chain is mismatched.
-     * @param chainId The desired chain ID for the transaction.
-     * @param walletChainId The connected wallet chain ID.
+     * Ensures the wallet is on the chain of the transaction, switching it if the adapter can. Rejects when the chain
+     * does not match, which aborts `executeTxAction`.
+     * @param chainId - The `desiredChainID` of the transaction.
      */
     checkChainForTx: (chainId: string | number) => Promise<void>;
     /**
-     * Determines the appropriate tracker and final `txKey` from the result of an action.
-     * @returns An object containing the final `txKey` and the `TransactionTracker` to be used.
+     * Picks the tracker and the final `txKey` for the key returned by `actionFunction`.
+     * @param params - The returned key, the connector type and the requested tracker.
+     * @returns The `txKey` to store the transaction under and the tracker to use.
      */
-    checkTransactionsTracker: ({ actionTxKey, connectorType, tracker }: CheckTxTracker) => {
+    checkTransactionsTracker: (params: CheckTxTracker) => {
+        /** The key the transaction is stored under. */
         txKey: string;
+        /** The tracker that monitors the transaction. */
         tracker: TransactionTracker;
     };
     /**
-     * Selects and initializes the correct background tracker for a given transaction.
-     * @param params The parameters for initializing the tracker, including the transaction and store callbacks.
+     * Starts the background tracker of a transaction. Trackers update the transaction through `updateTxParams`. The
+     * built-in trackers keep failed transactions in the pool; `removeTxFromPool` is available to custom trackers.
+     * @param params - The transaction, the Gelato API key, the callbacks and the store members used by trackers.
      */
     checkAndInitializeTrackerInStore: (params: {
         tx: T;
         gelatoApiKey?: string;
     } & TrackerCallbacks<T> & Pick<ITxTrackingStore<T>, 'updateTxParams' | 'removeTxFromPool' | 'transactionsPool'>) => Promise<void> | void;
     /**
-     * Optional: Logic to cancel a pending EVM transaction.
-     * @param tx The transaction to cancel.
-     * @returns The new transaction hash for the cancellation.
+     * Optional: cancels a pending transaction by sending a replacement with the same nonce.
+     * @param tx - The transaction to cancel.
+     * @returns The hash of the cancellation transaction.
      */
     cancelTxAction?: (tx: T) => Promise<string>;
     /**
-     * Optional: Logic to speed up a pending EVM transaction.
-     * @param tx The transaction to speed up.
-     * @returns The new transaction hash for the sped-up transaction.
+     * Optional: speeds up a pending transaction by resending it with the same nonce and higher fees.
+     * @param tx - The transaction to speed up.
+     * @returns The hash of the replacement transaction.
      */
     speedUpTxAction?: (tx: T) => Promise<string>;
     /**
-     * Optional: Logic to retry a failed transaction.
-     * @param params The parameters for retrying the transaction.
-     * @param params.txKey The unique key of the transaction to retry.
-     * @param params.tx The initial parameters of the transaction.
-     * @param params.onClose Callback function to close the tracking modal.
+     * Optional: closes the tracking modal and runs a failed transaction again through `executeTxAction`.
+     * @param params - The retry parameters.
+     * @param params.txKey - The key of the failed transaction, passed to `onClose`.
+     * @param params.tx - The parameters of the transaction, including its `actionFunction`.
+     * @param params.onClose - Closes the tracking modal.
+     * @param params.executeTxAction - The store's `executeTxAction`.
      */
     retryTxAction?: (params: {
         txKey: string;
@@ -331,92 +416,118 @@ type TxAdapter<T extends Transaction> = Pick<BaseAdapter, 'getExplorerUrl'> & {
         onClose: (txKey?: string) => void;
     } & Partial<Pick<ITxTrackingStore<T>, 'executeTxAction'>>) => Promise<void>;
     /**
-     * Optional: Constructs a full explorer URL for a specific transaction.
-     * May require the full transaction pool to resolve details for replaced transactions.
-     * @param tx The transaction object.
-     * @returns The full URL to the transaction on the explorer.
+     * Optional: builds the explorer URL of a transaction.
+     * @param tx - The transaction.
+     * @returns The URL, or an empty string when it cannot be built.
      */
     getExplorerTxUrl?: (tx: T) => string;
 };
 /**
- * Defines the structure of the transaction pool, a key-value store of transactions indexed by their unique keys.
- * @template T The type of the transaction object being tracked.
+ * The transaction pool: transactions indexed by `txKey`.
+ *
+ * @template T - The application transaction type.
  */
 type TransactionPool<T extends Transaction> = Record<string, T>;
 /**
- * A utility type that creates a union of all fields that can be safely updated
- * on a transaction object via the `updateTxParams` action. This ensures type safety
- * and prevents accidental modification of immutable properties.
+ * The fields `updateTxParams` accepts: the fields trackers change while a transaction is tracked.
  */
 type UpdatableTransactionFields = Partial<Pick<EvmTransaction, 'to' | 'nonce' | 'txKey' | 'pending' | 'hash' | 'status' | 'replacedTxHash' | 'error' | 'finishedTimestamp' | 'isTrackedModalOpen' | 'isError' | 'maxPriorityFeePerGas' | 'maxFeePerGas' | 'input' | 'value' | 'confirmations' | 'requiredConfirmations'>> & Partial<Pick<SolanaTransaction, 'slot' | 'confirmations' | 'fee' | 'instructions' | 'recentBlockhash' | 'rpcUrl'>>;
 /**
- * The interface for the base transaction tracking store slice.
- * It includes the state and actions for managing the transaction lifecycle.
- * @template T The specific transaction type.
+ * The state and actions of the core store slice created by `initializeTxTrackingStore`.
+ *
+ * @template T - The application transaction type.
  */
 interface IInitializeTxTrackingStore<T extends Transaction> {
-    /** A pool of all transactions currently being tracked, indexed by `txKey`. */
+    /** Every tracked transaction, indexed by `txKey`. Persisted to `localStorage` by `createPulsarStore`. */
     transactionsPool: TransactionPool<T>;
-    /** The `txKey` of the most recently added transaction. */
+    /** The `txKey` of the transaction added last. */
     lastAddedTxKey?: string;
-    /** The state for a transaction being initiated, used for verify feedback before it's submitted to the chain. */
+    /**
+     * The transaction `executeTxAction` is processing, before it is added to the pool. Not persisted by
+     * `createPulsarStore`: after a reload it is `undefined`.
+     */
     initialTx?: InitialTransaction;
     /**
-     * Adds a new transaction to the tracking pool and marks it as pending.
-     * @param tx The transaction object to add.
+     * Validates a transaction and adds it to the pool with `pending: true`. When the pool already holds
+     * `maxTransactions` transactions, the oldest one is evicted. If `onRemoteCreate` is configured, the transaction gets
+     * `syncStatus: 'pending-sync'`, its key is listed in `unsyncedTxKeys`, and `onRemoteCreate` runs in the background
+     * (see `SyncCallbacks`). Does not start a tracker.
+     * @param tx - The transaction to add.
+     * @returns A promise that resolves once the transaction is in the pool, without waiting for `onRemoteCreate`.
+     * @throws `PulsarTransactionValidationError` synchronously, before anything is written, when the title, description
+     * or payload is invalid.
      */
     addTxToPool: (tx: T) => Promise<void>;
     /**
-     * Updates one or more properties of an existing transaction in the pool.
-     * @param txKey The key of the transaction to update.
-     * @param fields The partial object containing the fields to update.
+     * Merges fields into a transaction of the pool; does nothing if the key is unknown. When `fields.status` is terminal
+     * and the transaction is in `unsyncedTxKeys`, it starts `reconcileUnsyncedTransactions` in the background.
+     * @param txKey - The key of the transaction.
+     * @param fields - The fields to merge.
      */
     updateTxParams: (txKey: string, fields: UpdatableTransactionFields) => void;
     /**
-     * Removes a transaction from the tracking pool by its key.
-     * @param txKey The key of the transaction to remove.
+     * Removes a transaction from the pool. Does not stop its tracker.
+     * @param txKey - The key of the transaction.
      */
     removeTxFromPool: (txKey: string) => void;
     /**
-     * Closes the tracking modal for a transaction and clears any initial transaction state.
-     * @param txKey The optional key of the transaction modal to close.
+     * Sets `isTrackedModalOpen: false` on a transaction and always clears `initialTx`.
+     * @param txKey - The key of the transaction whose modal is closed, if any.
      */
     closeTxTrackedModal: (txKey?: string) => void;
     /**
-     * A selector function to retrieve the key of the last transaction added to the pool.
-     * @returns The key of the last added transaction, or undefined if none exists.
+     * Returns `lastAddedTxKey`.
+     * @returns The key of the transaction added last, or `undefined`.
      */
     getLastTxKey: () => string | undefined;
     /**
-     * A record of transaction keys that failed to sync with the remote backend (Quasar)
-     * when `onRemoteCreate` was called. They will be retried automatically.
+     * Keys of transactions that `onRemoteCreate` has not confirmed yet: in flight, failed, or interrupted by a reload.
+     * `reconcileUnsyncedTransactions` retries them. Persisted to `localStorage`.
      */
     unsyncedTxKeys?: Record<string, boolean>;
     /**
-     * Attempts to synchronize any transactions in `unsyncedTxKeys` that have reached a terminal
-     * status but failed their initial `onRemoteCreate` call.
+     * Calls `onRemoteCreate` again for every key in `unsyncedTxKeys`, one after another, skipping keys whose call is still
+     * in flight. Successful transactions are marked `'synced'` and removed from the list; failures are logged and stay
+     * listed; keys of transactions no longer in the pool are removed. Does nothing without `onRemoteCreate` or while a
+     * previous run is in progress. Runs at the start of every `executeTxAction`, when an
+     * unsynced transaction reaches a terminal status, and when `createTxInMemoryStore` loads the first history page.
+     * @returns A promise that resolves when the run is finished. It does not reject.
      */
     reconcileUnsyncedTransactions: () => Promise<void>;
 }
 /**
- * The complete interface for the Pulsar transaction tracking store.
- * @template T The transaction type.
+ * The state and actions of the store created by `createPulsarStore`.
+ *
+ * @template T - The application transaction type.
  */
 type ITxTrackingStore<T extends Transaction> = IInitializeTxTrackingStore<T> & {
-    /** A getter function that returns the configured transaction adapter(s). */
+    /**
+     * Returns the adapter configuration passed to `createPulsarStore`.
+     * @returns The adapter, or the array of adapters.
+     */
     getAdapter: () => TxAdapter<T> | TxAdapter<T>[];
     /**
-     * The primary method for initiating and tracking a new transaction from start to finish.
-     * It manages UI state, executes the on-chain action, and initiates background tracking.
+     * Runs a transaction from start to tracking: validates `params`, sets `initialTx`, checks the chain (the EVM adapter
+     * may ask the wallet to switch), runs `beforeTxProcess`, calls `actionFunction`, adds the transaction to the pool
+     * (see `addTxToPool`) and starts its tracker. When `actionFunction` returns `undefined`, `initialTx` is cleared and
+     * nothing is tracked. Also starts `reconcileUnsyncedTransactions` in the background.
      *
-     * @param params The parameters for handling the transaction.
-     * @param params.actionFunction The async function to execute (e.g., a smart contract write call). Must return a unique key or undefined.
-     * @param params.params The metadata for the transaction. Title, description, and payload are validated before execution.
-     * @param params.defaultTracker The default tracker to use if it cannot be determined automatically.
-     * @param params.beforeTxProcess Optional local preflight callback. When provided, it overrides the global callback from `createPulsarStore`.
-     * @param params.onSuccess Callback to execute when the transaction is successfully submitted.
-     * @param params.onError Callback to execute when the transaction fails.
-     * @param params.onReplaced Callback to execute when the transaction is replaced.
+     * @param params - The action, its metadata and the callbacks.
+     * @param params.actionFunction - Signs and submits the transaction; returns its key, or `undefined` if cancelled.
+     * @param params.params - The transaction metadata. `title`, `description` and `payload` are validated before
+     * anything else runs.
+     * @param params.defaultTracker - Tracker used when the adapter does not return one.
+     * @param params.beforeTxProcess - Preflight callback for this transaction; replaces the global one.
+     * @param params.abortOnTxError - Overrides the global `abortOnTxError` for this transaction.
+     * @param params.onSuccess - Called when the transaction succeeds (see `TrackerCallbacks`).
+     * @param params.onError - Called when the transaction fails after it was submitted (see `TrackerCallbacks`).
+     * @param params.onReplaced - Called when the transaction is replaced (see `TrackerCallbacks`).
+     * @returns A promise that resolves when the adapter's `checkAndInitializeTrackerInStore` resolves: once polling has
+     * started for polling trackers (Solana, Safe, ERC-4337, Gelato), but only when tracking has finished for standard
+     * EVM transactions (`TransactionTracker.Ethereum`). Read the state from the store instead of awaiting the result.
+     * @throws `PulsarTransactionValidationError` when the metadata is invalid (before `initialTx` is set). Rejects with
+     * the underlying error when no adapter is configured, or when the chain check, `beforeTxProcess` (with
+     * `abortOnTxError`), `actionFunction` or the tracker start fails; `initialTx.error` is set first.
      */
     executeTxAction: (params: {
         actionFunction: () => Promise<ActionTxKey | undefined>;
@@ -426,64 +537,83 @@ type ITxTrackingStore<T extends Transaction> = IInitializeTxTrackingStore<T> & {
         abortOnTxError?: boolean;
     } & TrackerCallbacks<T>) => Promise<void>;
     /**
-     * Initializes trackers for all pending transactions in the pool.
-     * This is essential for resuming tracking after a page reload or application restart.
+     * Restarts the trackers of all pending transactions in the pool, for example after a page reload. Pending
+     * transactions that fail validation are removed from the pool. Call it once per page load: every call starts new
+     * trackers, and trackers started here have no `TrackerCallbacks`.
+     * @returns A promise that resolves when all trackers have started.
      */
     initializeTransactionsPool: () => Promise<void>;
     /**
-     * Cross-device synchronization bridge.
-     * Injects remote pending transactions into the local pool and starts their lifecycle trackers.
-     * Also self-heals local pending transactions if the remote DB knows they are terminal.
+     * Merges transactions from a remote backend into the pool (cross-device sync). Invalid transactions are skipped
+     * with a warning. Pending remote transactions that are not in the pool are added and tracked. Local pending
+     * transactions that are terminal remotely take the remote `status`, `txKey` and `finishedTimestamp` and are marked
+     * not pending.
+     * @param remoteTxs - Transactions returned by the backend.
+     * @returns A promise that resolves when the trackers of the added transactions have started.
      */
     injectExternalPendingTxs: (remoteTxs: T[]) => Promise<void>;
 };
 /**
- * Represents the structure and behavior of an in-memory pagination system
- * for managing transaction history.
+ * The pagination state and action of the in-memory history store, as consumed by UI components.
  */
 type TxInMemoryPagination = {
-    /** Indicates whether the store is currently loading transaction history. */
+    /** `true` while a history page is loading. */
     isLoading: boolean;
-    /** Indicates whether the last loading request ended with an error. */
+    /** `true` when the last history request failed. */
     isError: boolean;
-    /** Indicates whether more history pages are available. */
+    /** `true` when the last loaded page reported a next page. */
     hasMore: boolean;
-    /** The current page number in the paginated history. */
+    /** The last loaded page number. */
     currentPage: number;
-    /** Loads the next page of transaction history and appends it to the pool. */
+    /**
+     * Loads the page after `currentPage` and merges it into the pool. Does nothing while loading, when `hasMore` is
+     * `false`, or without `getHistory`.
+     * @param walletAddress - The wallet whose history is loaded.
+     */
     fetchNextPage: (walletAddress: string) => Promise<void>;
 };
 /**
- * The complete interface for the Pulsar transaction in-memory store.
- * It keeps a paginated remote history in sync with a local transaction pool.
+ * The state and actions of the store created by `createTxInMemoryStore`: a paginated remote history merged with the
+ * local pool. Nothing in it is persisted.
  *
- * @template T The transaction type.
+ * @template T - The application transaction type.
  */
 type ITxInMemoryStore<T extends Transaction> = {
-    /** A pool of all transactions currently being tracked and loaded from history, indexed by `txKey`. */
+    /** The local and remote transactions, indexed by `txKey`. */
     transactionsPool: TransactionPool<T>;
-    /** Loads the first page of transaction history. */
+    /**
+     * Runs `reconcileUnsyncedTransactions` (if provided), then loads the first history page and merges it into the
+     * pool. Does nothing without `getHistory` or an empty `walletAddress`.
+     * @param walletAddress - The wallet whose history is loaded.
+     */
     fetchInitial: (walletAddress: string) => Promise<void>;
-    /** Merges a local transaction pool into the in-memory store. */
+    /**
+     * Merges a local pool into the in-memory pool. Transactions that are `Success` or `Replaced` in memory are kept;
+     * pending ones are overwritten only by a terminal transaction or one with more confirmations.
+     * @param localPool - The pool of the persistent store, usually from its `subscribe` listener.
+     */
     syncWithLocalPool: (localPool: TransactionPool<T>) => void;
 } & TxInMemoryPagination;
 /**
- * Parameters used to configure and manage an in-memory transaction store.
+ * The configuration of `createTxInMemoryStore`.
  *
- * @template T The transaction type.
+ * @template T - The application transaction type.
  */
 type ITxInMemoryStoreParameters<T extends Transaction> = {
-    /** A localTransactionsPool. */
+    /** The initial pool, usually `transactionsPool` of the persistent store. */
     localTransactionsPool: TransactionPool<T>;
-    /**
-     * Attempts to synchronize any transactions in `unsyncedTxKeys` that have reached a terminal
-     * status but failed their initial `onRemoteCreate` call.
-     */
+    /** Called by `fetchInitial` before the first page is loaded, usually the store's `reconcileUnsyncedTransactions`. */
     reconcileUnsyncedTransactions?: () => Promise<void>;
-    /** * Callback fired when remote history is successfully fetched.
-     * Used to inject remote pending transactions into the persistent tracking store.
+    /**
+     * Called in a microtask with the valid transactions of every loaded page, usually to pass them to the store's
+     * `injectExternalPendingTxs`.
+     * @param remoteTxs - The transactions of the loaded page.
      */
     onHistoryFetched?: (remoteTxs: T[]) => void;
+    /**
+     * Loads one page of the remote history of a wallet. Return `null` when there is no history to show (for example,
+     * the user is not signed in); throw on errors to set `isError`.
+     */
     getHistory?: ({ page, walletAddress, }: {
         /**
          * Page number for pagination.
@@ -491,6 +621,7 @@ type ITxInMemoryStoreParameters<T extends Transaction> = {
          * @defaultValue `1`
          */
         page?: number;
+        /** The wallet whose history is requested. */
         walletAddress: string;
     }) => Promise<{
         /** Array of transactions for the current page. */
@@ -509,95 +640,135 @@ type ITxInMemoryStoreParameters<T extends Transaction> = {
 };
 
 /**
- * @file This file defines the core Zustand slice for managing the state of transactions. It includes the state,
- * actions, and types necessary for initializing the store and performing CRUD operations on the transaction pool.
+ * @file The core Zustand slice of the transaction store: the transaction pool and the actions that add, update and
+ * remove transactions and synchronize them with a remote backend.
  */
 
 /**
- * Creates a Zustand store slice with the core logic for transaction state management.
- * This function is a slice creator intended for use with Zustand's `create` function.
+ * Creates the core slice of the transaction store: `transactionsPool`, `initialTx`, `unsyncedTxKeys` and the actions
+ * that change them. `createPulsarStore` uses it; call it directly only to compose a custom Zustand store.
  *
- * @template T The specific transaction type.
- * @param options Configuration for the store slice.
- * @returns A Zustand store slice implementing `IInitializeTxTrackingStore`.
+ * The slice keeps its state in memory; persistence is added by the store that uses it.
+ *
+ * @template T - The application transaction type.
+ * @param params - The slice options.
+ * @param params.maxTransactions - Maximum number of transactions in the pool; `addTxToPool` evicts the oldest one
+ * (by `localTimestamp`) when the pool is full.
+ * @param params.onRemoteCreate - Optional remote sync callback, called in the background by `addTxToPool` (see
+ * `SyncCallbacks`).
+ * @returns A slice creator for Zustand's `create` / `createStore`.
  */
 declare function initializeTxTrackingStore<T extends Transaction>({ maxTransactions, onRemoteCreate, }: Pick<PulsarAdapter<T>, 'onRemoteCreate'> & {
     maxTransactions: number;
 }): StoreSlice<IInitializeTxTrackingStore<T>>;
 
 /**
- * @file This file contains selector functions for deriving state from the transaction tracking store.
- * Selectors help abstract the state's shape and provide efficient, memoized access to computed data.
+ * @file Selectors that derive lists of transactions from a transaction pool. They are plain functions: each call
+ * returns a new array, so memoize the result (or compare it shallowly) when using it in a React selector.
  */
 
 /**
- * Selects all transactions from the pool and sorts them by their creation timestamp in ascending order.
- * @template T - The transaction type.
- * @param {TransactionPool<T>} transactionsPool - The entire transaction pool from the store.
- * @returns {T[]} An array of all transactions, sorted chronologically.
+ * Returns every transaction of the pool, oldest first (by `localTimestamp`).
+ *
+ * @template T - The application transaction type.
+ * @param transactionsPool - The transaction pool of the store.
+ * @returns A new array of all transactions, sorted chronologically.
  */
 declare const selectAllTransactions: <T extends Transaction>(transactionsPool: TransactionPool<T>) => T[];
 /**
- * Selects all transactions that are currently in a pending state, sorted chronologically.
- * @template T - The transaction type.
- * @param {TransactionPool<T>} transactionsPool - The entire transaction pool from the store.
- * @returns {T[]} An array of pending transactions.
+ * Returns the transactions with `pending: true`, oldest first.
+ *
+ * @template T - The application transaction type.
+ * @param transactionsPool - The transaction pool of the store.
+ * @returns A new array of pending transactions, sorted chronologically.
  */
 declare const selectPendingTransactions: <T extends Transaction>(transactionsPool: TransactionPool<T>) => T[];
 /**
- * Selects a single transaction from the pool by its unique key (`txKey`).
- * @template T - The transaction type.
- * @param {TransactionPool<T>} transactionsPool - The entire transaction pool from the store.
- * @param {string} key - The `txKey` of the transaction to retrieve.
- * @returns {T | undefined} The transaction object if found, otherwise undefined.
+ * Returns the transaction stored under a `txKey`.
+ *
+ * @template T - The application transaction type.
+ * @param transactionsPool - The transaction pool of the store.
+ * @param key - The `txKey` of the transaction.
+ * @returns The transaction, or `undefined` if the pool has no such key.
  */
 declare const selectTxByKey: <T extends Transaction>(transactionsPool: TransactionPool<T>, key: string) => T | undefined;
 /**
- * Selects all transactions initiated by a specific wallet address, sorted chronologically.
- * @template T - The transaction type.
- * @param {TransactionPool<T>} transactionsPool - The entire transaction pool from the store.
- * @param {string} from - The wallet address (`from` address) to filter transactions by.
- * @returns {T[]} An array of transactions associated with the given wallet.
+ * Returns the transactions sent by a wallet, oldest first. Addresses are compared case-insensitively.
+ *
+ * @template T - The application transaction type.
+ * @param transactionsPool - The transaction pool of the store.
+ * @param from - The wallet address to match against the `from` field.
+ * @returns A new array of the wallet's transactions, sorted chronologically.
  */
 declare const selectAllTransactionsByActiveWallet: <T extends Transaction>(transactionsPool: TransactionPool<T>, from: string) => T[];
 /**
- * Selects all pending transactions for a specific wallet address, sorted chronologically.
- * @template T - The transaction type.
- * @param {TransactionPool<T>} transactionsPool - The entire transaction pool from the store.
- * @param {string} from - The wallet address (`from` address) to filter transactions by.
- * @returns {T[]} An array of pending transactions for the given wallet.
+ * Returns the pending transactions sent by a wallet, oldest first. Addresses are compared case-insensitively.
+ *
+ * @template T - The application transaction type.
+ * @param transactionsPool - The transaction pool of the store.
+ * @param from - The wallet address to match against the `from` field.
+ * @returns A new array of the wallet's pending transactions, sorted chronologically.
  */
 declare const selectPendingTransactionsByActiveWallet: <T extends Transaction>(transactionsPool: TransactionPool<T>, from: string) => T[];
 
 /**
- * Creates an in-memory transaction store with synchronized local and remote sources.
+ * Creates an in-memory store that shows the remote transaction history of a wallet (for example from Quasar) together
+ * with the local pool of the persistent store. Nothing in it is persisted. Keep it in sync with the persistent store by
+ * calling `syncWithLocalPool` from that store's `subscribe` listener.
  *
- * The store is designed to:
- * - keep a local transaction pool in sync with remote history
- * - preserve terminal transaction states
- * - support paginated history loading
- * - avoid duplicated merge logic across store actions
+ * Merge rules: a transaction that is `Success` or `Replaced` in memory is never overwritten; a pending one is
+ * overwritten only by a terminal transaction or by one with more confirmations; any other one is overwritten.
  *
- * @template T The transaction type.
- * @param params Store configuration parameters.
- * @param params.getHistory Optional remote history fetcher.
- * @returns A Zustand vanilla store instance for in-memory transaction management.
+ * History pages are validated like `injectExternalPendingTxs` does: transactions whose title, description or payload
+ * break the safety limits are skipped with a warning and are not passed to `onHistoryFetched`.
+ *
+ * Side effects: `fetchInitial` and `fetchNextPage` call `getHistory`, usually a network request. The store uses its
+ * own Immer instance without auto-freeze and does not change the global Immer configuration.
+ *
+ * @template T - The application transaction type.
+ * @param params - The store configuration.
+ * @param params.localTransactionsPool - The initial pool.
+ * @param params.reconcileUnsyncedTransactions - Called by `fetchInitial` before the first page is loaded.
+ * @param params.getHistory - Loads one page of the remote history. A `null` result stops loading without changing the
+ * pool; a thrown error sets `isError`.
+ * @param params.onHistoryFetched - Called in a microtask with the valid transactions of every loaded page.
+ * @returns A vanilla Zustand store; bind it to React with `createBoundedUseStore`.
  */
 declare function createTxInMemoryStore<T extends Transaction>({ localTransactionsPool, reconcileUnsyncedTransactions, getHistory, onHistoryFetched, }: ITxInMemoryStoreParameters<T>): zustand.StoreApi<ITxInMemoryStore<T>>;
 
 /**
- * Creates the main Pulsar store for transaction tracking.
+ * Creates the Pulsar transaction store: a vanilla Zustand store (use it from any framework, or bind it to React with
+ * `createBoundedUseStore`) that runs transactions through chain adapters and tracks them in the background.
  *
- * This function configures a Zustand store enhanced with persistence. It combines the core transaction management
- * slice with a powerful orchestration logic that leverages chain-specific adapters to handle the entire
- * lifecycle of a transaction—from initiation and chain validation to execution and background status tracking.
+ * Side effects: the state is saved with Zustand's `persist` middleware under the key `name`, by default in
+ * `localStorage`, on every change: `transactionsPool`, `lastAddedTxKey` and `unsyncedTxKeys`. `initialTx` is neither
+ * saved nor restored (pass your own `partialize` and `merge` to change that). In the browser the saved state is
+ * restored synchronously when the store is created. Where
+ * `localStorage` is not available (server rendering), nothing is read or written and Zustand logs a warning on
+ * updates. Creating the store does not start any tracker: call `initializeTransactionsPool` once on the client.
  *
- * @template T The specific transaction type, extending the base `Transaction`.
+ * @template T - The application transaction type.
+ * @param params - The adapters, the store options and the options of Zustand's `persist` middleware.
+ * @param params.adapter - A chain adapter, or an array of adapters, such as `pulsarEvmAdapter` from
+ * `@tuwaio/pulsar-evm` or `pulsarSolanaAdapter` from `@tuwaio/pulsar-solana`.
+ * @param params.maxTransactions - Maximum number of transactions in the pool. Defaults to 50.
+ * @param params.onRemoteCreate - Remote sync callback (see `SyncCallbacks`).
+ * @param params.gelatoApiKey - Deprecated Gelato API key, passed to the trackers.
+ * @param params.beforeTxProcess - Global preflight callback (see `BeforeTxProcess`).
+ * @param params.abortOnTxError - Whether a `beforeTxProcess` error aborts the transaction. Defaults to `true`.
+ * @param params.name - The storage key. Required by `persist`; use a different key for every store.
+ * @returns The vanilla Zustand store. `store.persist` exposes the `persist` API (for example `clearStorage()`).
  *
- * @param config Configuration object for creating the store.
- * @param config.adapter Adapter or an array of adapters for different chains or transaction types.
- * @param options Configuration for the Zustand `persist` middleware.
- * @returns A fully configured Zustand store instance.
+ * @example
+ * ```ts
+ * import { createPulsarStore } from '@tuwaio/pulsar-core';
+ * import { pulsarEvmAdapter } from '@tuwaio/pulsar-evm';
+ *
+ * export const pulsarStore = createPulsarStore({
+ *   name: 'transactions-tracking-storage',
+ *   adapter: pulsarEvmAdapter(wagmiConfig, appChains),
+ * });
+ * ```
  */
 declare function createPulsarStore<T extends Transaction>({ adapter, maxTransactions, onRemoteCreate, gelatoApiKey, beforeTxProcess, abortOnTxError, ...options }: PulsarAdapter<T> & PersistOptions<ITxTrackingStore<T>>): Omit<zustand.StoreApi<ITxTrackingStore<T>>, "setState" | "persist"> & {
     setState(partial: ITxTrackingStore<T> | Partial<ITxTrackingStore<T>> | ((state: ITxTrackingStore<T>) => ITxTrackingStore<T> | Partial<ITxTrackingStore<T>>), replace?: false | undefined): unknown;
@@ -614,36 +785,36 @@ declare function createPulsarStore<T extends Transaction>({ adapter, maxTransact
 };
 
 /**
- * @file This file provides a utility for creating a type-safe, bounded Zustand hook from a vanilla store.
- * This pattern is recommended by the official Zustand documentation to ensure full type
- * safety when integrating vanilla stores with React.
+ * @file Binds a vanilla Zustand store (such as the Pulsar stores) to React with a typed hook.
  *
- * @see https://docs.pmnd.rs/zustand/guides/typescript#bounded-usestore-hook-for-vanilla-stores
+ * @see {@link https://zustand.docs.pmnd.rs/guides/typescript#bounded-usestore-hook-for-vanilla-stores Zustand: bounded useStore hook}
  */
 
 /**
- * A utility type that infers the state shape from a Zustand `StoreApi`.
- * It extracts the return type of the `getState` method.
- * @template S - The type of the Zustand store (`StoreApi`).
+ * The state type of a Zustand store: the return type of its `getState` method.
+ *
+ * @template S - The store type.
  */
 type ExtractState<S> = S extends {
     getState: () => infer T;
 } ? T : never;
 /**
- * Creates a bounded `useStore` hook from a vanilla Zustand store.
+ * Creates a React hook bound to a vanilla Zustand store, so components do not pass the store on every call.
  *
- * This function takes a vanilla Zustand store instance and returns a React hook
- * that is pre-bound to that store. This approach provides a cleaner API and
- * enhances type inference, eliminating the need to pass the store instance
- * on every use.
+ * The hook calls `useStore` from `zustand`, so it follows the rules of React hooks and needs `react` in the app. Call it
+ * without arguments to subscribe to the whole state, or with a selector to subscribe to a slice. A selector that
+ * returns a new object or array on every call (such as the transaction selectors) re-renders on every store update;
+ * select stable values or memoize.
  *
- * The returned hook supports two signatures:
- * 1. `useBoundedStore()`: Selects the entire state.
- * 2. `useBoundedStore(selector)`: Selects a slice of the state, returning only what the selector function specifies.
+ * @template S - The store type.
+ * @param store - The vanilla Zustand store, for example the result of `createPulsarStore`.
+ * @returns A hook: `useBoundedStore()` returns the whole state, `useBoundedStore(selector)` returns the selected value.
  *
- * @template S - The type of the Zustand store (`StoreApi`).
- * @param {S} store - The vanilla Zustand store instance to bind the hook to.
- * @returns {function} A fully typed React hook for accessing the store's state.
+ * @example
+ * ```ts
+ * const usePulsarStore = createBoundedUseStore(pulsarStore);
+ * const executeTxAction = usePulsarStore((state) => state.executeTxAction);
+ * ```
  */
 declare const createBoundedUseStore: <S extends StoreApi<unknown>>(store: S) => {
     (): ExtractState<S>;
@@ -651,95 +822,206 @@ declare const createBoundedUseStore: <S extends StoreApi<unknown>>(store: S) =>
 };
 
 /**
- * @file This file provides a generic utility for creating a polling mechanism to track
- * asynchronous tasks, such as API-based transaction status checks (e.g., for Gelato or Safe).
+ * @file Helper for store-connected trackers that keeps their copy of a transaction in sync with the fields they write.
  */
 
 /**
- * Defines the parameters for the fetcher function used within the polling tracker.
- * The fetcher is the core logic that performs the actual API call.
- * @template R The expected type of the successful API response.
- * @template T The type of the transaction object being tracked.
+ * Creates an updater for a store-connected tracker: it writes fields to the store with `updateTxParams` and returns the
+ * tracked transaction with every update applied so far.
+ *
+ * The `transactionsPool` a tracker receives is a snapshot taken when tracking starts, and Immer replaces the pool on
+ * every update, so reading the snapshot after `updateTxParams` returns stale data. Pass the object returned here to
+ * `TrackerCallbacks` instead. The built-in trackers of `@tuwaio/pulsar-evm` and `@tuwaio/pulsar-solana` use it; use it
+ * in custom trackers too.
+ *
+ * @template T - The application transaction type.
+ * @param params - The tracked transaction and the store members used by trackers.
+ * @param params.tx - The tracked transaction.
+ * @param params.transactionsPool - The pool snapshot; the tracked transaction is read from it once.
+ * @param params.updateTxParams - The store's `updateTxParams`.
+ * @returns A function that calls `updateTxParams(tx.txKey, fields)` and returns the updated transaction, or `undefined`
+ * when the transaction was not in the pool when tracking started. The snapshot is not mutated.
+ *
+ * @example
+ * ```ts
+ * const updateTx = createTxUpdater({ tx, transactionsPool, updateTxParams });
+ * const updatedTx = updateTx({ status: TransactionStatus.Success, pending: false });
+ * if (updatedTx) onSuccess?.(updatedTx);
+ * ```
+ */
+declare function createTxUpdater<T extends Transaction>({ tx, transactionsPool, updateTxParams, }: Pick<ITxTrackingStore<T>, 'transactionsPool' | 'updateTxParams'> & {
+    tx: T;
+}): (fields: UpdatableTransactionFields) => T | undefined;
+
+/**
+ * @file A generic polling loop for trackers that check a transaction through an API or RPC method (Safe, Gelato,
+ * ERC-4337 bundlers, Solana).
+ */
+
+/**
+ * The argument passed to a polling fetcher on every tick. The fetcher checks the transaction once and reports the result
+ * through the callbacks.
+ *
+ * @template R - The response type the fetcher reports.
+ * @template T - The tracked transaction type.
  */
 type PollingFetcherParams<R, T> = {
-    /** The transaction object being tracked. */
+    /** The tracked transaction, as passed to `initializePollingTracker`. */
     tx: T;
-    /** A callback to stop the polling mechanism, typically called on success or terminal failure. */
+    /**
+     * Stops polling. Unless `withoutRemoving` is `true`, it also calls `removeTxFromPool` (if configured) with the
+     * transaction key.
+     * @param options - Stop options.
+     */
     stopPolling: (options?: {
+        /** Keep the transaction in the pool. Defaults to `false`. */
         withoutRemoving?: boolean;
     }) => void;
-    /** Callback to be invoked when the fetcher determines the transaction has succeeded. */
+    /**
+     * The `onSuccess` callback of the tracker configuration.
+     * @param response - The result of the check.
+     */
     onSuccess: (response: R) => void;
-    /** Callback to be invoked when the fetcher determines the transaction has failed. */
+    /**
+     * The `onFailure` callback of the tracker configuration.
+     * @param response - The result of the check, if any.
+     */
     onFailure: (response?: R) => void;
-    /** Optional callback for each successful poll, useful for updating UI with intermediate states. */
+    /**
+     * The `onIntervalTick` callback of the tracker configuration, if any.
+     * @param response - The intermediate result.
+     */
     onIntervalTick?: (response: R) => void;
-    /** Optional callback for when a transaction is replaced (e.g., speed-up). */
+    /**
+     * The `onReplaced` callback of the tracker configuration, if any.
+     * @param response - The result describing the replacement.
+     */
     onReplaced?: (response: R) => void;
 };
 /**
- * Defines the configuration object for the `initializePollingTracker` function.
- * @template R The expected type of the successful API response.
- * @template T The type of the transaction object.
+ * The configuration of `initializePollingTracker`.
+ *
+ * @template R - The response type the fetcher reports.
+ * @template T - The tracked transaction type; only `txKey` and `pending` are required.
  */
-type PollingTrackerConfig<R, T extends Transaction> = {
-    /** The transaction object to be tracked. It must include `txKey` and `pending` status. */
-    tx: T & Pick<Transaction, 'txKey' | 'pending'>;
-    /** The function that performs the data fetching (e.g., an API call) on each interval. */
+type PollingTrackerConfig<R, T extends Pick<Transaction, 'txKey' | 'pending'>> = {
+    /** The transaction to track. Polling starts only if `pending` is `true`. */
+    tx: T;
+    /**
+     * Checks the transaction once per tick and reports through the callbacks it receives. It must call `stopPolling` on a
+     * terminal result. A thrown error counts as a failed attempt.
+     * @param params - The transaction, `stopPolling` and the callbacks.
+     */
     fetcher: (params: PollingFetcherParams<R, T>) => Promise<void>;
-    /** Callback to be invoked when the transaction successfully completes. */
+    /**
+     * Called by the fetcher when the transaction succeeded.
+     * @param response - The result reported by the fetcher.
+     */
     onSuccess: (response: R) => void;
-    /** Callback to be invoked when the transaction fails. */
+    /**
+     * Called by the fetcher when the transaction failed, and without arguments by the tracker after `maxRetries`
+     * consecutive failed attempts.
+     * @param response - The result reported by the fetcher, if any.
+     */
     onFailure: (response?: R) => void;
-    /** Optional callback executed once when the tracker is initialized. */
+    /** Called once, synchronously, when polling starts. */
     onInitialize?: () => void;
-    /** Optional callback for each successful poll. */
+    /**
+     * Called by the fetcher with intermediate results.
+     * @param response - The intermediate result.
+     */
     onIntervalTick?: (response: R) => void;
-    /** Optional callback for when a transaction is replaced. */
+    /**
+     * Called by the fetcher when the transaction was replaced.
+     * @param response - The result describing the replacement.
+     */
     onReplaced?: (response: R) => void;
-    /** Optional function to remove the transaction from the main pool, typically after polling stops. */
+    /**
+     * Called when polling stops, unless it was stopped with `withoutRemoving: true`.
+     * @param txKey - The `txKey` of the tracked transaction.
+     */
     removeTxFromPool?: (txKey: string) => void;
-    /** The interval (in milliseconds) between polling attempts. Defaults to 5000ms. */
+    /** The delay before each attempt, in milliseconds. Defaults to 5000. */
     pollingInterval?: number;
-    /** The number of consecutive failed fetches before stopping the tracker. Defaults to 10. */
+    /** The number of consecutive failed attempts (thrown errors) after which polling stops. Defaults to 10. */
     maxRetries?: number;
 };
 /**
- * Initializes a generic polling tracker that repeatedly calls a fetcher function
- * to monitor the status of an asynchronous task.
+ * Starts polling a transaction in the background and returns immediately. Does nothing if `tx.pending` is `false`.
+ *
+ * Every `pollingInterval` milliseconds (the first attempt also waits) it calls `fetcher`. Polling continues until the
+ * fetcher calls `stopPolling`. A fetcher that throws counts as a failed attempt; after `maxRetries` consecutive failed
+ * attempts the tracker calls `onFailure()` without arguments, logs a warning and stops (which calls
+ * `removeTxFromPool`, if configured). A successful attempt resets the count.
  *
- * This function handles the lifecycle of polling, including starting, stopping,
- * and automatic termination after a certain number of failed attempts.
+ * Side effects: runs a timer loop until it is stopped; there is no way to cancel it from the outside.
  *
- * @template R The expected type of the API response.
- * @template T The type of the transaction object.
- * @param {PollingTrackerConfig<R, T>} config - The configuration for the tracker.
+ * @template R - The response type the fetcher reports.
+ * @template T - The tracked transaction type.
+ * @param config - The transaction, the fetcher and the callbacks.
+ *
+ * @example
+ * ```ts
+ * initializePollingTracker<string, { txKey: string; pending: boolean }>({
+ *   tx: { txKey: taskId, pending: true },
+ *   fetcher: async ({ tx, stopPolling, onSuccess, onFailure }) => {
+ *     const status = await getTaskStatus(tx.txKey); // your API call; throw on network errors
+ *     if (status === 'done') onSuccess(status);
+ *     if (status === 'failed') onFailure(status);
+ *     if (status !== 'pending') stopPolling({ withoutRemoving: true });
+ *   },
+ *   onSuccess: () => console.log('Done'),
+ *   onFailure: () => console.log('Failed'),
+ * });
+ * ```
  */
-declare function initializePollingTracker<R, T extends Transaction>(config: PollingTrackerConfig<R, T>): void;
+declare function initializePollingTracker<R, T extends Pick<Transaction, 'txKey' | 'pending'>>(config: PollingTrackerConfig<R, T>): void;
 
-/** Maximum allowed length for each transaction title string. */
+/**
+ * @file Safety limits for the user-facing metadata of transactions (title, description, payload), checked before a
+ * transaction is executed, stored, restored or synchronized.
+ */
+
+/** Maximum length, in characters, of each `title` string. */
 declare const MAX_TRANSACTION_TITLE_LENGTH = 100;
-/** Maximum allowed length for each transaction description string. */
+/** Maximum length, in characters, of each `description` string. */
 declare const MAX_TRANSACTION_DESCRIPTION_LENGTH = 300;
-/** Maximum allowed serialized UTF-8 payload size in bytes. */
+/** Maximum size, in bytes, of the UTF-8 JSON of `payload`. */
 declare const MAX_TRANSACTION_PAYLOAD_BYTES: number;
 /**
- * Error thrown when transaction metadata fails Pulsar's safety limits.
+ * Thrown when the title, description or payload of a transaction breaks Pulsar's safety limits.
  */
 declare class PulsarTransactionValidationError extends Error {
-    /** The transaction field that failed validation. */
+    /** The field that failed, for example `title`, `description[1]` or `payload.amount`. */
     readonly field: string;
+    /**
+     * @param field - The field that failed.
+     * @param message - The error message.
+     */
     constructor(field: string, message: string);
 }
 /**
- * Validates metadata used before a transaction action is executed.
- * Throws when title, description, or payload violates Pulsar safety limits.
+ * Validates the metadata passed to `executeTxAction` before anything else runs.
+ *
+ * Each `title` string must be at most {@link MAX_TRANSACTION_TITLE_LENGTH} characters and each `description` string at
+ * most {@link MAX_TRANSACTION_DESCRIPTION_LENGTH}. `payload` must be JSON-serializable and at most
+ * {@link MAX_TRANSACTION_PAYLOAD_BYTES} bytes as UTF-8 JSON. Strings (including payload keys) must not match
+ * executable-like patterns: `eval(`, `Function(`, `setTimeout`/`setInterval` with a string argument, and `javascript:`.
+ * This is a defensive gate, not a replacement for escaping output in the UI.
+ *
+ * @param params - The transaction metadata.
+ * @throws {@link PulsarTransactionValidationError} for the first field that breaks a rule.
  */
 declare function validateInitialTransactionParams(params: Omit<InitialTransactionParams, 'actionFunction'>): void;
 /**
- * Validates a complete transaction before it is persisted or synchronized.
- * Throws when title, description, or payload violates Pulsar safety limits.
+ * Validates the title, description and payload of a complete transaction with the rules of
+ * {@link validateInitialTransactionParams}. Used by `addTxToPool`, `initializeTransactionsPool` and
+ * `injectExternalPendingTxs`.
+ *
+ * @template T - The application transaction type.
+ * @param tx - The transaction.
+ * @throws {@link PulsarTransactionValidationError} for the first field that breaks a rule.
  */
 declare function validateTransaction<T extends Transaction>(tx: T): void;
 
-export { type ActionTxKey, type BaseTransaction, type BeforeTxProcess, type CheckTxTracker, type EvmTransaction, type IInitializeTxTrackingStore, type ITxInMemoryStore, type ITxInMemoryStoreParameters, type ITxTrackingStore, type InitialTransaction, type InitialTransactionParams, MAX_TRANSACTION_DESCRIPTION_LENGTH, MAX_TRANSACTION_PAYLOAD_BYTES, MAX_TRANSACTION_TITLE_LENGTH, type PollingFetcherParams, type PollingTrackerConfig, type PulsarAdapter, PulsarTransactionValidationError, type SolanaTransaction, type StarknetTransaction, type StoreSlice, type SyncCallbacks, type TrackerCallbacks, type Transaction, type TransactionPool, TransactionStatus, TransactionTracker, type TxAdapter, type TxInMemoryPagination, type UpdatableTransactionFields, createBoundedUseStore, createPulsarStore, createTxInMemoryStore, initializePollingTracker, initializeTxTrackingStore, selectAllTransactions, selectAllTransactionsByActiveWallet, selectPendingTransactions, selectPendingTransactionsByActiveWallet, selectTxByKey, validateInitialTransactionParams, validateTransaction };
+export { type ActionTxKey, type BaseTransaction, type BeforeTxProcess, type CheckTxTracker, type EvmTransaction, type ExtractState, type IInitializeTxTrackingStore, type ITxInMemoryStore, type ITxInMemoryStoreParameters, type ITxTrackingStore, type InitialTransaction, type InitialTransactionParams, MAX_TRANSACTION_DESCRIPTION_LENGTH, MAX_TRANSACTION_PAYLOAD_BYTES, MAX_TRANSACTION_TITLE_LENGTH, type PollingFetcherParams, type PollingTrackerConfig, type PulsarAdapter, PulsarTransactionValidationError, type SolanaTransaction, type StarknetTransaction, type StoreSlice, type SyncCallbacks, type TrackerCallbacks, type Transaction, type TransactionPool, TransactionStatus, TransactionTracker, type TxAdapter, type TxInMemoryPagination, type UpdatableTransactionFields, createBoundedUseStore, createPulsarStore, createTxInMemoryStore, createTxUpdater, initializePollingTracker, initializeTxTrackingStore, selectAllTransactions, selectAllTransactionsByActiveWallet, selectPendingTransactions, selectPendingTransactionsByActiveWallet, selectTxByKey, validateInitialTransactionParams, validateTransaction };