@etherkit/viem-tx-tracker 0.0.9 → 0.2.0

package/src/TrackedWalletClient.ts

@@ -109,19 +109,72 @@ function inferTxType(
 	return undefined; // Wallet will determine
 }
 
+/**
+ * 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];
+
+/**
+ * Resolve the configured source option into a value.
+ *
+ * A thunk is called every time (at broadcast), never memoized: one client can
+ * serve different wallets/accounts over its lifetime.
+ */
+function resolveSource<TSource>(
+	source: TSource | (() => TSource) | undefined,
+): TSource {
+	return typeof source === 'function'
+		? (source as () => TSource)()
+		: (source as TSource);
+}
+
+/**
+ * The values that are carried onto a tracked transaction rather than observed:
+ * they exist only because the caller (or the client construction) supplied
+ * them, so every emission path must thread them explicitly.
+ *
+ * They travel as one object so that adding a carried field cannot silently
+ * miss a path, and so that two same-typed markers cannot be swapped by a
+ * positional-argument mistake.
+ *
+ * The tracker never inspects any of them.
+ */
+interface CarriedFields<TMetadata, TSource> {
+	/** What the application says the transaction MEANS. Persisted by consumers. */
+	metadata: TMetadata;
+	/** WHICH SIGNING ROUTE produced it. Observed at dispatch, persisted. */
+	source: TSource;
+	/**
+	 * Which CALLER-SIDE REQUEST this send answers. Ephemeral plumbing.
+	 *
+	 * Deliberately a required property of type `string | undefined` rather than
+	 * an optional one: a new call site must state that it has no correlation,
+	 * instead of getting `undefined` by forgetting the field.
+	 */
+	correlation: string | undefined;
+}
+
 /**
  * Create an UnknownTrackedTransaction for immediate emission.
  * Populates all known intended values from the transaction parameters.
  */
