@etherkit/viem-tx-tracker 0.1.0 → 0.2.0

package/src/types.ts

@@ -108,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.
  */
@@ -145,6 +185,27 @@ type CommonTrackedFields<TMetadata, TSource = undefined> = {
 	 * 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}`;
@@ -152,9 +213,10 @@ type CommonTrackedFields<TMetadata, TSource = undefined> = {
 };
 
 /**
- * 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.
@@ -261,7 +323,8 @@ export type UnknownTrackedTransaction<
 
 /**
  * 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, TSource = undefined> =
@@ -303,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.
@@ -395,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.
@@ -417,7 +482,8 @@ export type TrackedSendTransactionParameters<
 	 * - undefined: fetch nonce using 'pending' (default)
 	 */
 	nonce?: NonceOption;
-} & MetadataField<TMetadata>;
+} & MetadataField<TMetadata> &
+	CorrelationField;
 
 /**
  * Parameters for sendRawTransaction with metadata.
@@ -429,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.
@@ -593,10 +660,25 @@ export type TrackedWalletClientEvents<TMetadata, TSource = undefined> = {
 	 */
 	'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, TSource>;
+	'transaction:known': KnownTrackedTransaction<TMetadata, TSource>;
 };
 
 /**