@tuwaio/pulsar-core 0.0.4 → 0.0.5

package/dist/index.d.ts

@@ -9,108 +9,107 @@ import { PersistOptions } from 'zustand/middleware';
  */
 
 /**
- * A utility type for creating modular Zustand store slices.
- * @template T The state slice type.
- * @template E The full store state type, defaults to T.
+ * A utility type for creating modular Zustand store slices, enabling composable state management.
+ * @template T - The type of the state slice.
+ * @template S - The type of the full store state, defaulting to T.
  */
-type StoreSlice<T extends object, E extends object = T> = (set: StoreApi<E extends T ? E : E & T>['setState'], get: StoreApi<E extends T ? E : E & T>['getState']) => 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;
 /**
- * Represents the blockchain adapter for a transaction.
+ * Defines the supported blockchain adapters. Each adapter corresponds to a specific chain architecture.
  */
 declare enum TransactionAdapter {
-    /** EVM adapter. */
+    /** For Ethereum Virtual Machine (EVM) compatible chains like Ethereum, Polygon, etc. */
     EVM = "evm",
-    /** Solana adapter. */
+    /** For the Solana blockchain. */
     SOLANA = "solana",
-    /** Starknet adapter. */
-    Starknet = "Starknet"
+    /** For the Starknet L2 network. */
+    Starknet = "starknet"
 }
 /**
- * Represents the final status of a transaction.
+ * Represents the terminal status of a transaction after it has been processed.
  */
 declare enum TransactionStatus {
-    /** The transaction failed to execute. */
+    /** The transaction failed to execute due to an on-chain error or rejection. */
     Failed = "Failed",
     /** The transaction was successfully mined and executed. */
     Success = "Success",
-    /** The transaction was replaced by another (e.g., speed-up). */
+    /** The transaction was replaced by another with the same nonce (e.g., a speed-up or cancel). */
     Replaced = "Replaced"
 }
 /**
- * The base structure for any transaction being tracked.
- * @template T The type of the tracker identifier (e.g., 'evm', 'safe').
+ * The fundamental structure for any transaction being tracked by Pulsar.
+ * This forms the base upon which chain-specific transaction types are built.
+ * @template T - The type of the tracker identifier (e.g., 'ethereum', 'gelato', 'safe').
  */
 type BaseTransaction<T> = {
-    /** A key identifying the retry logic for this transaction from the actions registry. */
+    /** A unique key identifying a re-executable action from the `TxActions` registry. */
     actionKey?: string;
     /** The chain identifier (e.g., 1 for Ethereum Mainnet, 'SN_MAIN' for Starknet). */
     chainId: number | string;
-    /** A description for the transaction, with states for [pending, success, error, replaced]. */
+    /** A user-facing description. Can be a single string or an array for [pending, success, error, replaced] states. */
     description?: string | [string, string, string, string];
-    /** An error message if the transaction failed. */
+    /** The error message if the transaction failed. */
     errorMessage?: string;
-    /** The timestamp (in seconds) when the transaction was finalized on-chain. */
+    /** The on-chain timestamp (in seconds) when the transaction was finalized. */
     finishedTimestamp?: number;
-    /** The sender's address. */
+    /** The sender's wallet address. */
     from: string;
     /** A flag indicating if the transaction is in a failed state. */
     isError?: boolean;
-    /** A flag indicating if the detailed tracking modal should be open for this transaction. For UI purposes. */
+    /** A UI flag to control the visibility of a detailed tracking modal for this transaction. */
     isTrackedModalOpen?: boolean;
-    /** The local timestamp (in seconds) when the transaction was initiated. */
+    /** The local timestamp (in seconds) when the transaction was initiated by the user. */
     localTimestamp: number;
-    /** Any additional data associated with the transaction. */
+    /** Any additional, custom data associated with the transaction. */
     payload?: object;
-    /** Indicates if the transaction is still pending confirmation. */
+    /** A flag indicating if the transaction is still awaiting on-chain confirmation. */
     pending: boolean;
-    /** The final status of the transaction. */
+    /** The final on-chain status of the transaction. */
     status?: TransactionStatus;
-    /** A title for the transaction, with states for [pending, success, error, replaced]. */
+    /** A user-facing title. Can be a single string or an array for [pending, success, error, replaced] states. */
     title?: string | [string, string, string, string];
-    /** The specific tracker responsible for monitoring this transaction (e.g., 'evm', 'safe', 'gelato', etc.). */
+    /** The specific tracker responsible for monitoring this transaction's status. */
     tracker: T;
-    /** The unique key for the transaction within its tracker (e.g., EVM hash, Gelato task ID). */
+    /** The unique identifier for the transaction (e.g., EVM hash, Gelato task ID). */
     txKey: string;
-    /** The type or category of the transaction (e.g., 'increment', 'approve'). */
+    /** The application-specific type or category of the transaction (e.g., 'SWAP', 'APPROVE'). */
     type: string;
-    /** The type of wallet used for the transaction. */
+    /** The type of wallet used to sign the transaction (e.g., 'injected', 'walletConnect'). */
     walletType: string;
 };
 /**
- * Represents an EVM-specific transaction, extending the base properties.
- * @template T The type of the tracker identifier.
+ * Represents an EVM-specific transaction, extending the base properties with EVM fields.
+ * @template T - The type of the tracker identifier.
  */
 type EvmTransaction<T> = BaseTransaction<T> & {
-    /** The transaction adapter type. */
     adapter: TransactionAdapter.EVM;
     /** The on-chain transaction hash, available after submission. */
-    hash?: string;
-    /** The data payload for the transaction, typically for contract interactions. */
-    input?: string;
-    /** The maximum fee per gas for the transaction (EIP-1559). */
+    hash?: `0x${string}`;
+    /** The data payload for the transaction, typically for smart contract interactions. */
+    input?: `0x${string}`;
+    /** The maximum fee per gas for an EIP-1559 transaction (in wei). */
     maxFeePerGas?: string;
-    /** The maximum priority fee per gas for the transaction (EIP-1559). */
+    /** The maximum priority fee per gas for an EIP-1559 transaction (in wei). */
     maxPriorityFeePerGas?: string;
-    /** The transaction nonce. */
+    /** The transaction nonce, a sequential number for the sender's account. */
     nonce?: number;
-    /** The hash of a transaction that this one replaced (e.g., for speed-up). */
-    replacedTxHash?: string;
-    /** The recipient's address. */
-    to?: string;
-    /** The value (in wei) being sent with the transaction. */
+    /** The hash of a transaction that this one replaced. */
+    replacedTxHash?: `0x${string}`;
+    /** The recipient's address or contract address. */
+    to?: `0x${string}`;
+    /** The amount of native currency (in wei) being sent. */
     value?: string;
 };
 /**
  * Represents a Solana-specific transaction, extending the base properties.
- * @template T The type of the tracker identifier.
+ * @template T - The type of the tracker identifier.
  */
 type SolanaTransaction<T> = BaseTransaction<T> & {
-    /** The transaction adapter type. */
     adapter: TransactionAdapter.SOLANA;
-    /** The transaction fee. */
+    /** The transaction fee in lamports. */
     fee?: number;
     /** The instructions included in the transaction. */
-    instructions?: any[];
+    instructions?: unknown[];
     /** The recent blockhash used for the transaction. */
     recentBlockhash?: string;
     /** The slot in which the transaction was processed. */
@@ -118,9 +117,10 @@ type SolanaTransaction<T> = BaseTransaction<T> & {
 };
 /**
  * Represents a Starknet-specific transaction, extending the base properties.
- * @template T The type of the tracker identifier.
+ * @template T - The type of the tracker identifier.
  */
 type StarknetTransaction<T> = BaseTransaction<T> & {
+    adapter: TransactionAdapter.Starknet;
     /** The actual fee paid for the transaction. */
     actualFee?: {
         amount: string;
@@ -128,88 +128,118 @@ type StarknetTransaction<T> = BaseTransaction<T> & {
     };
     /** The address of the contract being interacted with. */
     contractAddress?: string;
-    /** The transaction adapter type. */
-    adapter: TransactionAdapter.Starknet;
     /** The reason for transaction failure, if applicable. */
     revertReason?: string;
 };
-/** A union type representing any possible transaction structure. */
+/** A union type representing any possible transaction structure that Pulsar can handle. */
 type Transaction<T> = EvmTransaction<T> | SolanaTransaction<T> | StarknetTransaction<T>;
 /**
- * Represents the parameters required to initiate a new transaction.
+ * A registry of functions that can be re-executed, keyed by `actionKey`.
+ * Used for implementing "Retry" functionality.
+ */
+type TxActions = Record<string, (...args: any[]) => Promise<unknown>>;
+/**
+ * Represents the parameters required to initiate a new transaction tracking flow.
  */
 type InitialTransactionParams = {
-    /** The transaction adapter type. */
     adapter: TransactionAdapter;
-    /** A key identifying the retry logic from the actions registry. */
+    /** A key to identify the re-executable action from the `TxActions` registry. */
     actionKey?: string;
-    /** A description for the transaction, with states for [pending, success, error, replaced]. */
+    /** A user-facing description for the transaction. */
     description?: string | [string, string, string, string];
-    /** The ID of the desired blockchain network. */
+    /** The target chain ID for the transaction. */
     desiredChainID: number | string;
-    /** Any additional data to be associated with the transaction. */
+    /** Any custom data to associate with the transaction. */
     payload?: object;
-    /** A title for the transaction, with states for [pending, success, error, replaced]. */
+    /** A user-facing title for the transaction. */
     title?: string | [string, string, string, string];
-    /** The type or category of the transaction (e.g., 'increment', 'approve'). */
+    /** The application-specific type of the transaction. */
     type: string;
-    /** If true, the detailed tracking modal will open automatically for this transaction. */
+    /** If true, the detailed tracking modal will open automatically upon initiation. */
     withTrackedModal?: boolean;
 };
 /**
- * Represents a transaction in its initial, pre-submission state within the store.
+ * Represents a transaction in its temporary, pre-submission state.
  * This is used for UI feedback while the transaction is being signed and sent.
  */
 type InitialTransaction = InitialTransactionParams & {
-    /** An error message if the initialization process fails (e.g., user rejects signature). */
+    /** An error message if the initialization fails (e.g., user rejects signature). */
     errorMessage?: string;
-    /** True if the transaction is currently being processed (e.g., waiting for user signature). */
+    /** A flag indicating if the transaction is being processed (e.g., waiting for signature). */
     isInitializing: boolean;
-    /** The key of the on-chain transaction that this action produced, used for linking. */
+    /** The `txKey` of the on-chain transaction that this action produced, used for linking the states. */
     lastTxKey?: string;
     /** The local timestamp when the user initiated the action. */
     localTimestamp: number;
 };
+/**
+ * Defines the interface for a transaction adapter, which provides chain-specific logic and utilities.
+ * @template TR - The type of the tracker identifier (e.g., a string enum).
+ * @template T - The specific transaction type, extending `Transaction<TR>`.
+ * @template A - The type of the key returned by the `actionFunction` (e.g., a transaction hash).
+ */
 type TxAdapter<TR, T extends Transaction<TR>, A> = {
+    /** The unique key identifying this adapter. */
     key: TransactionAdapter;
+    /** Returns information about the currently connected wallet. */
     getWalletInfo: () => {
-        /** Wallet address. */
         walletAddress: string;
-        /** Type of the wallet. (injected, wallet connect, etc.) */
         walletType: string;
     };
+    /** Ensures the connected wallet is on the correct network for the transaction. */
     checkChainForTx: (chainId: string | number) => Promise<void>;
+    /** Determines the appropriate tracker and final `txKey` based on the result of an action. */
     checkTransactionsTracker: (actionTxKey: A, walletType: string) => {
         txKey: string;
         tracker: TR;
     };
-    checkAndInitializeTrackerInStore: ({ tx, ...rest }: {
+    /** Initializes the correct background tracker for a given transaction. */
+    checkAndInitializeTrackerInStore: (params: {
         tx: T;
     } & Pick<ITxTrackingStore<TR, T, A>, 'transactionsPool' | 'updateTxParams' | 'onSucceedCallbacks' | 'removeTxFromPool'>) => Promise<void>;
+    /** Returns the base URL for the blockchain explorer. */
+    getExplorerUrl: () => string | undefined;
+    /** Optional: Fetches a name from a chain-specific name service (e.g., ENS). */
+    getName?: (address: string) => Promise<string | null>;
+    /** Optional: Fetches an avatar URL from a chain-specific name service. */
+    getAvatar?: (name: string) => Promise<string | null>;
+    /** Optional: Logic to cancel a pending EVM transaction. */
+    cancelTxAction?: (tx: T) => Promise<string>;
+    /** Optional: Logic to speed up a pending EVM transaction. */
+    speedUpTxAction?: (tx: T) => Promise<string>;
+    /** Optional: Logic to retry a failed transaction. */
+    retryTxAction?: (params: {
+        txKey: string;
+        tx: InitialTransactionParams;
+        actions?: TxActions;
+        onClose: (txKey?: string) => void;
+    } & Partial<Pick<ITxTrackingStore<TR, T, A>, 'handleTransaction'>>) => Promise<void>;
+    /** Optional: Constructs a full explorer URL for a specific transaction. */
+    getExplorerTxUrl?: (transactionsPool: TransactionPool<TR, T>, txKey: string, replacedTxHash?: string) => string;
 };
 /**
- * Interface for the complete transaction tracking store.
- * @template TR The type of the tracker identifier.
- * @template T The transaction type.
- * @template C The configuration object type (e.g., wagmi config).
- * @template A The return type of the action function being wrapped.
+ * The complete interface for the Pulsar transaction tracking store.
+ * @template TR - The type of the tracker identifier.
+ * @template T - The transaction type.
+ * @template A - The return type of the `actionFunction`.
  */
 type ITxTrackingStore<TR, T extends Transaction<TR>, A> = IInitializeTxTrackingStore<TR, T> & {
     /**
-     * A wrapper function that handles the entire lifecycle of a transaction.
-     * It creates an `InitialTransaction`, executes the on-chain action, and tracks its status.
+     * The core function that handles the entire lifecycle of a new transaction.
+     * It manages UI state, executes the on-chain action, and initiates background tracking.
      * @param params - The parameters for handling the transaction.
      */
     handleTransaction: (params: {
-        /** The async function to execute (e.g., a smart contract write call). */
+        /** The async function to execute (e.g., a smart contract write call). Must return a unique key or undefined. */
         actionFunction: () => Promise<A | undefined>;
-        /** The metadata for the transaction to be created, of type `InitialTransactionParams`. */
+        /** The metadata for the transaction. */
         params: InitialTransactionParams;
+        /** The default tracker to use if it cannot be determined automatically. */
         defaultTracker?: TR;
     }) => Promise<void>;
     /**
-     * Initializes all active trackers for pending transactions in the pool.
-     * This is useful for resuming tracking after a page reload.
+     * Initializes trackers for all pending transactions in the pool.
+     * This is essential for resuming tracking after a page reload.
      */
     initializeTransactionsPool: () => Promise<void>;
 };
@@ -230,14 +260,14 @@ type TransactionPool<TR, T extends Transaction<TR>> = Record<string, T>;
  * that are updatable via the `updateTxParams` action.
  * @template TR - The type of the tracker identifier.
  */
-type UpdatedParamsFields<TR> = Pick<EvmTransaction<TR>, 'to' | 'nonce' | 'txKey' | 'pending' | 'hash' | 'status' | 'replacedTxHash' | 'errorMessage' | 'finishedTimestamp' | 'isTrackedModalOpen' | 'isError' | 'maxPriorityFeePerGas' | 'maxFeePerGas' | 'input' | 'value'>;
+type UpdatableTransactionFields<TR> = Partial<Pick<EvmTransaction<TR>, 'to' | 'nonce' | 'txKey' | 'pending' | 'hash' | 'status' | 'replacedTxHash' | 'errorMessage' | 'finishedTimestamp' | 'isTrackedModalOpen' | 'isError' | 'maxPriorityFeePerGas' | 'maxFeePerGas' | 'input' | 'value'>>;
 /**
  * Defines the interface for the base transaction tracking store slice.
  * It includes the state and actions for managing transactions.
  * @template TR - The type of the tracker identifier.
  * @template T - The transaction type.
  */
-type IInitializeTxTrackingStore<TR, T extends Transaction<TR>> = {
+interface IInitializeTxTrackingStore<TR, T extends Transaction<TR>> {
     /** An optional callback function to be executed when a transaction successfully completes. */
     onSucceedCallbacks?: (tx: T) => Promise<void> | void;
     /** A pool of all transactions currently being tracked, indexed by their `txKey`. */
@@ -247,18 +277,16 @@ type IInitializeTxTrackingStore<TR, T extends Transaction<TR>> = {
     /** The state of a transaction that is currently being initiated but not yet submitted. */
     initialTx?: InitialTransaction;
     /** Adds a new transaction to the tracking pool. */
-    addTxToPool: ({ tx }: {
-        tx: T;
-    }) => void;
+    addTxToPool: (tx: T) => void;
     /** Updates one or more parameters of an existing transaction in the pool. */
-    updateTxParams: (fields: UpdatedParamsFields<TR>) => void;
+    updateTxParams: (txKey: string, fields: UpdatableTransactionFields<TR>) => void;
     /** Removes a transaction from the tracking pool using its key. */
     removeTxFromPool: (txKey: string) => void;
     /** Closes the tracking modal for a specific transaction. */
     closeTxTrackedModal: (txKey?: string) => void;
     /** Returns the key of the last transaction that was added to the pool. */
     getLastTxKey: () => string | undefined;
-};
+}
 /**
  * Creates a Zustand store slice containing the core logic for transaction tracking.
  * This function is a slice creator and is meant to be used within `createStore` from Zustand.
@@ -272,91 +300,118 @@ declare function initializeTxTrackingStore<TR, T extends Transaction<TR>>({ onSu
 
 /**
  * @file This file contains selector functions for deriving state from the transaction tracking store.
- * Selectors help abstract away the shape of the state and provide memoized, efficient access to computed data.
+ * Selectors help abstract the state's shape and provide efficient, memoized access to computed data.
  */
 
 /**
- * Selects all transactions from the pool and sorts them by their creation timestamp.
+ * Selects all transactions from the pool and sorts them by their creation timestamp in ascending order.
  * @template TR - The type of the tracker identifier.
  * @template T - The transaction type.
- * @param {TransactionPool<TR, T>} transactionsPool - The entire pool of transactions from the store.
+ * @param {TransactionPool<TR, T>} transactionsPool - The entire transaction pool from the store.
  * @returns {T[]} An array of all transactions, sorted chronologically.
  */
 declare const selectAllTransactions: <TR, T extends Transaction<TR>>(transactionsPool: TransactionPool<TR, T>) => T[];
 /**
- * Selects all transactions that are currently in a pending state.
+ * Selects all transactions that are currently in a pending state, sorted chronologically.
  * @template TR - The type of the tracker identifier.
  * @template T - The transaction type.
- * @param {TransactionPool<TR, T>} transactionsPool - The entire pool of transactions from the store.
+ * @param {TransactionPool<TR, T>} transactionsPool - The entire transaction pool from the store.
  * @returns {T[]} An array of pending transactions.
  */
 declare const selectPendingTransactions: <TR, T extends Transaction<TR>>(transactionsPool: TransactionPool<TR, T>) => T[];
 /**
- * Selects a single transaction from the pool by its unique transaction key (`txKey`).
- * This is the most direct way to retrieve a transaction.
+ * Selects a single transaction from the pool by its unique key (`txKey`).
  * @template TR - The type of the tracker identifier.
  * @template T - The transaction type.
- * @param {TransactionPool<TR, T>} transactionsPool - The entire pool of transactions from the store.
+ * @param {TransactionPool<TR, 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.
  */
-declare const selectTXByKey: <TR, T extends Transaction<TR>>(transactionsPool: TransactionPool<TR, T>, key: string) => T | undefined;
+declare const selectTxByKey: <TR, T extends Transaction<TR>>(transactionsPool: TransactionPool<TR, T>, key: string) => T | undefined;
 /**
- * Selects all transactions initiated by a specific wallet address.
+ * Selects all transactions initiated by a specific wallet address, sorted chronologically.
  * @template TR - The type of the tracker identifier.
  * @template T - The transaction type.
- * @param {TransactionPool<TR, T>} transactionsPool - The entire pool of transactions from the store.
+ * @param {TransactionPool<TR, 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.
  */
 declare const selectAllTransactionsByActiveWallet: <TR, T extends Transaction<TR>>(transactionsPool: TransactionPool<TR, T>, from: string) => T[];
 /**
- * Selects all pending transactions initiated by a specific wallet address.
+ * Selects all pending transactions for a specific wallet address, sorted chronologically.
  * @template TR - The type of the tracker identifier.
  * @template T - The transaction type.
- * @param {TransactionPool<TR, T>} transactionsPool - The entire pool of transactions from the store.
+ * @param {TransactionPool<TR, 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 associated with the given wallet.
+ * @returns {T[]} An array of pending transactions for the given wallet.
  */
 declare const selectPendingTransactionsByActiveWallet: <TR, T extends Transaction<TR>>(transactionsPool: TransactionPool<TR, T>, from: string) => T[];
 
+/**
+ * Creates the main Pulsar store for transaction tracking.
+ *
+ * This function sets up a Zustand store with persistence, combining the core
+ * transaction slice with adapter-specific logic to handle the entire lifecycle
+ * of a transaction.
+ *
+ * @template TR - The type of the tracker identifier (e.g., a string enum).
+ * @template T - The specific transaction type, extending the base `Transaction`.
+ * @template A - The type for the adapter-specific context or API.
+ *
+ * @param {object} config - Configuration object for creating the store.
+ * @param {function} [config.onSucceedCallbacks] - Optional async callback executed on transaction success.
+ * @param {TxAdapter<TR, T, A>[]} config.adapters - An array of adapters for different transaction types or chains.
+ * @param {PersistOptions<ITxTrackingStore<TR, T, A>>} [options] - Configuration for the Zustand persist middleware.
+ * @returns A fully configured Zustand store instance.
+ */
 declare function createPulsarStore<TR, T extends Transaction<TR>, A>({ onSucceedCallbacks, adapters, ...options }: {
     onSucceedCallbacks?: (tx: T) => Promise<void> | void;
     adapters: TxAdapter<TR, T, A>[];
-} & PersistOptions<ITxTrackingStore<TR, T, A>>): Omit<zustand.StoreApi<ITxTrackingStore<TR, T, A>>, "persist"> & {
+} & PersistOptions<ITxTrackingStore<TR, T, A>>): Omit<zustand.StoreApi<ITxTrackingStore<TR, T, A>>, "setState" | "persist"> & {
+    setState(partial: ITxTrackingStore<TR, T, A> | Partial<ITxTrackingStore<TR, T, A>> | ((state: ITxTrackingStore<TR, T, A>) => ITxTrackingStore<TR, T, A> | Partial<ITxTrackingStore<TR, T, A>>), replace?: false | undefined): unknown;
+    setState(state: ITxTrackingStore<TR, T, A> | ((state: ITxTrackingStore<TR, T, A>) => ITxTrackingStore<TR, T, A>), replace: true): unknown;
     persist: {
-        setOptions: (options: Partial<PersistOptions<ITxTrackingStore<TR, T, A>, ITxTrackingStore<TR, T, A>>>) => void;
+        setOptions: (options: Partial<PersistOptions<ITxTrackingStore<TR, T, A>, ITxTrackingStore<TR, T, A>, unknown>>) => void;
         clearStorage: () => void;
         rehydrate: () => Promise<void> | void;
         hasHydrated: () => boolean;
         onHydrate: (fn: (state: ITxTrackingStore<TR, T, A>) => void) => () => void;
         onFinishHydration: (fn: (state: ITxTrackingStore<TR, T, A>) => void) => () => void;
-        getOptions: () => Partial<PersistOptions<ITxTrackingStore<TR, T, A>, ITxTrackingStore<TR, T, A>>>;
+        getOptions: () => Partial<PersistOptions<ITxTrackingStore<TR, T, A>, ITxTrackingStore<TR, T, A>, unknown>>;
     };
 };
 
 /**
- * @file This file provides a utility for creating a bounded Zustand hook from a vanilla store.
- * This is a recommended pattern for using vanilla stores with React to ensure full type safety.
+ * @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.
  *
- * @see https://zustand.docs.pmnd.rs/guides/typescript#bounded-usestore-hook-for-vanilla-stores
+ * @see https://docs.pmnd.rs/zustand/guides/typescript#bounded-usestore-hook-for-vanilla-stores
  */
 
 /**
- * A utility type to infer the state shape from a Zustand store type.
- * @template S The type of the Zustand store (`StoreApi`).
+ * 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`).
  */
 type ExtractState<S> = S extends {
-    getState: () => infer X;
-} ? X : never;
+    getState: () => infer T;
+} ? T : never;
 /**
- * Creates a bounded `useStore` hook from a vanilla Zustand store instance.
- * The returned hook is fully typed and can be used with or without a selector.
+ * Creates a bounded `useStore` hook from a vanilla Zustand store.
+ *
+ * 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.
  *
- * @template S The type of the Zustand store (`StoreApi`).
- * @param {S} store - The vanilla Zustand store instance.
- * @returns {function} A hook that can be called with an optional selector function.
- * - When called with a selector (`useBoundedStore(state => state.someValue)`), it returns the selected slice of the state.
+ * 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 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.
  */
 declare const createBoundedUseStore: <S extends StoreApi<unknown>>(store: S) => {
     (): ExtractState<S>;
@@ -364,63 +419,99 @@ declare const createBoundedUseStore: <S extends StoreApi<unknown>>(store: S) =>
 };
 
 /**
- * @file This file contains 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 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).
  */
 
+/**
+ * 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.
+ */
+type PollingFetcherParams<R, T> = {
+    /** The transaction object being tracked. */
+    tx: T;
+    /** A callback to stop the polling mechanism, typically called on success or terminal failure. */
+    stopPolling: (options?: {
+        withoutRemoving?: boolean;
+    }) => void;
+    /** Callback to be invoked when the fetcher determines the transaction has succeeded. */
+    onSuccess: (response: R) => void;
+    /** Callback to be invoked when the fetcher determines the transaction has failed. */
+    onFailure: (response?: R) => void;
+    /** Optional callback for each successful poll, useful for updating UI with intermediate states. */
+    onIntervalTick?: (response: R) => void;
+    /** Optional callback for when a transaction is replaced (e.g., speed-up). */
+    onReplaced?: (response: R) => void;
+};
 /**
  * Defines the configuration object for the `initializePollingTracker` function.
- * @template R The expected type of the successful API response from the fetcher.
- * @template T The type of the transaction object being tracked.
- * @template TR The type of the tracker identifier used in the `Transaction` type.
- */
-type InitializePollingTracker<R, T, TR> = {
-    /** The transaction object to be tracked. It must include `txKey` and an optional `pending` status. */
-    tx: T & Pick<Transaction<TR>, 'txKey'> & {
-        pending?: boolean;
-    };
-    /** The function that performs the actual data fetching (e.g., an API call). */
-    fetcher: (params: {
-        /** The transaction object being tracked. */
-        tx: T;
-        /** A callback to stop the polling mechanism, typically called on success or terminal failure. */
-        clearWatch: (withoutRemoving?: boolean) => void;
-        /** Callback to be invoked when the fetcher determines the transaction has succeeded. */
-        onSucceed: (response: R) => void;
-        /** Callback to be invoked when the fetcher determines the transaction has failed. */
-        onFailed: (response: R) => void;
-        /** Optional callback for each successful poll, useful for updating UI with intermediate states. */
-        onIntervalTick?: (response: R) => void;
-        /** Optional callback for when a transaction is replaced by another. */
-        onReplaced?: (response: R) => void;
-    }) => Promise<Response>;
+ * @template R - The expected type of the successful API response.
+ * @template T - The type of the transaction object.
+ * @template TR - The type of the tracker identifier.
+ */
+type PollingTrackerConfig<R, T, TR> = {
+    /** The transaction object to be tracked. It must include `txKey` and `pending` status. */
+    tx: T & Pick<Transaction<TR>, 'txKey' | 'pending'>;
+    /** The function that performs the data fetching (e.g., an API call) on each interval. */
+    fetcher: (params: PollingFetcherParams<R, T>) => Promise<void>;
+    /** Callback to be invoked when the transaction successfully completes. */
+    onSuccess: (response: R) => void;
+    /** Callback to be invoked when the transaction fails. */
+    onFailure: (response?: R) => void;
     /** Optional callback executed once when the tracker is initialized. */
     onInitialize?: () => void;
-    /** Callback to be invoked when the transaction has succeeded. */
-    onSucceed: (response: R) => void;
-    /** Callback to be invoked when the transaction has failed. */
-    onFailed: (response: R) => void;
     /** Optional callback for each successful poll. */
     onIntervalTick?: (response: R) => void;
     /** Optional callback for when a transaction is replaced. */
     onReplaced?: (response: R) => void;
     /** Optional function to remove the transaction from the main pool, typically after polling stops. */
-    removeTxFromPool?: (taskId: string) => void;
+    removeTxFromPool?: (txKey: string) => void;
     /** The interval (in milliseconds) between polling attempts. Defaults to 5000ms. */
     pollingInterval?: number;
     /** The number of consecutive failed fetches before stopping the tracker. Defaults to 10. */
-    retryCount?: number;
+    maxRetries?: number;
 };
 /**
  * Initializes a generic polling tracker that repeatedly calls a fetcher function
- * to monitor the status of a transaction or any asynchronous task.
+ * to monitor the status of an asynchronous task.
  *
- * @template R The expected type of the successful API response.
+ * This function handles the lifecycle of polling, including starting, stopping,
+ * and automatic termination after a certain number of failed attempts.
+ *
+ * @template R The expected type of the API response.
  * @template T The type of the transaction object.
  * @template TR The type of the tracker identifier.
- * @param {InitializePollingTracker<R, T, TR>} params - The configuration object for the tracker.
- * @returns {Promise<void>} A promise that resolves when the tracker is set up (note: polling happens asynchronously).
+ * @param {PollingTrackerConfig<R, T, TR>} config - The configuration for the tracker.
+ */
+declare function initializePollingTracker<R, T, TR>(config: PollingTrackerConfig<R, T, TR>): void;
+
+/**
+ * @file This file contains a utility function for selecting a specific transaction adapter from a list.
  */
-declare function initializePollingTracker<R, T, TR>({ onInitialize, tx, removeTxFromPool, fetcher, onFailed, onIntervalTick, onSucceed, pollingInterval, retryCount, onReplaced, }: InitializePollingTracker<R, T, TR>): Promise<void>;
 
-export { type BaseTransaction, type EvmTransaction, type IInitializeTxTrackingStore, type ITxTrackingStore, type InitialTransaction, type InitialTransactionParams, type InitializePollingTracker, type SolanaTransaction, type StarknetTransaction, type StoreSlice, type Transaction, TransactionAdapter, type TransactionPool, TransactionStatus, type TxAdapter, createBoundedUseStore, createPulsarStore, initializePollingTracker, initializeTxTrackingStore, selectAllTransactions, selectAllTransactionsByActiveWallet, selectPendingTransactions, selectPendingTransactionsByActiveWallet, selectTXByKey };
+/**
+ * Selects a transaction adapter from a list based on a provided key.
+ *
+ * This function searches through an array of `TxAdapter` instances and returns the one
+ * that matches the given `adapterKey`. If no specific adapter is found, it logs a warning
+ * and returns the first adapter in the array as a fallback. This fallback mechanism
+ * ensures that the system can still function, but it highlights a potential configuration issue.
+ *
+ * @template TR - The type of the tracker identifier.
+ * @template T - The transaction type, extending the base `Transaction`.
+ * @template A - The type for the adapter-specific context or API.
+ *
+ * @param {object} params - The parameters for the selection.
+ * @param {TransactionAdapter} params.adapterKey - The key of the desired adapter.
+ * @param {TxAdapter<TR, T, A>[]} params.adapters - An array of available transaction adapters.
+ *
+ * @returns {TxAdapter<TR, T, A> | undefined} The found transaction adapter, the fallback adapter, or undefined if the adapters array is empty.
+ */
+declare const selectAdapterByKey: <TR, T extends Transaction<TR>, A>({ adapterKey, adapters, }: {
+    adapterKey: TransactionAdapter;
+    adapters: TxAdapter<TR, T, A>[];
+}) => TxAdapter<TR, T, A> | undefined;
+
+export { type BaseTransaction, type EvmTransaction, type IInitializeTxTrackingStore, type ITxTrackingStore, type InitialTransaction, type InitialTransactionParams, type PollingTrackerConfig, type SolanaTransaction, type StarknetTransaction, type StoreSlice, type Transaction, TransactionAdapter, type TransactionPool, TransactionStatus, type TxActions, type TxAdapter, createBoundedUseStore, createPulsarStore, initializePollingTracker, initializeTxTrackingStore, selectAdapterByKey, selectAllTransactions, selectAllTransactionsByActiveWallet, selectPendingTransactions, selectPendingTransactionsByActiveWallet, selectTxByKey };