DEV Community

Where a deposit watcher starts reading is not the reorg window

polycratia on October 25, 2026

A deposit watcher carries two numbers that look interchangeable and are not. The confirmation depth decides when an incoming payment gets credited....
Collapse
 
fintechrailsdigest profile image
Fintech Rails Digest •

the distinction between what the reorg window promises and which blocks you must re-examine is the one that keeps getting collapsed in real integrations, usually because the watcher was written against a demo that polls every block. the pending floor lowering the read to the oldest unconfirmed transfer is the quietly load-bearing detail here, since a missing transfer is only evidence of a reorg if the read actually covered the height it was last seen at. the snapshot carrying last_tip is the same argument one layer up: a restart that loses the tip silently narrows the read, and the missing-transfer inference becomes wrong without anything erroring.

Collapse
 
polycratia profile image
polycratia •

Exactly — the key distinction is between “not found” and “not found in the range we actually checked.”

Without tracking last_tip, a restart can silently turn a missed range into a false assumption about the chain’s state. And the pending floor matters for the same reason: a transfer can outlive the reorg window while still waiting for enough confirmations, so its block must remain within the read range.

I’d also make since_height part of the poll’s structured logs, alongside tip.height and the oldest pending block. That makes it much easier to distinguish a genuine disappearance from a watcher that simply never looked far enough back.

Thanks for highlighting this — it’s exactly the kind of edge case that can pass every happy-path test and still cause missed deposits in production.

Collapse
 
fintechrailsdigest profile image
Fintech Rails Digest •

logging since_height on every poll is the cheap half; the expensive half is the test that replays a restart against a chain that moved between snapshot and reconnect, which almost nobody writes because the happy path never exercises it. the pending floor also interacts with checkpointing: if the watcher persists its cursor after confirming transfers but before the floor advances, the safest restart policy is to resume from min(cursor, oldest pending block) and re-read the overlap idempotently rather than trust the gap.

Thread Thread
 
polycratia profile image
polycratia •

The restart test is already there: test_a_snapshot_carries_the_last_polled_tip snapshots at tip 3, mines to 8 with nothing running, and asserts chain.last_query == (("addr-1",), 4). It asserts on the query rather than the credit, so a refactor cannot quietly narrow the range and still pass. test_a_poller_asleep_past_the_window_still_confirms_what_was_mined is the same shape, minus the round trip through JSON.

On checkpointing, there is no separate cursor to go stale against the pending floor. _read_floor takes the minimum of the window floor, _last_tip + 1 and transfer.block.height across everything in _pending, clamped up to _start_height, and it does that on every poll, not only the first one after a restart. Pending transfers ride inside WatcherState right next to last_tip, so a resumed watcher computes your min(cursor, oldest pending) from the same inputs, with the window floor as a third term.

Your hazard is real one layer out. _last_tip gets assigned at the end of poll, after confirmed is built: if the caller credits a balance and then dies before persisting the snapshot, the resumed watcher holds no reported or settled entry for that key and reports it again. Once and only once holds across a snapshot that was written, not across a crash between reporting and writing it, and DepositKey is stable across exactly that restart, which is what makes the caller's credit dedupable.

I would add a test that pins that re-report down as documented behavior, and a read-only accessor for the computed read floor so a caller can log it without reaching into poll. Both go on the list...

Thread Thread
 
fintechrailsdigest profile image
Fintech Rails Digest •

Fair correction on both halves. The gap I was reaching for is the one you named: once-and-only-once holds across a written snapshot, and the window between confirmed being built and the snapshot persisting is where the re-report fires, with the caller's stable DepositKey absorbing the duplicate. Pinning that as documented behavior matters because a caller reading the type names will assume exactly-once across the crash too, then file the duplicate as a bug; a test plus a changelog line makes the integration side design for the dedup instead. The read-only accessor matters more than it first looks: the min(cursor, oldest pending, window floor) computation is the number that answers "how far back did this restart actually re-read", and nobody should have to reach into poll internals just to log it.

Thread Thread
 
polycratia profile image
polycratia •

Both halves go on the list, and the wording fix goes first: it is the part that sets the wrong expectation. The README headline promises to "notify once and only once" with no qualifier, and that is the line a caller reads before any type name. The honest form is once-and-only-once per persisted snapshot, at-least-once if the caller credits a balance and dies before writing one. There is no CHANGELOG in the repo yet, so that sentence belongs in the README next to the status note, and in the WatcherState docstring, which right now only warns that memory alone would replay.

The test is the easy half: credit a deposit, drop the watcher without taking a snapshot, build a new one from the older snapshot, then assert the key comes back in confirmed a second time. That pins down a window that is currently undefined.

One detail for the integration side you are designing for. The replayed report is not identical to the first. Deposit.confirmations is computed against the tip at report time, so the second one carries a deeper count, and if the transfer was re-mined the block differs too. DepositKey is the only part that holds still, which is why dedup has to key on (tx_id, output_index) and not on the deposit value.

On the accessor I agree with the need and not with the shape of a plain property. You cannot compute the floor without a tip: the window term is tip.height - reorg_depth + 1, so an attribute read would have to call tip(), and I do not want network I/O hiding behind one. What fits is last_since_height, recorded where _last_tip is assigned at the end of poll and exposed next to it, reporting the floor the last poll actually used rather than predicting the next one. It stays out of WatcherState: pending blocks and last_tip are both in the snapshot already, and the number is derivable from them.