@etherkit/viem-tx-tracker 0.0.9 → 0.2.0

package/README.md

@@ -1,322 +1,296 @@
-# @etherkit/tx-observer
+# @etherkit/viem-tx-tracker
 
-A TypeScript library for monitoring Ethereum onchain operations containing multiple transactions, with automatic status merging and finality tracking.
+A thin wrapper around a viem `WalletClient` that records what you sent, so you can track it afterwards.
 
 ## Overview
 
-The Operation Processor tracks **operations** - logical groupings of transactions that belong together. This is useful when:
+viem gives you a transaction hash. That is rarely enough: to show a meaningful pending state, to resume tracking after a reload, or to replace a stuck transaction, you also need to know what the transaction was for, who sent it, with which nonce, and through which signing route.
 
-- **Gas price bumping**: Multiple transactions with the same nonce but different gas prices
-- **Sequential retries**: Transactions with different nonces for the same logical action
-- **Multi-step operations**: Related transactions that form a single user action
+This package wraps a `WalletClient` with the same method names (`sendTransaction`, `writeContract`, their `*Sync` variants, `sendRawTransaction`) and emits an event for every broadcast, carrying:
 
-The processor monitors all transactions in an operation and computes a merged status, emitting events when the operation status changes.
+- the facts observed at dispatch: `hash`, `from`, `nonce`, `to`, `value`, `data`, `broadcastTimestampMs`, the intended gas parameters and inferred transaction type
+- `metadata`: whatever your application says the transaction means, in your own type
+- `source`: an opaque marker of which signing route produced it, in your own type
+- `correlation`: an opaque marker of which caller-side request a send answers, supplied per call
+
+It also resolves the nonce for you (`pending` by default) and, once broadcast, reads the transaction back from the chain and emits a second event with the values that were actually recorded.
+
+The tracker never interprets `metadata`, `source` or `correlation`. It carries them.
 
 ## Installation
 
 ```bash
-npm install @etherkit/tx-observer
+npm install @etherkit/viem-tx-tracker viem
 ```
 
-## Quick Start
+`viem` (`^2.46.3`) is a peer dependency.
+
+## Quick start
 
 ```typescript
-import { createTransactionObserver } from '@etherkit/tx-observer';
-import type { OnchainOperation, BroadcastedTransaction, OnchainOperationEvent } from '@etherkit/tx-observer';
-
-// Initialize the processor
-const processor = createTransactionObserver({
-  finality: 12, // blocks until considered final
-  throttle: 5000, // optional: throttle process() calls
-  provider: window.ethereum,
-});
+import {createPublicClient, createWalletClient, custom, http, parseEther} from 'viem';
+import {mainnet} from 'viem/chains';
+import {createTrackedWalletClient} from '@etherkit/viem-tx-tracker';
 
-// Create an operation with one or more transactions
-const operation: OnchainOperation = {
-  transactions: [
-    {
-      hash: '0xabc...',
-      from: '0x123...',
-      nonce: 5,
-      broadcastTimestamp: Date.now(),
-    },
-  ],,
-};
+// What a transaction means, in your own words
+type MyMetadata = {id: string; title: string};
+
+const walletClient = createWalletClient({chain: mainnet, transport: custom(window.ethereum)});
+const publicClient = createPublicClient({chain: mainnet, transport: http()});
 
-// Add the operation to tracking (ID is passed separately)
-processor.add('my-operation-1', operation);
-
-// Listen for operation status changes (for UI updates)
-processor.onOperationStatusUpdated((event: OnchainOperationEvent) => {
-  console.log(`Operation ${event.id}: ${event.operation.state?.inclusion}`);
-  
-  if (event.operation.state?.inclusion === 'Included') {
-    const winningTx = event.operation.transactions[event.operation.state.txIndex];
-    console.log(`Status: ${event.operation.state.status}`);
-    console.log(`Winning TX: ${winningTx.hash}`);
-  }
-  
-  return () => {}; // cleanup function
+const tracked = createTrackedWalletClient<MyMetadata>().using(walletClient, publicClient);
+
+tracked.on('transaction:broadcasted', (tx) => {
+  // Fires immediately. Save this: it is everything you need to resume tracking.
+  save(tx.hash, tx);
 });
 
-// Listen for any transaction changes (for persistence)
-processor.onOperationUpdated((event: OnchainOperationEvent) => {
-  console.log(`Operation ${event.id} updated, save to storage`);
-  return () => {}; // cleanup function
+tracked.on('transaction:known', (tx) => {
+  // Fires once the transaction has been read back from the chain,
+  // with the values the chain actually recorded.
+  save(tx.hash, tx);
 });
 
-// Process periodically (check for status updates)
-setInterval(() => processor.process(), 5000);
+const hash = await tracked.sendTransaction({
+  to: '0x...',
+  value: parseEther('0.1'),
+  metadata: {id: 'deposit-1', title: 'Deposit'},
+});
 ```
 
