@valve-tech/tx-tracker 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -6,6 +6,21 @@ this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.8.0] — 2026-05-06
+
+### Added
+- `lostSignalPolicy: { strategy: 'receipt-poll-fallback', pollEveryBlocks: N }` runtime. Closes the type-vs-runtime gap from v0.3.x — when a tracked subscription is in a degraded state, the tracker fetches `getReceipt` every N block ticks and emits `seen-in-block` with `source: 'receipt-poll'` on hit. Capability gate: requires `receiptByHash === 'available'`.
+- `withReceipts: true` opt-in receipt enrichment on `TrackOptions`. When set, the tracker pre-fetches the receipt before the per-record block decision and attaches it to `seen-in-block` events via the new `TxEventSeenInBlock.receipt` field. One emit per inclusion — receipt is on the first event, not a follow-up.
+- `tracker.group(hashes, options?)` — cross-tx correlation (spec §18.1). Emits `group-progress` / `group-complete` / `group-failed` / `group-stopped` derived from per-member event streams. Replacement does NOT auto-promote.
+- `watchTransaction({ client, hash, ... })` — one-shot callback convenience export.
+- `waitForTransaction({ client, hash, ... })` — Promise variant of `watchTransaction`. Resolves with discriminated-union outcome (`mined` / `dropped` / `replaced` / `failed`).
+- `waitForPending({ client, hash, timeoutBlocks })` — Promise that resolves on first `seen-in-mempool`; rejects with typed `WaitForPendingTimeoutError` if the hash isn't observed within `timeoutBlocks`.
+- `replaceTransaction({ original, walletClient, newGas })` — same-nonce replacement primitive. Caller-provides-newGas keeps tx-tracker independent of `@valve-tech/gas-oracle`.
+
+### Changed
+- `onBlock` is now async to support pre-fetching receipts before the per-record decision. Stale-block guard added against the resulting interleave window so a delayed pre-fetch can't clobber state advanced by a concurrent block tick.
+- `decideBlockObservation` accepts an optional `prefetchedReceipts: ReadonlyMap<Hash, TransactionReceipt>` parameter (backward-compatible — existing callsites omit it).
+
 ## [0.7.0] — 2026-05-06
 
 > **The implementation lands.** This is the first release of

package/dist/events.d.ts

@@ -19,7 +19,7 @@
  * No I/O, no wall-clock, no mutation — pure data shape + pure
  * builders. Browser/mobile safe (§2.4).
  */
