@valve-tech/tx-tracker 0.5.0 → 0.7.0

package/dist/observations.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Per-record decision functions — the **pure** logic that turns one
+ * upstream observation (a block or a mempool snapshot) plus one
+ * tracked record's current state into the events that should be
+ * emitted and the state patch the orchestrator should apply.
+ *
+ * These functions are extracted from `tracker.ts`'s `onBlock` /
+ * `onMempool` so each branch of the per-record state machine is
+ * testable with literal fixture inputs — no stub source, no async
+ * orchestration, no shared mutable closure. This is the same
+ * primitive-vs-orchestrator split that `oracle.ts` (`reducePollInputs`
+ * pure / poll loop stateful) and `chain-source` (math pure / source
+ * stateful) already follow.
+ *
+ * Inputs are immutable; outputs are immutable. The caller in
+ * `tracker.ts` applies the returned `statusPatch` and `identityPatch`
+ * 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 At, type Hash, type TxEvent, type TxStatus } from './events.js';
+/**
+ * Read-only projection of `TrackedRecord` that the decision functions
+ * consume. The orchestrator passes its mutable record through this
+ * shape so the pure layer cannot accidentally mutate state.
+ */
+export interface ReadonlyTrackedRecord {
+    hash: Hash;
+    status: TxStatus;
+    identity: {
+        from: string;
+        nonce: string;
+    } | null;
+    inLastMempoolSnapshot: boolean;
+    unseenThresholdBlocks: number;
+}
+/**
+ * Cached `(from, nonce)` identity of the tracked tx. Used for
+ * replacement detection.
+ */
+export interface IdentityPatch {
+    from: string;
+    nonce: string;
+}
+/**
+ * Result of a decision function: events to emit and patches to apply
+ * to the tracked record. The patch shapes are deliberately narrow —
+ * only the fields the function decided to change. The orchestrator
+ * merges them into its mutable record.
+ */
+export interface ObservationResult {
+    events: TxEvent[];
+    statusPatch: Partial<TxStatus>;
+    identityPatch: IdentityPatch | null;
+    /** Set when the per-mempool-tick "in-snapshot?" flag should change. */
+    inMempoolPatch: boolean | null;
+}
+/**
+ * Inputs to `decideBlockObservation`. The orchestrator builds a
+ * `txHashSet` once per block and passes it for O(1) "did this hash
+ * appear?" lookups across every tracked record.
+ */
+export interface BlockObservationInput {
+    record: ReadonlyTrackedRecord;
+    blockHash: Hash;
+    blockNumber: bigint;
+    txHashSet: ReadonlySet<Hash>;
+    txs: ReadonlyArray<RawTx>;
+    chainId: number;
+    eventSource: EventSource;
+    envelope: At;
+    /**
+     * The previous canonical tip's block number, or `null` if this is
+     * the first block the tracker has seen. Used to gate the
+     * "confirmation bump" path — we don't bump confirmations on the
+     * very first block we observe.
+     */
+    previousTipNumber: bigint | null;
+}
+/**
+ * Per-record decision for one new canonical block. Returns the events
+ * to emit and the state patch to apply. Mutually-exclusive paths,
+ * evaluated in order:
+ *
+ *   1. Hash is in this block → fresh inclusion (emit `seen-in-block`
+ *      with `confirmations: 1`) OR same-block re-observation (no
+ *      emit; `lastSeenInBlock` is already current).
+ *   2. Hash NOT in this block but was previously included → bump
+ *      `confirmations` on the cached observation, emit a fresh
+ *      `seen-in-block` carrying the new count.
+ *   3. Hash NOT in this block, no prior inclusion, but identity is
+ *      cached AND a different hash with the same `(from, nonce)` is
+ *      in this block → emit `replaced-by` with the replacement's
+ *      block number.
+ *   4. Truly unseen → bump the unseen-block streak; emit
+ *      `unseen-for-N-blocks` when the streak crosses the
+ *      subscription's threshold. Does NOT emit on the first block
+ *      after subscription (no `firstObservedAtBlock` yet).
+ */
+export declare const decideBlockObservation: (input: BlockObservationInput) => ObservationResult;
+/**
+ * Inputs to `decideMempoolObservation`. The orchestrator builds the
+ * hash-keyed snapshot index once per mempool tick.
+ */
+export interface MempoolObservationInput {
+    record: ReadonlyTrackedRecord;
+    presence: {
+        bucket: 'pending' | 'queued';
+        tx: RawTx;
+    } | null;
+    /**
+     * The replacement candidate found in the snapshot for this record's
+     * `(from, nonce)` identity, or `null` if none. Computed by the
+     * orchestrator once per record so this function stays pure on
+     * inputs (no closure over the snapshot).
+     */
+    replacementInMempool: RawTx | null;
+    chainId: number;
+    eventSource: EventSource;
+    envelope: At;
+    /**
+     * The current canonical-tip block number the orchestrator is using
+     * for `firstObservedAtBlock` / `lastObservedAtBlock` book-keeping.
+     * Falls back to `0n` when no tip has been observed yet.
+     */
+    tipBlockNumber: bigint;
+}
+/**
+ * Per-record decision for one mempool snapshot. Three independent
+ * outputs that may all fire on the same call:
+ *
+ *   - **Presence transition** — emit `seen-in-mempool` on first
+ *     observation or bucket change; emit `left-mempool` when a
+ *     previously-seen hash is absent from this snapshot.
+ *   - **Replacement** — emit `replaced-by` (with `null` block) when
+ *     the orchestrator's pre-computed `replacementInMempool` is set
+ *     AND the record hasn't already recorded a replacement.
+ */
+export declare const decideMempoolObservation: (input: MempoolObservationInput) => ObservationResult;
+/**
+ * Find a tx in `txs` whose `(from, nonce)` matches `identity` but
+ * whose hash differs from `originalHash` — the replacement candidate
+ * for the original tracked tx. Compares senders case-insensitively
+ * since upstreams disagree on checksum form.
+ */
+export declare const findReplacementInBlock: (identity: {
+    from: string;
+    nonce: string;
+}, originalHash: Hash, txs: ReadonlyArray<RawTx>) => RawTx | null;
+/**
+ * Cache the tx's `(from, nonce)` as the record's identity if it's
+ * not already cached AND the tx carries both fields. Returns the
+ * patch to apply (or `null` when no change).
+ */
+export declare const cacheIdentity: (current: {
+    from: string;
+    nonce: string;
+} | null, tx: RawTx) => IdentityPatch | null;
+//# sourceMappingURL=observations.d.ts.map