-## API Reference
+The client is built in two steps. `createTrackedWalletClient<TMetadata>(options?)` fixes the types and the options, `.using(walletClient, publicClient)` binds the clients. This is what lets `TMetadata` be explicit while the transport, chain and account types stay inferred from your wallet client.
 
-### `createTransactionObserver(config)`
+## Metadata
 
-Creates a new operation processor instance.
-
-**Config:**
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `finality` | `number` | Number of blocks until a transaction is considered final |
-| `throttle` | `number?` | Optional: throttle interval in ms for `process()` calls |
-| `provider` | `EIP1193ProviderWithoutEvents?` | Optional Ethereum provider (can be set later) |
-
-**Returns:** Processor instance with the following methods:
-
-#### `add(id: string, operation: OnchainOperation)`
-
-Add an operation to track. If an operation with the same ID already exists, the transactions are merged into the existing operation.
+`TMetadata` is yours and it is mandatory to declare. Whether the `metadata` argument is required follows from the type:
 
 ```typescript
-// Add new operation
-processor.add('my-operation-1', operation);
+// metadata is required on every call
+createTrackedWalletClient<{id: string}>();
 
-// Add another transaction to existing operation (same ID merges)
-processor.add('my-operation-1', {
-  transactions: [bumpedTx], // New tx with higher gas
-  // ... state fields
-});
-// and in case where you track the txs already you can simply re-add
-operation.transactions.push(bumpedTx);
-processor.add('my-operation-1', operation);
+// metadata may be omitted
+createTrackedWalletClient<{id: string} | undefined>();
 ```
 
-#### `addMultiple(operations: {[id: string]: OnchainOperation})`
+### Auto-populated metadata
 
-Add multiple operations at once.
+With `populateMetadata: true`, `writeContract` and `writeContractSync` fill in the call they made:
 
 ```typescript
-processor.addMultiple({
-  'operation-1': operation1,
-  'operation-2': operation2,
-});
-```
-
-#### `remove(operationId: string)`
+import type {PopulatedMetadata} from '@etherkit/viem-tx-tracker';
 
-Remove an operation by ID and stop tracking it.
+const tracked = createTrackedWalletClient({populateMetadata: true}).using(
+  walletClient,
+  publicClient,
+);
 
-```typescript
-processor.remove('my-operation-1');
+await tracked.writeContract({address, abi, functionName: 'transfer', args: [to, amount]});
+// metadata: {type: 'functionCall', functionName: 'transfer', args: [to, amount]}
 ```
 
-#### `clear()`
-
-Remove all operations.
+`type`, `functionName` and `args` are then owned by the tracker: passing any of them yourself throws. You can still extend the rest of the type, in which case your own fields stay required:
 
 ```typescript
-processor.clear();
-```
-
-#### `process(): Promise<void>`
+type MyMetadata = FunctionCallMetadata & {purpose: string};
 
-Check and update the status of all tracked operations. This queries the Ethereum provider for transaction receipts and updates statuses accordingly.
+const tracked = createTrackedWalletClient<MyMetadata>({populateMetadata: true}).using(
+  walletClient,
+  publicClient,
+);
 
-```typescript
-await processor.process();
+await tracked.writeContract({address, abi, functionName: 'transfer', args, metadata: {purpose: 'checkout'}});
 ```
 
-#### `setProvider(provider: EIP1193Provider)`
+`sendTransaction` and `sendRawTransaction` have no contract call to read, so they still take metadata in full. The default `PopulatedMetadata` type includes an `UnknownTypeMetadata` variant for them.
 
-Update the Ethereum provider.
+## Source: which route signed
 
-```typescript
-processor.setProvider(newProvider);
-```
+An application can have several ways to send: the wallet the user is connected with, a local signer whose key it holds, a separate wallet connection used only to pay. When one of those transactions gets stuck, replacing or cancelling it means reactivating the route that signed it and reusing that nonce. `from` is not enough to find that route again: it may be dormant, and a locked wallet will not tell you which addresses it holds.
 
