@valve-tech/tx-tracker 0.6.0 → 0.8.0

package/dist/events.d.ts

@@ -0,0 +1,309 @@
+/**
+ * `TxEvent` — the discriminated union of every observation the
+ * tracker emits, plus payload builders that guarantee every event
+ * carries a complete envelope.
+ *
+ * Per `docs/tx-tracker-spec.md` §6, this taxonomy is the contract
+ * between the tracker and every consumer. Naming is **strictly
+ * neutral** (§2.1): `seen-in-mempool` not `pending`, `seen-in-block`
+ * not `mined`, `vanished-from-block` not `reorged`. The tracker
+ * publishes facts; the consumer writes the policy on top.
+ *
+ * Every event variant extends a common `Envelope` carrying the
+ * tracked `hash`, the `chainId`, the `source` discriminator (per
+ * §2.2 — never silently downgrade) and the `at` block coordinate
+ * the observation was made at. Builders here produce that envelope
+ * once so the state machine in `tracker.ts` cannot accidentally
+ * publish a partial event.
+ *
+ * No I/O, no wall-clock, no mutation — pure data shape + pure
+ * builders. Browser/mobile safe (§2.4).
+ */
+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
+ * permissive at the JSON boundary; tx-tracker mirrors that posture
+ * — every consumer can `as Hash` at the seam if they need the
+ * branded form.
+ */
+export type Hash = string;
+/**
+ * EVM address. Same posture as `Hash` — plain `string` so consumers
+ * who normalize to lowercase or to checksum form don't trip a brand
+ * check at the boundary.
+ */
+export type Address = string;
+/**
+ * Block coordinate the observation was made at. `blockNumber` is the
+ * canonical-tip number when the observation landed; `timestamp` is
+ * the tip block's timestamp (seconds since epoch, same units the
+ * EVM exposes). Both `bigint` per the toolkit's wire-format rule
+ * (§2.5).
+ */
+export interface At {
+    blockNumber: bigint;
+    timestamp: bigint;
+}
+/**
+ * Common envelope on every event. The state machine builds this once
+ * per emit and merges it into the variant-specific payload below.
+ */
+export interface Envelope {
+    hash: Hash;
+    chainId: number;
+    source: EventSource;
+    at: At;
+}
+/**
+ * Per-variant payload shapes. Consumers narrow on `event.kind` to
+ * access variant-specific fields. The eslint config disallows TS
+ * namespaces, so each variant is a top-level interface and the
+ * `TxEvent` union below sums them.
+ */
+/**
+ * Synthetic first event of a subscription when `emitInitial: true`
+ * (the default). Carries the capability snapshot at subscribe time
+ * so consumers can decide their fallback posture without a separate
+ * call.
+ */
+export interface TxEventStarted extends Envelope {
+    kind: 'started';
+    capabilities: Capabilities;
+}
+/**
+ * Tracked hash was observed in the upstream's mempool snapshot or
+ * pushed via `eth_subscribe('newPendingTransactions')`. `bucket`
+ * disambiguates `txpool_content`'s pending-vs-queued split.
+ */
+export interface TxEventSeenInMempool extends Envelope {
+    kind: 'seen-in-mempool';
+    bucket: 'pending' | 'queued';
+    tx: RawTx;
+}
+/**
+ * Tracked hash is no longer in the mempool snapshot. The tx may
+ * have been mined, replaced, or evicted by the upstream node;
+ * subsequent `seen-in-block` / `replaced-by` / `unseen-for-N-blocks`
+ * disambiguates which of those happened.
+ */
+export interface TxEventLeftMempool extends Envelope {
+    kind: 'left-mempool';
+}
+/**
+ * Tracked hash was found in the canonical block at
+ * `blockNumber` / `blockHash`, at index `transactionIndex`.
+ * `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';
+    blockHash: Hash;
+    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
+ * `previousBlockHash`, but the canonical block at the same height
+ * now has `canonicalBlockHash` and the tracked tx is not in its
+ * `transactions`. Reorg.
+ *
+ * Per spec §12.3, this event never carries
+ * `source: 'receipt-poll'` — receipt-poll cannot detect a reorg
+ * because most providers happily return a receipt for a tx in a
+ * no-longer-canonical block.
+ */
+export interface TxEventVanishedFromBlock extends Envelope {
+    kind: 'vanished-from-block';
+    previousBlockHash: Hash;
+    canonicalBlockHash: Hash;
+    blockNumber: bigint;
+}
+/**
+ * A different hash with the same `(from, nonce)` pair was either
+ * seen in the mempool or mined. `replacementBlockNumber` is `null`
+ * when the replacement was only observed in the mempool; it
+ * carries the mined block's number when the replacement reached
+ * inclusion before the original.
+ */
+export interface TxEventReplacedBy extends Envelope {
+    kind: 'replaced-by';
+    replacementHash: Hash;
+    replacementBlockNumber: bigint | null;
+}
+/**
+ * Tracked hash has not been in the mempool nor in any polled
+ * block for `blocks` consecutive observations. Threshold is
+ * configurable per subscription (`unseenThresholdBlocks`,
+ * default 30 — see `tracker.ts`). Consumer interprets as
+ * "likely dropped" / "stuck" / "rejected" in their own UX.
+ */
+export interface TxEventUnseenForNBlocks extends Envelope {
+    kind: 'unseen-for-N-blocks';
+    blocks: number;
+}
+/**
+ * A capability the tracker had been relying on for this hash is
+ * no longer authoritative — typically because the WS subscription
+ * dropped or `txpool_content` was newly gated. Tracking continues
+ * via `fallbackSource`; the consumer's interpretation of subsequent
+ * events should weigh that lower authority.
+ */
+export interface TxEventSignalDegraded extends Envelope {
+    kind: 'signal-degraded';
+    capabilityLost: keyof Capabilities;
+    fallbackSource: EventSource;
+}
+/**
+ * A previously-degraded capability is back. Fired after a
+ * matching `signal-degraded` only.
+ */
+export interface TxEventSignalRecovered extends Envelope {
+    kind: 'signal-recovered';
+    capabilityRestored: keyof Capabilities;
+}
+/**
+ * Subscription teardown — fires once per subscription. Always the
+ * final event in the stream for that subscription. `reason`
+ * disambiguates which lifecycle path closed the iterator:
+ *
+ * - `'unsubscribed'`: consumer called the returned unsubscribe
+ *   handle (or `break`'d an async iterator).
+ * - `'retention-expired'`: store's retention window elapsed past
+ *   the last terminal observation; the record was GC'd.
+ * - `'tracker-stopped'`: `tracker.stop()` was called.
+ */
+export interface TxEventStopped extends Envelope {
+    kind: 'stopped';
+    reason: 'unsubscribed' | 'retention-expired' | 'tracker-stopped';
+}
+/**
+ * Discriminated union of every event variant. Narrow on `kind` to
+ * access variant-specific fields.
+ */
+export type TxEvent = TxEventStarted | TxEventSeenInMempool | TxEventLeftMempool | TxEventSeenInBlock | TxEventVanishedFromBlock | TxEventReplacedBy | TxEventUnseenForNBlocks | TxEventSignalDegraded | TxEventSignalRecovered | TxEventStopped;
+/**
+ * `TxStatus` — cached snapshot the state machine maintains per
+ * tracked hash. `getTxStatus(hash)` returns this; the iterator and
+ * callback adapters read from the same backing store so all three
+ * consumption shapes see consistent state.
+ *
+ * Carries the **last observation** rather than a derived editorial
+ * verb. Consumers interpret the fields as policy.
+ */
+export interface TxStatus {
+    hash: Hash;
+    chainId: number;
+    /** Last observed inclusion (null if never observed in a block). */
+    lastSeenInBlock: {
+        blockHash: Hash;
+        blockNumber: bigint;
+        transactionIndex: number;
+        /** Most recent confirmations count emitted. */
+        confirmations: number;
+        source: EventSource;
+    } | null;
+    /** Last observed mempool placement (null if never observed). */
+    lastSeenInMempool: {
+        bucket: 'pending' | 'queued';
+        tx: RawTx;
+        at: At;
+        source: EventSource;
+    } | null;
+    /** Replacement hash if ever observed (null otherwise). */
+    replacedBy: {
+        hash: Hash;
+        blockNumber: bigint | null;
+    } | null;
+    /** Last vanished-from-block observation, when applicable. */
+    vanishedAt: {
+        previousBlockHash: Hash;
+        canonicalBlockHash: Hash;
+        blockNumber: bigint;
+    } | null;
+    /** Number of consecutive observed blocks the hash has been unseen. */
+    unseenStreak: number;
+    /** First observation block number — used by retention. */
+    firstObservedAtBlock: bigint | null;
+    /** Most recent observation block number — used by retention. */
+    lastObservedAtBlock: bigint | null;
+    /** Capabilities at the most recent emit. */
+    capabilities: Capabilities;
+}
+/** Build a `started` event. */
+export declare const buildStarted: (input: Envelope & {
+    capabilities: Capabilities;
+}) => TxEventStarted;
+/** Build a `seen-in-mempool` event. */
+export declare const buildSeenInMempool: (input: Envelope & {
+    bucket: "pending" | "queued";
+    tx: RawTx;
+}) => TxEventSeenInMempool;
+/** Build a `left-mempool` event. */
+export declare const buildLeftMempool: (input: Envelope) => TxEventLeftMempool;
+/** Build a `seen-in-block` event. */
+export declare const buildSeenInBlock: (input: Envelope & {
+    blockHash: Hash;
+    blockNumber: bigint;
+    transactionIndex: number;
+    confirmations: number;
+    receipt?: TransactionReceipt;
+}) => TxEventSeenInBlock;
+/**
+ * Build a `vanished-from-block` event. Spec §12.3 forbids
+ * `source: 'receipt-poll'` for this kind — receipt-poll cannot
+ * detect a reorg authoritatively, so the builder rejects that
+ * combination at construction rather than letting a malformed
+ * event ship to consumers.
+ */
+export declare const buildVanishedFromBlock: (input: Envelope & {
+    previousBlockHash: Hash;
+    canonicalBlockHash: Hash;
+    blockNumber: bigint;
+}) => TxEventVanishedFromBlock;
+/** Build a `replaced-by` event. */
+export declare const buildReplacedBy: (input: Envelope & {
+    replacementHash: Hash;
+    replacementBlockNumber: bigint | null;
+}) => TxEventReplacedBy;
+/** Build an `unseen-for-N-blocks` event. */
+export declare const buildUnseenForNBlocks: (input: Envelope & {
+    blocks: number;
+}) => TxEventUnseenForNBlocks;
+/** Build a `signal-degraded` event. */
+export declare const buildSignalDegraded: (input: Envelope & {
+    capabilityLost: keyof Capabilities;
+    fallbackSource: EventSource;
+}) => TxEventSignalDegraded;
+/** Build a `signal-recovered` event. */
+export declare const buildSignalRecovered: (input: Envelope & {
+    capabilityRestored: keyof Capabilities;
+}) => TxEventSignalRecovered;
+/** Build a `stopped` event. */
+export declare const buildStopped: (input: Envelope & {
+    reason: "unsubscribed" | "retention-expired" | "tracker-stopped";
+}) => TxEventStopped;
+/**
+ * Snapshot constructor for a freshly-tracked hash. Used by the
+ * tracker to seed its in-memory record before any observation has
+ * landed. All "last observed" fields start `null`; `unseenStreak`
+ * starts `0`. Capabilities are passed in (sourced from
+ * `source.capabilities()` at construction).
+ */
+export declare const buildInitialStatus: (input: {
+    hash: Hash;
+    chainId: number;
+    capabilities: Capabilities;
+}) => TxStatus;
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

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