package/dist/observations.d.ts.map

@@ -0,0 +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"}

package/dist/observations.js

@@ -0,0 +1,283 @@
+/**
+ * Per-record decision functions — the **pure** logic that turns one
+ * upstream observation (a block or a mempool snapshot) plus one
+ * tracked record's current state into the events that should be
+ * emitted and the state patch the orchestrator should apply.
+ *
+ * These functions are extracted from `tracker.ts`'s `onBlock` /
+ * `onMempool` so each branch of the per-record state machine is
+ * testable with literal fixture inputs — no stub source, no async
+ * orchestration, no shared mutable closure. This is the same
+ * primitive-vs-orchestrator split that `oracle.ts` (`reducePollInputs`
+ * pure / poll loop stateful) and `chain-source` (math pure / source
+ * stateful) already follow.
+ *
+ * Inputs are immutable; outputs are immutable. The caller in
+ * `tracker.ts` applies the returned `statusPatch` and `identityPatch`
+ * to its mutable `TrackedRecord`, then emits the returned `events`
+ * via its event-bus + store-audit-log machinery.
+ */
+import { buildLeftMempool, buildReplacedBy, buildSeenInBlock, buildSeenInMempool, buildUnseenForNBlocks, } from './events.js';
+const EMPTY_RESULT = {
+    events: [],
+    statusPatch: {},
+    identityPatch: null,
+    inMempoolPatch: null,
+};
+/**
+ * Per-record decision for one new canonical block. Returns the events
+ * to emit and the state patch to apply. Mutually-exclusive paths,
+ * evaluated in order:
+ *
+ *   1. Hash is in this block → fresh inclusion (emit `seen-in-block`
+ *      with `confirmations: 1`) OR same-block re-observation (no
+ *      emit; `lastSeenInBlock` is already current).
+ *   2. Hash NOT in this block but was previously included → bump
+ *      `confirmations` on the cached observation, emit a fresh
+ *      `seen-in-block` carrying the new count.
+ *   3. Hash NOT in this block, no prior inclusion, but identity is
+ *      cached AND a different hash with the same `(from, nonce)` is
+ *      in this block → emit `replaced-by` with the replacement's
+ *      block number.
+ *   4. Truly unseen → bump the unseen-block streak; emit
+ *      `unseen-for-N-blocks` when the streak crosses the
+ *      subscription's threshold. Does NOT emit on the first block
+ *      after subscription (no `firstObservedAtBlock` yet).
+ */
+export const decideBlockObservation = (input) => {
+    const { record, blockHash, blockNumber, txHashSet, txs, chainId, eventSource, envelope, previousTipNumber, } = input;
+    const wasSeenInThisBlock = txHashSet.has(record.hash);
+    if (wasSeenInThisBlock) {
+        const tx = txs.find((t) => t.hash === record.hash);
+        if (!tx) {
+            // Defensive: hash was in the set but the find missed. Should
+            // be unreachable since the set is built from the same tx list.
+            return EMPTY_RESULT;
+        }
+        const transactionIndex = txs.indexOf(tx);
+        const isFreshInclusion = record.status.lastSeenInBlock?.blockHash !== blockHash;
+        const confirmations = isFreshInclusion
+            ? 1
+            : record.status.lastSeenInBlock.confirmations;
+        const lastSeenInBlock = {
+            blockHash,
+            blockNumber,
+            transactionIndex,
+            confirmations,
+            source: eventSource,
+        };
+        const events = isFreshInclusion
+            ? [
+                buildSeenInBlock({
+                    hash: record.hash,
+                    chainId,
+                    source: eventSource,
+                    at: envelope,
+                    blockHash,
+                    blockNumber,
+                    transactionIndex,
+                    confirmations,
+                }),
+            ]
+            : [];
+        return {
+            events,
+            statusPatch: {
+                lastSeenInBlock,
+                unseenStreak: 0,
+                firstObservedAtBlock: record.status.firstObservedAtBlock ?? blockNumber,
+                lastObservedAtBlock: blockNumber,
+            },
+            identityPatch: cacheIdentity(record.identity, tx),
+            inMempoolPatch: null,
+        };
+    }
+    // Path 2: not in this block, but previously observed → confirmation bump
+    if (record.status.lastSeenInBlock && previousTipNumber !== null) {
+        const bumped = record.status.lastSeenInBlock.confirmations + 1;
+        const updated = {
+            ...record.status.lastSeenInBlock,
+            confirmations: bumped,
+        };
+        return {
+            events: [
+                buildSeenInBlock({
+                    hash: record.hash,
+                    chainId,
+                    source: eventSource,
+                    at: envelope,
+                    blockHash: updated.blockHash,
+                    blockNumber: updated.blockNumber,
+                    transactionIndex: updated.transactionIndex,
+                    confirmations: bumped,
+                }),
+            ],
+            statusPatch: {
+                lastSeenInBlock: updated,
+                lastObservedAtBlock: blockNumber,
+            },
+            identityPatch: null,
+            inMempoolPatch: null,
+        };
+    }
+    // Path 3: replacement detection
+    if (record.identity) {
+        const replacement = findReplacementInBlock(record.identity, record.hash, txs);
+        if (replacement && replacement.hash) {
+            return {
+                events: [
+                    buildReplacedBy({
+                        hash: record.hash,
+                        chainId,
+                        source: eventSource,
+                        at: envelope,
+                        replacementHash: replacement.hash,
+                        replacementBlockNumber: blockNumber,
+                    }),
+                ],
+                statusPatch: {
+                    replacedBy: { hash: replacement.hash, blockNumber },
+                    lastObservedAtBlock: blockNumber,
+                },
+                identityPatch: null,
+                inMempoolPatch: null,
+            };
+        }
+    }
+    // Path 4: truly unseen — only counts when there's a prior
+    // observation to count from.
+    if (record.status.firstObservedAtBlock === null) {
+        return EMPTY_RESULT;
+    }
+    const nextStreak = record.status.unseenStreak + 1;
+    const events = nextStreak === record.unseenThresholdBlocks
+        ? [
+            buildUnseenForNBlocks({
+                hash: record.hash,
+                chainId,
+                source: eventSource,
+                at: envelope,
+                blocks: nextStreak,
+            }),
+        ]
+        : [];
+    return {
+        events,
+        statusPatch: { unseenStreak: nextStreak },
+        identityPatch: null,
+        inMempoolPatch: null,
+    };
+};
+/**
+ * Per-record decision for one mempool snapshot. Three independent
+ * outputs that may all fire on the same call:
+ *
+ *   - **Presence transition** — emit `seen-in-mempool` on first
+ *     observation or bucket change; emit `left-mempool` when a
+ *     previously-seen hash is absent from this snapshot.
+ *   - **Replacement** — emit `replaced-by` (with `null` block) when
+ *     the orchestrator's pre-computed `replacementInMempool` is set
+ *     AND the record hasn't already recorded a replacement.
+ */
+export const decideMempoolObservation = (input) => {
+    const { record, presence, replacementInMempool, chainId, eventSource, envelope, tipBlockNumber, } = input;
+    const events = [];
+    let statusPatch = {};
+    let identityPatch = null;
+    let inMempoolPatch = null;
+    if (presence) {
+        identityPatch = cacheIdentity(record.identity, presence.tx);
+        const isFreshOrBucketChange = !record.inLastMempoolSnapshot ||
+            record.status.lastSeenInMempool?.bucket !== presence.bucket;
+        statusPatch = {
+            lastSeenInMempool: {
+                bucket: presence.bucket,
+                tx: presence.tx,
+                at: envelope,
+                source: eventSource,
+            },
+            unseenStreak: 0,
+            firstObservedAtBlock: record.status.firstObservedAtBlock ?? tipBlockNumber,
+            lastObservedAtBlock: tipBlockNumber,
+        };
+        inMempoolPatch = true;
+        if (isFreshOrBucketChange) {
+            events.push(buildSeenInMempool({
+                hash: record.hash,
+                chainId,
+                source: eventSource,
+                at: envelope,
+                bucket: presence.bucket,
+                tx: presence.tx,
+            }));
+        }
+    }
+    else if (record.inLastMempoolSnapshot) {
+        inMempoolPatch = false;
+        events.push(buildLeftMempool({
+            hash: record.hash,
+            chainId,
+            source: eventSource,
+            at: envelope,
+        }));
+    }
+    // Replacement detection runs independently. The orchestrator skips
+    // it when the record already carries a replacement; we mirror that
+    // here so the function is self-contained.
+    if (record.identity &&
+        !record.status.replacedBy &&
+        replacementInMempool &&
+        replacementInMempool.hash &&
+        replacementInMempool.hash !== record.hash) {
+        statusPatch = {
+            ...statusPatch,
+            replacedBy: { hash: replacementInMempool.hash, blockNumber: null },
+        };
+        events.push(buildReplacedBy({
+            hash: record.hash,
+            chainId,
+            source: eventSource,
+            at: envelope,
+            replacementHash: replacementInMempool.hash,
+            replacementBlockNumber: null,
+        }));
+    }
+    return { events, statusPatch, identityPatch, inMempoolPatch };
+};
+// -------------------------------------------------------------
+// Helpers (also pure)
+// -------------------------------------------------------------
+/**
+ * Find a tx in `txs` whose `(from, nonce)` matches `identity` but
+ * whose hash differs from `originalHash` — the replacement candidate
+ * for the original tracked tx. Compares senders case-insensitively
+ * since upstreams disagree on checksum form.
+ */
+export const findReplacementInBlock = (identity, originalHash, txs) => {
+    const targetFrom = identity.from.toLowerCase();
+    for (const tx of txs) {
+        if (tx.from?.toLowerCase() !== targetFrom)
+            continue;
+        if (tx.nonce !== identity.nonce)
+            continue;
+        if (!tx.hash)
+            continue;
+        if (tx.hash === originalHash)
+            continue;
+        return tx;
+    }
+    return null;
+};
+/**
+ * Cache the tx's `(from, nonce)` as the record's identity if it's
+ * not already cached AND the tx carries both fields. Returns the
+ * patch to apply (or `null` when no change).
+ */
+export const cacheIdentity = (current, tx) => {
+    if (current)
+        return null;
+    if (!tx.from || !tx.nonce)
+        return null;
+    return { from: tx.from, nonce: tx.nonce };
+};
+//# sourceMappingURL=observations.js.map

