@tuwaio/pulsar-core 1.0.0-fix-retry-actions-alpha.2.49e2be4 → 1.0.0-fix-callbacks-alpha.1.227594b

package/README.md

@@ -62,20 +62,12 @@ import { wagmiConfig, chains } from './path/to/your/wagmi/config';
 const pulsarStore = createPulsarStore({
   // A unique name for Zustand's persistence middleware. This will be the key in localStorage.
   name: 'my-app-pulsar-storage',
-
   // An array of adapters for different blockchain ecosystems.
   // Each adapter provides chain-specific logic.
-  adapters: [
+  adapter: [
     evmAdapter(wagmiConfig, chains),
     // ... add other adapters like solanaAdapter here
   ],
-
-  // (Optional) A callback function to execute on every successful transaction.
-  // Ideal for global logic like showing a success notification.
-  onSucceedCallbacks: (tx) => {
-    console.log('Transaction succeeded!', tx);
-    // e.g., showToast('Success!', { type: 'success' });
-  },
 });
 
 export default pulsarStore;

package/dist/index.d.mts

@@ -4,14 +4,14 @@ import { PersistOptions } from 'zustand/middleware';
 
 /**
  * @file This file defines the core data structures and TypeScript types for the Pulsar transaction tracking engine.
- * It includes types for transactions, their statuses, store interfaces, and utility types for Zustand slices.
- * These types are framework-agnostic and form the foundation of the entire tracking system.
+ * It specifies the framework-agnostic models for transactions, their lifecycle statuses, and the interfaces for
+ * the Zustand-based store and chain-specific adapters.
  */
 
 /**
  * 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.
+ * @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;
 /**
@@ -25,26 +25,64 @@ declare enum TransactionAdapter {
     /** For the Starknet L2 network. */
     Starknet = "starknet"
 }
+/**
+ * Enum representing the different tracking strategies available for EVM transactions.
+ * Each tracker corresponds to a specific method of monitoring a transaction's lifecycle.
+ */
+declare enum TransactionTracker {
+    /** For standard on-chain EVM transactions tracked by their hash. */
+    Ethereum = "ethereum",
+    /** For multi-signature transactions managed and executed via a Safe contract. */
+    Safe = "safe",
+    /** For meta-transactions relayed and executed by the Gelato Network. */
+    Gelato = "gelato",
+    /** The tracker for monitoring standard Solana transaction signatures. */
+    Solana = "solana"
+}
 /**
  * Represents the terminal status of a transaction after it has been processed.
  */
 declare enum TransactionStatus {
     /** The transaction failed to execute due to an on-chain error or rejection. */
     Failed = "Failed",
-    /** The transaction was successfully mined and executed. */
+    /** The transaction was successfully mined and included in a block. */
     Success = "Success",
     /** The transaction was replaced by another with the same nonce (e.g., a speed-up or cancel). */
     Replaced = "Replaced"
 }
+/**
+ * Defines the shape of the identifier for a Gelato transaction task.
+ */
+type GelatoTxKey = {
+    taskId: string;
+};
+/**
+ * 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 EVM adapter to determine which tracker should
+ * monitor the transaction.
+ *
+ * It can be one of the following:
+ * - A standard `0x...` transaction hash (`Hex`).
+ * - A structured object from a relay service like Gelato (`GelatoTxKey`).
+ */
+type ActionTxKey = `0x${string}` | GelatoTxKey | string;
 /**
  * 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').
+ * This serves as the base upon which chain-specific transaction types are built.
  */
