@etherkit/viem-tx-tracker 0.0.2

package/dist/types.d.ts

@@ -0,0 +1,189 @@
+import type { Abi, Account, Address, Chain, ContractFunctionArgs, ContractFunctionName, Hash, PublicClient, SendTransactionParameters, TransactionReceipt, TransactionSerialized, Transport, WalletClient, WriteContractParameters } from 'viem';
+/**
+ * Block tags that can be used to specify nonce fetching strategy
+ */
+export type BlockTag = 'latest' | 'pending' | 'earliest' | 'safe' | 'finalized';
+/**
+ * Nonce can be:
+ * - number: exact nonce to use
+ * - BlockTag: fetch nonce using this block tag
+ * - undefined: fetch nonce using 'pending' (default)
+ */
+export type NonceOption = number | BlockTag;
+/**
+ * Expected event for success detection.
+ * Even if tx hash changes due to replacement, we can detect success by watching for this event.
+ */
+export interface ExpectedEvent {
+    address: Address;
+    eventName: string;
+    args?: Record<string, unknown>;
+}
+/**
+ * Metadata that can be attached to a transaction for tracking purposes.
+ * All fields are optional and extensible.
+ */
+export interface TransactionMetadata {
+    /**
+     * Optional custom ID - if provided, used instead of tx hash for tracking.
+     * Useful for correlating transactions with business logic (e.g., order IDs).
+     */
+    id?: string;
+    /**
+     * Human-readable title for the transaction.
+     */
+    title?: string;
+    /**
+     * Detailed description of what the transaction does.
+     */
+    description?: string;
+    /**
+     * Expected event signature/filter for success detection.
+     * Even if tx hash changes due to replacement, we can detect success by watching for this event.
+     */
+    expectedEvent?: ExpectedEvent;
+    /**
+     * Extensible: user can add any additional fields.
+     */
+    [key: string]: unknown;
+}
+/**
+ * A tracked transaction record with all relevant information for tracking.
+ */
+export interface TrackedTransaction<M extends TransactionMetadata = TransactionMetadata> {
+    /**
+     * Tracking ID - either metadata.id or auto-generated UUID.
+     */
+    trackingId: string;
+    /**
+     * The transaction hash once known.
+     */
+    txHash: Hash;
+    /**
+     * Sender address.
+     */
+    from: Address;
+    /**
+     * Transaction nonce (actual nonce from fetched tx, or intended if fetch failed).
+     */
+    nonce: number;
+    /**
+     * Chain ID.
+     */
+    chainId: number;
+    /**
+     * The full metadata provided by the caller.
+     */
+    metadata: M;
+    /**
+     * Timestamp when the transaction was initiated (ms since epoch).
+     */
+    initiatedAt: number;
+    /**
+     * The original transaction request data.
+     */
+    request: unknown;
+}
+/**
+ * Extended WriteContractParameters with optional metadata and flexible nonce.
+ */
+export type TrackedWriteContractParameters<TAbi extends Abi | readonly unknown[] = Abi, TFunctionName extends ContractFunctionName<TAbi, 'nonpayable' | 'payable'> = ContractFunctionName<TAbi, 'nonpayable' | 'payable'>, TArgs extends ContractFunctionArgs<TAbi, 'nonpayable' | 'payable', TFunctionName> = ContractFunctionArgs<TAbi, 'nonpayable' | 'payable', TFunctionName>, TChain extends Chain | undefined = Chain | undefined, TAccount extends Account | undefined = Account | undefined, TChainOverride extends Chain | undefined = Chain | undefined> = Omit<WriteContractParameters<TAbi, TFunctionName, TArgs, TChain, TAccount, TChainOverride>, 'nonce'> & {
+    /**
+     * Optional metadata to attach to the transaction for tracking.
+     */
+    metadata?: TransactionMetadata;
+    /**
+     * Nonce option:
+     * - number: exact nonce to use
+     * - BlockTag ('latest', 'pending', etc.): fetch nonce using this block tag
+     * - undefined: fetch nonce using 'pending' (default)
+     */
+    nonce?: NonceOption;
+};
+/**
+ * Extended SendTransactionParameters with optional metadata and flexible nonce.
+ */
+export type TrackedSendTransactionParameters<TChain extends Chain | undefined = Chain | undefined, TAccount extends Account | undefined = Account | undefined, TChainOverride extends Chain | undefined = Chain | undefined> = Omit<SendTransactionParameters<TChain, TAccount, TChainOverride>, 'nonce'> & {
+    /**
+     * Optional metadata to attach to the transaction for tracking.
+     */
+    metadata?: TransactionMetadata;
+    /**
+     * Nonce option:
+     * - number: exact nonce to use
+     * - BlockTag ('latest', 'pending', etc.): fetch nonce using this block tag
+     * - undefined: fetch nonce using 'pending' (default)
+     */
+    nonce?: NonceOption;
+};
+/**
+ * Parameters for sendRawTransaction with optional metadata.
+ * The serialized transaction already contains from/nonce which will be decoded.
+ */
+export interface TrackedRawTransactionParameters {
+    /**
+     * The RLP-encoded signed transaction.
+     */
+    serializedTransaction: TransactionSerialized;
+    /**
+     * Optional metadata to attach to the transaction for tracking.
+     */
+    metadata?: TransactionMetadata;
+}
+/**
+ * A wallet client wrapper that tracks transactions with metadata.
+ */
+export interface TrackedWalletClient<TTransport extends Transport = Transport, TChain extends Chain | undefined = Chain | undefined, TAccount extends Account | undefined = Account | undefined> {
+    /**
+     * The underlying wallet client.
+     */
+    readonly walletClient: WalletClient<TTransport, TChain, TAccount>;
+    /**
+     * The public client used for nonce fetching and tx verification.
+     */
+    readonly publicClient: PublicClient;
+    /**
+     * Write to a contract with optional metadata tracking.
+     * Returns immediately after broadcast with the transaction hash.
+     */
+    writeContract<const TAbi extends Abi | readonly unknown[], TFunctionName extends ContractFunctionName<TAbi, 'nonpayable' | 'payable'>, TArgs extends ContractFunctionArgs<TAbi, 'nonpayable' | 'payable', TFunctionName>, TChainOverride extends Chain | undefined = undefined>(args: TrackedWriteContractParameters<TAbi, TFunctionName, TArgs, TChain, TAccount, TChainOverride>): Promise<Hash>;
+    /**
+     * Send a transaction with optional metadata tracking.
+     * Returns immediately after broadcast with the transaction hash.
+     */
+    sendTransaction<TChainOverride extends Chain | undefined = undefined>(args: TrackedSendTransactionParameters<TChain, TAccount, TChainOverride>): Promise<Hash>;
+    /**
+     * Send a signed raw transaction with optional metadata tracking.
+     * The nonce and from address are decoded from the serialized transaction.
+     * Returns immediately after broadcast with the transaction hash.
+     */
+    sendRawTransaction(args: TrackedRawTransactionParameters): Promise<Hash>;
+    /**
+     * Write to a contract and wait for confirmation.
+     * Returns the transaction receipt after the transaction is confirmed.
+     */
+    writeContractSync<const TAbi extends Abi | readonly unknown[], TFunctionName extends ContractFunctionName<TAbi, 'nonpayable' | 'payable'>, TArgs extends ContractFunctionArgs<TAbi, 'nonpayable' | 'payable', TFunctionName>, TChainOverride extends Chain | undefined = undefined>(args: TrackedWriteContractParameters<TAbi, TFunctionName, TArgs, TChain, TAccount, TChainOverride>): Promise<TransactionReceipt>;
+    /**
+     * Send a transaction and wait for confirmation.
+     * Returns the transaction receipt after the transaction is confirmed.
+     */
+    sendTransactionSync<TChainOverride extends Chain | undefined = undefined>(args: TrackedSendTransactionParameters<TChain, TAccount, TChainOverride>): Promise<TransactionReceipt>;
+    /**
+     * Send a signed raw transaction and wait for confirmation.
+     * Returns the transaction receipt after the transaction is confirmed.
+     */
+    sendRawTransactionSync(args: TrackedRawTransactionParameters): Promise<TransactionReceipt>;
+    /**
+     * Subscribe to transaction broadcast events.
+     * Called immediately after a transaction is successfully broadcast.
+     * @param listener - Callback function receiving TrackedTransaction
+     * @returns Unsubscribe function
+     */
+    onTransactionBroadcasted(listener: (event: TrackedTransaction) => void): () => void;
+    /**
+     * Unsubscribe from transaction broadcast events.
+     * @param listener - The same listener function passed to onTransactionBroadcasted
+     */
+    offTransactionBroadcasted(listener: (event: TrackedTransaction) => void): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,GAAG,EACH,OAAO,EACP,OAAO,EACP,KAAK,EACL,oBAAoB,EACpB,oBAAoB,EACpB,IAAI,EACJ,YAAY,EACZ,yBAAyB,EACzB,kBAAkB,EAClB,qBAAqB,EACrB,SAAS,EACT,YAAY,EACZ,uBAAuB,EACvB,MAAM,MAAM,CAAC;AAEd;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,MAAM,GAAG,WAAW,CAAC;AAEhF;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE5C;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IACnC;;;OAGG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IAEZ;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAE9B;;OAEG;IACH,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAClC,CAAC,SAAS,mBAAmB,GAAG,mBAAmB;IAEnD;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,MAAM,EAAE,IAAI,CAAC;IAEb;;OAEG;IACH,IAAI,EAAE,OAAO,CAAC;IAEd;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,QAAQ,EAAE,CAAC,CAAC;IAEZ;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,MAAM,8BAA8B,CACzC,IAAI,SAAS,GAAG,GAAG,SAAS,OAAO,EAAE,GAAG,GAAG,EAC3C,aAAa,SAAS,oBAAoB,CAAC,IAAI,EAAE,YAAY,GAAG,SAAS,CAAC,GACzE,oBAAoB,CAAC,IAAI,EAAE,YAAY,GAAG,SAAS,CAAC,EACrD,KAAK,SAAS,oBAAoB,CACjC,IAAI,EACJ,YAAY,GAAG,SAAS,EACxB,aAAa,CACb,GAAG,oBAAoB,CAAC,IAAI,EAAE,YAAY,GAAG,SAAS,EAAE,aAAa,CAAC,EACvE,MAAM,SAAS,KAAK,GAAG,SAAS,GAAG,KAAK,GAAG,SAAS,EACpD,QAAQ,SAAS,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,EAC1D,cAAc,SAAS,KAAK,GAAG,SAAS,GAAG,KAAK,GAAG,SAAS,IACzD,IAAI,CACP,uBAAuB,CACtB,IAAI,EACJ,aAAa,EACb,KAAK,EACL,MAAM,EACN,QAAQ,EACR,cAAc,CACd,EACD,OAAO,CACP,GAAG;IACH;;OAEG;IACH,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAE/B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,WAAW,CAAC;CACpB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gCAAgC,CAC3C,MAAM,SAAS,KAAK,GAAG,SAAS,GAAG,KAAK,GAAG,SAAS,EACpD,QAAQ,SAAS,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,EAC1D,cAAc,SAAS,KAAK,GAAG,SAAS,GAAG,KAAK,GAAG,SAAS,IACzD,IAAI,CACP,yBAAyB,CAAC,MAAM,EAAE,QAAQ,EAAE,cAAc,CAAC,EAC3D,OAAO,CACP,GAAG;IACH;;OAEG;IACH,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAE/B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,WAAW,CAAC;CACpB,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,+BAA+B;IAC/C;;OAEG;IACH,qBAAqB,EAAE,qBAAqB,CAAC;IAE7C;;OAEG;IACH,QAAQ,CAAC,EAAE,mBAAmB,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB,CACnC,UAAU,SAAS,SAAS,GAAG,SAAS,EACxC,MAAM,SAAS,KAAK,GAAG,SAAS,GAAG,KAAK,GAAG,SAAS,EACpD,QAAQ,SAAS,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS;IAE1D;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;IAElE;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IAMpC;;;OAGG;IACH,aAAa,CACZ,KAAK,CAAC,IAAI,SAAS,GAAG,GAAG,SAAS,OAAO,EAAE,EAC3C,aAAa,SAAS,oBAAoB,CAAC,IAAI,EAAE,YAAY,GAAG,SAAS,CAAC,EAC1E,KAAK,SAAS,oBAAoB,CACjC,IAAI,EACJ,YAAY,GAAG,SAAS,EACxB,aAAa,CACb,EACD,cAAc,SAAS,KAAK,GAAG,SAAS,GAAG,SAAS,EAEpD,IAAI,EAAE,8BAA8B,CACnC,IAAI,EACJ,aAAa,EACb,KAAK,EACL,MAAM,EACN,QAAQ,EACR,cAAc,CACd,GACC,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;OAGG;IACH,eAAe,CAAC,cAAc,SAAS,KAAK,GAAG,SAAS,GAAG,SAAS,EACnE,IAAI,EAAE,gCAAgC,CAAC,MAAM,EAAE,QAAQ,EAAE,cAAc,CAAC,GACtE,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;OAIG;IACH,kBAAkB,CAAC,IAAI,EAAE,+BAA+B,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAMzE;;;OAGG;IACH,iBAAiB,CAChB,KAAK,CAAC,IAAI,SAAS,GAAG,GAAG,SAAS,OAAO,EAAE,EAC3C,aAAa,SAAS,oBAAoB,CAAC,IAAI,EAAE,YAAY,GAAG,SAAS,CAAC,EAC1E,KAAK,SAAS,oBAAoB,CACjC,IAAI,EACJ,YAAY,GAAG,SAAS,EACxB,aAAa,CACb,EACD,cAAc,SAAS,KAAK,GAAG,SAAS,GAAG,SAAS,EAEpD,IAAI,EAAE,8BAA8B,CACnC,IAAI,EACJ,aAAa,EACb,KAAK,EACL,MAAM,EACN,QAAQ,EACR,cAAc,CACd,GACC,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAE/B;;;OAGG;IACH,mBAAmB,CAAC,cAAc,SAAS,KAAK,GAAG,SAAS,GAAG,SAAS,EACvE,IAAI,EAAE,gCAAgC,CAAC,MAAM,EAAE,QAAQ,EAAE,cAAc,CAAC,GACtE,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAE/B;;;OAGG;IACH,sBAAsB,CACrB,IAAI,EAAE,+BAA+B,GACnC,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAM/B;;;;;OAKG;IACH,wBAAwB,CACvB,QAAQ,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,GAC3C,MAAM,IAAI,CAAC;IAEd;;;OAGG;IACH,yBAAyB,CACxB,QAAQ,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,GAC3C,IAAI,CAAC;CACR"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@etherkit/viem-tx-tracker",
+  "version": "0.0.2",
+  "description": "",
+  "license": "MIT",
+  "author": "Ronan Sandford",
+  "homepage": "https://github.com/wighawag/etherkit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wighawag/etherkit.git",
+    "directory": "packages/viem-tx-tracker"
+  },
+  "bugs": {
+    "url": "https://github.com/wighawag/etherkit/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "radiate": "^0.3.2"
+  },
+  "peerDependencies": {
+    "viem": "^2.46.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.0",
+    "as-soon": "^0.1.5",
+    "prettier": "^3.8.0",
+    "prool": "^0.2.2",
+    "typescript": "^5.3.3",
+    "viem": "^2.46.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "build": "tsc",
+    "dev": "as-soon -w src pnpm build",
+    "typecheck": "tsc --noEmit -p tsconfig-check.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  }
+}