@etherkit/viem-tx-tracker 0.0.8 → 0.1.0

package/README.md

@@ -1,322 +1,251 @@
-# @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
+
+It also resolves the nonce for you (`pending` by default) and, once broadcast, fetches the transaction back from the chain and emits a second event with the values the chain actually recorded.
+
+The tracker never interprets `metadata` or `source`. 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()});
+
+const tracked = createTrackedWalletClient<MyMetadata>().using(walletClient, publicClient);
 
-// 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
+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:fetched', (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
-
-### `createTransactionObserver(config)`
-
-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:
+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.
 
-#### `add(id: string, operation: OnchainOperation)`
+## Metadata
 
-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();
-```
+type MyMetadata = FunctionCallMetadata & {purpose: string};
 
-#### `process(): Promise<void>`
+const tracked = createTrackedWalletClient<MyMetadata>({populateMetadata: true}).using(
+  walletClient,
+  publicClient,
+);
 
-Check and update the status of all tracked operations. This queries the Ethereum provider for transaction receipts and updates statuses accordingly.
-
-```typescript
-await processor.process();
+await tracked.writeContract({address, abi, functionName: 'transfer', args, metadata: {purpose: 'checkout'}});
 ```
 
-#### `setProvider(provider: EIP1193Provider)`
-
-Update the Ethereum provider.
+`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.
 
-```typescript
-processor.setProvider(newProvider);
-```
+## Source: which route signed
 
-#### `onOperationUpdated(listener): void`
+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.
 
-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:
 
-Unsubscribe from operation changes.
+- 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.
 
-#### `onOperationStatusUpdated(listener): void`
+## Nonces
 
-Subscribe to operation status changes only (when the merged status changes). Useful for UI updates.
+Every method takes `nonce` as either an exact number or a block tag:
 
 ```typescript
-processor.onOperationStatusUpdated((event: OnchainOperationEvent) => {
-  console.log(`Operation ${event.id} status:`, event.operation.state?.inclusion);
-  return () => {}; // cleanup
-});
+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)
 ```
 
-#### `offOperationStatusUpdated(listener): void`
-
-Unsubscribe from operation status changes.
-
-## Types
+The resolved nonce is injected into the request and recorded on the emitted transaction, so a replacement can reuse it.
 
-### `BroadcastedTransaction`
+## Events
 
-Represents a single broadcasted transaction.
+| Event | Payload | When |
+|-------|---------|------|
+| `transaction:broadcasted` | `TrackedTransaction<TMetadata, TSource>` | Immediately after the broadcast succeeds |
+| `transaction:fetched` | `KnownTrackedTransaction<TMetadata, TSource>` | Once the transaction has been read back from the chain |
 
 ```typescript
-type BroadcastedTransaction = {
-  readonly hash: `0x${string}`;
-  readonly from: `0x${string}`;
-  nonce?: number;
-  readonly broadcastTimestamp: number;
-  state?: BroadcastedTransactionState;
-};
-
-type BroadcastedTransactionState =
-  | { inclusion: 'InMemPool' | 'NotFound'; final: undefined; status: undefined }
-  | { inclusion: 'Dropped'; final?: number; status: undefined }
-  | { inclusion: 'Included'; status: 'Failure' | 'Success'; final?: number };
+const unsubscribe = tracked.on('transaction:broadcasted', listener);
+unsubscribe();
+// or
+tracked.off('transaction:broadcasted', listener);
 ```
 
-### `OnchainOperationStatus`
+`transaction:fetched` is best effort: if the fetch fails (not in the mempool yet, network trouble) it simply does not fire, and a warning is logged. Treat `transaction:broadcasted` as the event you must handle and `transaction:fetched` as a refinement.
 
-The merged status of all transactions in an operation.
+For `sendRawTransaction` the full transaction can be parsed from the signed payload, so `transaction:broadcasted` already carries confirmed values (`known: true`) and no separate fetch is needed.
 
-```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 };
-```
+## The transaction shape
 
-- `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`
+A tracked transaction is discriminated by `known`:
 
-### `OnchainOperation`
+- `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.
 
-An operation containing multiple transactions.
+Both share the same field paths, so `tx.hash`, `tx.metadata`, `tx.source`, `tx.gasParameters` are always reachable:
 
 ```typescript