-type BaseTransaction<T> = {
+type BaseTransaction = {
     /** The chain identifier (e.g., 1 for Ethereum Mainnet, 'SN_MAIN' for Starknet). */
     chainId: number | string;
-    /** A user-facing description. Can be a single string or an array for [pending, success, error, replaced] states. */
+    /**
+     * User-facing description. Can be a single string for all states, or a tuple for specific states.
+     * @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']
+     */
     description?: string | [string, string, string, string];
     /** The error message if the transaction failed. */
     errorMessage?: string;
@@ -64,10 +102,17 @@ type BaseTransaction<T> = {
     pending: boolean;
     /** The final on-chain status of the transaction. */
     status?: TransactionStatus;
-    /** A user-facing title. Can be a single string or an array for [pending, success, error, replaced] states. */
+    /**
+     * User-facing title. Can be a single string for all states, or a tuple for specific states.
+     * @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']
+     */
     title?: string | [string, string, string, string];
     /** The specific tracker responsible for monitoring this transaction's status. */
-    tracker: T;
+    tracker: TransactionTracker;
     /** The unique identifier for the transaction (e.g., EVM hash, Gelato task ID). */
     txKey: string;
     /** The application-specific type or category of the transaction (e.g., 'SWAP', 'APPROVE'). */
@@ -77,9 +122,8 @@ type BaseTransaction<T> = {
 };
 /**
  * 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> & {
+type EvmTransaction = BaseTransaction & {
     adapter: TransactionAdapter.EVM;
     /** The on-chain transaction hash, available after submission. */
     hash?: `0x${string}`;
@@ -100,9 +144,8 @@ type EvmTransaction<T> = BaseTransaction<T> & {
 };
 /**
  * Represents a Solana-specific transaction, extending the base properties.
- * @template T - The type of the tracker identifier.
  */
-type SolanaTransaction<T> = BaseTransaction<T> & {
+type SolanaTransaction = BaseTransaction & {
     adapter: TransactionAdapter.SOLANA;
     /** The transaction fee in lamports. */
     fee?: number;
@@ -112,16 +155,15 @@ type SolanaTransaction<T> = BaseTransaction<T> & {
     recentBlockhash?: string;
     /** The slot in which the transaction was processed. */
     slot?: number;
-    /** The number of confirmations the transaction has received, or null if the transaction is still pending. */
-    confirmations?: number | null;
-    /** The RPC URL used for the transaction. */
+    /** The number of confirmations received. `string` when tx successed. `null` if the transaction is pending or unconfirmed. */
+    confirmations?: number | string | null;
+    /** The RPC URL used to submit and track this transaction. */
     rpcUrl?: string;
 };
 /**
  * Represents a Starknet-specific transaction, extending the base properties.
- * @template T - The type of the tracker identifier.
  */
-type StarknetTransaction<T> = BaseTransaction<T> & {
+type StarknetTransaction = BaseTransaction & {
     adapter: TransactionAdapter.Starknet;
     /** The actual fee paid for the transaction. */
     actualFee?: {
@@ -130,38 +172,36 @@ type StarknetTransaction<T> = BaseTransaction<T> & {
     };
     /** The address of the contract being interacted with. */
     contractAddress?: string;
-    /** The reason for transaction failure, if applicable. */
-    revertReason?: string;
 };
 /** A union type representing any possible transaction structure that Pulsar can handle. */
-type Transaction<T> = EvmTransaction<T> | SolanaTransaction<T> | StarknetTransaction<T>;
+type Transaction = EvmTransaction | SolanaTransaction | StarknetTransaction;
 /**
  * Represents the parameters required to initiate a new transaction tracking flow.
  */
-type InitialTransactionParams<A> = {
+type InitialTransactionParams = {
     adapter: TransactionAdapter;
-    /** A function that can be re-executed. */
-    actionFunction: (...args: any[]) => Promise<A | undefined>;
-    /** A user-facing description for the transaction. */
+    /** 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>;
+    /** A user-facing description for the transaction. Supports state-specific descriptions. */
     description?: string | [string, string, string, string];
     /** The target chain ID for the transaction. */
     desiredChainID: number | string;
     /** Any custom data to associate with the transaction. */
     payload?: object;
-    /** A user-facing title for the transaction. */
+    /** A user-facing title for the transaction. Supports state-specific titles. */
     title?: string | [string, string, string, string];
     /** The application-specific type of the transaction. */
     type: string;
     /** If true, the detailed tracking modal will open automatically upon initiation. */
     withTrackedModal?: boolean;
-    /** Required for Solana transactions. The RPC URL to use for the transaction. */
+    /** The RPC URL to use for the transaction. Required for Solana transactions. */
     rpcUrl?: string;
 };
 /**
  * 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<A> = InitialTransactionParams<A> & {
+type InitialTransaction = InitialTransactionParams & {
     /** An error message if the initialization fails (e.g., user rejects signature). */
     errorMessage?: string;
     /** A flag indicating if the transaction is being processed (e.g., waiting for signature). */
@@ -173,11 +213,9 @@ type InitialTransaction<A> = InitialTransactionParams<A> & {
 };
 /**
  * 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).
+ * @template T The specific transaction type, extending `Transaction`.
  */
-type TxAdapter<TR, T extends Transaction<TR>, A> = {
+type TxAdapter<T extends Transaction> = {
     /** The unique key identifying this adapter. */
     key: TransactionAdapter;
     /** Returns information about the currently connected wallet. */
@@ -185,19 +223,19 @@ type TxAdapter<TR, T extends Transaction<TR>, A> = {
         walletAddress: string;
         walletType: string;
     };
-    /** Ensures the connected wallet is on the correct network for the transaction. */
+    /** Ensures the connected wallet is on the correct network for the transaction. Throws an error if the chain is mismatched. */
     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) => {
+    /** Determines the appropriate tracker and final `txKey` from the result of an action. */
+    checkTransactionsTracker: (actionTxKey: ActionTxKey, walletType: string) => {
         txKey: string;
-        tracker: TR;
+        tracker: TransactionTracker;
     };
-    /** Initializes the correct background tracker for a given transaction. */
+    /** Selects and 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;
+    } & Pick<ITxTrackingStore<T>, 'updateTxParams' | 'removeTxFromPool'>) => Promise<void>;
+    /** Returns the base URL for the blockchain explorer for the current network. */
+    getExplorerUrl: (url?: string) => 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. */
@@ -209,31 +247,34 @@ type TxAdapter<TR, T extends Transaction<TR>, A> = {
     /** Optional: Logic to retry a failed transaction. */
     retryTxAction?: (params: {
         txKey: string;
-        tx: InitialTransactionParams<A>;
+        tx: InitialTransactionParams;
         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;
+    } & Partial<Pick<ITxTrackingStore<T>, 'handleTransaction'>>) => Promise<void>;
+    /**
+     * Optional: Constructs a full explorer URL for a specific transaction.
+     * May require the full transaction pool to resolve details for replaced transactions.
+     */
+    getExplorerTxUrl?: (tx: T) => string;
 };
 /**
  * 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`.
+ * @template T The transaction type.
  */
-type ITxTrackingStore<TR, T extends Transaction<TR>, A> = IInitializeTxTrackingStore<TR, T, A> & {
+type ITxTrackingStore<T extends Transaction> = IInitializeTxTrackingStore<T> & {
     /**
-     * The core function that handles the entire lifecycle of a new transaction.
+     * 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.
-     * @param params - The parameters for handling the transaction.
+     * @param params The parameters for handling the transaction.
      */
     handleTransaction: (params: {
         /** The async function to execute (e.g., a smart contract write call). Must return a unique key or undefined. */
-        actionFunction: () => Promise<A | undefined>;
+        actionFunction: () => Promise<ActionTxKey | undefined>;
         /** The metadata for the transaction. */
-        params: Omit<InitialTransactionParams<A>, 'actionFunction'>;
+        params: Omit<InitialTransactionParams, 'actionFunction'>;
         /** The default tracker to use if it cannot be determined automatically. */
-        defaultTracker?: TR;
+        defaultTracker?: TransactionTracker;
+        /** Callback to execute when the transaction is successfully submitted. */
+        onSucceedCallback?: (tx: T) => Promise<void> | void;
     }) => Promise<void>;
     /**
      * Initializes trackers for all pending transactions in the pool.
@@ -243,58 +284,53 @@ type ITxTrackingStore<TR, T extends Transaction<TR>, A> = IInitializeTxTrackingS
 };
 
 /**
- * @file This file provides the core slice for the Zustand store, responsible for managing the state of transactions.
- * It includes functions and types for initializing the store and performing basic CRUD operations on the transaction pool.
+ * @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.
  */
 
 /**
- * Defines the structure of the transaction pool, which is a record of transactions indexed by their unique keys.
- * @template TR - The type of the tracker identifier.
- * @template T - The transaction type.
+ * 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.
  */
-type TransactionPool<TR, T extends Transaction<TR>> = Record<string, T>;
+type TransactionPool<T extends Transaction> = Record<string, T>;
 /**
- * A utility type that extracts a subset of fields from the `Transaction` type
- * that are updatable via the `updateTxParams` action.
- * @template TR - The type of the tracker identifier.
+ * 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.
  */
-type UpdatableTransactionFields<TR> = Partial<Pick<EvmTransaction<TR>, 'to' | 'nonce' | 'txKey' | 'pending' | 'hash' | 'status' | 'replacedTxHash' | 'errorMessage' | 'finishedTimestamp' | 'isTrackedModalOpen' | 'isError' | 'maxPriorityFeePerGas' | 'maxFeePerGas' | 'input' | 'value'>> & Partial<Pick<SolanaTransaction<TR>, 'slot' | 'confirmations' | 'fee' | 'instructions' | 'recentBlockhash' | 'rpcUrl'>>;
+type UpdatableTransactionFields = Partial<Pick<EvmTransaction, 'to' | 'nonce' | 'txKey' | 'pending' | 'hash' | 'status' | 'replacedTxHash' | 'errorMessage' | 'finishedTimestamp' | 'isTrackedModalOpen' | 'isError' | 'maxPriorityFeePerGas' | 'maxFeePerGas' | 'input' | 'value'>> & Partial<Pick<SolanaTransaction, 'slot' | 'confirmations' | 'fee' | 'instructions' | 'recentBlockhash' | 'rpcUrl'>>;
 /**
- * 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.
+ * 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.
  */
-interface IInitializeTxTrackingStore<TR, T extends Transaction<TR>, A> {
-    /** 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`. */
-    transactionsPool: TransactionPool<TR, T>;
-    /** The key of the most recently added transaction. */
+interface IInitializeTxTrackingStore<T extends Transaction> {
+    /** A pool of all transactions currently being tracked, indexed by `txKey`. */
+    transactionsPool: TransactionPool<T>;
+    /** The `txKey` of the most recently added transaction. */
     lastAddedTxKey?: string;
-    /** The state of a transaction that is currently being initiated but not yet submitted. */
-    initialTx?: InitialTransaction<A>;
-    /** Adds a new transaction to the tracking pool. */
-    addTxToPool: (tx: Transaction<TR>) => void;
-    /** Updates one or more parameters of an existing transaction in the pool. */
-    updateTxParams: (txKey: string, fields: UpdatableTransactionFields<TR>) => void;
-    /** Removes a transaction from the tracking pool using its key. */
+    /** The state for a transaction being initiated, used for UI feedback before it's submitted to the chain. */
+    initialTx?: InitialTransaction;
+    /** Adds a new transaction to the tracking pool and marks it as pending. */
+    addTxToPool: (tx: T) => void;
+    /** Updates one or more properties of an existing transaction in the pool. */
+    updateTxParams: (txKey: string, fields: UpdatableTransactionFields) => void;
+    /** Removes a transaction from the tracking pool by its key. */
     removeTxFromPool: (txKey: string) => void;
-    /** Closes the tracking modal for a specific transaction. */
+    /** Closes the tracking modal for a transaction and clears any initial transaction state. */
     closeTxTrackedModal: (txKey?: string) => void;
-    /** Returns the key of the last transaction that was added to the pool. */
+    /** A selector function to retrieve the key of the last transaction 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.
- * @param {object} options - Configuration options for the store slice.
- * @param {function} [options.onSucceedCallbacks] - An optional async callback to run when a transaction succeeds.
- * @returns {StoreSlice<IInitializeTxTrackingStore<TR, T>>} A Zustand store slice.
+ * 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.
+ *
+ * @template T The specific transaction type.
+ * @param options Configuration for the store slice.
+ * @returns A Zustand store slice implementing `IInitializeTxTrackingStore`.
  */
-declare function initializeTxTrackingStore<TR, T extends Transaction<TR>, A>({ onSucceedCallbacks, }: {
-    onSucceedCallbacks?: (tx: T) => Promise<void> | void;
-}): StoreSlice<IInitializeTxTrackingStore<TR, T, A>>;
+declare function initializeTxTrackingStore<T extends Transaction>(): StoreSlice<IInitializeTxTrackingStore<T>>;
 
 /**
  * @file This file contains selector functions for deriving state from the transaction tracking store.
@@ -303,79 +339,70 @@ declare function initializeTxTrackingStore<TR, T extends Transaction<TR>, A>({ o
 
 /**
  * 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 transaction pool from the store.
+ * @param {TransactionPool<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[];
+declare const selectAllTransactions: <T extends Transaction>(transactionsPool: TransactionPool<T>) => T[];
 /**
  * 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 transaction pool from the store.
+ * @param {TransactionPool<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[];
+declare const selectPendingTransactions: <T extends Transaction>(transactionsPool: TransactionPool<T>) => T[];
 /**
  * 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 transaction pool from the store.
+ * @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.
  */
-declare const selectTxByKey: <TR, T extends Transaction<TR>>(transactionsPool: TransactionPool<TR, T>, key: string) => T | undefined;
+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 TR - The type of the tracker identifier.
  * @template T - The transaction type.
- * @param {TransactionPool<TR, T>} transactionsPool - The entire transaction pool from the store.
+ * @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.
  */
-declare const selectAllTransactionsByActiveWallet: <TR, T extends Transaction<TR>>(transactionsPool: TransactionPool<TR, T>, from: string) => T[];
+declare const selectAllTransactionsByActiveWallet: <T extends Transaction>(transactionsPool: TransactionPool<T>, from: string) => T[];
 /**
  * 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 transaction pool from the store.
+ * @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.
  */
-declare const selectPendingTransactionsByActiveWallet: <TR, T extends Transaction<TR>>(transactionsPool: TransactionPool<TR, T>, from: string) => T[];
+declare const selectPendingTransactionsByActiveWallet: <T extends Transaction>(transactionsPool: TransactionPool<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.
+ * 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.
  *
- * @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.
+ * @template T The specific transaction type, extending the base `Transaction`.
  *
- * @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.
+ * @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.
  */
-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>>, "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;
+declare function createPulsarStore<T extends Transaction>({ adapter, ...options }: {
+    adapter: TxAdapter<T> | TxAdapter<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;
+    setState(state: ITxTrackingStore<T> | ((state: ITxTrackingStore<T>) => ITxTrackingStore<T>), replace: true): unknown;
     persist: {
-        setOptions: (options: Partial<PersistOptions<ITxTrackingStore<TR, T, A>, ITxTrackingStore<TR, T, A>, unknown>>) => void;
+        setOptions: (options: Partial<PersistOptions<ITxTrackingStore<T>, ITxTrackingStore<T>, 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>, unknown>>;
+        onHydrate: (fn: (state: ITxTrackingStore<T>) => void) => () => void;
+        onFinishHydration: (fn: (state: ITxTrackingStore<T>) => void) => () => void;
+        getOptions: () => Partial<PersistOptions<ITxTrackingStore<T>, ITxTrackingStore<T>, unknown>>;
     };
 };
 
@@ -424,8 +451,8 @@ declare const createBoundedUseStore: <S extends StoreApi<unknown>>(store: S) =>
 /**
  * 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.
+ * @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. */
@@ -445,13 +472,12 @@ type PollingFetcherParams<R, T> = {
 };
 /**
  * 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.
- * @template TR - The type of the tracker identifier.
+ * @template R The expected type of the successful API response.
+ * @template T The type of the transaction object.
  */
-type PollingTrackerConfig<R, T, TR> = {
+type PollingTrackerConfig<R, T extends Transaction> = {
     /** The transaction object to be tracked. It must include `txKey` and `pending` status. */
-    tx: T & Pick<Transaction<TR>, 'txKey' | 'pending'>;
+    tx: T & Pick<Transaction, '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. */
@@ -480,10 +506,9 @@ type PollingTrackerConfig<R, T, TR> = {
  *
  * @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 {PollingTrackerConfig<R, T, TR>} config - The configuration for the tracker.
+ * @param {PollingTrackerConfig<R, T>} config - The configuration for the tracker.
  */
-declare function initializePollingTracker<R, T, TR>(config: PollingTrackerConfig<R, T, TR>): void;
+declare function initializePollingTracker<R, T extends Transaction>(config: PollingTrackerConfig<R, T>): void;
 
 /**
  * @file This file contains a utility function for selecting a specific transaction adapter from a list.
@@ -497,19 +522,17 @@ declare function initializePollingTracker<R, T, TR>(config: PollingTrackerConfig
  * 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.
+ * @param {TxAdapter<T> | TxAdapter<T>[]} params.adapter - Adapter or an array of adapters for different chains or transaction types.
  *
- * @returns {TxAdapter<TR, T, A> | undefined} The found transaction adapter, the fallback adapter, or undefined if the adapters array is empty.
+ * @returns {TxAdapter<T> | 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, }: {
+declare const selectAdapterByKey: <T extends Transaction>({ adapterKey, adapter, }: {
     adapterKey: TransactionAdapter;
-    adapters: TxAdapter<TR, T, A>[];
-}) => TxAdapter<TR, T, A> | undefined;
+    adapter: TxAdapter<T> | TxAdapter<T>[];
+}) => TxAdapter<T> | 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 TxAdapter, createBoundedUseStore, createPulsarStore, initializePollingTracker, initializeTxTrackingStore, selectAdapterByKey, selectAllTransactions, selectAllTransactionsByActiveWallet, selectPendingTransactions, selectPendingTransactionsByActiveWallet, selectTxByKey };
+export { type ActionTxKey, type BaseTransaction, type EvmTransaction, type GelatoTxKey, type IInitializeTxTrackingStore, type ITxTrackingStore, type InitialTransaction, type InitialTransactionParams, type PollingTrackerConfig, type SolanaTransaction, type StarknetTransaction, type StoreSlice, type Transaction, TransactionAdapter, type TransactionPool, TransactionStatus, TransactionTracker, type TxAdapter, createBoundedUseStore, createPulsarStore, initializePollingTracker, initializeTxTrackingStore, selectAdapterByKey, selectAllTransactions, selectAllTransactionsByActiveWallet, selectPendingTransactions, selectPendingTransactionsByActiveWallet, selectTxByKey };