-#### `onOperationUpdated(listener): void`
-
-Subscribe to any operation changes (when any transaction in the operation changes). Useful for persistence.
+Declare a `TSource` and the tracker will stamp it on every transaction:
 
 ```typescript
-processor.onOperationUpdated((event: OnchainOperationEvent) => {
-  console.log(`Operation ${event.id} changed:`, event.operation);
-  return () => {}; // cleanup
+type MySource = 'connected-wallet' | 'local-signer' | 'payer-wallet';
+
+const tracked = createTrackedWalletClient<MyMetadata, MySource>({
+  source: 'local-signer',
+}).using(walletClient, publicClient);
+
+tracked.on('transaction:broadcasted', (tx) => {
+  tx.source; // 'local-signer'
 });
 ```
 
-#### `offOperationUpdated(listener): void`
+Points worth knowing:
+
+- It is supplied once, at construction, and never per call. The source is a property of the route, not of an individual transaction, and a per-call argument is something a call site can forget or state wrongly.
+- It can be a thunk, `() => TSource`, evaluated at every broadcast, in the same step that stamps `from`, `nonce` and `broadcastTimestampMs`. Use this when one client can serve different wallets or accounts over its life: a value captured at construction would be silently wrong in exactly that case.
+- Declaring a `TSource` that excludes `undefined` makes the option mandatory, so a route cannot be built without saying what it is. `TSource` must always be written explicitly: it is never inferred from the option value.
+- It defaults to `undefined`, in which case `source` is simply `undefined` on every transaction.
+- The tracker never inspects it. There is no wallet, EIP-6963 or connection-library knowledge in this package: the union is yours.
+
+## Correlation: which request this send answers
 
-Unsubscribe from operation changes.
+A send is asynchronous in a way that matters: `transaction:broadcasted` fires after the wallet round trip, which includes a popup the user may read for a while, during which the page stays interactive and can issue further sends. So the handler has to work out which of its own in-flight requests the event belongs to.
 
-#### `onOperationStatusUpdated(listener): void`
+`(from, nonce)` cannot answer that. Replacing or cancelling a stuck transaction deliberately creates a second operation at the *same* nonce, so two concurrent replacements collide and the handler silently attaches a broadcast to the wrong one.
 
-Subscribe to operation status changes only (when the merged status changes). Useful for UI updates.
+Pass a `correlation` on the call and read it off the event:
 
 ```typescript
-processor.onOperationStatusUpdated((event: OnchainOperationEvent) => {
-  console.log(`Operation ${event.id} status:`, event.operation.state?.inclusion);
-  return () => {}; // cleanup
+const correlation = crypto.randomUUID();
+
+tracked.on('transaction:broadcasted', (tx) => {
+  // route this broadcast to the request that issued it, not to a (from, nonce) guess
+  if (tx.correlation) pendingRequests.get(tx.correlation)?.resolve(tx);
 });
+
+await tracked.sendTransaction({to, value, metadata: {id: 'deposit-1'}, correlation});
 ```
 
-#### `offOperationStatusUpdated(listener): void`
+It is a sibling of `metadata` and `nonce` on every tracked send, never nested inside metadata. Three fields are now carried on a tracked transaction and they answer three different questions:
 
-Unsubscribe from operation status changes.
+| Field | Question it answers | Supplied | Lifetime |
+|-------|---------------------|----------|----------|
+| `metadata` | What the application says the transaction **means** | Per call, in your own type | Persisted by consumers |
+| `source` | **Which signing route** produced it, a fact observed at dispatch | Once, at client construction, in your own type | Persisted by consumers |
+| `correlation` | Which **caller-side request** this send answers | Per call, as a `string` | Ephemeral plumbing, not persisted |
 
-## Types
+Points worth knowing:
 
-### `BroadcastedTransaction`
+- It is **not intended to be persisted**. That is the whole reason it is not part of `metadata`: metadata is what consumers store, so plumbing written there ends up in every stored record forever.
+- It is **not an identity** for the transaction. `hash` is that.
+- It is **meaningless outside the session that issued the send**. A value rehydrated from storage carries no information, because the requests it referred to are gone.
+- It is typed `correlation?: string`, deliberately, rather than a generic type parameter: identity is all a consumer needs to route an event, and the value is not `unknown`, which would invite smuggling structured data into a field the tracker will never interpret.
+- The tracker never inspects, interprets, validates or defaults it, exactly as with `source`. It is also removed from the arguments before they reach viem, so the wallet never sees an unrecognised field.
+- It is optional everywhere. Omit it and `correlation` is simply `undefined` on the emitted transaction.
 
-Represents a single broadcasted transaction.
+## Nonces
 
