@etherkit/viem-tx-tracker 0.1.0 → 0.2.0

package/README.md

@@ -11,10 +11,11 @@ This package wraps a `WalletClient` with the same method names (`sendTransaction
 - 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, fetches the transaction back from the chain and emits a second event with the values the chain actually recorded.
+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` or `source`. It carries them.
+The tracker never interprets `metadata`, `source` or `correlation`. It carries them.
 
 ## Installation
 
@@ -44,7 +45,7 @@ tracked.on('transaction:broadcasted', (tx) => {
   save(tx.hash, tx);
 });
 
-tracked.on('transaction:fetched', (tx) => {
+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);
@@ -128,6 +129,42 @@ Points worth knowing:
 - 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
+
+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.
+
+`(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.
+
+Pass a `correlation` on the call and read it off the event:
+
+```typescript
+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});
+```
+
+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:
+
+| 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 |
+
+Points worth knowing:
+
+- 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.
+
 ## Nonces
 
 Every method takes `nonce` as either an exact number or a block tag:
@@ -145,7 +182,7 @@ The resolved nonce is injected into the request and recorded on the emitted tran
 | 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 |
+| `transaction:known` | `KnownTrackedTransaction<TMetadata, TSource>` | Once the values are known to be final rather than intended |
 
 ```typescript
 const unsubscribe = tracked.on('transaction:broadcasted', listener);
@@ -154,9 +191,16 @@ unsubscribe();
 tracked.off('transaction:broadcasted', listener);
 ```
 
-`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.
+`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.
+
+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.
+
+The two paths differ in reliability, which the name cannot express, so it is worth stating plainly:
+
+- **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.
 
-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.
+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
 
@@ -178,6 +222,7 @@ type CommonFields = {
   readonly broadcastTimestampMs: number;
   readonly metadata: TMetadata;
   readonly source: TSource;
+  readonly correlation?: string;
 };
 ```
 