-function createUnknownTrackedTransaction<TMetadata>(
+function createUnknownTrackedTransaction<TMetadata, TSource>(
 	hash: Hash,
 	from: Address,
 	nonce: number,
 	chainId: number | undefined,
-	metadata: TMetadata,
+	carried: CarriedFields<TMetadata, TSource>,
 	broadcastTimestampMs: number,
 	params: IntendedTransactionParams,
-): UnknownTrackedTransaction<TMetadata> {
+): UnknownTrackedTransaction<TMetadata, TSource> {
 	const base = {
 		known: false as const,
 		chainId,
@@ -129,7 +182,7 @@ function createUnknownTrackedTransaction<TMetadata>(
 		from,
 		nonce,
 		broadcastTimestampMs,
-		metadata,
+		...carried,
 		to: params.to,
 		value: params.value,
 		data: params.data,
@@ -247,12 +300,16 @@ function extractTransactionTypeFields(tx: Transaction):
 
 /**
  * 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,
+ * correlation) must be threaded in explicitly.
  */
-function createKnownTrackedTransaction<TMetadata>(
+function createKnownTrackedTransaction<TMetadata, TSource>(
 	tx: Transaction,
-	metadata: TMetadata,
+	carried: CarriedFields<TMetadata, TSource>,
 	broadcastTimestampMs: number,
-): KnownTrackedTransaction<TMetadata> {
+): KnownTrackedTransaction<TMetadata, TSource> {
 	const base = {
 		known: true as const,
 		hash: tx.hash,
@@ -262,7 +319,7 @@ function createKnownTrackedTransaction<TMetadata>(
 		value: tx.value,
 		data: tx.input,
 		broadcastTimestampMs,
-		metadata,
+		...carried,
 	};
 
 	const typeFields = extractTransactionTypeFields(tx);
@@ -270,20 +327,20 @@ function createKnownTrackedTransaction<TMetadata>(
 	return {
 		...base,
 		...typeFields,
-	} as KnownTrackedTransaction<TMetadata>;
+	} as KnownTrackedTransaction<TMetadata, TSource>;
 }
 
 /**
  * Create a KnownTrackedTransaction from a parsed raw transaction.
  */
-function createKnownTrackedTransactionFromRaw<TMetadata>(
+function createKnownTrackedTransactionFromRaw<TMetadata, TSource>(
 	parsedTx: ParseTransactionReturnType<`0x${string}`>,
 	from: `0x${string}`,
 	hash: Hash,
-	metadata: TMetadata,
+	carried: CarriedFields<TMetadata, TSource>,
 	chainId: number | undefined,
 	broadcastTimestampMs: number,
-): KnownTrackedTransaction<TMetadata> {
+): KnownTrackedTransaction<TMetadata, TSource> {
 	const base = {
 		known: true as const,
 		hash,
@@ -293,7 +350,7 @@ function createKnownTrackedTransactionFromRaw<TMetadata>(
 		value: parsedTx.value ?? 0n,
 		data: parsedTx.data ?? '0x',
 		broadcastTimestampMs,
-		metadata,
+		...carried,
 	};
 
 	// Determine transaction type from parsed tx
@@ -428,7 +485,7 @@ type InferAccount<T> =
 /**
  * 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.
 	 *
@@ -443,7 +500,8 @@ export interface TrackedWalletClientBuilder<TMetadata> {
 		TMetadata,
 		InferTransport<TClient>,
 		InferChain<TClient>,
-		InferAccount<TClient>
+		InferAccount<TClient>,
+		TSource
 	>;
 }
 
@@ -452,7 +510,10 @@ export interface TrackedWalletClientBuilder<TMetadata> {
  * 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.
@@ -468,7 +529,8 @@ export interface TrackedWalletClientAutoPopulateBuilder<TMetadata> {
 		TMetadata,
 		InferTransport<TClient>,
 		InferChain<TClient>,
-		InferAccount<TClient>
+		InferAccount<TClient>,
+		TSource
 	>;
 }
 
@@ -482,6 +544,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
@@ -502,12 +570,32 @@ 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);
  * ```
  */
-// Overload 1: Standard mode, no options
-export function createTrackedWalletClient<
-	TMetadata,
->(): TrackedWalletClientBuilder<TMetadata>;
+// Overload 1: Standard mode. The options argument is required only when
+// TSource does not include undefined.
+export function createTrackedWalletClient<TMetadata, TSource = undefined>(
+	...args: undefined extends TSource
+		? [
+				options?: CreateTrackedWalletClientOptions<
+					false,
+					NoInferSource<TSource>
+				>,
+			]
+		: [options: CreateTrackedWalletClientOptions<false, NoInferSource<TSource>>]
+): TrackedWalletClientBuilder<TMetadata, TSource>;
 
 // Overload 2: Auto-populate mode with default PopulatedMetadata
 export function createTrackedWalletClient(
@@ -515,23 +603,31 @@ export function createTrackedWalletClient(
 ): TrackedWalletClientAutoPopulateBuilder<PopulatedMetadata>;
 
 // Overload 3: Auto-populate mode with custom metadata (must allow FunctionCallMetadata)
-export function createTrackedWalletClient<TMetadata>(
-	options: CreateTrackedWalletClientOptions<true>,
-): TrackedWalletClientAutoPopulateBuilder<TMetadata>;
+export function createTrackedWalletClient<TMetadata, TSource = undefined>(
+	options: CreateTrackedWalletClientOptions<true, NoInferSource<TSource>>,
+): TrackedWalletClientAutoPopulateBuilder<TMetadata, TSource>;
 
 // Implementation
-export function createTrackedWalletClient<TMetadata>(
-	options?: CreateTrackedWalletClientOptions<boolean>,
-):
-	| TrackedWalletClientBuilder<TMetadata>
-	| TrackedWalletClientAutoPopulateBuilder<TMetadata> {
+export function createTrackedWalletClient<
+	TMetadata,
+	TSource = undefined,
+>(options?: {
+	populateMetadata?: boolean;
+	clock?: () => number;
+	source?: TSource | (() => TSource);
+}):
+	| TrackedWalletClientBuilder<TMetadata, TSource>
+	| TrackedWalletClientAutoPopulateBuilder<TMetadata, TSource> {
 	const populateMetadata = options?.populateMetadata ?? false;
 	const clock = options?.clock ?? Date.now;
+	// Kept unresolved: a thunk is evaluated at each broadcast, not here.
+	const sourceOption = options?.source;
 
 	if (populateMetadata) {
-		return createAutoPopulateBuilder<TMetadata>(
+		return createAutoPopulateBuilder<TMetadata, TSource>(
 			clock,
-		) as TrackedWalletClientAutoPopulateBuilder<TMetadata>;
+			sourceOption,
+		) as TrackedWalletClientAutoPopulateBuilder<TMetadata, TSource>;
 	}
 
 	return {
@@ -542,7 +638,8 @@ export function createTrackedWalletClient<TMetadata>(
 			TMetadata,
 			InferTransport<TClient>,
 			InferChain<TClient>,
-			InferAccount<TClient>
+			InferAccount<TClient>,
+			TSource
 		> {
 			// Type aliases for internal use
 			type TTransport = InferTransport<TClient>;
@@ -551,8 +648,8 @@ export function createTrackedWalletClient<TMetadata>(
 
 			// Create emitter for transaction events
 			const emitter = new Emitter<{
-				'transaction:broadcasted': TrackedTransaction<TMetadata>;
-				'transaction:fetched': KnownTrackedTransaction<TMetadata>;
+				'transaction:broadcasted': TrackedTransaction<TMetadata, TSource>;
+				'transaction:known': KnownTrackedTransaction<TMetadata, TSource>;
 			}>();
 
 			/**
@@ -608,27 +705,27 @@ export function createTrackedWalletClient<TMetadata>(
 			}
 
 			/**
-			 * 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: Hash,
-				metadata: TMetadata,
+				carried: CarriedFields<TMetadata, TSource>,
 				broadcastTimestampMs: number,
 			): Promise<void> {
 				try {
 					const tx = await publicClient.getTransaction({hash});
 					const knownTx = createKnownTrackedTransaction(
 						tx,
-						metadata,
+						carried,
 						broadcastTimestampMs,
 					);
-					emitter.emit('transaction:fetched', knownTx);
+					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}`,
 					);
 				}
 			}
@@ -636,19 +733,46 @@ export function createTrackedWalletClient<TMetadata>(
 			/**
 			 * 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<T, R>(args: {
 				account?: Account | Address;
 				nonce?: NonceOption;
 				metadata: TMetadata;
-				restArgs: T;
+				correlation: string | undefined;
+				/**
+				 * The caller's remaining args, spread verbatim into viem's own call.
+				 *
+				 * `{correlation?: never}` is the compile-time half of the no-forwarding
+				 * rule: a wrapper that forgets to destructure `correlation` out fails
+				 * here instead of handing the wallet an unrecognised parameter. Nothing
+				 * downstream would catch it, since the viem call is behind an `as any`.
+				 */
+				restArgs: T & {correlation?: never};
 				intendedParams: IntendedTransactionParams;
 				execute: (argsWithNonce: T & {nonce: number}) => Promise<R>;
 				extractHash: (result: R) => Hash;
 			}): Promise<R> {
-				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: CarriedFields<TMetadata, TSource> = {
+					metadata,
+					source,
+					correlation,
+				};
 
 				// Extract common context
 				const {from, intendedNonce} = await extractTransactionContext(args);
@@ -668,14 +792,14 @@ export function createTrackedWalletClient<TMetadata>(
 					from,
 					intendedNonce,
 					walletClient.chain?.id,
-					metadata,
+					carried,
 					broadcastTimestampMs,
 					intendedParams,
 				);
 				emitter.emit('transaction:broadcasted', unknownTx);
 
-				// Fire-and-forget: fetch full data and emit transaction:fetched
-				fetchAndEmitFullData(hash, metadata, broadcastTimestampMs);
+				// Fire-and-forget: fetch full data and emit transaction:known
+				fetchAndEmitFullData(hash, carried, broadcastTimestampMs);
 
 				return result;
 			}
@@ -688,11 +812,26 @@ export function createTrackedWalletClient<TMetadata>(
 			async function executeTrackedRawTransaction<R>(args: {
 				serializedTransaction: TransactionSerialized;
 				metadata: TMetadata;
+				correlation: string | undefined;
 				execute: () => Promise<R>;
 				extractHash: (result: R) => Hash;
 			}): Promise<R> {
-				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: CarriedFields<TMetadata, TSource> = {
+					metadata,
+					source,
+					correlation,
+				};
 
 				const from = await recoverTransactionAddress({serializedTransaction});
 
@@ -707,7 +846,7 @@ export function createTrackedWalletClient<TMetadata>(
 					parsedTx,
 					from,
 					hash,
-					metadata,
+					carried,
 					walletClient.chain?.id,
 					broadcastTimestampMs,
 				);
@@ -715,8 +854,11 @@ export function createTrackedWalletClient<TMetadata>(
 				// 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;
 			}
@@ -756,13 +898,14 @@ export function createTrackedWalletClient<TMetadata>(
 						TChainOverride
 					>,
 				): Promise<Hash> {
-					const {metadata, nonce, ...writeArgs} = args;
+					const {metadata, correlation, nonce, ...writeArgs} = args;
 					const intendedParams = extractIntendedParamsFromWriteContract(args);
 
 					return executeTrackedTransaction({
 						account: normalizeAccount(args.account),
 						nonce,
 						metadata: metadata as TMetadata,
+						correlation,
 						restArgs: writeArgs,
 						intendedParams,
 						execute: (argsWithNonce) =>
@@ -781,13 +924,14 @@ export function createTrackedWalletClient<TMetadata>(
 						TChainOverride
 					>,
 				): Promise<Hash> {
-					const {metadata, nonce, ...sendArgs} = args;
+					const {metadata, correlation, nonce, ...sendArgs} = args;
 					const intendedParams = extractIntendedParamsFromSendTransaction(args);
 
 					return executeTrackedTransaction({
 						account: normalizeAccount(args.account),
 						nonce,
 						metadata: metadata as TMetadata,
+						correlation,
 						restArgs: sendArgs,
 						intendedParams,
 						execute: (argsWithNonce) =>
@@ -799,11 +943,12 @@ export function createTrackedWalletClient<TMetadata>(
 				async sendRawTransaction(
 					args: TrackedRawTransactionParameters<TMetadata>,
 				): Promise<Hash> {
-					const {metadata, serializedTransaction} = args;
+					const {metadata, correlation, serializedTransaction} = args;
 
 					return executeTrackedRawTransaction({
 						serializedTransaction,
 						metadata: metadata as TMetadata,
+						correlation,
 						execute: () =>
 							walletClient.sendRawTransaction({serializedTransaction}),
 						extractHash: (hash) => hash,
@@ -837,13 +982,14 @@ export function createTrackedWalletClient<TMetadata>(
 						TChainOverride
 					>,
 				): Promise<TransactionReceipt> {
-					const {metadata, nonce, ...writeArgs} = args;
+					const {metadata, correlation, nonce, ...writeArgs} = args;
 					const intendedParams = extractIntendedParamsFromWriteContract(args);
 
 					return executeTrackedTransaction({
 						account: normalizeAccount(args.account),
 						nonce,
 						metadata: metadata as TMetadata,
+						correlation,
 						restArgs: writeArgs,
 						intendedParams,
 						execute: (argsWithNonce) =>
@@ -862,13 +1008,14 @@ export function createTrackedWalletClient<TMetadata>(
 						TChainOverride
 					>,
 				): Promise<TransactionReceipt> {
-					const {metadata, nonce, ...sendArgs} = args;
+					const {metadata, correlation, nonce, ...sendArgs} = args;
 					const intendedParams = extractIntendedParamsFromSendTransaction(args);
 
 					return executeTrackedTransaction({
 						account: normalizeAccount(args.account),
 						nonce,
 						metadata: metadata as TMetadata,
+						correlation,
 						restArgs: sendArgs,
 						intendedParams,
 						execute: (argsWithNonce) =>
@@ -880,11 +1027,12 @@ export function createTrackedWalletClient<TMetadata>(
 				async sendRawTransactionSync(
 					args: TrackedRawTransactionParameters<TMetadata>,
 				): Promise<TransactionReceipt> {
-					const {metadata, serializedTransaction} = args;
+					const {metadata, correlation, serializedTransaction} = args;
 
 					return executeTrackedRawTransaction({
 						serializedTransaction,
 						metadata: metadata as TMetadata,
+						correlation,
 						execute: () =>
 							walletClient.sendRawTransactionSync({serializedTransaction}),
 						extractHash: (receipt) => receipt.transactionHash,
@@ -906,9 +1054,10 @@ export function createTrackedWalletClient<TMetadata>(
  * Create an auto-populate builder for TrackedWalletClient.
  * This builder auto-populates operation, functionName and args in writeContract metadata.
  */
-function createAutoPopulateBuilder<TMetadata>(
+function createAutoPopulateBuilder<TMetadata, TSource>(
 	clock: () => number,
-): TrackedWalletClientAutoPopulateBuilder<TMetadata> {
+	sourceOption: TSource | (() => TSource) | undefined,
+): TrackedWalletClientAutoPopulateBuilder<TMetadata, TSource> {
 	return {
 		using<TClient extends WalletClient>(
 			walletClient: TClient,
@@ -917,7 +1066,8 @@ function createAutoPopulateBuilder<TMetadata>(
 			TMetadata,
 			InferTransport<TClient>,
 			InferChain<TClient>,
-			InferAccount<TClient>
+			InferAccount<TClient>,
+			TSource
 		> {
 			// Type aliases for internal use
 			type TTransport = InferTransport<TClient>;
@@ -926,8 +1076,8 @@ function createAutoPopulateBuilder<TMetadata>(
 
 			// Create emitter for transaction events
 			const emitter = new Emitter<{
-				'transaction:broadcasted': TrackedTransaction<TMetadata>;
-				'transaction:fetched': KnownTrackedTransaction<TMetadata>;
+				'transaction:broadcasted': TrackedTransaction<TMetadata, TSource>;
+				'transaction:known': KnownTrackedTransaction<TMetadata, TSource>;
 			}>();
 
 			/**
@@ -969,27 +1119,27 @@ function createAutoPopulateBuilder<TMetadata>(
 			}
 
 			/**
-			 * 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: Hash,
-				metadata: TMetadata,
+				carried: CarriedFields<TMetadata, TSource>,
 				broadcastTimestampMs: number,
 			): Promise<void> {
 				try {
 					const tx = await publicClient.getTransaction({hash});
 					const knownTx = createKnownTrackedTransaction(
 						tx,
-						metadata,
+						carried,
 						broadcastTimestampMs,
 					);
-					emitter.emit('transaction:fetched', knownTx);
+					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}`,
 					);
 				}
 			}
@@ -1026,19 +1176,46 @@ function createAutoPopulateBuilder<TMetadata>(
 			/**
 			 * 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<T, R>(args: {
 				account?: Account | Address;
 				nonce?: NonceOption;
 				metadata: TMetadata;
-				restArgs: T;
+				correlation: string | undefined;
+				/**
+				 * The caller's remaining args, spread verbatim into viem's own call.
+				 *
+				 * `{correlation?: never}` is the compile-time half of the no-forwarding
+				 * rule: a wrapper that forgets to destructure `correlation` out fails
+				 * here instead of handing the wallet an unrecognised parameter. Nothing
+				 * downstream would catch it, since the viem call is behind an `as any`.
+				 */
+				restArgs: T & {correlation?: never};
 				intendedParams: IntendedTransactionParams;
 				execute: (argsWithNonce: T & {nonce: number}) => Promise<R>;
 				extractHash: (result: R) => Hash;
 			}): Promise<R> {
-				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: CarriedFields<TMetadata, TSource> = {
+					metadata,
+					source,
+					correlation,
+				};
 
 				const {from, intendedNonce} = await extractTransactionContext(args);
 
@@ -1056,14 +1233,14 @@ function createAutoPopulateBuilder<TMetadata>(
 					from,
 					intendedNonce,
 					walletClient.chain?.id,
-					metadata,
+					carried,
 					broadcastTimestampMs,
 					intendedParams,
 				);
 				emitter.emit('transaction:broadcasted', unknownTx);
 
-				// Fire-and-forget: fetch full data and emit transaction:fetched
-				fetchAndEmitFullData(hash, metadata, broadcastTimestampMs);
+				// Fire-and-forget: fetch full data and emit transaction:known
+				fetchAndEmitFullData(hash, carried, broadcastTimestampMs);
 
 				return result;
 			}
@@ -1076,11 +1253,26 @@ function createAutoPopulateBuilder<TMetadata>(
 			async function executeTrackedRawTransaction<R>(args: {
 				serializedTransaction: TransactionSerialized;
 				metadata: TMetadata;
+				correlation: string | undefined;
 				execute: () => Promise<R>;
 				extractHash: (result: R) => Hash;
 			}): Promise<R> {
-				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: CarriedFields<TMetadata, TSource> = {
+					metadata,
+					source,
+					correlation,
+				};
 
 				const from = await recoverTransactionAddress({serializedTransaction});
 				const parsedTx = parseTransaction(serializedTransaction);
@@ -1094,7 +1286,7 @@ function createAutoPopulateBuilder<TMetadata>(
 					parsedTx,
 					from,
 					hash,
-					metadata,
+					carried,
 					walletClient.chain?.id,
 					broadcastTimestampMs,
 				);
@@ -1102,7 +1294,11 @@ function createAutoPopulateBuilder<TMetadata>(
 				// 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;
 			}
@@ -1142,7 +1338,12 @@ function createAutoPopulateBuilder<TMetadata>(
 						TChainOverride
 					>,
 				): Promise<Hash> {
-					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);
@@ -1161,6 +1362,7 @@ function createAutoPopulateBuilder<TMetadata>(
 						account: normalizeAccount(args.account),
 						nonce,
 						metadata: finalMetadata,
+						correlation,
 						restArgs: writeArgs,
 						intendedParams,
 						execute: (argsWithNonce) =>
@@ -1179,13 +1381,14 @@ function createAutoPopulateBuilder<TMetadata>(
 						TChainOverride
 					>,
 				): Promise<Hash> {
-					const {metadata, nonce, ...sendArgs} = args;
+					const {metadata, correlation, nonce, ...sendArgs} = args;
 					const intendedParams = extractIntendedParamsFromSendTransaction(args);
 
 					return executeTrackedTransaction({
 						account: normalizeAccount(args.account),
 						nonce,
 						metadata: metadata as TMetadata,
+						correlation,
 						restArgs: sendArgs,
 						intendedParams,
 						execute: (argsWithNonce) =>
@@ -1197,11 +1400,12 @@ function createAutoPopulateBuilder<TMetadata>(
 				async sendRawTransaction(
 					args: TrackedRawTransactionParameters<TMetadata>,
 				): Promise<Hash> {
-					const {metadata, serializedTransaction} = args;
+					const {metadata, correlation, serializedTransaction} = args;
 
 					return executeTrackedRawTransaction({
 						serializedTransaction,
 						metadata: metadata as TMetadata,
+						correlation,
 						execute: () =>
 							walletClient.sendRawTransaction({serializedTransaction}),
 						extractHash: (hash) => hash,
@@ -1235,7 +1439,12 @@ function createAutoPopulateBuilder<TMetadata>(
 						TChainOverride
 					>,
 				): Promise<TransactionReceipt> {
-					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);
@@ -1254,6 +1463,7 @@ function createAutoPopulateBuilder<TMetadata>(
 						account: normalizeAccount(args.account),
 						nonce,
 						metadata: finalMetadata,
+						correlation,
 						restArgs: writeArgs,
 						intendedParams,
 						execute: (argsWithNonce) =>
@@ -1272,13 +1482,14 @@ function createAutoPopulateBuilder<TMetadata>(
 						TChainOverride
 					>,
 				): Promise<TransactionReceipt> {
-					const {metadata, nonce, ...sendArgs} = args;
+					const {metadata, correlation, nonce, ...sendArgs} = args;
 					const intendedParams = extractIntendedParamsFromSendTransaction(args);
 
 					return executeTrackedTransaction({
 						account: normalizeAccount(args.account),
 						nonce,
 						metadata: metadata as TMetadata,
+						correlation,
 						restArgs: sendArgs,
 						intendedParams,
 						execute: (argsWithNonce) =>
@@ -1290,11 +1501,12 @@ function createAutoPopulateBuilder<TMetadata>(
 				async sendRawTransactionSync(
 					args: TrackedRawTransactionParameters<TMetadata>,
 				): Promise<TransactionReceipt> {
-					const {metadata, serializedTransaction} = args;
+					const {metadata, correlation, serializedTransaction} = args;
 
 					return executeTrackedRawTransaction({
 						serializedTransaction,
 						metadata: metadata as TMetadata,
+						correlation,
 						execute: () =>
 							walletClient.sendRawTransactionSync({serializedTransaction}),
 						extractHash: (receipt) => receipt.transactionHash,