-import type { Capabilities, EventSource, RawTx } from '@valve-tech/chain-source';
+import type { Capabilities, EventSource, RawTx, TransactionReceipt } from '@valve-tech/chain-source';
 /**
  * Hash type carried on every event. The chain-source layer keeps
  * hashes as plain `string` rather than viem's `Hash` brand to stay
@@ -96,6 +96,9 @@ export interface TxEventLeftMempool extends Envelope {
  * `confirmations` counts blocks observed since this inclusion
  * inclusive of the inclusion block itself (so the first
  * inclusion event has `confirmations: 1`).
+ *
+ * `receipt` is present iff the subscription set `withReceipts: true`.
+ * Adds one RPC per inclusion (spec §18.2, v0.8.0 design F2).
  */
 export interface TxEventSeenInBlock extends Envelope {
     kind: 'seen-in-block';
@@ -103,6 +106,12 @@ export interface TxEventSeenInBlock extends Envelope {
     blockNumber: bigint;
     transactionIndex: number;
     confirmations: number;
+    /**
+     * Transaction receipt — present iff the subscription set
+     * `withReceipts: true`. Adds one RPC per inclusion (spec §18.2,
+     * v0.8.0 design F2).
+     */
+    receipt?: TransactionReceipt;
 }
 /**
  * Tx was previously seen at block `blockNumber` with hash
@@ -249,6 +258,7 @@ export declare const buildSeenInBlock: (input: Envelope & {
     blockNumber: bigint;
     transactionIndex: number;
     confirmations: number;
+    receipt?: TransactionReceipt;
 }) => TxEventSeenInBlock;
 /**
  * Build a `vanished-from-block` event. Spec §12.3 forbids

package/dist/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"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"}

package/dist/events.js

@@ -56,6 +56,7 @@ export const buildSeenInBlock = (input) => ({
     blockNumber: input.blockNumber,
     transactionIndex: input.transactionIndex,
     confirmations: input.confirmations,
+    ...(input.receipt !== undefined ? { receipt: input.receipt } : {}),
 });
 /**
  * Build a `vanished-from-block` event. Spec §12.3 forbids

package/dist/events.js.map

@@ -1 +1 @@
-{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"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"}

package/dist/group-events.d.ts

@@ -0,0 +1,82 @@
+/**
+ * `TxGroupEvent` — composite event union for `tracker.group([...hashes])`
+ * cross-tx correlation (spec §18.1, v0.8.0 design F3).
+ *
+ * Group emits its own kinds (group-progress / group-complete /
+ * group-failed / group-stopped) derived from the per-member event
+ * streams. Per-member events still flow through the underlying
+ * tracker.subscribe path; the group is a synthesis layer on top.
+ *
+ * Pure data shapes + pure builders. No I/O, no mutation.
+ */
+import type { At, Hash } from './events.js';
+/**
+ * Common envelope on every group event. Carries the group identifier
+ * and the block coordinate the observation was made at.
+ */
+export interface TxGroupEventEnvelope {
+    groupId: string;
+    at: At;
+}
+/**
+ * Emitted when one or more members of the tracked group have reached
+ * inclusion in the canonical chain. `confirmed` is the count of members
+ * observed in blocks; `total` is the group size; `lastHash` is the most
+ * recently-included member's hash.
+ */
+export interface TxGroupEventProgress extends TxGroupEventEnvelope {
+    kind: 'group-progress';
+    confirmed: number;
+    total: number;
+    lastHash: Hash;
+}
+/**
+ * All members of the group have reached inclusion in the canonical
+ * chain and none have been replaced or reorged. Final progress event
+ * before group stream closes (unless a reorg or replacement occurs).
+ */
+export interface TxGroupEventComplete extends TxGroupEventEnvelope {
+    kind: 'group-complete';
+    total: number;
+}
+/**
+ * One member of the group was dropped (unseen for the threshold),
+ * failed (reverted or invalid), or replaced by a different tx with
+ * the same (from, nonce) pair. `reason` disambiguates the failure mode.
+ */
+export interface TxGroupEventFailed extends TxGroupEventEnvelope {
+    kind: 'group-failed';
+    failedHash: Hash;
+    reason: 'dropped' | 'failed' | 'replaced';
+}
+/**
+ * Group subscription was stopped before all members reached inclusion.
+ * Fires once per group subscription. Always the final event in the
+ * stream for that group.
+ */
+export interface TxGroupEventStopped extends TxGroupEventEnvelope {
+    kind: 'group-stopped';
+}
+/**
+ * Discriminated union of every group event variant. Narrow on `kind`
+ * to access variant-specific fields.
+ */
+export type TxGroupEvent = TxGroupEventProgress | TxGroupEventComplete | TxGroupEventFailed | TxGroupEventStopped;
+/** Build a `group-progress` event. */
+export declare const buildGroupProgress: (input: TxGroupEventEnvelope & {
+    confirmed: number;
+    total: number;
+    lastHash: Hash;
+}) => TxGroupEventProgress;
+/** Build a `group-complete` event. */
+export declare const buildGroupComplete: (input: TxGroupEventEnvelope & {
+    total: number;
+}) => TxGroupEventComplete;
+/** Build a `group-failed` event. */
+export declare const buildGroupFailed: (input: TxGroupEventEnvelope & {
+    failedHash: Hash;
+    reason: "dropped" | "failed" | "replaced";
+}) => TxGroupEventFailed;
+/** Build a `group-stopped` event. */
+export declare const buildGroupStopped: (input: TxGroupEventEnvelope) => TxGroupEventStopped;
+//# sourceMappingURL=group-events.d.ts.map

package/dist/group-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-events.d.ts","sourceRoot":"","sources":["../src/group-events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAE3C;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAA;IACf,EAAE,EAAE,EAAE,CAAA;CACP;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAqB,SAAQ,oBAAoB;IAChE,IAAI,EAAE,gBAAgB,CAAA;IACtB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,IAAI,CAAA;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAqB,SAAQ,oBAAoB;IAChE,IAAI,EAAE,gBAAgB,CAAA;IACtB,KAAK,EAAE,MAAM,CAAA;CACd;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAmB,SAAQ,oBAAoB;IAC9D,IAAI,EAAE,cAAc,CAAA;IACpB,UAAU,EAAE,IAAI,CAAA;IAChB,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,UAAU,CAAA;CAC1C;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAoB,SAAQ,oBAAoB;IAC/D,IAAI,EAAE,eAAe,CAAA;CACtB;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,GACpB,oBAAoB,GACpB,oBAAoB,GACpB,kBAAkB,GAClB,mBAAmB,CAAA;AAYvB,sCAAsC;AACtC,eAAO,MAAM,kBAAkB,GAC7B,OAAO,oBAAoB,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,IAAI,CAAA;CAAE,KACjF,oBAMD,CAAA;AAEF,sCAAsC;AACtC,eAAO,MAAM,kBAAkB,GAC7B,OAAO,oBAAoB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,KAC9C,oBAID,CAAA;AAEF,oCAAoC;AACpC,eAAO,MAAM,gBAAgB,GAC3B,OAAO,oBAAoB,GAAG;IAC5B,UAAU,EAAE,IAAI,CAAA;IAChB,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,UAAU,CAAA;CAC1C,KACA,kBAKD,CAAA;AAEF,qCAAqC;AACrC,eAAO,MAAM,iBAAiB,GAC5B,OAAO,oBAAoB,KAC1B,mBAGD,CAAA"}

package/dist/group-events.js

@@ -0,0 +1,47 @@
+/**
+ * `TxGroupEvent` — composite event union for `tracker.group([...hashes])`
+ * cross-tx correlation (spec §18.1, v0.8.0 design F3).
+ *
+ * Group emits its own kinds (group-progress / group-complete /
+ * group-failed / group-stopped) derived from the per-member event
+ * streams. Per-member events still flow through the underlying
+ * tracker.subscribe path; the group is a synthesis layer on top.
+ *
+ * Pure data shapes + pure builders. No I/O, no mutation.
+ */
+/**
+ * Build an event envelope from the group context. Used by every builder
+ * below so the envelope shape is centralized and always produces a fresh
+ * copy (no aliasing).
+ */
+const makeEnvelope = (input) => ({
+    groupId: input.groupId,
+    at: { blockNumber: input.at.blockNumber, timestamp: input.at.timestamp },
+});
+/** Build a `group-progress` event. */
+export const buildGroupProgress = (input) => ({
+    ...makeEnvelope(input),
+    kind: 'group-progress',
+    confirmed: input.confirmed,
+    total: input.total,
+    lastHash: input.lastHash,
+});
+/** Build a `group-complete` event. */
+export const buildGroupComplete = (input) => ({
+    ...makeEnvelope(input),
+    kind: 'group-complete',
+    total: input.total,
+});
+/** Build a `group-failed` event. */
+export const buildGroupFailed = (input) => ({
+    ...makeEnvelope(input),
+    kind: 'group-failed',
+    failedHash: input.failedHash,
+    reason: input.reason,
+});
+/** Build a `group-stopped` event. */
+export const buildGroupStopped = (input) => ({
+    ...makeEnvelope(input),
+    kind: 'group-stopped',
+});
+//# sourceMappingURL=group-events.js.map

package/dist/group-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-events.js","sourceRoot":"","sources":["../src/group-events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAkEH;;;;GAIG;AACH,MAAM,YAAY,GAAG,CAAC,KAA2B,EAAwB,EAAE,CAAC,CAAC;IAC3E,OAAO,EAAE,KAAK,CAAC,OAAO;IACtB,EAAE,EAAE,EAAE,WAAW,EAAE,KAAK,CAAC,EAAE,CAAC,WAAW,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,CAAC,SAAS,EAAE;CACzE,CAAC,CAAA;AAEF,sCAAsC;AACtC,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,KAAkF,EAC5D,EAAE,CAAC,CAAC;IAC1B,GAAG,YAAY,CAAC,KAAK,CAAC;IACtB,IAAI,EAAE,gBAAgB;IACtB,SAAS,EAAE,KAAK,CAAC,SAAS;IAC1B,KAAK,EAAE,KAAK,CAAC,KAAK;IAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;CACzB,CAAC,CAAA;AAEF,sCAAsC;AACtC,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,KAA+C,EACzB,EAAE,CAAC,CAAC;IAC1B,GAAG,YAAY,CAAC,KAAK,CAAC;IACtB,IAAI,EAAE,gBAAgB;IACtB,KAAK,EAAE,KAAK,CAAC,KAAK;CACnB,CAAC,CAAA;AAEF,oCAAoC;AACpC,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,KAGC,EACmB,EAAE,CAAC,CAAC;IACxB,GAAG,YAAY,CAAC,KAAK,CAAC;IACtB,IAAI,EAAE,cAAc;IACpB,UAAU,EAAE,KAAK,CAAC,UAAU;IAC5B,MAAM,EAAE,KAAK,CAAC,MAAM;CACrB,CAAC,CAAA;AAEF,qCAAqC;AACrC,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,KAA2B,EACN,EAAE,CAAC,CAAC;IACzB,GAAG,YAAY,CAAC,KAAK,CAAC;IACtB,IAAI,EAAE,eAAe;CACtB,CAAC,CAAA"}

package/dist/group.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `createTxGroup` — synthesis layer on top of per-hash tracker
+ * subscriptions. Spec §18.1, v0.8.0 design F3.
+ *
+ * Listens to each member hash via the tracker's existing subscribe API,
+ * tracks confirmed/failed counters, and emits group-progress /
+ * group-complete / group-failed once per terminal transition. Member
+ * unsubscribes are torn down on stop().
+ *
+ * Replacement does NOT auto-promote — if a member is replaced via
+ * same-nonce bump, the group emits group-failed with reason
+ * 'replaced'. The consumer constructs a new group with the new hash
+ * if they want the replacement to count.
+ *
+ * Edge case: an empty hashes array immediately emits group-complete
+ * with total=0 (vacuously all confirmed) and marks the group terminal.
+ * This is a safe, predictable default and matches the mathematical
+ * sense of "all zero members confirmed."
+ */
+import type { Hash } from './events.js';
+import type { GroupOptions, TxGroupSubscription, TxTracker } from './tracker.js';
+/**
+ * Construct a group subscription that synthesises per-member `TxEvent`
+ * streams into group-level events.
+ *
+ * @param tracker - The tracker instance to call `subscribe` on.
+ * @param hashes  - Member transaction hashes. Order is not significant.
+ * @param options - Optional group-level and member-level overrides.
+ */
+export declare const createTxGroup: (tracker: TxTracker, hashes: Hash[], options?: GroupOptions) => TxGroupSubscription;
+//# sourceMappingURL=group.d.ts.map

package/dist/group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"group.d.ts","sourceRoot":"","sources":["../src/group.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,KAAK,EAAE,IAAI,EAAqB,MAAM,aAAa,CAAA;AAQ1D,OAAO,KAAK,EACV,YAAY,EAEZ,mBAAmB,EACnB,SAAS,EACV,MAAM,cAAc,CAAA;AAErB;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,GACxB,SAAS,SAAS,EAClB,QAAQ,IAAI,EAAE,EACd,UAAS,YAAiB,KACzB,mBAyLF,CAAA"}

package/dist/group.js

@@ -0,0 +1,196 @@
+/**
+ * `createTxGroup` — synthesis layer on top of per-hash tracker
+ * subscriptions. Spec §18.1, v0.8.0 design F3.
+ *
+ * Listens to each member hash via the tracker's existing subscribe API,
+ * tracks confirmed/failed counters, and emits group-progress /
+ * group-complete / group-failed once per terminal transition. Member
+ * unsubscribes are torn down on stop().
+ *
+ * Replacement does NOT auto-promote — if a member is replaced via
+ * same-nonce bump, the group emits group-failed with reason
+ * 'replaced'. The consumer constructs a new group with the new hash
+ * if they want the replacement to count.
+ *
+ * Edge case: an empty hashes array immediately emits group-complete
+ * with total=0 (vacuously all confirmed) and marks the group terminal.
+ * This is a safe, predictable default and matches the mathematical
+ * sense of "all zero members confirmed."
+ */
+import { Subscriptions } from '@valve-tech/chain-source';
+import { buildGroupComplete, buildGroupFailed, buildGroupProgress, buildGroupStopped, } from './group-events.js';
+/**
+ * Construct a group subscription that synthesises per-member `TxEvent`
+ * streams into group-level events.
+ *
+ * @param tracker - The tracker instance to call `subscribe` on.
+ * @param hashes  - Member transaction hashes. Order is not significant.
+ * @param options - Optional group-level and member-level overrides.
+ */
+export const createTxGroup = (tracker, hashes, options = {}) => {
+    const groupId = options.groupId ??
+        `grp-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const memberOptions = options.memberOptions ?? {};
+    const subs = new Subscriptions();
+    const total = hashes.length;
+    const confirmedSet = new Set();
+    let terminal = false;
+    const memberUnsubs = [];
+    const emit = (event) => subs.emit(event);
+    // Empty group — vacuously all confirmed. Emit complete immediately
+    // (synchronously; no member subscriptions to set up).
+    if (total === 0) {
+        terminal = true;
+        const zeroAt = { blockNumber: 0n, timestamp: 0n };
+        emit(buildGroupComplete({ groupId, at: zeroAt, total: 0 }));
+    }
+    const handleMemberEvent = (memberHash, event) => {
+        if (terminal)
+            return;
+        const at = event.at;
+        if (event.kind === 'seen-in-block' && event.confirmations >= 1) {
+            // Idempotency guard: same hash can emit multiple seen-in-block
+            // events (confirmations 1, 2, 3 …) — only count it once.
+            if (confirmedSet.has(memberHash))
+                return;
+            confirmedSet.add(memberHash);
+            if (confirmedSet.size < total) {
+                emit(buildGroupProgress({
+                    groupId,
+                    at,
+                    confirmed: confirmedSet.size,
+                    total,
+                    lastHash: memberHash,
+                }));
+            }
+            else {
+                terminal = true;
+                emit(buildGroupComplete({ groupId, at, total }));
+            }
+            return;
+        }
+        if (event.kind === 'unseen-for-N-blocks') {
+            terminal = true;
+            emit(buildGroupFailed({
+                groupId,
+                at,
+                failedHash: memberHash,
+                reason: 'dropped',
+            }));
+            return;
+        }
+        if (event.kind === 'replaced-by') {
+            terminal = true;
+            emit(buildGroupFailed({
+                groupId,
+                at,
+                failedHash: memberHash,
+                reason: 'replaced',
+            }));
+            return;
+        }
+    };
+    for (const hash of hashes) {
+        const unsub = tracker.subscribe(hash, (event) => handleMemberEvent(hash, event), { ...memberOptions, emitInitial: false });
+        memberUnsubs.push(unsub);
+    }
+    let stopped = false;
+    const stop = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        for (const unsub of memberUnsubs) {
+            try {
+                unsub();
+            }
+            catch {
+                // Swallow per-sub teardown errors — we always emit group-stopped.
+            }
+        }
+        emit(buildGroupStopped({ groupId, at: { blockNumber: 0n, timestamp: 0n } }));
+    };
+    const snapshot = () => {
+        const out = {};
+        for (const hash of hashes)
+            out[hash] = tracker.getTxStatus(hash);
+        return out;
+    };
+    /**
+     * Async-iterable surface over the group event stream. Resolves each
+     * `next()` call with the next queued event, or parks the caller in a
+     * waiter array until one arrives. Terminal events (group-complete /
+     * group-failed / group-stopped) flip `done` so subsequent `next()`
+     * calls resolve immediately with `done: true`.
+     */
+    const events = () => ({
+        [Symbol.asyncIterator]: () => {
+            const queue = [];
+            const waiters = [];
+            let done = false;
+            const unsub = subs.subscribe((event) => {
+                if (event.kind === 'group-stopped' ||
+                    event.kind === 'group-complete' ||
+                    event.kind === 'group-failed') {
+                    done = true;
+                }
+                const waiter = waiters.shift();
+                if (waiter) {
+                    waiter({ value: event, done: false });
+                    if (done) {
+                        // Drain remaining waiters with done after a terminal event.
+                        // Reachable when a consumer parks multiple `next()` calls
+                        // concurrently before any event arrives — first waiter gets
+                        // the terminal event, the rest resolve with done:true here.
+                        while (waiters.length > 0) {
+                            waiters.shift()({
+                                value: undefined,
+                                done: true,
+                            });
+                        }
+                    }
+                }
+                else {
+                    queue.push(event);
+                }
+            });
+            return {
+                next: () => {
+                    if (queue.length > 0) {
+                        const value = queue.shift();
+                        return Promise.resolve({ value, done: false });
+                    }
+                    if (done) {
+                        return Promise.resolve({
+                            value: undefined,
+                            done: true,
+                        });
+                    }
+                    return new Promise((resolve) => {
+                        waiters.push(resolve);
+                    });
+                },
+                return: () => {
+                    unsub();
+                    done = true;
+                    while (waiters.length > 0) {
+                        waiters.shift()({
+                            value: undefined,
+                            done: true,
+                        });
+                    }
+                    return Promise.resolve({
+                        value: undefined,
+                        done: true,
+                    });
+                },
+            };
+        },
+    });
+    return {
+        events,
+        subscribe: (cb) => subs.subscribe(cb),
+        snapshot,
+        stop,
+    };
+};
+//# sourceMappingURL=group.js.map

package/dist/group.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"group.js","sourceRoot":"","sources":["../src/group.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -40,7 +40,7 @@
  *   source.stop()
  */
 export { createTxTracker } from './tracker.js';
-export type { CreateTxTrackerOptions, TxTracker, TrackOptions, BulkTrackOptions, TxMatchEvent, TxSubscription, LostSignalPolicy, } from './tracker.js';
+export type { CreateTxTrackerOptions, TxTracker, TrackOptions, BulkTrackOptions, TxMatchEvent, TxSubscription, LostSignalPolicy, GroupOptions, TxGroupSubscription, } from './tracker.js';
 export { buildStarted, buildSeenInMempool, buildLeftMempool, buildSeenInBlock, buildVanishedFromBlock, buildReplacedBy, buildUnseenForNBlocks, buildSignalDegraded, buildSignalRecovered, buildStopped, buildInitialStatus, } from './events.js';
 export type { Address, At, Envelope, Hash, TxEvent, TxEventStarted, TxEventSeenInMempool, TxEventLeftMempool, TxEventSeenInBlock, TxEventVanishedFromBlock, TxEventReplacedBy, TxEventUnseenForNBlocks, TxEventSignalDegraded, TxEventSignalRecovered, TxEventStopped, TxStatus, } from './events.js';
 export { createInMemoryStore, computeRetentionExpiry, defaultRetentionBlocks, } from './store.js';
@@ -49,4 +49,15 @@ export { appendBlock, defaultReorgDepthBlocks, detectDivergences, } from './reor
 export type { BlockDivergence, BlockSample } from './reorg.js';
 export { compileSelector, defaultMaxBulkSubscriptions, matchAll, } from './selectors.js';
 export type { BulkMatchPayload, CompiledSelector } from './selectors.js';
+export { createTxGroup } from './group.js';
+export { watchTransaction } from './watch-transaction.js';
+export type { WatchTransactionOptions } from './watch-transaction.js';
+export { waitForTransaction } from './wait-for-transaction.js';
+export type { WaitForTransactionOptions, WaitForTransactionOutcome, } from './wait-for-transaction.js';
+export { waitForPending, WaitForPendingTimeoutError, } from './wait-for-pending.js';
+export type { WaitForPendingOptions } from './wait-for-pending.js';
+export { buildGroupComplete, buildGroupFailed, buildGroupProgress, buildGroupStopped, } from './group-events.js';
+export type { TxGroupEvent, TxGroupEventComplete, TxGroupEventEnvelope, TxGroupEventFailed, TxGroupEventProgress, TxGroupEventStopped, } from './group-events.js';
+export { replaceTransaction } from './replace-transaction.js';
+export type { ReplaceTransactionNewGas, ReplaceTransactionOptions, ReplaceTransactionOriginal, } from './replace-transaction.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAC9C,YAAY,EACV,sBAAsB,EACtB,SAAS,EACT,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,gBAAgB,GACjB,MAAM,cAAc,CAAA;AAErB,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,kBAAkB,GACnB,MAAM,aAAa,CAAA;AACpB,YAAY,EACV,OAAO,EACP,EAAE,EACF,QAAQ,EACR,IAAI,EACJ,OAAO,EACP,cAAc,EACd,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,EAClB,wBAAwB,EACxB,iBAAiB,EACjB,uBAAuB,EACvB,qBAAqB,EACrB,sBAAsB,EACtB,cAAc,EACd,QAAQ,GACT,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,YAAY,CAAA;AACnB,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,oBAAoB,EACpB,qBAAqB,EACrB,eAAe,EACf,cAAc,GACf,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,WAAW,EACX,uBAAuB,EACvB,iBAAiB,GAClB,MAAM,YAAY,CAAA;AACnB,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE9D,OAAO,EACL,eAAe,EACf,2BAA2B,EAC3B,QAAQ,GACT,MAAM,gBAAgB,CAAA;AACvB,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAC9C,YAAY,EACV,sBAAsB,EACtB,SAAS,EACT,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,GACpB,MAAM,cAAc,CAAA;AAErB,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,kBAAkB,GACnB,MAAM,aAAa,CAAA;AACpB,YAAY,EACV,OAAO,EACP,EAAE,EACF,QAAQ,EACR,IAAI,EACJ,OAAO,EACP,cAAc,EACd,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,EAClB,wBAAwB,EACxB,iBAAiB,EACjB,uBAAuB,EACvB,qBAAqB,EACrB,sBAAsB,EACtB,cAAc,EACd,QAAQ,GACT,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,YAAY,CAAA;AACnB,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,oBAAoB,EACpB,qBAAqB,EACrB,eAAe,EACf,cAAc,GACf,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,WAAW,EACX,uBAAuB,EACvB,iBAAiB,GAClB,MAAM,YAAY,CAAA;AACnB,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE9D,OAAO,EACL,eAAe,EACf,2BAA2B,EAC3B,QAAQ,GACT,MAAM,gBAAgB,CAAA;AACvB,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAExE,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AACzD,YAAY,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAA;AAErE,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAC9D,YAAY,EACV,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,2BAA2B,CAAA;AAElC,OAAO,EACL,cAAc,EACd,0BAA0B,GAC3B,MAAM,uBAAuB,CAAA;AAC9B,YAAY,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAElE,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,mBAAmB,CAAA;AAC1B,YAAY,EACV,YAAY,EACZ,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAC7D,YAAY,EACV,wBAAwB,EACxB,yBAAyB,EACzB,0BAA0B,GAC3B,MAAM,0BAA0B,CAAA"}

package/dist/index.js

@@ -44,4 +44,10 @@ export { buildStarted, buildSeenInMempool, buildLeftMempool, buildSeenInBlock, b
 export { createInMemoryStore, computeRetentionExpiry, defaultRetentionBlocks, } from './store.js';
 export { appendBlock, defaultReorgDepthBlocks, detectDivergences, } from './reorg.js';
 export { compileSelector, defaultMaxBulkSubscriptions, matchAll, } from './selectors.js';
+export { createTxGroup } from './group.js';
+export { watchTransaction } from './watch-transaction.js';
+export { waitForTransaction } from './wait-for-transaction.js';
+export { waitForPending, WaitForPendingTimeoutError, } from './wait-for-pending.js';
+export { buildGroupComplete, buildGroupFailed, buildGroupProgress, buildGroupStopped, } from './group-events.js';
+export { replaceTransaction } from './replace-transaction.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAW9C,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,kBAAkB,GACnB,MAAM,aAAa,CAAA;AAoBpB,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,YAAY,CAAA;AAUnB,OAAO,EACL,WAAW,EACX,uBAAuB,EACvB,iBAAiB,GAClB,MAAM,YAAY,CAAA;AAGnB,OAAO,EACL,eAAe,EACf,2BAA2B,EAC3B,QAAQ,GACT,MAAM,gBAAgB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAa9C,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,kBAAkB,GACnB,MAAM,aAAa,CAAA;AAoBpB,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,YAAY,CAAA;AAUnB,OAAO,EACL,WAAW,EACX,uBAAuB,EACvB,iBAAiB,GAClB,MAAM,YAAY,CAAA;AAGnB,OAAO,EACL,eAAe,EACf,2BAA2B,EAC3B,QAAQ,GACT,MAAM,gBAAgB,CAAA;AAGvB,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAGzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAM9D,OAAO,EACL,cAAc,EACd,0BAA0B,GAC3B,MAAM,uBAAuB,CAAA;AAG9B,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,mBAAmB,CAAA;AAU1B,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA"}

package/dist/observations.d.ts

@@ -17,7 +17,7 @@
  * to its mutable `TrackedRecord`, then emits the returned `events`
  * via its event-bus + store-audit-log machinery.
  */
-import type { EventSource, RawTx } from '@valve-tech/chain-source';
+import type { EventSource, RawTx, TransactionReceipt } from '@valve-tech/chain-source';
 import { type At, type Hash, type TxEvent, type TxStatus } from './events.js';
 /**
  * Read-only projection of `TrackedRecord` that the decision functions
@@ -76,6 +76,16 @@ export interface BlockObservationInput {
      * very first block we observe.
      */
     previousTipNumber: bigint | null;
+    /**
+     * Pre-fetched receipts for hashes whose `withReceipts` flag is set.
+     * When a hash appears in this map, the receipt is attached to the
+     * `seen-in-block` event. Omitted or empty means no enrichment. This
+     * is the sole path for F2 eager receipt attachment (spec §18.2) —
+     * the orchestrator fetches and populates this map before calling
+     * `decideBlockObservation`, so the first emitted event carries the
+     * receipt without a follow-up re-emit.
+     */
+    prefetchedReceipts?: ReadonlyMap<Hash, TransactionReceipt>;
 }
 /**
  * Per-record decision for one new canonical block. Returns the events

package/dist/observations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observations.d.ts","sourceRoot":"","sources":["../src/observations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAA;AAElE,OAAO,EAML,KAAK,EAAE,EACP,KAAK,IAAI,EACT,KAAK,OAAO,EACZ,KAAK,QAAQ,EACd,MAAM,aAAa,CAAA;AAEpB;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,IAAI,CAAA;IACV,MAAM,EAAE,QAAQ,CAAA;IAChB,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;IAChD,qBAAqB,EAAE,OAAO,CAAA;IAC9B,qBAAqB,EAAE,MAAM,CAAA;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;CACd;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,OAAO,EAAE,CAAA;IACjB,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAA;IAC9B,aAAa,EAAE,aAAa,GAAG,IAAI,CAAA;IACnC,uEAAuE;IACvE,cAAc,EAAE,OAAO,GAAG,IAAI,CAAA;CAC/B;AAaD;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,qBAAqB,CAAA;IAC7B,SAAS,EAAE,IAAI,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,WAAW,CAAC,IAAI,CAAC,CAAA;IAC5B,GAAG,EAAE,aAAa,CAAC,KAAK,CAAC,CAAA;IACzB,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,WAAW,CAAA;IACxB,QAAQ,EAAE,EAAE,CAAA;IACZ;;;;;OAKG;IACH,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAA;CACjC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,sBAAsB,GACjC,OAAO,qBAAqB,KAC3B,iBA6IF,CAAA;AAMD;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,qBAAqB,CAAA;IAC7B,QAAQ,EAAE;QAAE,MAAM,EAAE,SAAS,GAAG,QAAQ,CAAC;QAAC,EAAE,EAAE,KAAK,CAAA;KAAE,GAAG,IAAI,CAAA;IAC5D;;;;;OAKG;IACH,oBAAoB,EAAE,KAAK,GAAG,IAAI,CAAA;IAClC,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,WAAW,CAAA;IACxB,QAAQ,EAAE,EAAE,CAAA;IACZ;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,GACnC,OAAO,uBAAuB,KAC7B,iBAqFF,CAAA;AAMD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,GACjC,UAAU;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EACzC,cAAc,IAAI,EAClB,KAAK,aAAa,CAAC,KAAK,CAAC,KACxB,KAAK,GAAG,IAUV,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,aAAa,GACxB,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,EAC/C,IAAI,KAAK,KACR,aAAa,GAAG,IAIlB,CAAA"}
+{"version":3,"file":"observations.d.ts","sourceRoot":"","sources":["../src/observations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAEtF,OAAO,EAML,KAAK,EAAE,EACP,KAAK,IAAI,EACT,KAAK,OAAO,EACZ,KAAK,QAAQ,EACd,MAAM,aAAa,CAAA;AAEpB;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,IAAI,CAAA;IACV,MAAM,EAAE,QAAQ,CAAA;IAChB,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;IAChD,qBAAqB,EAAE,OAAO,CAAA;IAC9B,qBAAqB,EAAE,MAAM,CAAA;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;CACd;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,OAAO,EAAE,CAAA;IACjB,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAA;IAC9B,aAAa,EAAE,aAAa,GAAG,IAAI,CAAA;IACnC,uEAAuE;IACvE,cAAc,EAAE,OAAO,GAAG,IAAI,CAAA;CAC/B;AAaD;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,qBAAqB,CAAA;IAC7B,SAAS,EAAE,IAAI,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,WAAW,CAAC,IAAI,CAAC,CAAA;IAC5B,GAAG,EAAE,aAAa,CAAC,KAAK,CAAC,CAAA;IACzB,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,WAAW,CAAA;IACxB,QAAQ,EAAE,EAAE,CAAA;IACZ;;;;;OAKG;IACH,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC;;;;;;;;OAQG;IACH,kBAAkB,CAAC,EAAE,WAAW,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAA;CAC3D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,sBAAsB,GACjC,OAAO,qBAAqB,KAC3B,iBAkJF,CAAA;AAMD;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,qBAAqB,CAAA;IAC7B,QAAQ,EAAE;QAAE,MAAM,EAAE,SAAS,GAAG,QAAQ,CAAC;QAAC,EAAE,EAAE,KAAK,CAAA;KAAE,GAAG,IAAI,CAAA;IAC5D;;;;;OAKG;IACH,oBAAoB,EAAE,KAAK,GAAG,IAAI,CAAA;IAClC,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,WAAW,CAAA;IACxB,QAAQ,EAAE,EAAE,CAAA;IACZ;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,GACnC,OAAO,uBAAuB,KAC7B,iBAqFF,CAAA;AAMD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,GACjC,UAAU;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EACzC,cAAc,IAAI,EAClB,KAAK,aAAa,CAAC,KAAK,CAAC,KACxB,KAAK,GAAG,IAUV,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,aAAa,GACxB,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,EAC/C,IAAI,KAAK,KACR,aAAa,GAAG,IAIlB,CAAA"}

package/dist/observations.js

@@ -45,7 +45,7 @@ const EMPTY_RESULT = {
  *      after subscription (no `firstObservedAtBlock` yet).
  */
 export const decideBlockObservation = (input) => {
-    const { record, blockHash, blockNumber, txHashSet, txs, chainId, eventSource, envelope, previousTipNumber, } = input;
+    const { record, blockHash, blockNumber, txHashSet, txs, chainId, eventSource, envelope, previousTipNumber, prefetchedReceipts, } = input;
     const wasSeenInThisBlock = txHashSet.has(record.hash);
     if (wasSeenInThisBlock) {
         const tx = txs.find((t) => t.hash === record.hash);
@@ -66,6 +66,9 @@ export const decideBlockObservation = (input) => {
             confirmations,
             source: eventSource,
         };
+        const receipt = isFreshInclusion
+            ? prefetchedReceipts?.get(record.hash)
+            : undefined;
         const events = isFreshInclusion
             ? [
                 buildSeenInBlock({
@@ -77,6 +80,7 @@ export const decideBlockObservation = (input) => {
                     blockNumber,
                     transactionIndex,
                     confirmations,
+                    ...(receipt !== undefined ? { receipt } : {}),
                 }),
             ]
             : [];