@etherkit/viem-tx-tracker 0.0.4 → 0.0.6

package/src/TrackedWalletClient.ts

@@ -1,5 +1,6 @@
 import {
 	parseTransaction,
+	ParseTransactionReturnType,
 	recoverTransactionAddress,
 	type Abi,
 	type Account,
@@ -9,6 +10,7 @@ import {
 	type ContractFunctionName,
 	type Hash,
 	type PublicClient,
+	type Transaction,
 	type TransactionReceipt,
 	type TransactionSerialized,
 	type Transport,
@@ -16,14 +18,20 @@ import {
 } from 'viem';
 import {Emitter} from 'radiate';
 import type {
+	AccessList,
 	BlockTag,
-	MetadataField,
+	CreateTrackedWalletClientOptions,
+	KnownTrackedTransaction,
 	NonceOption,
+	PopulatedMetadata,
 	TrackedRawTransactionParameters,
 	TrackedSendTransactionParameters,
 	TrackedTransaction,
 	TrackedWalletClient,
+	TrackedWalletClientAutoPopulate,
+	TrackedWriteContractAutoPopulateParameters,
 	TrackedWriteContractParameters,
+	UnknownTrackedTransaction,
 } from './types.js';
 
 /**
@@ -56,13 +64,6 @@ function normalizeAccount(
 	return account === null ? undefined : account;
 }
 
-/**
- * Generate a unique tracking ID if not provided in metadata
- */
-function generateTrackingId(): string {
-	return crypto.randomUUID();
-}
-
 /**
  * Context for transaction tracking - common data extracted from request
  */
@@ -71,6 +72,253 @@ interface TransactionContext {
 	intendedNonce: number;
 }
 
+/**
+ * Parameters we can extract from writeContract/sendTransaction calls.
+ * These are the intended values - wallet may modify them.
+ */
+interface IntendedTransactionParams {
+	to?: Address | null;
+	value?: bigint;
+	data?: `0x${string}`;
+	gas?: bigint;
+	gasPrice?: bigint;
+	maxFeePerGas?: bigint;
+	maxPriorityFeePerGas?: bigint;
+	accessList?: AccessList;
+}
+
+/**
+ * Infer transaction type from provided params.
+ * Returns undefined if can't be determined (wallet will decide).
+ */
+function inferTxType(
+	params: IntendedTransactionParams,
+): 'eip1559' | 'legacy' | 'eip2930' | undefined {
+	if (params.maxFeePerGas !== undefined) {
+		return 'eip1559';
+	}
+	if (params.gasPrice !== undefined && params.accessList !== undefined) {
+		return 'eip2930';
+	}
+	if (params.gasPrice !== undefined) {
+		return 'legacy';
+	}
+	return undefined; // Wallet will determine
+}
+
+/**
+ * Create an UnknownTrackedTransaction for immediate emission.
+ * Populates all known intended values from the transaction parameters.
+ */
+function createUnknownTrackedTransaction<TMetadata>(
+	hash: Hash,
+	from: Address,
+	nonce: number | undefined,
+	chainId: number | undefined,
+	metadata: TMetadata,
+	broadcastTimestampMs: number,
+	params: IntendedTransactionParams,
+): UnknownTrackedTransaction<TMetadata> {
+	const txType = inferTxType(params);
+	return {
+		known: false,
+		chainId,
+		hash,
+		from,
+		nonce,
+		broadcastTimestampMs,
+		metadata,
+		...(txType !== undefined && {txType}),
+		...(params.to !== undefined && {to: params.to}),
+		...(params.value !== undefined && {value: params.value}),
+		...(params.data !== undefined && {data: params.data}),
+		...(params.gas !== undefined && {gas: params.gas}),
+		...(params.gasPrice !== undefined && {gasPrice: params.gasPrice}),
+		...(params.maxFeePerGas !== undefined && {
+			maxFeePerGas: params.maxFeePerGas,
+		}),
+		...(params.maxPriorityFeePerGas !== undefined && {
+			maxPriorityFeePerGas: params.maxPriorityFeePerGas,
+		}),
+		...(params.accessList !== undefined && {accessList: params.accessList}),
+	};
+}
+
+/**
+ * Extract transaction type-specific fields from a fetched transaction.
+ */
+function extractTransactionTypeFields(tx: Transaction): {
+	txType: 'eip1559' | 'legacy' | 'eip2930';
+	gasPrice?: bigint;
+	maxFeePerGas?: bigint;
+	maxPriorityFeePerGas?: bigint;
+	accessList?: AccessList;
+} {
+	if (tx.type === 'eip1559') {
+		return {
+			txType: 'eip1559',
+			maxFeePerGas: tx.maxFeePerGas!,
+			maxPriorityFeePerGas: tx.maxPriorityFeePerGas!,
+			...(tx.accessList && {accessList: tx.accessList as AccessList}),
+		};
+	} else if (tx.type === 'eip2930') {
+		return {
+			txType: 'eip2930',
+			gasPrice: tx.gasPrice!,
+			accessList: (tx.accessList ?? []) as AccessList,
+		};
+	} else {
+		// Legacy or unknown - treat as legacy
+		return {
+			txType: 'legacy',
+			gasPrice: tx.gasPrice!,
+		};
+	}
+}
+
+/**
+ * Create a KnownTrackedTransaction from a fetched transaction.
+ */
+function createKnownTrackedTransaction<TMetadata>(
+	tx: Transaction,
+	metadata: TMetadata,
+	broadcastTimestampMs: number,
+): KnownTrackedTransaction<TMetadata> {
+	const typeFields = extractTransactionTypeFields(tx);
+
+	return {
+		known: true,
+		chainId: tx.chainId!,
+		hash: tx.hash,
+		from: tx.from,
+		to: tx.to,
+		nonce: tx.nonce,
+		value: tx.value,
+		data: tx.input,
+		gas: tx.gas,
+		broadcastTimestampMs,
+		metadata,
+		...typeFields,
+	} as KnownTrackedTransaction<TMetadata>;
+}
+
+/**
+ * Create a KnownTrackedTransaction from a parsed raw transaction.
+ */
+function createKnownTrackedTransactionFromRaw<TMetadata>(
+	parsedTx: ParseTransactionReturnType<`0x${string}`>,
+	from: `0x${string}`,
+	hash: Hash,
+	metadata: TMetadata,
+	chainId: number | undefined,
+	broadcastTimestampMs: number,
+): KnownTrackedTransaction<TMetadata> {
+	// Determine transaction type from parsed tx
+	let typeFields: {
+		txType: 'eip1559' | 'legacy' | 'eip2930';
+		gasPrice?: bigint;
+		maxFeePerGas?: bigint;
+		maxPriorityFeePerGas?: bigint;
+		accessList?: AccessList;
+	};
+
+	if ('maxFeePerGas' in parsedTx && parsedTx.maxFeePerGas !== undefined) {
+		typeFields = {
+			txType: 'eip1559',
+			maxFeePerGas: parsedTx.maxFeePerGas,
+			maxPriorityFeePerGas: parsedTx.maxPriorityFeePerGas!,
+			...('accessList' in parsedTx &&
+				parsedTx.accessList && {
+					accessList: parsedTx.accessList as AccessList,
+				}),
+		};
+	} else if ('accessList' in parsedTx && parsedTx.accessList) {
+		typeFields = {
+			txType: 'eip2930',
+			gasPrice: parsedTx.gasPrice!,
+			accessList: parsedTx.accessList as AccessList,
+		};
+	} else {
+		typeFields = {
+			txType: 'legacy',
+			gasPrice: parsedTx.gasPrice!,
+		};
+	}
+
+	return {
+		known: true,
+		chainId: parsedTx.chainId ?? chainId!,
+		hash,
+		from,
+		to: parsedTx.to ?? null,
+		nonce: parsedTx.nonce!,
+		value: parsedTx.value ?? 0n,
+		data: parsedTx.data ?? '0x',
+		gas: parsedTx.gas!,
+		broadcastTimestampMs,
+		metadata,
+		...typeFields,
+	} as KnownTrackedTransaction<TMetadata>;
+}
+
+/**
+ * Extract intended params from sendTransaction args.
+ * Uses 'unknown' for 'to' since viem's SendTransactionParameters has a complex type for it.
+ */
+function extractIntendedParamsFromSendTransaction(args: {
+	to?: unknown;
+	value?: bigint;
+	data?: `0x${string}`;
+	gas?: bigint;
+	gasPrice?: bigint;
+	maxFeePerGas?: bigint;
+	maxPriorityFeePerGas?: bigint;
+	accessList?: AccessList;
+}): IntendedTransactionParams {
+	// Normalize 'to' to either a hex address, null, or undefined
+	const to =
+		args.to === null || args.to === undefined
+			? (args.to as null | undefined)
+			: typeof args.to === 'string'
+				? (args.to as Address)
+				: undefined;
+
+	return {
+		to,
+		value: args.value ?? 0n,
+		data: args.data,
+		gas: args.gas,
+		gasPrice: args.gasPrice,
+		maxFeePerGas: args.maxFeePerGas,
+		maxPriorityFeePerGas: args.maxPriorityFeePerGas,
+		accessList: args.accessList,
+	};
+}
+
+/**
+ * Extract intended params from writeContract args.
+ */
+function extractIntendedParamsFromWriteContract(args: {
+	address: Address;
+	value?: bigint;
+	gas?: bigint;
+	gasPrice?: bigint;
+	maxFeePerGas?: bigint;
+	maxPriorityFeePerGas?: bigint;
+	accessList?: AccessList;
+}): IntendedTransactionParams {
+	return {
+		to: args.address,
+		value: args.value ?? 0n,
+		// Note: data could be encoded using encodeFunctionData(args) if desired
+		gas: args.gas,
+		gasPrice: args.gasPrice,
+		maxFeePerGas: args.maxFeePerGas,
+		maxPriorityFeePerGas: args.maxPriorityFeePerGas,
+		accessList: args.accessList,
+	};
+}
+
 /**
  * Infer transport type from WalletClient
  */
@@ -113,6 +361,31 @@ export interface TrackedWalletClientBuilder<TMetadata> {
 	>;
 }
 
+/**
+ * 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> {
+	/**
+	 * Create the tracked wallet client using the provided wallet and public clients.
+	 * writeContract and writeContractSync will automatically populate operation, functionName and args.
+	 *
+	 * @param walletClient - The underlying viem WalletClient
+	 * @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>
+	>;
+}
+
 /**
  * Create a tracked wallet client that wraps a viem WalletClient.
  *
@@ -127,18 +400,54 @@ export interface TrackedWalletClientBuilder<TMetadata> {
  *
  * @example
  * ```typescript
- * // With required metadata
+ * // Standard mode with required metadata
  * const tracked = createTrackedWalletClient<{purpose: string}>()
  *   .using(walletClient, publicClient);
  *
- * // With optional metadata
+ * // Standard mode with optional metadata
  * const tracked = createTrackedWalletClient<{purpose: string} | undefined>()
  *   .using(walletClient, publicClient);
+ *
+ * // Auto-populate mode - functionName and args are auto-populated
+ * const tracked = createTrackedWalletClient({ populateMetadata: true })
+ *   .using(walletClient, publicClient);
+ *
+ * // Auto-populate mode with extended metadata
+ * type MyMetadata = OperationMetadata & { purpose: string };
+ * const tracked = createTrackedWalletClient<MyMetadata>({ populateMetadata: true })
+ *   .using(walletClient, publicClient);
  * ```
  */
+// Overload 1: Standard mode, no options
 export function createTrackedWalletClient<
 	TMetadata,
->(): TrackedWalletClientBuilder<TMetadata> {
+>(): TrackedWalletClientBuilder<TMetadata>;
+
+// Overload 2: Auto-populate mode with default PopulatedMetadata
+export function createTrackedWalletClient(options: {
+	populateMetadata: true;
+}): TrackedWalletClientAutoPopulateBuilder<PopulatedMetadata>;
+
+// Overload 3: Auto-populate mode with custom metadata (must allow FunctionCallMetadata)
+export function createTrackedWalletClient<TMetadata>(options: {
+	populateMetadata: true;
+}): TrackedWalletClientAutoPopulateBuilder<TMetadata>;
+
+// Implementation
+export function createTrackedWalletClient<TMetadata>(
+	options?: CreateTrackedWalletClientOptions<boolean>,
+):
+	| TrackedWalletClientBuilder<TMetadata>
+	| TrackedWalletClientAutoPopulateBuilder<TMetadata> {
+	const populateMetadata = options?.populateMetadata ?? false;
+	const clock = options?.clock ?? Date.now;
+
+	if (populateMetadata) {
+		return createAutoPopulateBuilder<TMetadata>(
+			clock,
+		) as TrackedWalletClientAutoPopulateBuilder<TMetadata>;
+	}
+
 	return {
 		using<TClient extends WalletClient>(
 			walletClient: TClient,
@@ -154,9 +463,10 @@ export function createTrackedWalletClient<
 			type TChain = InferChain<TClient>;
 			type TAccount = InferAccount<TClient>;
 
-			// Create emitter for transaction broadcast events
+			// Create emitter for transaction events
 			const emitter = new Emitter<{
 				'transaction:broadcasted': TrackedTransaction<TMetadata>;
+				'transaction:fetched': KnownTrackedTransaction<TMetadata>;
 			}>();
 
 			/**
@@ -212,106 +522,440 @@ export function createTrackedWalletClient<
 			}
 
 			/**
-			 * Extract transaction context from a serialized (signed) transaction.
-			 * Parses the transaction and recovers the sender address.
-			 *
-			 * @param serializedTransaction - The RLP-encoded signed transaction
-			 * @returns TransactionContext with from address and nonce
+			 * Fetch full transaction data and emit transaction:fetched event.
+			 * Non-blocking, runs in background. Does not throw.
 			 */
-			async function extractRawTransactionContext(
-				serializedTransaction: TransactionSerialized,
-			): Promise<TransactionContext> {
-				// Parse the serialized transaction to get the nonce
-				const parsedTx = parseTransaction(serializedTransaction);
-
-				if (parsedTx.nonce === undefined) {
-					throw new Error(
-						'[TrackedWalletClient] Could not extract nonce from serialized transaction.',
+			async function fetchAndEmitFullData(
+				hash: Hash,
+				metadata: TMetadata,
+				broadcastTimestampMs: number,
+			): Promise<void> {
+				try {
+					const tx = await publicClient.getTransaction({hash});
+					const knownTx = createKnownTrackedTransaction(
+						tx,
+						metadata,
+						broadcastTimestampMs,
+					);
+					emitter.emit('transaction:fetched', knownTx);
+				} catch (error) {
+					// Log but don't throw - transaction:fetched simply won't fire
+					console.warn(
+						`[TrackedWalletClient] Could not fetch tx ${hash}. ` +
+							`transaction:fetched 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.
+			 */
+			async function executeTrackedTransaction<T, R>(args: {
+				account?: Account | Address;
+				nonce?: NonceOption;
+				metadata: TMetadata;
+				restArgs: T;
+				intendedParams: IntendedTransactionParams;
+				execute: (argsWithNonce: T & {nonce: number}) => Promise<R>;
+				extractHash: (result: R) => Hash;
+			}): Promise<R> {
+				const {metadata, restArgs, intendedParams, execute, extractHash} = args;
+				const broadcastTimestampMs = clock();
 
-				// Recover the sender address from the signature
-				const from = await recoverTransactionAddress({
-					serializedTransaction,
+				// Extract common context
+				const {from, intendedNonce} = await extractTransactionContext(args);
+
+				// Execute the underlying transaction with nonce injected
+				const result = await execute({
+					...restArgs,
+					nonce: intendedNonce,
+				} as T & {
+					nonce: number;
 				});
+				const hash = extractHash(result);
 
-				return {
+				// Emit transaction:broadcasted immediately with intended values
+				const unknownTx = createUnknownTrackedTransaction(
+					hash,
 					from,
-					intendedNonce: parsedTx.nonce,
-				};
+					intendedNonce,
+					walletClient.chain?.id,
+					metadata,
+					broadcastTimestampMs,
+					intendedParams,
+				);
+				emitter.emit('transaction:broadcasted', unknownTx);
+
+				// Fire-and-forget: fetch full data and emit transaction:fetched
+				fetchAndEmitFullData(hash, metadata, broadcastTimestampMs);
+
+				return result;
 			}
 
 			/**
-			 * Fetch the transaction after broadcast to verify nonce.
-			 * Logs a warning if the nonce was overridden or if tx cannot be found.
-			 *
-			 * @param hash - The transaction hash
-			 * @param intendedNonce - The nonce we intended to use
-			 * @returns The actual nonce, or the intended nonce if fetch failed
+			 * Common wrapper for raw transaction broadcasts (sendRawTransaction).
+			 * For raw transactions, we can parse full data immediately.
+			 * Emits KnownTrackedTransaction directly to transaction:broadcasted.
 			 */
-			async function verifyTransactionNonce(
-				hash: Hash,
-				intendedNonce: number,
+			async function executeTrackedRawTransaction<R>(args: {
+				serializedTransaction: TransactionSerialized;
+				metadata: TMetadata;
+				execute: () => Promise<R>;
+				extractHash: (result: R) => Hash;
+			}): Promise<R> {
+				const {serializedTransaction, metadata, execute, extractHash} = args;
+				const broadcastTimestampMs = clock();
+
+				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,
+					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);
+
+				return result;
+			}
+
+			return {
+				walletClient: walletClient as unknown as WalletClient<
+					TTransport,
+					TChain,
+					TAccount
+				>,
+				publicClient,
+
+				// ============================================
+				// Async methods (return hash)
+				// ============================================
+
+				async writeContract<
+					const TAbi extends Abi | readonly unknown[],
+					TFunctionName extends ContractFunctionName<
+						TAbi,
+						'nonpayable' | 'payable'
+					>,
+					TArgs extends ContractFunctionArgs<
+						TAbi,
+						'nonpayable' | 'payable',
+						TFunctionName
+					>,
+					TChainOverride extends Chain | undefined = undefined,
+				>(
+					args: TrackedWriteContractParameters<
+						TMetadata,
+						TAbi,
+						TFunctionName,
+						TArgs,
+						TChain,
+						TAccount,
+						TChainOverride
+					>,
+				): Promise<Hash> {
+					const {metadata, nonce, ...writeArgs} = args;
+					const intendedParams = extractIntendedParamsFromWriteContract(args);
+
+					return executeTrackedTransaction({
+						account: normalizeAccount(args.account),
+						nonce,
+						metadata: metadata as TMetadata,
+						restArgs: writeArgs,
+						intendedParams,
+						execute: (argsWithNonce) =>
+							walletClient.writeContract(argsWithNonce as any),
+						extractHash: (hash) => hash,
+					});
+				},
+
+				async sendTransaction<
+					TChainOverride extends Chain | undefined = undefined,
+				>(
+					args: TrackedSendTransactionParameters<
+						TMetadata,
+						TChain,
+						TAccount,
+						TChainOverride
+					>,
+				): Promise<Hash> {
+					const {metadata, nonce, ...sendArgs} = args;
+					const intendedParams = extractIntendedParamsFromSendTransaction(args);
+
+					return executeTrackedTransaction({
+						account: normalizeAccount(args.account),
+						nonce,
+						metadata: metadata as TMetadata,
+						restArgs: sendArgs,
+						intendedParams,
+						execute: (argsWithNonce) =>
+							walletClient.sendTransaction(argsWithNonce as any),
+						extractHash: (hash) => hash,
+					});
+				},
+
+				async sendRawTransaction(
+					args: TrackedRawTransactionParameters<TMetadata>,
+				): Promise<Hash> {
+					const {metadata, serializedTransaction} = args;
+
+					return executeTrackedRawTransaction({
+						serializedTransaction,
+						metadata: metadata as TMetadata,
+						execute: () =>
+							walletClient.sendRawTransaction({serializedTransaction}),
+						extractHash: (hash) => hash,
+					});
+				},
+
+				// ============================================
+				// Sync methods (return receipt, wait for confirmation)
+				// ============================================
+
+				async writeContractSync<
+					const TAbi extends Abi | readonly unknown[],
+					TFunctionName extends ContractFunctionName<
+						TAbi,
+						'nonpayable' | 'payable'
+					>,
+					TArgs extends ContractFunctionArgs<
+						TAbi,
+						'nonpayable' | 'payable',
+						TFunctionName
+					>,
+					TChainOverride extends Chain | undefined = undefined,
+				>(
+					args: TrackedWriteContractParameters<
+						TMetadata,
+						TAbi,
+						TFunctionName,
+						TArgs,
+						TChain,
+						TAccount,
+						TChainOverride
+					>,
+				): Promise<TransactionReceipt> {
+					const {metadata, nonce, ...writeArgs} = args;
+					const intendedParams = extractIntendedParamsFromWriteContract(args);
+
+					return executeTrackedTransaction({
+						account: normalizeAccount(args.account),
+						nonce,
+						metadata: metadata as TMetadata,
+						restArgs: writeArgs,
+						intendedParams,
+						execute: (argsWithNonce) =>
+							walletClient.writeContractSync(argsWithNonce as any),
+						extractHash: (receipt) => receipt.transactionHash,
+					});
+				},
+
+				async sendTransactionSync<
+					TChainOverride extends Chain | undefined = undefined,
+				>(
+					args: TrackedSendTransactionParameters<
+						TMetadata,
+						TChain,
+						TAccount,
+						TChainOverride
+					>,
+				): Promise<TransactionReceipt> {
+					const {metadata, nonce, ...sendArgs} = args;
+					const intendedParams = extractIntendedParamsFromSendTransaction(args);
+
+					return executeTrackedTransaction({
+						account: normalizeAccount(args.account),
+						nonce,
+						metadata: metadata as TMetadata,
+						restArgs: sendArgs,
+						intendedParams,
+						execute: (argsWithNonce) =>
+							walletClient.sendTransactionSync(argsWithNonce as any),
+						extractHash: (receipt) => receipt.transactionHash,
+					});
+				},
+
+				async sendRawTransactionSync(
+					args: TrackedRawTransactionParameters<TMetadata>,
+				): Promise<TransactionReceipt> {
+					const {metadata, serializedTransaction} = args;
+
+					return executeTrackedRawTransaction({
+						serializedTransaction,
+						metadata: metadata as TMetadata,
+						execute: () =>
+							walletClient.sendRawTransactionSync({serializedTransaction}),
+						extractHash: (receipt) => receipt.transactionHash,
+					});
+				},
+
+				// ============================================
+				// Event subscription methods
+				// ============================================
+
+				on: emitter.on.bind(emitter),
+				off: emitter.off.bind(emitter),
+			};
+		},
+	};
+}
+
+/**
+ * Create an auto-populate builder for TrackedWalletClient.
+ * This builder auto-populates operation, functionName and args in writeContract metadata.
+ */
+function createAutoPopulateBuilder<TMetadata>(
+	clock: () => number,
+): TrackedWalletClientAutoPopulateBuilder<TMetadata> {
+	return {
+		using<TClient extends WalletClient>(
+			walletClient: TClient,
+			publicClient: PublicClient,
+		): TrackedWalletClientAutoPopulate<
+			TMetadata,
+			InferTransport<TClient>,
+			InferChain<TClient>,
+			InferAccount<TClient>
+		> {
+			// Type aliases for internal use
+			type TTransport = InferTransport<TClient>;
+			type TChain = InferChain<TClient>;
+			type TAccount = InferAccount<TClient>;
+
+			// Create emitter for transaction events
+			const emitter = new Emitter<{
+				'transaction:broadcasted': TrackedTransaction<TMetadata>;
+				'transaction:fetched': KnownTrackedTransaction<TMetadata>;
+			}>();
+
+			/**
+			 * Resolve the nonce to use for a transaction.
+			 */
+			async function resolveNonce(
+				nonceOption: NonceOption | undefined,
+				from: Address,
 			): Promise<number> {
-				try {
-					const tx = await publicClient.getTransaction({hash});
-					const actualNonce = tx.nonce;
+				if (typeof nonceOption === 'number') {
+					return nonceOption;
+				}
+				const blockTag = isBlockTag(nonceOption) ? nonceOption : 'pending';
+				return await publicClient.getTransactionCount({
+					address: from,
+					blockTag,
+				});
+			}
 
-					if (actualNonce !== intendedNonce) {
-						console.warn(
-							`[TrackedWalletClient] Nonce mismatch: intended ${intendedNonce}, actual ${actualNonce}. ` +
-								`Wallet may have overridden the nonce.`,
-						);
-					}
+			/**
+			 * Extract common transaction context (account, nonce) from request args.
+			 */
+			async function extractTransactionContext(args: {
+				account?: Account | Address;
+				nonce?: NonceOption;
+			}): Promise<TransactionContext> {
+				const account = args.account ?? walletClient.account;
+				const from = resolveAccountAddress(account);
 
-					return actualNonce;
-				} catch (fetchError) {
-					// Transaction not found in mempool/chain yet
-					console.warn(
-						`[TrackedWalletClient] Could not fetch tx ${hash} after broadcast. ` +
-							`It may not be in the mempool yet.`,
+				if (!from) {
+					throw new Error(
+						'[TrackedWalletClient] No account available. ' +
+							'Provide an account in the request or configure the wallet client with an account.',
 					);
-					return intendedNonce;
 				}
+
+				const intendedNonce = await resolveNonce(args.nonce, from);
+				return {from, intendedNonce};
 			}
 
 			/**
-			 * Create a tracked transaction record.
+			 * Fetch full transaction data and emit transaction:fetched event.
+			 * Non-blocking, runs in background. Does not throw.
 			 */
-			function createTrackedTransactionRecord(
-				txHash: Hash,
-				from: Address,
-				nonce: number,
+			async function fetchAndEmitFullData(
+				hash: Hash,
 				metadata: TMetadata,
-			): TrackedTransaction<TMetadata> {
-				return {
-					hash: txHash,
-					from,
-					nonce,
-					chainId: walletClient.chain?.id,
-					metadata,
-					broadcastTimestampMs: Date.now(),
-				};
+				broadcastTimestampMs: number,
+			): Promise<void> {
+				try {
+					const tx = await publicClient.getTransaction({hash});
+					const knownTx = createKnownTrackedTransaction(
+						tx,
+						metadata,
+						broadcastTimestampMs,
+					);
+					emitter.emit('transaction:fetched', knownTx);
+				} catch (error) {
+					// Log but don't throw - transaction:fetched simply won't fire
+					console.warn(
+						`[TrackedWalletClient] Could not fetch tx ${hash}. ` +
+							`transaction:fetched event will not be emitted. Error: ${error}`,
+					);
+				}
 			}
 
 			/**
-			 * Common wrapper for transaction methods that broadcast (sendTransaction, writeContract).
-			 * Handles nonce resolution, underlying call, post-broadcast verification, and tracking record creation.
+			 * Validate that user didn't provide operation, functionName or args in metadata
+			 * when populateMetadata is enabled.
+			 */
+			function validateNoAutoPopulatedFieldsInMetadata(
+				userMetadata: unknown,
+			): void {
+				if (userMetadata && typeof userMetadata === 'object') {
+					if ('type' in userMetadata) {
+						throw new Error(
+							'[TrackedWalletClient] Cannot specify type in metadata when populateMetadata is enabled. ' +
+								'The type is automatically populated from the contract call.',
+						);
+					}
+					if ('functionName' in userMetadata) {
+						throw new Error(
+							'[TrackedWalletClient] Cannot specify functionName in metadata when populateMetadata is enabled. ' +
+								'The functionName is automatically populated from the contract call.',
+						);
+					}
+					if ('args' in userMetadata) {
+						throw new Error(
+							'[TrackedWalletClient] Cannot specify args in metadata when populateMetadata is enabled. ' +
+								'The args are automatically populated from the contract call.',
+						);
+					}
+				}
+			}
+
+			/**
+			 * Common wrapper for transaction methods that broadcast.
+			 * Emits transaction:broadcasted immediately with intended values,
+			 * then fetches and emits transaction:fetched with actual values.
 			 */
 			async function executeTrackedTransaction<T, R>(args: {
 				account?: Account | Address;
 				nonce?: NonceOption;
 				metadata: TMetadata;
 				restArgs: T;
+				intendedParams: IntendedTransactionParams;
 				execute: (argsWithNonce: T & {nonce: number}) => Promise<R>;
 				extractHash: (result: R) => Hash;
 			}): Promise<R> {
-				const {metadata, restArgs, execute, extractHash} = args;
+				const {metadata, restArgs, intendedParams, execute, extractHash} = args;
+				const broadcastTimestampMs = clock();
 
-				// Extract common context
 				const {from, intendedNonce} = await extractTransactionContext(args);
 
-				// Execute the underlying transaction with nonce injected
 				const result = await execute({
 					...restArgs,
 					nonce: intendedNonce,
@@ -320,26 +964,28 @@ export function createTrackedWalletClient<
 				});
 				const hash = extractHash(result);
 
-				// Verify transaction and get actual nonce
-				const actualNonce = await verifyTransactionNonce(hash, intendedNonce);
-
-				// Create tracked transaction record
-				const trackedTx = createTrackedTransactionRecord(
+				// Emit transaction:broadcasted immediately with intended values
+				const unknownTx = createUnknownTrackedTransaction(
 					hash,
 					from,
-					actualNonce,
+					intendedNonce,
+					walletClient.chain?.id,
 					metadata,
+					broadcastTimestampMs,
+					intendedParams,
 				);
+				emitter.emit('transaction:broadcasted', unknownTx);
 
-				// Emit transaction broadcasted event
-				emitter.emit('transaction:broadcasted', trackedTx);
+				// Fire-and-forget: fetch full data and emit transaction:fetched
+				fetchAndEmitFullData(hash, metadata, broadcastTimestampMs);
 
 				return result;
 			}
 
 			/**
-			 * Common wrapper for raw transaction broadcasts (sendRawTransaction).
-			 * Decodes the transaction to extract from/nonce, broadcasts, and creates tracking record.
+			 * Common wrapper for raw transaction broadcasts.
+			 * For raw transactions, we can parse full data immediately.
+			 * Emits KnownTrackedTransaction directly to transaction:broadcasted.
 			 */
 			async function executeTrackedRawTransaction<R>(args: {
 				serializedTransaction: TransactionSerialized;
@@ -348,29 +994,29 @@ export function createTrackedWalletClient<
 				extractHash: (result: R) => Hash;
 			}): Promise<R> {
 				const {serializedTransaction, metadata, execute, extractHash} = args;
+				const broadcastTimestampMs = clock();
 
-				// Extract context from the serialized transaction
-				const {from, intendedNonce} = await extractRawTransactionContext(
-					serializedTransaction,
-				);
+				const from = await recoverTransactionAddress({serializedTransaction});
+				const parsedTx = parseTransaction(serializedTransaction);
 
 				// Execute the broadcast
 				const result = await execute();
 				const hash = extractHash(result);
 
-				// For raw transactions, the nonce is already embedded, so no verification needed
-				// (wallet cannot override nonce in an already-signed transaction)
-
-				// Create tracked transaction record
-				const trackedTx = createTrackedTransactionRecord(
-					hash,
+				// For raw transactions, we can parse full data immediately
+				const knownTx = createKnownTrackedTransactionFromRaw(
+					parsedTx,
 					from,
-					intendedNonce,
+					hash,
 					metadata,
+					walletClient.chain?.id,
+					broadcastTimestampMs,
 				);
 
-				// Emit transaction broadcasted event
-				emitter.emit('transaction:broadcasted', trackedTx);
+				// Emit as KnownTrackedTransaction since we have all data
+				emitter.emit('transaction:broadcasted', knownTx);
+
+				// We do not emit fetched as the tx is already known
 
 				return result;
 			}
@@ -400,7 +1046,7 @@ export function createTrackedWalletClient<
 					>,
 					TChainOverride extends Chain | undefined = undefined,
 				>(
-					args: TrackedWriteContractParameters<
+					args: TrackedWriteContractAutoPopulateParameters<
 						TMetadata,
 						TAbi,
 						TFunctionName,
@@ -410,13 +1056,27 @@ export function createTrackedWalletClient<
 						TChainOverride
 					>,
 				): Promise<Hash> {
-					const {metadata, nonce, ...writeArgs} = args;
+					const {metadata: userMetadata, nonce, ...writeArgs} = args;
+
+					// Validate that user didn't provide operation, functionName or args
+					validateNoAutoPopulatedFieldsInMetadata(userMetadata);
+
+					// Auto-populate type, functionName and args
+					const finalMetadata = {
+						...(userMetadata ?? {}),
+						type: 'functionCall' as const,
+						functionName: args.functionName as string,
+						args: args.args as readonly unknown[],
+					} as TMetadata;
+
+					const intendedParams = extractIntendedParamsFromWriteContract(args);
 
 					return executeTrackedTransaction({
 						account: normalizeAccount(args.account),
 						nonce,
-						metadata: metadata as TMetadata,
+						metadata: finalMetadata,
 						restArgs: writeArgs,
+						intendedParams,
 						execute: (argsWithNonce) =>
 							walletClient.writeContract(argsWithNonce as any),
 						extractHash: (hash) => hash,
@@ -434,12 +1094,14 @@ export function createTrackedWalletClient<
 					>,
 				): Promise<Hash> {
 					const {metadata, nonce, ...sendArgs} = args;
+					const intendedParams = extractIntendedParamsFromSendTransaction(args);
 
 					return executeTrackedTransaction({
 						account: normalizeAccount(args.account),
 						nonce,
 						metadata: metadata as TMetadata,
 						restArgs: sendArgs,
+						intendedParams,
 						execute: (argsWithNonce) =>
 							walletClient.sendTransaction(argsWithNonce as any),
 						extractHash: (hash) => hash,
@@ -477,7 +1139,7 @@ export function createTrackedWalletClient<
 					>,
 					TChainOverride extends Chain | undefined = undefined,
 				>(
-					args: TrackedWriteContractParameters<
+					args: TrackedWriteContractAutoPopulateParameters<
 						TMetadata,
 						TAbi,
 						TFunctionName,
@@ -487,13 +1149,27 @@ export function createTrackedWalletClient<
 						TChainOverride
 					>,
 				): Promise<TransactionReceipt> {
-					const {metadata, nonce, ...writeArgs} = args;
+					const {metadata: userMetadata, nonce, ...writeArgs} = args;
+
+					// Validate that user didn't provide operation, functionName or args
+					validateNoAutoPopulatedFieldsInMetadata(userMetadata);
+
+					// Auto-populate type, functionName and args
+					const finalMetadata = {
+						...(userMetadata ?? {}),
+						type: 'functionCall' as const,
+						functionName: args.functionName as string,
+						args: args.args as readonly unknown[],
+					} as TMetadata;
+
+					const intendedParams = extractIntendedParamsFromWriteContract(args);
 
 					return executeTrackedTransaction({
 						account: normalizeAccount(args.account),
 						nonce,
-						metadata: metadata as TMetadata,
+						metadata: finalMetadata,
 						restArgs: writeArgs,
+						intendedParams,
 						execute: (argsWithNonce) =>
 							walletClient.writeContractSync(argsWithNonce as any),
 						extractHash: (receipt) => receipt.transactionHash,
@@ -511,12 +1187,14 @@ export function createTrackedWalletClient<
 					>,
 				): Promise<TransactionReceipt> {
 					const {metadata, nonce, ...sendArgs} = args;
+					const intendedParams = extractIntendedParamsFromSendTransaction(args);
 
 					return executeTrackedTransaction({
 						account: normalizeAccount(args.account),
 						nonce,
 						metadata: metadata as TMetadata,
 						restArgs: sendArgs,
+						intendedParams,
 						execute: (argsWithNonce) =>
 							walletClient.sendTransactionSync(argsWithNonce as any),
 						extractHash: (receipt) => receipt.transactionHash,
@@ -541,13 +1219,8 @@ export function createTrackedWalletClient<
 				// Event subscription methods
 				// ============================================
 
-				onTransactionBroadcasted: (
-					listener: (event: TrackedTransaction<TMetadata>) => void,
-				) => emitter.on('transaction:broadcasted', listener),
-
-				offTransactionBroadcasted: (
-					listener: (event: TrackedTransaction<TMetadata>) => void,
-				) => emitter.off('transaction:broadcasted', listener),
+				on: emitter.on.bind(emitter),
+				off: emitter.off.bind(emitter),
 			};
 		},
 	};