package/dist/observations.js.map

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

package/dist/reorg.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Reorg detector — pure function over a recent-block ring.
+ *
+ * Per `docs/tx-tracker-spec.md` §12. The tracker keeps a small ring
+ * of recently-observed canonical blocks (`BlockSample` below). On
+ * every new tip, it walks the ring backward up to `reorgDepthBlocks`
+ * (default 12) and asks: "is the canonical chain at any of those
+ * heights different from what we recorded?" Any divergence becomes
+ * a `vanished-from-block` candidate the tracker translates per
+ * affected hash.
+ *
+ * Bounded depth (§12.2): a fixed 12-block window keeps the per-tick
+ * work O(depth) regardless of how anomalous the upstream's history
+ * is. Deeper reorgs are vanishingly rare on chains the package
+ * targets; "find the common ancestor" would let one bad reorg make
+ * a tick arbitrarily long.
+ *
+ * Pure: no I/O, no clock, no mutation of input. The tracker (in
+ * `tracker.ts`) calls `appendBlock` to fold each newly-observed
+ * canonical block into the ring, and `detectDivergences` against
+ * a candidate canonical sequence (typically the source's most
+ * recent emit + the on-demand block fetches the tracker did to
+ * walk the chain backward).
+ */
+import type { Hash } from './events.js';
+/**
+ * One canonical-block coordinate the tracker has observed. The
+ * tracker also records the `transactions` it saw on that block
+ * (just the hashes, not the full RawTx) so it can quickly answer
+ * "was tx X in block N?" without a fresh RPC.
+ */
+export interface BlockSample {
+    number: bigint;
+    hash: Hash;
+    parentHash: Hash | null;
+    /** Tx hashes observed in this block at the time it was canonical. */
+    transactionHashes: ReadonlySet<Hash>;
+}
+/**
+ * One divergence the detector found between the tracker's recorded
+ * ring and a freshly-observed canonical chain. The tracker
+ * translates this into per-hash `vanished-from-block` events for
+ * every tracked hash whose `seen-in-block` referenced the previous
+ * (now-stale) hash at this height.
+ */
+export interface BlockDivergence {
+    blockNumber: bigint;
+    /** Hash the ring previously had at this height. */
+    previousBlockHash: Hash;
+    /**
+     * Hash the canonical chain has at this height now. The detector
+     * only emits divergences for heights where the caller passed an
+     * explicit canonical block, so this is always a real hash.
+     */
+    canonicalBlockHash: Hash;
+    /**
+     * Tx hashes the ring saw on the previously-canonical block at
+     * this height. Tracker uses this to scope which tracked hashes
+     * are affected.
+     */
+    vanishedTransactionHashes: ReadonlySet<Hash>;
+}
+/**
+ * Append a freshly-observed canonical block into a bounded ring
+ * keyed by block number, capped at `capacityBlocks` entries. Returns
+ * a new ring (input is not mutated). The newest entry overwrites
+ * any previous entry at the same number — a same-height reorg
+ * replaces the stale block with the new canonical one.
+ */
+export declare const appendBlock: (ring: ReadonlyArray<BlockSample>, block: BlockSample, capacityBlocks: number) => BlockSample[];
+/**
+ * Compare the tracker's `ring` (already-recorded canonical blocks)
+ * against a freshly-observed `canonical` sequence (the tracker's
+ * latest observation, plus any walk-back probes it performed). At
+ * each height present in BOTH sides, if the hashes disagree the
+ * detector returns a `BlockDivergence`.
+ *
+ * **Heights present only in `ring` are skipped** — the detector
+ * treats "no canonical entry at this height" as "no information,"
+ * not "vanished." A real same-height reorg requires the caller to
+ * explicitly pass the new canonical block at that height; gapping
+ * (e.g. caller skipped a height) is not a divergence signal.
+ *
+ * If you need to detect "ring's tip is no longer in canonical" you
+ * pass the canonical chain that explicitly covers that height; with
+ * a partial canonical sequence the detector stays conservative.
+ *
+ * `depthBlocks` caps how far back the comparison runs. The tracker
+ * rarely cares about divergences beyond `reorgDepthBlocks` because
+ * any tracked tx that deep would already be considered finalized by
+ * downstream consumer policy.
+ *
+ * Returns an empty array on a clean chain extension (no divergences).
+ */
+export declare const detectDivergences: (input: {
+    ring: ReadonlyArray<BlockSample>;
+    canonical: ReadonlyArray<BlockSample>;
+    depthBlocks: number;
+}) => BlockDivergence[];
+/**
+ * Default reorg-detection depth in blocks. Conservative — even
+ * Ethereum's worst recent reorgs are under 7 blocks, and unbounded
+ * walks would let a single anomalous reorg make the tick arbitrarily
+ * long (§12.2). Tunable per-tracker via
+ * `CreateTxTrackerOptions.reorgDepthBlocks`.
+ */
+export declare const defaultReorgDepthBlocks = 12;
+//# sourceMappingURL=reorg.d.ts.map