-```typescript
-type BroadcastedTransaction = {
-  readonly hash: `0x${string}`;
-  readonly from: `0x${string}`;
-  nonce?: number;
-  readonly broadcastTimestamp: number;
-  state?: BroadcastedTransactionState;
-};
+Every method takes `nonce` as either an exact number or a block tag:
 
-type BroadcastedTransactionState =
-  | { inclusion: 'InMemPool' | 'NotFound'; final: undefined; status: undefined }
-  | { inclusion: 'Dropped'; final?: number; status: undefined }
-  | { inclusion: 'Included'; status: 'Failure' | 'Success'; final?: number };
+```typescript
+await tracked.sendTransaction({to, value, nonce: 42});        // exact
+await tracked.sendTransaction({to, value, nonce: 'latest'});  // fetch with this block tag
+await tracked.sendTransaction({to, value});                   // fetch with 'pending' (default)
 ```
 
-### `OnchainOperationStatus`
+The resolved nonce is injected into the request and recorded on the emitted transaction, so a replacement can reuse it.
 
-The merged status of all transactions in an operation.
+## Events
+
+| Event | Payload | When |
+|-------|---------|------|
+| `transaction:broadcasted` | `TrackedTransaction<TMetadata, TSource>` | Immediately after the broadcast succeeds |
+| `transaction:known` | `KnownTrackedTransaction<TMetadata, TSource>` | Once the values are known to be final rather than intended |
 
 ```typescript
-type OnchainOperationStatus =
-  | { inclusion: 'InMemPool' | 'NotFound'; final: undefined; status: undefined; txIndex: undefined }
-  | { inclusion: 'Dropped'; final?: number; status: undefined; txIndex: undefined }
-  | { inclusion: 'Included'; status: 'Failure' | 'Success'; final?: number; txIndex: number };
+const unsubscribe = tracked.on('transaction:broadcasted', listener);
+unsubscribe();
+// or
+tracked.off('transaction:broadcasted', listener);
 ```
 
-- `txIndex`: Index into `transactions[]` for the "winning" transaction (first success, or first failure if all failed)
-- Get the winning tx hash via: `operation.transactions[operation.state.txIndex].hash`
+`transaction:known` says the values are the final ones, not the ones you intended. It deliberately names that promise rather than the mechanism, because the mechanism differs: for a normal send the transaction is read back from the chain, and for `sendRawTransaction` the values are parsed from the signed payload, which needs no network call at all. Both produce final values, so both emit the event, and you can persist on it alone.
 
-### `OnchainOperation`
+It does not say the transaction was mined. It fires while the transaction is still in the mempool, so it is not a substitute for waiting on a receipt.
 
-An operation containing multiple transactions.
+The two paths differ in reliability, which the name cannot express, so it is worth stating plainly:
 
-```typescript
-type OnchainOperation = {
-  transactions: BroadcastedTransaction[];
-  state?: OnchainOperationStatus;
-};
-```
+- **Normal sends**: best effort. If the read fails (not in the mempool yet, network trouble) the event simply never fires and a warning is logged.
+- **Raw sends**: always fires, immediately, since nothing can fail. The same object is delivered to `transaction:broadcasted` first, so a handler subscribed to both sees that transaction twice.
+
+Treat `transaction:broadcasted` as the event you must handle, and `transaction:known` as a refinement that is usually but not always delivered.
+
+## The transaction shape
+
+A tracked transaction is discriminated by `known`:
 
-### `OnchainOperationEvent`
+- `known: false` means the values are what was intended and provided. The wallet may still change them, typically gas and occasionally the nonce.
+- `known: true` means the values are confirmed, read from the chain or parsed from a signed transaction.
 
-Event payload emitted by listeners, includes both the operation ID and operation data.
+Both share the same field paths, so `tx.hash`, `tx.metadata`, `tx.source`, `tx.gasParameters` are always reachable:
 
 ```typescript