@@ -192,9 +237,9 @@ if (tx.txType === 'eip1559') {
 }
 ```
 
-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.
+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.
 
-`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.
+`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.
 
 ## API
 
@@ -214,20 +259,20 @@ Returns a builder with a single method, `.using(walletClient, publicClient)`.
 |--------|---------|
 | `writeContract(args)` | `Promise<Hash>` |
 | `sendTransaction(args)` | `Promise<Hash>` |
-| `sendRawTransaction({serializedTransaction, metadata})` | `Promise<Hash>` |
+| `sendRawTransaction({serializedTransaction, metadata, correlation})` | `Promise<Hash>` |
 | `writeContractSync(args)` | `Promise<TransactionReceipt>` |
 | `sendTransactionSync(args)` | `Promise<TransactionReceipt>` |
-| `sendRawTransactionSync({serializedTransaction, metadata})` | `Promise<TransactionReceipt>` |
+| `sendRawTransactionSync({serializedTransaction, metadata, correlation})` | `Promise<TransactionReceipt>` |
 | `on(event, listener)` | `() => void` (unsubscribe) |
 | `off(event, listener)` | `void` |
 
-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`.
+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`.
 
 The account comes from the call (`account`) or from the wallet client. If neither has one, the call throws.
 
 ### Types
 
-`TrackedTransaction`, `KnownTrackedTransaction`, `UnknownTrackedTransaction`, `TrackedWalletClient`, `TrackedWalletClientAutoPopulate`, `TrackedWalletClientEvents`, `PopulatedMetadata`, `FunctionCallMetadata`, `UnknownTypeMetadata`, `NonceOption`, `BlockTag`, `AccessList`, `IntendedGasParameters`, `CreateTrackedWalletClientOptions`.
+`TrackedTransaction`, `KnownTrackedTransaction`, `UnknownTrackedTransaction`, `TrackedWalletClient`, `TrackedWalletClientAutoPopulate`, `TrackedWalletClientEvents`, `PopulatedMetadata`, `FunctionCallMetadata`, `UnknownTypeMetadata`, `NonceOption`, `BlockTag`, `AccessList`, `IntendedGasParameters`, `CreateTrackedWalletClientOptions`, `CorrelationField`.
 
 `TrackedWalletClientType` is a convenience for declaring a client variable without spelling out the whole interface:
 

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;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"}
+{"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"}

package/dist/TrackedWalletClient.js

@@ -55,7 +55,7 @@ function resolveSource(source) {
  * Create an UnknownTrackedTransaction for immediate emission.
  * Populates all known intended values from the transaction parameters.
  */
-function createUnknownTrackedTransaction(hash, from, nonce, chainId, metadata, source, broadcastTimestampMs, params) {
+function createUnknownTrackedTransaction(hash, from, nonce, chainId, carried, broadcastTimestampMs, params) {
     const base = {
         known: false,
         chainId,
@@ -63,8 +63,7 @@ function createUnknownTrackedTransaction(hash, from, nonce, chainId, metadata, s
         from,
         nonce,
         broadcastTimestampMs,
-        metadata,
-        source,
+        ...carried,
         to: params.to,
         value: params.value,
         data: params.data,
@@ -158,10 +157,10 @@ function extractTransactionTypeFields(tx) {
  * Create a KnownTrackedTransaction from a fetched transaction.
  *
  * Note: this object is rebuilt from the chain fetch, not copied from the
- * broadcasted one, so every carried-but-not-observed field (metadata, source)
- * must be threaded in explicitly.
+ * broadcasted one, so every carried-but-not-observed field (metadata, source,
+ * correlation) must be threaded in explicitly.
  */
-function createKnownTrackedTransaction(tx, metadata, source, broadcastTimestampMs) {
+function createKnownTrackedTransaction(tx, carried, broadcastTimestampMs) {
     const base = {
         known: true,
         hash: tx.hash,
@@ -171,8 +170,7 @@ function createKnownTrackedTransaction(tx, metadata, source, broadcastTimestampM
         value: tx.value,
         data: tx.input,
         broadcastTimestampMs,
-        metadata,
-        source,
+        ...carried,
     };
     const typeFields = extractTransactionTypeFields(tx);
     return {
@@ -183,7 +181,7 @@ function createKnownTrackedTransaction(tx, metadata, source, broadcastTimestampM
 /**
  * Create a KnownTrackedTransaction from a parsed raw transaction.
  */
-function createKnownTrackedTransactionFromRaw(parsedTx, from, hash, metadata, source, chainId, broadcastTimestampMs) {
+function createKnownTrackedTransactionFromRaw(parsedTx, from, hash, carried, chainId, broadcastTimestampMs) {
     const base = {
         known: true,
         hash,
@@ -193,8 +191,7 @@ function createKnownTrackedTransactionFromRaw(parsedTx, from, hash, metadata, so
         value: parsedTx.value ?? 0n,
         data: parsedTx.data ?? '0x',
         broadcastTimestampMs,
-        metadata,
-        source,
+        ...carried,
     };
     // Determine transaction type from parsed tx
     if ('maxFeePerGas' in parsedTx && parsedTx.maxFeePerGas !== undefined) {
@@ -334,32 +331,40 @@ export function createTrackedWalletClient(options) {
                 return { from, intendedNonce };
             }
             /**
-             * Fetch full transaction data and emit transaction:fetched event.
+             * Fetch full transaction data and emit transaction:known event.
              * Non-blocking, runs in background. Does not throw.
              */
-            async function fetchAndEmitFullData(hash, metadata, source, broadcastTimestampMs) {
+            async function fetchAndEmitFullData(hash, carried, broadcastTimestampMs) {
                 try {
                     const tx = await publicClient.getTransaction({ hash });
-                    const knownTx = createKnownTrackedTransaction(tx, metadata, source, broadcastTimestampMs);
-                    emitter.emit('transaction:fetched', knownTx);
+                    const knownTx = createKnownTrackedTransaction(tx, carried, broadcastTimestampMs);
+                    emitter.emit('transaction:known', knownTx);
                 }
                 catch (error) {
-                    // Log but don't throw - transaction:fetched simply won't fire
+                    // Log but don't throw - transaction:known simply won't fire
                     console.warn(`[TrackedWalletClient] Could not fetch tx ${hash}. ` +
-                        `transaction:fetched event will not be emitted. Error: ${error}`);
+                        `transaction:known event will not be emitted. Error: ${error}`);
                 }
             }
             /**
              * Common wrapper for transaction methods that broadcast (sendTransaction, writeContract).
              * Emits transaction:broadcasted immediately with intended values,
-             * then fetches and emits transaction:fetched with actual values.
+             * then fetches and emits transaction:known with actual values.
              */
             async function executeTrackedTransaction(args) {
-                const { metadata, restArgs, intendedParams, execute, extractHash } = args;
+                const { metadata, correlation, restArgs, intendedParams, execute, extractHash, } = args;
                 const broadcastTimestampMs = clock();
                 // Stamped here, in the same step as from/nonce/broadcastTimestampMs.
                 // A thunk is re-evaluated on every send, never captured once.
                 const source = resolveSource(sourceOption);
+                // The carried values travel as one bundle from here on: metadata (what
+                // the tx means), source (which route signed) and correlation (which
+                // caller-side request this send answers). None is interpreted.
+                const carried = {
+                    metadata,
+                    source,
+                    correlation,
+                };
                 // Extract common context
                 const { from, intendedNonce } = await extractTransactionContext(args);
                 // Execute the underlying transaction with nonce injected
@@ -369,10 +374,10 @@ export function createTrackedWalletClient(options) {
                 });
                 const hash = extractHash(result);
                 // Emit transaction:broadcasted immediately with intended values
-                const unknownTx = createUnknownTrackedTransaction(hash, from, intendedNonce, walletClient.chain?.id, metadata, source, broadcastTimestampMs, intendedParams);
+                const unknownTx = createUnknownTrackedTransaction(hash, from, intendedNonce, walletClient.chain?.id, carried, broadcastTimestampMs, intendedParams);
                 emitter.emit('transaction:broadcasted', unknownTx);
-                // Fire-and-forget: fetch full data and emit transaction:fetched
-                fetchAndEmitFullData(hash, metadata, source, broadcastTimestampMs);
+                // Fire-and-forget: fetch full data and emit transaction:known
+                fetchAndEmitFullData(hash, carried, broadcastTimestampMs);
                 return result;
             }
             /**
@@ -381,22 +386,30 @@ export function createTrackedWalletClient(options) {
              * Emits KnownTrackedTransaction directly to transaction:broadcasted.
              */
             async function executeTrackedRawTransaction(args) {
-                const { serializedTransaction, metadata, execute, extractHash } = args;
+                const { serializedTransaction, metadata, correlation, execute, extractHash, } = args;
                 const broadcastTimestampMs = clock();
                 // Stamped here, in the same step as from/nonce/broadcastTimestampMs.
                 // A thunk is re-evaluated on every send, never captured once.
                 const source = resolveSource(sourceOption);
+                const carried = {
+                    metadata,
+                    source,
+                    correlation,
+                };
                 const from = await recoverTransactionAddress({ serializedTransaction });
                 const parsedTx = parseTransaction(serializedTransaction);
                 // Execute the broadcast
                 const result = await execute();
                 const hash = extractHash(result);
                 // For raw transactions, we can parse full data immediately
-                const knownTx = createKnownTrackedTransactionFromRaw(parsedTx, from, hash, metadata, source, walletClient.chain?.id, broadcastTimestampMs);
+                const knownTx = createKnownTrackedTransactionFromRaw(parsedTx, from, hash, carried, walletClient.chain?.id, broadcastTimestampMs);
                 // Emit as KnownTrackedTransaction since we have all data
                 emitter.emit('transaction:broadcasted', knownTx);
-                // Also emit to transaction:fetched for consistency
-                emitter.emit('transaction:fetched', knownTx);
+                // The values are final (parsed from the signed payload, not merely
+                // intended), which is exactly what transaction:known promises, so it
+                // is emitted here too: every tracked transaction reaches that event,
+                // and a consumer can persist on it alone.
+                emitter.emit('transaction:known', knownTx);
                 return result;
             }
             return {
@@ -406,12 +419,13 @@ export function createTrackedWalletClient(options) {
                 // Async methods (return hash)
                 // ============================================
                 async writeContract(args) {
-                    const { metadata, nonce, ...writeArgs } = args;
+                    const { metadata, correlation, nonce, ...writeArgs } = args;
                     const intendedParams = extractIntendedParamsFromWriteContract(args);
                     return executeTrackedTransaction({
                         account: normalizeAccount(args.account),
                         nonce,
                         metadata: metadata,
+                        correlation,
                         restArgs: writeArgs,
                         intendedParams,
                         execute: (argsWithNonce) => walletClient.writeContract(argsWithNonce),
@@ -419,12 +433,13 @@ export function createTrackedWalletClient(options) {
                     });
                 },
                 async sendTransaction(args) {
-                    const { metadata, nonce, ...sendArgs } = args;
+                    const { metadata, correlation, nonce, ...sendArgs } = args;
                     const intendedParams = extractIntendedParamsFromSendTransaction(args);
                     return executeTrackedTransaction({
                         account: normalizeAccount(args.account),
                         nonce,
                         metadata: metadata,
+                        correlation,
                         restArgs: sendArgs,
                         intendedParams,
                         execute: (argsWithNonce) => walletClient.sendTransaction(argsWithNonce),
@@ -432,10 +447,11 @@ export function createTrackedWalletClient(options) {
                     });
                 },
                 async sendRawTransaction(args) {
-                    const { metadata, serializedTransaction } = args;
+                    const { metadata, correlation, serializedTransaction } = args;
                     return executeTrackedRawTransaction({
                         serializedTransaction,
                         metadata: metadata,
+                        correlation,
                         execute: () => walletClient.sendRawTransaction({ serializedTransaction }),
                         extractHash: (hash) => hash,
                     });
@@ -444,12 +460,13 @@ export function createTrackedWalletClient(options) {
                 // Sync methods (return receipt, wait for confirmation)
                 // ============================================
                 async writeContractSync(args) {
-                    const { metadata, nonce, ...writeArgs } = args;
+                    const { metadata, correlation, nonce, ...writeArgs } = args;
                     const intendedParams = extractIntendedParamsFromWriteContract(args);
                     return executeTrackedTransaction({
                         account: normalizeAccount(args.account),
                         nonce,
                         metadata: metadata,
+                        correlation,
                         restArgs: writeArgs,
                         intendedParams,
                         execute: (argsWithNonce) => walletClient.writeContractSync(argsWithNonce),
@@ -457,12 +474,13 @@ export function createTrackedWalletClient(options) {
                     });
                 },
                 async sendTransactionSync(args) {
-                    const { metadata, nonce, ...sendArgs } = args;
+                    const { metadata, correlation, nonce, ...sendArgs } = args;
                     const intendedParams = extractIntendedParamsFromSendTransaction(args);
                     return executeTrackedTransaction({
                         account: normalizeAccount(args.account),
                         nonce,
                         metadata: metadata,
+                        correlation,
                         restArgs: sendArgs,
                         intendedParams,
                         execute: (argsWithNonce) => walletClient.sendTransactionSync(argsWithNonce),
@@ -470,10 +488,11 @@ export function createTrackedWalletClient(options) {
                     });
                 },
                 async sendRawTransactionSync(args) {
-                    const { metadata, serializedTransaction } = args;
+                    const { metadata, correlation, serializedTransaction } = args;
                     return executeTrackedRawTransaction({
                         serializedTransaction,
                         metadata: metadata,
+                        correlation,
                         execute: () => walletClient.sendRawTransactionSync({ serializedTransaction }),
                         extractHash: (receipt) => receipt.transactionHash,
                     });
@@ -523,19 +542,19 @@ function createAutoPopulateBuilder(clock, sourceOption) {
                 return { from, intendedNonce };
             }
             /**
-             * Fetch full transaction data and emit transaction:fetched event.
+             * Fetch full transaction data and emit transaction:known event.
              * Non-blocking, runs in background. Does not throw.
              */
-            async function fetchAndEmitFullData(hash, metadata, source, broadcastTimestampMs) {
+            async function fetchAndEmitFullData(hash, carried, broadcastTimestampMs) {
                 try {
                     const tx = await publicClient.getTransaction({ hash });
-                    const knownTx = createKnownTrackedTransaction(tx, metadata, source, broadcastTimestampMs);
-                    emitter.emit('transaction:fetched', knownTx);
+                    const knownTx = createKnownTrackedTransaction(tx, carried, broadcastTimestampMs);
+                    emitter.emit('transaction:known', knownTx);
                 }
                 catch (error) {
-                    // Log but don't throw - transaction:fetched simply won't fire
+                    // Log but don't throw - transaction:known simply won't fire
                     console.warn(`[TrackedWalletClient] Could not fetch tx ${hash}. ` +
-                        `transaction:fetched event will not be emitted. Error: ${error}`);
+                        `transaction:known event will not be emitted. Error: ${error}`);
                 }
             }
             /**
@@ -561,14 +580,22 @@ function createAutoPopulateBuilder(clock, sourceOption) {
             /**
              * Common wrapper for transaction methods that broadcast.
              * Emits transaction:broadcasted immediately with intended values,
-             * then fetches and emits transaction:fetched with actual values.
+             * then fetches and emits transaction:known with actual values.
              */
             async function executeTrackedTransaction(args) {
-                const { metadata, restArgs, intendedParams, execute, extractHash } = args;
+                const { metadata, correlation, restArgs, intendedParams, execute, extractHash, } = args;
                 const broadcastTimestampMs = clock();
                 // Stamped here, in the same step as from/nonce/broadcastTimestampMs.
                 // A thunk is re-evaluated on every send, never captured once.
                 const source = resolveSource(sourceOption);
+                // The carried values travel as one bundle from here on: metadata (what
+                // the tx means), source (which route signed) and correlation (which
+                // caller-side request this send answers). None is interpreted.
+                const carried = {
+                    metadata,
+                    source,
+                    correlation,
+                };
                 const { from, intendedNonce } = await extractTransactionContext(args);
                 const result = await execute({
                     ...restArgs,
@@ -576,10 +603,10 @@ function createAutoPopulateBuilder(clock, sourceOption) {
                 });
                 const hash = extractHash(result);
                 // Emit transaction:broadcasted immediately with intended values
-                const unknownTx = createUnknownTrackedTransaction(hash, from, intendedNonce, walletClient.chain?.id, metadata, source, broadcastTimestampMs, intendedParams);
+                const unknownTx = createUnknownTrackedTransaction(hash, from, intendedNonce, walletClient.chain?.id, carried, broadcastTimestampMs, intendedParams);
                 emitter.emit('transaction:broadcasted', unknownTx);
-                // Fire-and-forget: fetch full data and emit transaction:fetched
-                fetchAndEmitFullData(hash, metadata, source, broadcastTimestampMs);
+                // Fire-and-forget: fetch full data and emit transaction:known
+                fetchAndEmitFullData(hash, carried, broadcastTimestampMs);
                 return result;
             }
             /**
@@ -588,21 +615,30 @@ function createAutoPopulateBuilder(clock, sourceOption) {
              * Emits KnownTrackedTransaction directly to transaction:broadcasted.
              */
             async function executeTrackedRawTransaction(args) {
-                const { serializedTransaction, metadata, execute, extractHash } = args;
+                const { serializedTransaction, metadata, correlation, execute, extractHash, } = args;
                 const broadcastTimestampMs = clock();
                 // Stamped here, in the same step as from/nonce/broadcastTimestampMs.
                 // A thunk is re-evaluated on every send, never captured once.
                 const source = resolveSource(sourceOption);
+                const carried = {
+                    metadata,
+                    source,
+                    correlation,
+                };
                 const from = await recoverTransactionAddress({ serializedTransaction });
                 const parsedTx = parseTransaction(serializedTransaction);
                 // Execute the broadcast
                 const result = await execute();
                 const hash = extractHash(result);
                 // For raw transactions, we can parse full data immediately
-                const knownTx = createKnownTrackedTransactionFromRaw(parsedTx, from, hash, metadata, source, walletClient.chain?.id, broadcastTimestampMs);
+                const knownTx = createKnownTrackedTransactionFromRaw(parsedTx, from, hash, carried, walletClient.chain?.id, broadcastTimestampMs);
                 // Emit as KnownTrackedTransaction since we have all data
                 emitter.emit('transaction:broadcasted', knownTx);
-                // We do not emit fetched as the tx is already known
+                // The values are final (parsed from the signed payload, not merely
+                // intended), which is exactly what transaction:known promises, so it
+                // is emitted here too: every tracked transaction reaches that event,
+                // and a consumer can persist on it alone.
+                emitter.emit('transaction:known', knownTx);
                 return result;
             }
             return {
@@ -612,7 +648,7 @@ function createAutoPopulateBuilder(clock, sourceOption) {
                 // Async methods (return hash)
                 // ============================================
                 async writeContract(args) {
-                    const { metadata: userMetadata, nonce, ...writeArgs } = args;
+                    const { metadata: userMetadata, correlation, nonce, ...writeArgs } = args;
                     // Validate that user didn't provide operation, functionName or args
                     validateNoAutoPopulatedFieldsInMetadata(userMetadata);
                     // Auto-populate type, functionName and args
@@ -627,6 +663,7 @@ function createAutoPopulateBuilder(clock, sourceOption) {
                         account: normalizeAccount(args.account),
                         nonce,
                         metadata: finalMetadata,
+                        correlation,
                         restArgs: writeArgs,
                         intendedParams,
                         execute: (argsWithNonce) => walletClient.writeContract(argsWithNonce),
@@ -634,12 +671,13 @@ function createAutoPopulateBuilder(clock, sourceOption) {
                     });
                 },
                 async sendTransaction(args) {
-                    const { metadata, nonce, ...sendArgs } = args;
+                    const { metadata, correlation, nonce, ...sendArgs } = args;
                     const intendedParams = extractIntendedParamsFromSendTransaction(args);
                     return executeTrackedTransaction({
                         account: normalizeAccount(args.account),
                         nonce,
                         metadata: metadata,
+                        correlation,
                         restArgs: sendArgs,
                         intendedParams,
                         execute: (argsWithNonce) => walletClient.sendTransaction(argsWithNonce),
@@ -647,10 +685,11 @@ function createAutoPopulateBuilder(clock, sourceOption) {
                     });
                 },
                 async sendRawTransaction(args) {
-                    const { metadata, serializedTransaction } = args;
+                    const { metadata, correlation, serializedTransaction } = args;
                     return executeTrackedRawTransaction({
                         serializedTransaction,
                         metadata: metadata,
+                        correlation,
                         execute: () => walletClient.sendRawTransaction({ serializedTransaction }),
                         extractHash: (hash) => hash,
                     });
@@ -659,7 +698,7 @@ function createAutoPopulateBuilder(clock, sourceOption) {
                 // Sync methods (return receipt, wait for confirmation)
                 // ============================================
                 async writeContractSync(args) {
-                    const { metadata: userMetadata, nonce, ...writeArgs } = args;
+                    const { metadata: userMetadata, correlation, nonce, ...writeArgs } = args;
                     // Validate that user didn't provide operation, functionName or args
                     validateNoAutoPopulatedFieldsInMetadata(userMetadata);
                     // Auto-populate type, functionName and args
@@ -674,6 +713,7 @@ function createAutoPopulateBuilder(clock, sourceOption) {
                         account: normalizeAccount(args.account),
                         nonce,
                         metadata: finalMetadata,
+                        correlation,
                         restArgs: writeArgs,
                         intendedParams,
                         execute: (argsWithNonce) => walletClient.writeContractSync(argsWithNonce),
@@ -681,12 +721,13 @@ function createAutoPopulateBuilder(clock, sourceOption) {
                     });
                 },
                 async sendTransactionSync(args) {
-                    const { metadata, nonce, ...sendArgs } = args;
+                    const { metadata, correlation, nonce, ...sendArgs } = args;
                     const intendedParams = extractIntendedParamsFromSendTransaction(args);
                     return executeTrackedTransaction({
                         account: normalizeAccount(args.account),
                         nonce,
                         metadata: metadata,
+                        correlation,
                         restArgs: sendArgs,
                         intendedParams,
                         execute: (argsWithNonce) => walletClient.sendTransactionSync(argsWithNonce),
@@ -694,10 +735,11 @@ function createAutoPopulateBuilder(clock, sourceOption) {
                     });
                 },
                 async sendRawTransactionSync(args) {
-                    const { metadata, serializedTransaction } = args;
+                    const { metadata, correlation, serializedTransaction } = args;
                     return executeTrackedRawTransaction({
                         serializedTransaction,
                         metadata: metadata,
+                        correlation,
                         execute: () => walletClient.sendRawTransactionSync({ serializedTransaction }),
                         extractHash: (receipt) => receipt.transactionHash,
                     });