-type OnchainOperation = {
-  transactions: BroadcastedTransaction[];
-  state?: OnchainOperationStatus;
+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;
 };
 ```
 
-### `OnchainOperationEvent`
-
-Event payload emitted by listeners, includes both the operation ID and operation data.
+On top of that, a second discriminant, `txType`, carries the gas parameters that belong to that transaction type:
 
 ```typescript
-type OnchainOperationEvent = {
-  id: string;
-  operation: OnchainOperation;
-};
+if (tx.txType === 'eip1559') {
+  tx.gasParameters.maxFeePerGas;
+  tx.gasParameters.maxPriorityFeePerGas;
+} else if (tx.txType === 'legacy' || tx.txType === 'eip2930') {
+  tx.gasParameters.gasPrice;
+}
 ```
 
-## Status States
+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 fetched transaction (`known: true`) the type and its gas values are the ones the chain recorded, and every gas field is present.
 
-| 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 |
+`from` and `nonce` are re-read from the chain on `transaction:fetched`. `metadata` and `source` are not observable on chain, so they are carried through from dispatch unchanged.
 
-## Status Merging Logic
+## API
 
-When an operation contains multiple transactions, their statuses are merged using the following priority (highest wins):
+### `createTrackedWalletClient<TMetadata, TSource?>(options?)`
 
-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`
+Returns a builder with a single method, `.using(walletClient, publicClient)`.
 
-### For `Included` Operations
+| 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` |
 
-- 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
+### Client methods
 
-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**
+| Method | Returns |
+|--------|---------|
+| `writeContract(args)` | `Promise<Hash>` |
+| `sendTransaction(args)` | `Promise<Hash>` |
+| `sendRawTransaction({serializedTransaction, metadata})` | `Promise<Hash>` |
+| `writeContractSync(args)` | `Promise<TransactionReceipt>` |
+| `sendTransactionSync(args)` | `Promise<TransactionReceipt>` |
+| `sendRawTransactionSync({serializedTransaction, metadata})` | `Promise<TransactionReceipt>` |
+| `on(event, listener)` | `() => void` (unsubscribe) |
+| `off(event, listener)` | `void` |
 
-## Use Cases
+The arguments are viem's, with `nonce` widened to accept a block tag and a `metadata` field added. The underlying clients stay reachable as `tracked.walletClient` and `tracked.publicClient`.
 
-### Gas Price Bumping
+The account comes from the call (`account`) or from the wallet client. If neither has one, the call throws.
 
-When network congestion increases, submit a replacement transaction with the same nonce but higher gas price:
+### Types
 
-```typescript
-// Initial transaction
-const tx1: BroadcastedTransaction = {
-  hash: '0x111...',
-  from: '0xabc...',
-  nonce: 5,
-  broadcastTimestamp: Date.now(),
-  state: {
-    inclusion: 'InMemPool',
-    status: undefined,
-    final: undefined,
-  },
-};
+`TrackedTransaction`, `KnownTrackedTransaction`, `UnknownTrackedTransaction`, `TrackedWalletClient`, `TrackedWalletClientAutoPopulate`, `TrackedWalletClientEvents`, `PopulatedMetadata`, `FunctionCallMetadata`, `UnknownTypeMetadata`, `NonceOption`, `BlockTag`, `AccessList`, `IntendedGasParameters`, `CreateTrackedWalletClientOptions`.
 
-processor.add('transfer-1', {
-  transactions: [tx1],
-  state: {
-    inclusion: 'InMemPool',
-    status: undefined,
-    final: undefined,
-    txIndex: undefined,
-  },
-});
+`TrackedWalletClientType` is a convenience for declaring a client variable without spelling out the whole interface:
 
-// Later, bump gas price (same nonce)
-const tx2: BroadcastedTransaction = {
-  ...tx1,
-  hash: '0x222...', // Different hash
-};
-
-processor.add('transfer-1', { // Same ID → merges
-  transactions: [tx2],
-});
-
-// 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
-
-If a transaction is stuck, retry with a new nonce:
+`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.
 
-```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
-  ],
-});
+## License
 
-// 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;AAkUvD;;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"}