-type OnchainOperationEvent = {
-  id: string;
-  operation: OnchainOperation;
+type CommonFields = {
+  readonly hash: `0x${string}`;
+  readonly from: `0x${string}`;
+  readonly nonce: number;
+  readonly to: `0x${string}` | null;
+  readonly value: bigint;
+  readonly data: `0x${string}`;
+  readonly broadcastTimestampMs: number;
+  readonly metadata: TMetadata;
+  readonly source: TSource;
+  readonly correlation?: string;
 };
 ```
 
-## Status States
+On top of that, a second discriminant, `txType`, carries the gas parameters that belong to that transaction type:
 
-| Inclusion | Description |
-|-----------|-------------|
-| `Broadcasted` | At least one transaction is visible in the mempool |
-| `NotFound` | No transactions visible in mempool (may be temporary) |
-| `Dropped` | All transactions dropped (nonce was used by external tx) |
-| `Included` | At least one transaction was included in a block |
+```typescript
+if (tx.txType === 'eip1559') {
+  tx.gasParameters.maxFeePerGas;
+  tx.gasParameters.maxPriorityFeePerGas;
+} else if (tx.txType === 'legacy' || tx.txType === 'eip2930') {
+  tx.gasParameters.gasPrice;
+}
+```
 
-## Status Merging Logic
+For a broadcast transaction (`known: false`) the type is inferred from what you provided: `maxFeePerGas` gives `eip1559`, `gasPrice` with an `accessList` gives `eip2930`, `gasPrice` alone gives `legacy`, and nothing gives `txType: undefined`, meaning the wallet will decide. On a known transaction (`known: true`) the type and its gas values are the final ones, and every gas field is present.
 
-When an operation contains multiple transactions, their statuses are merged using the following priority (highest wins):
+`from` and `nonce` are re-read from the chain on `transaction:known`. `metadata`, `source` and `correlation` are not observable on chain, so they are carried through from dispatch unchanged, on every event that carries a transaction.
 
-1. **Included** - Any tx included in a block → operation is `Included`
-2. **Broadcasted** - Any tx in mempool → operation is `Broadcasted`
-3. **NotFound** - None visible → operation is `NotFound`
-4. **Dropped** - ALL txs dropped → operation is `Dropped`
+## API
 
-### For `Included` Operations
+### `createTrackedWalletClient<TMetadata, TSource?>(options?)`
 
-- If **any** transaction succeeded → `status: 'Success'`
-- If **all** included transactions failed → `status: 'Failure'`
-- `txIndex` points to the first successful tx, or first failure if all failed
+Returns a builder with a single method, `.using(walletClient, publicClient)`.
 
-This allows scenarios like:
-- Tx A (nonce 5) succeeds, Tx B (nonce 6) fails due to nonce conflict → Operation is **Success**
-- Tx A (nonce 5, low gas) dropped, Tx B (nonce 5, high gas) succeeds → Operation is **Success**
+| Option | Type | Description |
+|--------|------|-------------|
+| `source` | `TSource \| (() => TSource)` | The signing route this client is. Required when `TSource` excludes `undefined`, absent by default |
+| `populateMetadata` | `boolean` | Auto-populate `type`, `functionName` and `args` in `writeContract` metadata |
+| `clock` | `() => number` | Current time in milliseconds, for `broadcastTimestampMs`. Defaults to `Date.now` |
 
-## Use Cases
+### Client methods
 
-### Gas Price Bumping
+| Method | Returns |
+|--------|---------|
+| `writeContract(args)` | `Promise<Hash>` |
+| `sendTransaction(args)` | `Promise<Hash>` |
+| `sendRawTransaction({serializedTransaction, metadata, correlation})` | `Promise<Hash>` |
+| `writeContractSync(args)` | `Promise<TransactionReceipt>` |
+| `sendTransactionSync(args)` | `Promise<TransactionReceipt>` |
+| `sendRawTransactionSync({serializedTransaction, metadata, correlation})` | `Promise<TransactionReceipt>` |
+| `on(event, listener)` | `() => void` (unsubscribe) |
+| `off(event, listener)` | `void` |
 
-When network congestion increases, submit a replacement transaction with the same nonce but higher gas price:
+The arguments are viem's, with `nonce` widened to accept a block tag and two fields added: `metadata` and the optional `correlation`. Both are stripped from the arguments before they are handed to viem. The underlying clients stay reachable as `tracked.walletClient` and `tracked.publicClient`.
 
-```typescript
-// Initial transaction
-const tx1: BroadcastedTransaction = {
-  hash: '0x111...',
-  from: '0xabc...',
-  nonce: 5,
-  broadcastTimestamp: Date.now(),
-  state: {
-    inclusion: 'InMemPool',
-    status: undefined,
-    final: undefined,
-  },
-};
+The account comes from the call (`account`) or from the wallet client. If neither has one, the call throws.
 
-processor.add('transfer-1', {
-  transactions: [tx1],
-  state: {
-    inclusion: 'InMemPool',
-    status: undefined,
-    final: undefined,
-    txIndex: undefined,
-  },
-});
+### Types
 
-// Later, bump gas price (same nonce)
-const tx2: BroadcastedTransaction = {
-  ...tx1,
-  hash: '0x222...', // Different hash
-};
+`TrackedTransaction`, `KnownTrackedTransaction`, `UnknownTrackedTransaction`, `TrackedWalletClient`, `TrackedWalletClientAutoPopulate`, `TrackedWalletClientEvents`, `PopulatedMetadata`, `FunctionCallMetadata`, `UnknownTypeMetadata`, `NonceOption`, `BlockTag`, `AccessList`, `IntendedGasParameters`, `CreateTrackedWalletClientOptions`, `CorrelationField`.
 
-processor.add('transfer-1', { // Same ID → merges
-  transactions: [tx2],
-});
+`TrackedWalletClientType` is a convenience for declaring a client variable without spelling out the whole interface:
 
-// Operation now tracks both txs
-// Whichever is included first determines the operation result
+```typescript
+type MyClient = TrackedWalletClientType<MyMetadata>;
+type MyAutoClient = TrackedWalletClientType<PopulatedMetadata, true>;
+type MySourcedClient = TrackedWalletClientType<
+  MyMetadata,
+  false,
+  Transport,
+  Chain,
+  Account,
+  MySource
+>;
 ```
 
-### Sequential Retry
+`TSource` is the last type parameter on the client types and the second on the transaction types, so existing code that spelled out transport, chain and account keeps compiling untouched.
 
-If a transaction is stuck, retry with a new nonce:
+## License
 
-```typescript
-processor.add('my-action', {
-  transactions: [
-    { hash: '0x1...', from: '0xabc...', nonce: 5, broadcastTimestamp: Date.now() }, // Original
-    { hash: '0x2...', from: '0xabc...', nonce: 6, broadcastTimestamp: Date.now() }, // Retry with new nonce
-  ],
-});
-
-// If tx with nonce 5 succeeds, operation is Success
-// Even if tx with nonce 6 fails (nonce conflict), operation is still Success
-```
+MIT

package/dist/TrackedWalletClient.d.ts

@@ -1,5 +1,17 @@
 import { type Account, type Chain, type PublicClient, type Transport, type WalletClient } from 'viem';
 import type { CreateTrackedWalletClientOptions, PopulatedMetadata, TrackedWalletClient, TrackedWalletClientAutoPopulate } from './types.js';
+/**
+ * Blocks inference of TSource from the `source` option value.
+ *
+ * Without this, a call that passes no explicit type arguments would infer
+ * TSource from the value (widening `'local-signer'` to `string`) and silently
+ * collapse TMetadata to `unknown`, which turns metadata typing off. TSource is
+ * meant to be declared, never guessed.
+ *
+ * This is TypeScript 5.4's built-in `NoInfer`, spelled out so the package keeps
+ * working for consumers on older TypeScript versions.
+ */
+type NoInferSource<T> = [T][T extends any ? 0 : never];
 /**
  * Infer transport type from WalletClient
  */
@@ -15,7 +27,7 @@ type InferAccount<T> = T extends WalletClient<any, any, infer TAccount> ? TAccou
 /**
  * Builder interface returned by createTrackedWalletClient for the curried API.
  */
-export interface TrackedWalletClientBuilder<TMetadata> {
+export interface TrackedWalletClientBuilder<TMetadata, TSource = undefined> {
     /**
      * Create the tracked wallet client using the provided wallet and public clients.
      *
@@ -23,14 +35,14 @@ export interface TrackedWalletClientBuilder<TMetadata> {
      * @param publicClient - A PublicClient for nonce fetching and tx verification
      * @returns A TrackedWalletClient instance
      */
-    using<TClient extends WalletClient>(walletClient: TClient, publicClient: PublicClient): TrackedWalletClient<TMetadata, InferTransport<TClient>, InferChain<TClient>, InferAccount<TClient>>;
+    using<TClient extends WalletClient>(walletClient: TClient, publicClient: PublicClient): TrackedWalletClient<TMetadata, InferTransport<TClient>, InferChain<TClient>, InferAccount<TClient>, TSource>;
 }
 /**
  * Builder interface returned by createTrackedWalletClient with populateMetadata: true.
  * This builder returns a TrackedWalletClientAutoPopulate that auto-populates operation, functionName and args.
  * TMetadata must be a type where FunctionCallMetadata is assignable to it.
  */
-export interface TrackedWalletClientAutoPopulateBuilder<TMetadata> {
+export interface TrackedWalletClientAutoPopulateBuilder<TMetadata, TSource = undefined> {
     /**
      * Create the tracked wallet client using the provided wallet and public clients.
      * writeContract and writeContractSync will automatically populate operation, functionName and args.
@@ -39,7 +51,7 @@ export interface TrackedWalletClientAutoPopulateBuilder<TMetadata> {
      * @param publicClient - A PublicClient for nonce fetching and tx verification
      * @returns A TrackedWalletClientAutoPopulate instance
      */
-    using<TClient extends WalletClient>(walletClient: TClient, publicClient: PublicClient): TrackedWalletClientAutoPopulate<TMetadata, InferTransport<TClient>, InferChain<TClient>, InferAccount<TClient>>;
+    using<TClient extends WalletClient>(walletClient: TClient, publicClient: PublicClient): TrackedWalletClientAutoPopulate<TMetadata, InferTransport<TClient>, InferChain<TClient>, InferAccount<TClient>, TSource>;
 }
 /**
  * Create a tracked wallet client that wraps a viem WalletClient.
@@ -51,6 +63,12 @@ export interface TrackedWalletClientAutoPopulateBuilder<TMetadata> {
  * - Event emission for tracking
  *
  * @typeParam TMetadata - The metadata type. Use `MyMeta | undefined` to make metadata optional.
+ * @typeParam TSource - An opaque marker of which signing route this client is.
+ *   Defaults to `undefined` (no source). When it does not include `undefined`,
+ *   the `source` option is mandatory. It must always be passed explicitly:
+ *   inference from the option value is deliberately blocked, so passing a
+ *   `source` without also declaring TSource is an error rather than a silently
+ *   widened type.
  * @returns A builder with a `.using()` method to provide the wallet and public clients
  *
  * @example
@@ -71,10 +89,24 @@ export interface TrackedWalletClientAutoPopulateBuilder<TMetadata> {
  * type MyMetadata = OperationMetadata & { purpose: string };
  * const tracked = createTrackedWalletClient<MyMetadata>({ populateMetadata: true })
  *   .using(walletClient, publicClient);
+ *
+ * // With an opaque source marking which signing route this client is.
+ * // Non-undefined TSource makes the `source` option mandatory.
+ * type MySource = 'connected-wallet' | 'local-signer' | 'payer-wallet';
+ * const tracked = createTrackedWalletClient<{purpose: string}, MySource>({
+ *   source: 'local-signer',
+ * }).using(walletClient, publicClient);
+ *
+ * // ...or as a thunk, re-evaluated at every broadcast
+ * const tracked = createTrackedWalletClient<{purpose: string}, MySource>({
+ *   source: () => currentRoute(),
+ * }).using(walletClient, publicClient);
  * ```
  */
-export declare function createTrackedWalletClient<TMetadata>(): TrackedWalletClientBuilder<TMetadata>;
+export declare function createTrackedWalletClient<TMetadata, TSource = undefined>(...args: undefined extends TSource ? [
+    options?: CreateTrackedWalletClientOptions<false, NoInferSource<TSource>>
+] : [options: CreateTrackedWalletClientOptions<false, NoInferSource<TSource>>]): TrackedWalletClientBuilder<TMetadata, TSource>;
 export declare function createTrackedWalletClient(options: CreateTrackedWalletClientOptions<true>): TrackedWalletClientAutoPopulateBuilder<PopulatedMetadata>;
-export declare function createTrackedWalletClient<TMetadata>(options: CreateTrackedWalletClientOptions<true>): TrackedWalletClientAutoPopulateBuilder<TMetadata>;
+export declare function createTrackedWalletClient<TMetadata, TSource = undefined>(options: CreateTrackedWalletClientOptions<true, NoInferSource<TSource>>): TrackedWalletClientAutoPopulateBuilder<TMetadata, TSource>;
 export {};
 //# sourceMappingURL=TrackedWalletClient.d.ts.map

package/dist/TrackedWalletClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TrackedWalletClient.d.ts","sourceRoot":"","sources":["../src/TrackedWalletClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAMN,KAAK,OAAO,EAEZ,KAAK,KAAK,EAIV,KAAK,YAAY,EAIjB,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,MAAM,MAAM,CAAC;AAEd,OAAO,KAAK,EAGX,gCAAgC,EAIhC,iBAAiB,EAIjB,mBAAmB,EACnB,+BAA+B,EAI/B,MAAM,YAAY,CAAC;AAmXpB;;GAEG;AACH,KAAK,cAAc,CAAC,CAAC,IACpB,CAAC,SAAS,YAAY,CAAC,MAAM,UAAU,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,UAAU,GAAG,SAAS,CAAC;AAE7E;;GAEG;AACH,KAAK,UAAU,CAAC,CAAC,IAChB,CAAC,SAAS,YAAY,CAAC,GAAG,EAAE,MAAM,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC;AAE7E;;GAEG;AACH,KAAK,YAAY,CAAC,CAAC,IAClB,CAAC,SAAS,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC,GAC7C,QAAQ,GACR,OAAO,GAAG,SAAS,CAAC;AAExB;;GAEG;AACH,MAAM,WAAW,0BAA0B,CAAC,SAAS;IACpD;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,SAAS,YAAY,EACjC,YAAY,EAAE,OAAO,EACrB,YAAY,EAAE,YAAY,GACxB,mBAAmB,CACrB,SAAS,EACT,cAAc,CAAC,OAAO,CAAC,EACvB,UAAU,CAAC,OAAO,CAAC,EACnB,YAAY,CAAC,OAAO,CAAC,CACrB,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,WAAW,sCAAsC,CAAC,SAAS;IAChE;;;;;;;OAOG;IACH,KAAK,CAAC,OAAO,SAAS,YAAY,EACjC,YAAY,EAAE,OAAO,EACrB,YAAY,EAAE,YAAY,GACxB,+BAA+B,CACjC,SAAS,EACT,cAAc,CAAC,OAAO,CAAC,EACvB,UAAU,CAAC,OAAO,CAAC,EACnB,YAAY,CAAC,OAAO,CAAC,CACrB,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,wBAAgB,yBAAyB,CACxC,SAAS,KACL,0BAA0B,CAAC,SAAS,CAAC,CAAC;AAG3C,wBAAgB,yBAAyB,CACxC,OAAO,EAAE,gCAAgC,CAAC,IAAI,CAAC,GAC7C,sCAAsC,CAAC,iBAAiB,CAAC,CAAC;AAG7D,wBAAgB,yBAAyB,CAAC,SAAS,EAClD,OAAO,EAAE,gCAAgC,CAAC,IAAI,CAAC,GAC7C,sCAAsC,CAAC,SAAS,CAAC,CAAC"}
+{"version":3,"file":"TrackedWalletClient.d.ts","sourceRoot":"","sources":["../src/TrackedWalletClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAMN,KAAK,OAAO,EAEZ,KAAK,KAAK,EAIV,KAAK,YAAY,EAIjB,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,MAAM,MAAM,CAAC;AAEd,OAAO,KAAK,EAGX,gCAAgC,EAIhC,iBAAiB,EAIjB,mBAAmB,EACnB,+BAA+B,EAI/B,MAAM,YAAY,CAAC;AA2EpB;;;;;;;;;;GAUG;AACH,KAAK,aAAa,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,GAAG,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;AAsVvD;;GAEG;AACH,KAAK,cAAc,CAAC,CAAC,IACpB,CAAC,SAAS,YAAY,CAAC,MAAM,UAAU,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,UAAU,GAAG,SAAS,CAAC;AAE7E;;GAEG;AACH,KAAK,UAAU,CAAC,CAAC,IAChB,CAAC,SAAS,YAAY,CAAC,GAAG,EAAE,MAAM,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC;AAE7E;;GAEG;AACH,KAAK,YAAY,CAAC,CAAC,IAClB,CAAC,SAAS,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC,GAC7C,QAAQ,GACR,OAAO,GAAG,SAAS,CAAC;AAExB;;GAEG;AACH,MAAM,WAAW,0BAA0B,CAAC,SAAS,EAAE,OAAO,GAAG,SAAS;IACzE;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,SAAS,YAAY,EACjC,YAAY,EAAE,OAAO,EACrB,YAAY,EAAE,YAAY,GACxB,mBAAmB,CACrB,SAAS,EACT,cAAc,CAAC,OAAO,CAAC,EACvB,UAAU,CAAC,OAAO,CAAC,EACnB,YAAY,CAAC,OAAO,CAAC,EACrB,OAAO,CACP,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,WAAW,sCAAsC,CACtD,SAAS,EACT,OAAO,GAAG,SAAS;IAEnB;;;;;;;OAOG;IACH,KAAK,CAAC,OAAO,SAAS,YAAY,EACjC,YAAY,EAAE,OAAO,EACrB,YAAY,EAAE,YAAY,GACxB,+BAA+B,CACjC,SAAS,EACT,cAAc,CAAC,OAAO,CAAC,EACvB,UAAU,CAAC,OAAO,CAAC,EACnB,YAAY,CAAC,OAAO,CAAC,EACrB,OAAO,CACP,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAGH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,OAAO,GAAG,SAAS,EACvE,GAAG,IAAI,EAAE,SAAS,SAAS,OAAO,GAC/B;IACA,OAAO,CAAC,EAAE,gCAAgC,CACzC,KAAK,EACL,aAAa,CAAC,OAAO,CAAC,CACtB;CACD,GACA,CAAC,OAAO,EAAE,gCAAgC,CAAC,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,GAC3E,0BAA0B,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;AAGlD,wBAAgB,yBAAyB,CACxC,OAAO,EAAE,gCAAgC,CAAC,IAAI,CAAC,GAC7C,sCAAsC,CAAC,iBAAiB,CAAC,CAAC;AAG7D,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,OAAO,GAAG,SAAS,EACvE,OAAO,EAAE,gCAAgC,CAAC,IAAI,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC,GACrE,sCAAsC,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC"}