@etherkit/viem-tx-tracker 0.0.9 → 0.2.0

package/src/types.ts

@@ -47,12 +47,31 @@ export type UnknownTypeMetadata = {
  */
 export type PopulatedMetadata = FunctionCallMetadata | UnknownTypeMetadata;
 
+/**
+ * Conditional type that makes the `source` construction option required or
+ * optional based on TSource. Mirrors {@link MetadataField}.
+ *
+ * If TSource includes undefined (the default), `source` is optional.
+ * Otherwise a client cannot be constructed without supplying one.
+ *
+ * The value can be given directly or as a thunk. The thunk is evaluated at
+ * broadcast time, once per send, so a client whose signing route can change
+ * over its lifetime always stamps the route that actually signed.
+ *
+ * Note: a TSource that is itself a function type cannot be distinguished from
+ * a thunk at runtime - wrap it (e.g. `{fn: ...}`) if you need one.
+ */
+export type SourceField<TSource> = undefined extends TSource
+	? {source?: TSource | (() => TSource)}
+	: {source: TSource | (() => TSource)};
+
 /**
  * Options for creating a tracked wallet client.
  */
-export interface CreateTrackedWalletClientOptions<
+export type CreateTrackedWalletClientOptions<
 	TPopulate extends boolean = false,
-> {
+	TSource = undefined,
+> = {
 	/**
 	 * When true, writeContract and writeContractSync automatically populate
 	 * operation, functionName and args in the metadata from the contract call parameters.
@@ -65,7 +84,7 @@ export interface CreateTrackedWalletClientOptions<
 	 * Defaults to Date.now.
 	 */
 	clock?: () => number;
-}
+} & SourceField<TSource>;
 
 /**
  * Block tags that can be used to specify nonce fetching strategy
@@ -89,6 +108,46 @@ export type MetadataField<TMetadata> = undefined extends TMetadata
 	? {metadata?: TMetadata}
 	: {metadata: TMetadata};
 
+/**
+ * The optional, opaque, per-call correlation marker.
+ *
+ * It answers "which caller-side request does this send answer?", so the code
+ * that receives `transaction:broadcasted` can match the event to the in-flight
+ * send it issued, without an out-of-band map keyed on something like
+ * `from:nonce` (which is not unique: cancelling a stuck transaction creates a
+ * second operation at the same nonce by design).
+ *
+ * Three fields are carried on a tracked transaction and they answer three
+ * different questions:
+ *
+ * | field         | question                                     | lifetime            |
+ * | ------------- | -------------------------------------------- | ------------------- |
+ * | `metadata`    | what the application says the tx MEANS        | persisted           |
+ * | `source`      | WHICH SIGNING ROUTE produced it               | persisted           |
+ * | `correlation` | which CALLER-SIDE REQUEST this send answers   | ephemeral plumbing  |
+ *
+ * `correlation` is deliberately NOT any of the following:
+ *
+ * - It is not intended to be persisted. It is routing plumbing for the session
+ *   that issued the send, not a property of the transaction.
+ * - It is not an identity for the transaction. `hash` is that.
+ * - It is meaningless outside the session that issued the send, so a value
+ *   rehydrated from storage carries no information.
+ *
+ * The tracker never inspects, interprets, validates or defaults it, exactly as
+ * with `source`. It is a sibling of `metadata`, never nested inside it,
+ * precisely because metadata is what gets persisted.
+ */
+export type CorrelationField = {
+	/**
+	 * Opaque per-call marker tying this send back to the caller-side request
+	 * that issued it. Carried verbatim onto the emitted transaction. Ephemeral:
+	 * not intended to be persisted, not an identity, meaningless outside the
+	 * issuing session. See {@link CorrelationField}.
+	 */
+	correlation?: string;
+};
+
 /**
  * Access list type used in EIP-2930 and EIP-1559 transactions.
  */
@@ -113,11 +172,40 @@ export type IntendedGasParameters = {
  * Common fields for all tracked transactions.
  * All field paths are stable - you can always access tx.field
  */
-type CommonTrackedFields<TMetadata> = {
+type CommonTrackedFields<TMetadata, TSource = undefined> = {
 	readonly hash: `0x${string}`;
 	readonly from: `0x${string}`;
 	readonly broadcastTimestampMs: number;
 	readonly metadata: TMetadata;
+	/**
+	 * Opaque marker of which signing route produced this transaction.
+	 * Supplied once at client construction and carried verbatim: the tracker
+	 * never inspects or interprets it. Sibling of (never nested inside)
+	 * metadata, since it is a fact observed at dispatch rather than something
+	 * the application said the transaction means.
+	 */
+	readonly source: TSource;
+	/**
+	 * Opaque marker of which caller-side request this send answers, supplied per
+	 * call and carried verbatim: the tracker never inspects or interprets it.
+	 * Carried on every emitted transaction, so it reaches `transaction:known`
+	 * as well as `transaction:broadcasted`.
+	 *
+	 * Ephemeral plumbing, unlike its two siblings: `metadata` is what the
+	 * application says the transaction MEANS and `source` is WHICH SIGNING ROUTE
+	 * produced it, both of which consumers persist. `correlation` is not
+	 * intended to be persisted, is not an identity for the transaction, and is
+	 * meaningless outside the session that issued the send.
+	 * See {@link CorrelationField} for the full three-way distinction.
+	 *
+	 * Optional here, unlike the required `source` above, and deliberately so.
+	 * The property is in fact always present at runtime, so `string | undefined`
+	 * would be the more faithful type, but making it required would stop every
+	 * consumer-authored tracked-transaction literal (mocks, fixtures, values
+	 * rehydrated from storage) from compiling, turning an additive change into a
+	 * breaking one. Do not "tidy" this into a required property.
+	 */
+	readonly correlation?: string;
 	readonly to: `0x${string}` | null;
 	readonly value: bigint;
 	readonly data: `0x${string}`;
@@ -125,9 +213,10 @@ type CommonTrackedFields<TMetadata> = {
 };
 
 /**
- * A fully known tracked transaction with all fields confirmed from chain.
- * Emitted via transaction:fetched when tx data is fetched from chain,
- * or immediately for sendRawTransaction where we can parse the tx.
+ * A fully known tracked transaction: every field is a final value.
+ * Emitted via transaction:known, either once the tx has been read back from
+ * the chain, or immediately for sendRawTransaction where the signed payload
+ * can be parsed.
  *
  * When known=true, all values are the actual confirmed values used by the chain.
  * Uses discriminated union by txType to enforce correct field combinations.
@@ -135,39 +224,41 @@ type CommonTrackedFields<TMetadata> = {
  * - accessList at top level, presence depends on txType
  * - gasParameters at top level with txType-specific fields
  */
-export type KnownTrackedTransaction<TMetadata> =
-	CommonTrackedFields<TMetadata> & {
-		readonly known: true;
-	} & (
-			| {
-					readonly txType: 'eip1559';
-					readonly chainId: number;
-					readonly accessList?: AccessList;
-					readonly gasParameters: {
-						readonly gas: bigint;
-						readonly maxFeePerGas: bigint;
-						readonly maxPriorityFeePerGas: bigint;
-					};
-			  }
-			| {
-					readonly txType: 'legacy';
-					readonly chainId?: number;
-					// accessList not available for legacy
-					readonly gasParameters: {
-						readonly gas: bigint;
-						readonly gasPrice: bigint;
-					};
-			  }
-			| {
-					readonly txType: 'eip2930';
-					readonly chainId: number;
-					readonly accessList: AccessList;
-					readonly gasParameters: {
-						readonly gas: bigint;
-						readonly gasPrice: bigint;
-					};
-			  }
-		);
+export type KnownTrackedTransaction<
+	TMetadata,
+	TSource = undefined,
+> = CommonTrackedFields<TMetadata, TSource> & {
+	readonly known: true;
+} & (
+		| {
+				readonly txType: 'eip1559';
+				readonly chainId: number;
+				readonly accessList?: AccessList;
+				readonly gasParameters: {
+					readonly gas: bigint;
+					readonly maxFeePerGas: bigint;
+					readonly maxPriorityFeePerGas: bigint;
+				};
+		  }
+		| {
+				readonly txType: 'legacy';
+				readonly chainId?: number;
+				// accessList not available for legacy
+				readonly gasParameters: {
+					readonly gas: bigint;
+					readonly gasPrice: bigint;
+				};
+		  }
+		| {
+				readonly txType: 'eip2930';
+				readonly chainId: number;
+				readonly accessList: AccessList;
+				readonly gasParameters: {
+					readonly gas: bigint;
+					readonly gasPrice: bigint;
+				};
+		  }
+	);
 
 /**
  * A partially known tracked transaction with intended/provided values.
@@ -184,58 +275,61 @@ export type KnownTrackedTransaction<TMetadata> =
  * - gasPrice only → 'legacy'
  * - undefined → wallet will determine type
  */
-export type UnknownTrackedTransaction<TMetadata> =
-	CommonTrackedFields<TMetadata> & {
-		readonly known: false;
-	} & (
-			| {
-					// txType inferred as eip1559
-					readonly txType: 'eip1559';
-					readonly chainId?: number;
-					readonly accessList?: AccessList;
-					readonly gasParameters: {
-						readonly gas?: bigint;
-						readonly maxFeePerGas?: bigint;
-						readonly maxPriorityFeePerGas?: bigint;
-					};
-			  }
-			| {
-					// txType inferred as legacy
-					readonly txType: 'legacy';
-					readonly chainId?: number;
-					// no accessList for legacy
-					readonly gasParameters: {
-						readonly gas?: bigint;
-						readonly gasPrice?: bigint;
-					};
-			  }
-			| {
-					// txType inferred as eip2930
-					readonly txType: 'eip2930';
-					readonly chainId?: number;
-					readonly accessList?: AccessList;
-					readonly gasParameters: {
-						readonly gas?: bigint;
-						readonly gasPrice?: bigint;
-					};
-			  }
-			| {
-					// txType unknown - wallet will decide
-					readonly txType?: undefined;
-					readonly chainId?: number;
-					readonly accessList?: AccessList;
-					readonly gasParameters: IntendedGasParameters;
-			  }
-		);
+export type UnknownTrackedTransaction<
+	TMetadata,
+	TSource = undefined,
+> = CommonTrackedFields<TMetadata, TSource> & {
+	readonly known: false;
+} & (
+		| {
+				// txType inferred as eip1559
+				readonly txType: 'eip1559';
+				readonly chainId?: number;
+				readonly accessList?: AccessList;
+				readonly gasParameters: {
+					readonly gas?: bigint;
+					readonly maxFeePerGas?: bigint;
+					readonly maxPriorityFeePerGas?: bigint;
+				};
+		  }
+		| {
+				// txType inferred as legacy
+				readonly txType: 'legacy';
+				readonly chainId?: number;
+				// no accessList for legacy
+				readonly gasParameters: {
+					readonly gas?: bigint;
+					readonly gasPrice?: bigint;
+				};
+		  }
+		| {
+				// txType inferred as eip2930
+				readonly txType: 'eip2930';
+				readonly chainId?: number;
+				readonly accessList?: AccessList;
+				readonly gasParameters: {
+					readonly gas?: bigint;
+					readonly gasPrice?: bigint;
+				};
+		  }
+		| {
+				// txType unknown - wallet will decide
+				readonly txType?: undefined;
+				readonly chainId?: number;
+				readonly accessList?: AccessList;
+				readonly gasParameters: IntendedGasParameters;
+		  }
+	);
 
 /**
  * A tracked transaction - discriminated by 'known' field.
- * - known=true: Values are confirmed from chain fetch
+ * - known=true: Values are final, read back from chain or parsed from a
+ *   signed payload
  * - known=false: Values are intended/provided, may differ from actual
  */
-export type TrackedTransaction<TMetadata> =
-	| KnownTrackedTransaction<TMetadata>
-	| UnknownTrackedTransaction<TMetadata>;
+export type TrackedTransaction<TMetadata, TSource = undefined> =
+	| KnownTrackedTransaction<TMetadata, TSource>
+	| UnknownTrackedTransaction<TMetadata, TSource>;
 
 /**
  * Extended WriteContractParameters with metadata and flexible nonce.
@@ -272,7 +366,8 @@ export type TrackedWriteContractParameters<
 	 * - undefined: fetch nonce using 'pending' (default)
 	 */
 	nonce?: NonceOption;
-} & MetadataField<TMetadata>;
+} & MetadataField<TMetadata> &
+	CorrelationField;
 
 /**
  * The fields that are auto-populated by writeContract.
@@ -364,7 +459,8 @@ export type TrackedWriteContractAutoPopulateParameters<
 	 * - undefined: fetch nonce using 'pending' (default)
 	 */
 	nonce?: NonceOption;
-} & WriteContractAutoPopulateMetadataField<TMetadata>;
+} & WriteContractAutoPopulateMetadataField<TMetadata> &
+	CorrelationField;
 
 /**
  * Extended SendTransactionParameters with metadata and flexible nonce.
@@ -386,7 +482,8 @@ export type TrackedSendTransactionParameters<
 	 * - undefined: fetch nonce using 'pending' (default)
 	 */
 	nonce?: NonceOption;