package/dist/reorg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reorg.d.ts","sourceRoot":"","sources":["../src/reorg.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAEvC;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,IAAI,CAAA;IACV,UAAU,EAAE,IAAI,GAAG,IAAI,CAAA;IACvB,qEAAqE;IACrE,iBAAiB,EAAE,WAAW,CAAC,IAAI,CAAC,CAAA;CACrC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAA;IACnB,mDAAmD;IACnD,iBAAiB,EAAE,IAAI,CAAA;IACvB;;;;OAIG;IACH,kBAAkB,EAAE,IAAI,CAAA;IACxB;;;;OAIG;IACH,yBAAyB,EAAE,WAAW,CAAC,IAAI,CAAC,CAAA;CAC7C;AAED;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GACtB,MAAM,aAAa,CAAC,WAAW,CAAC,EAChC,OAAO,WAAW,EAClB,gBAAgB,MAAM,KACrB,WAAW,EAeb,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO;IACvC,IAAI,EAAE,aAAa,CAAC,WAAW,CAAC,CAAA;IAChC,SAAS,EAAE,aAAa,CAAC,WAAW,CAAC,CAAA;IACrC,WAAW,EAAE,MAAM,CAAA;CACpB,KAAG,eAAe,EA4ClB,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,KAAK,CAAA"}