package/dist/events.js

@@ -0,0 +1,132 @@
+/**
+ * `TxEvent` — the discriminated union of every observation the
+ * tracker emits, plus payload builders that guarantee every event
+ * carries a complete envelope.
+ *
+ * Per `docs/tx-tracker-spec.md` §6, this taxonomy is the contract
+ * between the tracker and every consumer. Naming is **strictly
+ * neutral** (§2.1): `seen-in-mempool` not `pending`, `seen-in-block`
+ * not `mined`, `vanished-from-block` not `reorged`. The tracker
+ * publishes facts; the consumer writes the policy on top.
+ *
+ * Every event variant extends a common `Envelope` carrying the
+ * tracked `hash`, the `chainId`, the `source` discriminator (per
+ * §2.2 — never silently downgrade) and the `at` block coordinate
+ * the observation was made at. Builders here produce that envelope
+ * once so the state machine in `tracker.ts` cannot accidentally
+ * publish a partial event.
+ *
+ * No I/O, no wall-clock, no mutation — pure data shape + pure
+ * builders. Browser/mobile safe (§2.4).
+ */
+/**
+ * Build an event envelope from the per-tracker context plus the
+ * call-site overrides. Used by every builder below so the envelope
+ * shape is centralized.
+ */
+const makeEnvelope = (input) => ({
+    hash: input.hash,
+    chainId: input.chainId,
+    source: input.source,
+    at: { blockNumber: input.at.blockNumber, timestamp: input.at.timestamp },
+});
+/** Build a `started` event. */
+export const buildStarted = (input) => ({
+    ...makeEnvelope(input),
+    kind: 'started',
+    capabilities: input.capabilities,
+});
+/** Build a `seen-in-mempool` event. */
+export const buildSeenInMempool = (input) => ({
+    ...makeEnvelope(input),
+    kind: 'seen-in-mempool',
+    bucket: input.bucket,
+    tx: input.tx,
+});
+/** Build a `left-mempool` event. */
+export const buildLeftMempool = (input) => ({
+    ...makeEnvelope(input),
+    kind: 'left-mempool',
+});
+/** Build a `seen-in-block` event. */
+export const buildSeenInBlock = (input) => ({
+    ...makeEnvelope(input),
+    kind: 'seen-in-block',
+    blockHash: input.blockHash,
+    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
+ * `source: 'receipt-poll'` for this kind — receipt-poll cannot
+ * detect a reorg authoritatively, so the builder rejects that
+ * combination at construction rather than letting a malformed
+ * event ship to consumers.
+ */
+export const buildVanishedFromBlock = (input) => {
+    if (input.source === 'receipt-poll') {
+        throw new Error('buildVanishedFromBlock: receipt-poll cannot detect reorgs ' +
+            '(spec §12.3). Use block-poll or subscription source.');
+    }
+    return {
+        ...makeEnvelope(input),
+        kind: 'vanished-from-block',
+        previousBlockHash: input.previousBlockHash,
+        canonicalBlockHash: input.canonicalBlockHash,
+        blockNumber: input.blockNumber,
+    };
+};
+/** Build a `replaced-by` event. */
+export const buildReplacedBy = (input) => ({
+    ...makeEnvelope(input),
+    kind: 'replaced-by',
+    replacementHash: input.replacementHash,
+    replacementBlockNumber: input.replacementBlockNumber,
+});
+/** Build an `unseen-for-N-blocks` event. */
+export const buildUnseenForNBlocks = (input) => ({
+    ...makeEnvelope(input),
+    kind: 'unseen-for-N-blocks',
+    blocks: input.blocks,
+});
+/** Build a `signal-degraded` event. */
+export const buildSignalDegraded = (input) => ({
+    ...makeEnvelope(input),
+    kind: 'signal-degraded',
+    capabilityLost: input.capabilityLost,
+    fallbackSource: input.fallbackSource,
+});
+/** Build a `signal-recovered` event. */
+export const buildSignalRecovered = (input) => ({
+    ...makeEnvelope(input),
+    kind: 'signal-recovered',
+    capabilityRestored: input.capabilityRestored,
+});
+/** Build a `stopped` event. */
+export const buildStopped = (input) => ({
+    ...makeEnvelope(input),
+    kind: 'stopped',
+    reason: input.reason,
+});
+/**
+ * Snapshot constructor for a freshly-tracked hash. Used by the
+ * tracker to seed its in-memory record before any observation has
+ * landed. All "last observed" fields start `null`; `unseenStreak`
+ * starts `0`. Capabilities are passed in (sourced from
+ * `source.capabilities()` at construction).
+ */
+export const buildInitialStatus = (input) => ({
+    hash: input.hash,
+    chainId: input.chainId,
+    lastSeenInBlock: null,
+    lastSeenInMempool: null,
+    replacedBy: null,
+    vanishedAt: null,
+    unseenStreak: 0,
+    firstObservedAtBlock: null,
+    lastObservedAtBlock: null,
+    capabilities: input.capabilities,
+});
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AA4PH;;;;GAIG;AACH,MAAM,YAAY,GAAG,CAAC,KAAe,EAAY,EAAE,CAAC,CAAC;IACnD,IAAI,EAAE,KAAK,CAAC,IAAI;IAChB,OAAO,EAAE,KAAK,CAAC,OAAO;IACtB,MAAM,EAAE,KAAK,CAAC,MAAM;IACpB,EAAE,EAAE,EAAE,WAAW,EAAE,KAAK,CAAC,EAAE,CAAC,WAAW,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,CAAC,SAAS,EAAE;CACzE,CAAC,CAAA;AAEF,+BAA+B;AAC/B,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,KAAgD,EAChC,EAAE,CAAC,CAAC;IACpB,GAAG,YAAY,CAAC,KAAK,CAAC;IACtB,IAAI,EAAE,SAAS;IACf,YAAY,EAAE,KAAK,CAAC,YAAY;CACjC,CAAC,CAAA;AAEF,uCAAuC;AACvC,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,KAA6D,EACvC,EAAE,CAAC,CAAC;IAC1B,GAAG,YAAY,CAAC,KAAK,CAAC;IACtB,IAAI,EAAE,iBAAiB;IACvB,MAAM,EAAE,KAAK,CAAC,MAAM;IACpB,EAAE,EAAE,KAAK,CAAC,EAAE;CACb,CAAC,CAAA;AAEF,oCAAoC;AACpC,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,KAAe,EAAsB,EAAE,CAAC,CAAC;IACxE,GAAG,YAAY,CAAC,KAAK,CAAC;IACtB,IAAI,EAAE,cAAc;CACrB,CAAC,CAAA;AAEF,qCAAqC;AACrC,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,KAMC,EACmB,EAAE,CAAC,CAAC;IACxB,GAAG,YAAY,CAAC,KAAK,CAAC;IACtB,IAAI,EAAE,eAAe;IACrB,SAAS,EAAE,KAAK,CAAC,SAAS;IAC1B,WAAW,EAAE,KAAK,CAAC,WAAW;IAC9B,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;IACxC,aAAa,EAAE,KAAK,CAAC,aAAa;IAClC,GAAG,CAAC,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;CACnE,CAAC,CAAA;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CACpC,KAIC,EACyB,EAAE;IAC5B,IAAI,KAAK,CAAC,MAAM,KAAK,cAAc,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CACb,4DAA4D;YAC1D,sDAAsD,CACzD,CAAA;IACH,CAAC;IACD,OAAO;QACL,GAAG,YAAY,CAAC,KAAK,CAAC;QACtB,IAAI,EAAE,qBAAqB;QAC3B,iBAAiB,EAAE,KAAK,CAAC,iBAAiB;QAC1C,kBAAkB,EAAE,KAAK,CAAC,kBAAkB;QAC5C,WAAW,EAAE,KAAK,CAAC,WAAW;KAC/B,CAAA;AACH,CAAC,CAAA;AAED,mCAAmC;AACnC,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,KAGC,EACkB,EAAE,CAAC,CAAC;IACvB,GAAG,YAAY,CAAC,KAAK,CAAC;IACtB,IAAI,EAAE,aAAa;IACnB,eAAe,EAAE,KAAK,CAAC,eAAe;IACtC,sBAAsB,EAAE,KAAK,CAAC,sBAAsB;CACrD,CAAC,CAAA;AAEF,4CAA4C;AAC5C,MAAM,CAAC,MAAM,qBAAqB,GAAG,CACnC,KAAoC,EACX,EAAE,CAAC,CAAC;IAC7B,GAAG,YAAY,CAAC,KAAK,CAAC;IACtB,IAAI,EAAE,qBAAqB;IAC3B,MAAM,EAAE,KAAK,CAAC,MAAM;CACrB,CAAC,CAAA;AAEF,uCAAuC;AACvC,MAAM,CAAC,MAAM,mBAAmB,GAAG,CACjC,KAGC,EACsB,EAAE,CAAC,CAAC;IAC3B,GAAG,YAAY,CAAC,KAAK,CAAC;IACtB,IAAI,EAAE,iBAAiB;IACvB,cAAc,EAAE,KAAK,CAAC,cAAc;IACpC,cAAc,EAAE,KAAK,CAAC,cAAc;CACrC,CAAC,CAAA;AAEF,wCAAwC;AACxC,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,KAA4D,EACpC,EAAE,CAAC,CAAC;IAC5B,GAAG,YAAY,CAAC,KAAK,CAAC;IACtB,IAAI,EAAE,kBAAkB;IACxB,kBAAkB,EAAE,KAAK,CAAC,kBAAkB;CAC7C,CAAC,CAAA;AAEF,+BAA+B;AAC/B,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,KAEC,EACe,EAAE,CAAC,CAAC;IACpB,GAAG,YAAY,CAAC,KAAK,CAAC;IACtB,IAAI,EAAE,SAAS;IACf,MAAM,EAAE,KAAK,CAAC,MAAM;CACrB,CAAC,CAAA;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,KAIlC,EAAY,EAAE,CAAC,CAAC;IACf,IAAI,EAAE,KAAK,CAAC,IAAI;IAChB,OAAO,EAAE,KAAK,CAAC,OAAO;IACtB,eAAe,EAAE,IAAI;IACrB,iBAAiB,EAAE,IAAI;IACvB,UAAU,EAAE,IAAI;IAChB,UAAU,EAAE,IAAI;IAChB,YAAY,EAAE,CAAC;IACf,oBAAoB,EAAE,IAAI;IAC1B,mBAAmB,EAAE,IAAI;IACzB,YAAY,EAAE,KAAK,CAAC,YAAY;CACjC,CAAC,CAAA"}

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"}