-} & MetadataField<TMetadata>;
+} & MetadataField<TMetadata> &
+	CorrelationField;
 
 /**
  * Parameters for sendRawTransaction with metadata.
@@ -398,7 +495,8 @@ export type TrackedRawTransactionParameters<TMetadata> = {
 	 * The RLP-encoded signed transaction.
 	 */
 	serializedTransaction: TransactionSerialized;
-} & MetadataField<TMetadata>;
+} & MetadataField<TMetadata> &
+	CorrelationField;
 
 /**
  * A wallet client wrapper that tracks transactions with metadata.
@@ -410,6 +508,7 @@ export interface TrackedWalletClient<
 	TTransport extends Transport = Transport,
 	TChain extends Chain | undefined = Chain | undefined,
 	TAccount extends Account | undefined = Account | undefined,
+	TSource = undefined,
 > {
 	/**
 	 * The underlying wallet client.
@@ -532,9 +631,11 @@ export interface TrackedWalletClient<
 	 * @param listener - Callback function receiving the event data
 	 * @returns Unsubscribe function
 	 */
-	on<TEvent extends keyof TrackedWalletClientEvents<TMetadata>>(
+	on<TEvent extends keyof TrackedWalletClientEvents<TMetadata, TSource>>(
 		event: TEvent,
-		listener: (data: TrackedWalletClientEvents<TMetadata>[TEvent]) => void,
+		listener: (
+			data: TrackedWalletClientEvents<TMetadata, TSource>[TEvent],
+		) => void,
 	): () => void;
 
 	/**
@@ -542,25 +643,42 @@ export interface TrackedWalletClient<
 	 * @param event - The event type to unsubscribe from
 	 * @param listener - The same listener function passed to on
 	 */
-	off<TEvent extends keyof TrackedWalletClientEvents<TMetadata>>(
+	off<TEvent extends keyof TrackedWalletClientEvents<TMetadata, TSource>>(
 		event: TEvent,
-		listener: (data: TrackedWalletClientEvents<TMetadata>[TEvent]) => void,
+		listener: (
+			data: TrackedWalletClientEvents<TMetadata, TSource>[TEvent],
+		) => void,
 	): void;
 }
 
 /**
  * Event map for TrackedWalletClient events.
  */
-export type TrackedWalletClientEvents<TMetadata> = {
+export type TrackedWalletClientEvents<TMetadata, TSource = undefined> = {
 	/**
 	 * Emitted immediately after a transaction is successfully broadcast.
 	 */
-	'transaction:broadcasted': TrackedTransaction<TMetadata>;
+	'transaction:broadcasted': TrackedTransaction<TMetadata, TSource>;
 	/**
-	 * Emitted when full transaction data is successfully fetched from chain.
-	 * Not guaranteed to fire if fetch fails (tx not in mempool yet, network issues, etc.)
+	 * Emitted when the transaction's values are known to be the final ones
+	 * rather than the ones that were merely intended.
+	 *
+	 * The name states the promise, not the mechanism, because the mechanism
+	 * differs by path: the values are read back from the chain for a normal
+	 * send, and parsed from the signed payload for a raw send. Both yield final
+	 * values, so both emit this event, and a consumer can persist on it alone.
+	 *
+	 * Note the two paths differ in RELIABILITY, which the name cannot express:
+	 *
+	 * - Normal sends: best effort. If the read fails (not in the mempool yet,
+	 *   network trouble) this 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 treat `transaction:broadcasted` as the event you must handle, and this
+	 * one as a refinement that is usually but not always delivered.
 	 */
-	'transaction:fetched': KnownTrackedTransaction<TMetadata>;
+	'transaction:known': KnownTrackedTransaction<TMetadata, TSource>;
 };
 
 /**
@@ -573,6 +691,7 @@ export interface TrackedWalletClientAutoPopulate<
 	TTransport extends Transport = Transport,
 	TChain extends Chain | undefined = Chain | undefined,
 	TAccount extends Account | undefined = Account | undefined,
+	TSource = undefined,
 > {
 	/**
 	 * The underlying wallet client.
@@ -697,9 +816,11 @@ export interface TrackedWalletClientAutoPopulate<
 	 * @param listener - Callback function receiving the event data
 	 * @returns Unsubscribe function
 	 */
-	on<TEvent extends keyof TrackedWalletClientEvents<TMetadata>>(
+	on<TEvent extends keyof TrackedWalletClientEvents<TMetadata, TSource>>(
 		event: TEvent,
-		listener: (data: TrackedWalletClientEvents<TMetadata>[TEvent]) => void,
+		listener: (
+			data: TrackedWalletClientEvents<TMetadata, TSource>[TEvent],
+		) => void,
 	): () => void;
 
 	/**
@@ -707,9 +828,11 @@ export interface TrackedWalletClientAutoPopulate<
 	 * @param event - The event type to unsubscribe from
 	 * @param listener - The same listener function passed to on
 	 */
-	off<TEvent extends keyof TrackedWalletClientEvents<TMetadata>>(
+	off<TEvent extends keyof TrackedWalletClientEvents<TMetadata, TSource>>(
 		event: TEvent,
-		listener: (data: TrackedWalletClientEvents<TMetadata>[TEvent]) => void,
+		listener: (
+			data: TrackedWalletClientEvents<TMetadata, TSource>[TEvent],
+		) => void,
 	): void;
 }
 
@@ -724,6 +847,7 @@ export interface TrackedWalletClientAutoPopulate<
  * @typeParam TTransport - The transport type (default: Transport)
  * @typeParam TChain - The chain type (default: Chain | undefined)
  * @typeParam TAccount - The account type (default: Account | undefined)
+ * @typeParam TSource - The opaque signing-route marker (default: undefined)
  *
  * @example
  * ```typescript
@@ -741,6 +865,17 @@ export interface TrackedWalletClientAutoPopulate<
  * type MyExtendedMetadata = FunctionCallMetadata & { priority: number };
  * type MyExtendedClient = TrackedWalletClientType<MyExtendedMetadata, true>;
  *
+ * // With an opaque source describing which signing route produced the tx
+ * type MySource = 'connected-wallet' | 'local-signer' | 'payer-wallet';
+ * type MySourcedClient = TrackedWalletClientType<
+ *   {purpose: string},
+ *   false,
+ *   Transport,
+ *   Chain | undefined,
+ *   Account | undefined,
+ *   MySource
+ * >;
+ *
  * // With specific wallet client types
  * type MySpecificClient = TrackedWalletClientType<
  *   {purpose: string},
@@ -757,6 +892,13 @@ export type TrackedWalletClientType<
 	TTransport extends Transport = Transport,
 	TChain extends Chain | undefined = Chain | undefined,
 	TAccount extends Account | undefined = Account | undefined,
+	TSource = undefined,
 > = TAutoPopulate extends true
-	? TrackedWalletClientAutoPopulate<TMetadata, TTransport, TChain, TAccount>
-	: TrackedWalletClient<TMetadata, TTransport, TChain, TAccount>;
+	? TrackedWalletClientAutoPopulate<
+			TMetadata,
+			TTransport,
+			TChain,
+			TAccount,
+			TSource
+		>
+	: TrackedWalletClient<TMetadata, TTransport, TChain, TAccount, TSource>;