Skip to content

blindbit-lib: one way to build and restore a scanner (SNB-673) - #47

Closed
setavenger wants to merge 2 commits into
integrationfrom
snb-673-one-way-to-build-scanner
Closed

setavenger wants to merge 2 commits into
integrationfrom
snb-673-one-way-to-build-scanner

Conversation

@setavenger

@setavenger setavenger commented Oct 3, 2026 •

Copy link
Copy Markdown
Owner

Stacked on #44; review only the commits after it.

Linear: SNB-673

Net: 98 insertions, 142 deletions (−44 lines) in scanner.rs, reorg.rs, scanning.rs.

What was merged and why

  • One constructor. Scanner::new and from_changeset each wrote out the whole struct literal. Both now pass their staged ChangeSet to one private from_stage, which derives the rest from it: the checkpoints with genesis, owned outputs, remembered hashes, and the Electrum index (address, labels, oracle-floor health). The public signatures of Scanner::new and from_changeset are unchanged.
  • One indexer restore. "New indexer, labels 0..=max, then apply_changeset" was written in both from_changeset and the reorg rollback. It is now restored_indexer, whose doc keeps the reason labels must come first.
  • One genesis hash. It was built in three places; now there is genesis_hash().
  • The second label loop in new() is gone. After initial_changeset() already carried labels 0..=max, new merged add_label(0..=max) into the stage a second time. label_lookup is a BTreeSet<Label>, so that merge changed nothing.
  • One remembered-hash lookup in reorg.rs (remembered_hash), used by check_block_hash and oracle_view.
  • Scanner.last_scanned_block_height_rescan is removed; the ChangeSet field stays. The scanner field was only ever restored, lowered on rollback and copied into every save. stage.last_scanned_block_height_rescan holds the same value at every point: both start from the same value, and the only merge into stage carries 0, which a max-merge ignores. So the rollback now lowers the stage value directly, and the save writes it unchanged. The state-file format and the field name are untouched.

Why behaviour is unchanged (measured)

I wrote a probe test (not committed; it lived in the scratch dir and was included via #[path] only for the runs). It dumps, for each scenario: the staged ChangeSet, the bytes save_to_file writes, and a full summary of the scanner. The summary covers heights, checkpoints, remembered hashes, owned outputs and prefixes, labels, the indexer's by_shared_secret/by_script/by_label/partial secrets, the graph's transactions with anchors, the SP address, balance, and the whole Electrum index (txs, headers, histories, tip, SP labels, scan health).

Scenarios:

  • fresh scanners with max_label_num 0 and 3;
  • a test-produced wallet (change at m=0 and label 2 received, the change spent), plus its saved file restored;
  • a rollback of each of those to 150;
  • that file with last_scanned_block_height_rescan = 240, restored (saves 240) and rolled back (saves 150);
  • the old-format fixture state_before_owned_outputs.json restored (format-0 rewind included) and rolled back to 50.

I ran the probe on #44's head and on this branch. All 42 outputs are identical, including the raw saved state files byte for byte. The probe output was checked to be deterministic across runs first; the stage's owned_outputs order follows HashMap order, so arrays are compared as sorted.

Verification

  • cargo check --workspace --all-targets --all-features → 0 warnings.
  • cargo check -p blindbit-lib --no-default-features --all-targets → 5 warnings (baseline 5).
  • cargo clippy --no-deps -p friglet -p friglet-ipc -p friglet-tray --all-targets -- -D warnings → clean.
  • cargo fmt -p friglet -p friglet-ipc -p friglet-tray -- --check → clean.
  • cargo test --workspace → 254 passed, 1 ignored, 0 failed. This includes the reorg, state_file and owned_outputs suites.

Left out

  • The issue asks to load a copy of a mainnet state file. There are no real state files on this machine, so the old-format repo fixture and test-produced state files were used instead, as above.
  • The "TODO: create a config" and other stale comments in scanner.rs belong to SNB-669.

setavenger and others added 2 commits October 3, 2026 08:43
Remove public items nothing calls, in this workspace or in the other
repos that use blindbit-lib (blindbit-node-apps, testkit, the talk
benchmark):

- broadcast_tx: its only caller, friglet's Electrum broadcast, uses
  friglet's own relay since #26.
- Scanner::from_config, get_last_scanned_block_height_rescan,
  staged_mut, take_staged and the commented-out get_outputs.
- watch_chain: friglet calls watch_chain_until; its doc moves there.
- BlockIdentifierDisplay (only .0.block_height was read), OwnedOutput
  (never built), ProbableMatch::new, _match_short_pubkey_bytes and the
  commented-out ScannerConfig Default. electrum_index becomes a private
  module; its items stay re-exported.
- The spent-outpoint and probabilistic-match channels and the code that
  only fed them. They had no subscribers and never sent anything: the
  sends were guarded by Sender::is_empty(), which means "no queued
  value", so they were always skipped. The malformed-hash branch that
  guarded them cannot run: check_block_identifier rejects such a block
  before scan_short_block_data sees it. The "possible spend of owned
  output" log line stays.
- save_to_file's back-fill of keys and max_label_num: stage holds them
  from construction on and only take_staged could clear them. A test
  run with assertions in place of the back-fill passed every workspace
  test.
- P2P: TimeoutParams setters the handshake never reads (it only uses
  the ping interval; the socket timeouts are set directly), history
  notes about deleted code, and a retry doc that predates the
  witness-stripped and bad-block retries.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Scanner::new and from_changeset each wrote out the whole struct; both
now hand their staged changeset to one private constructor,
from_stage, which derives the rest (checkpoints with genesis, owned
outputs, remembered hashes, Electrum index) from it.

- "New indexer, labels 0..=max, then apply_changeset" was written in
  from_changeset and in the reorg rollback; it is restored_indexer now,
  with the reason the labels must come first.
- The genesis checkpoint hash was built in three places; genesis_hash().
- new() merged add_label(0..=max) into the stage a second time after
  initial_changeset() already carried those labels (label_lookup is a
  set, so the merge changed nothing); dropped.
- The remembered-hash lookup in reorg.rs is one helper.
- Scanner.last_scanned_block_height_rescan was only restored, lowered on
  rollback and copied into every save. The stage already holds the same
  value, so the field goes; the ChangeSet field and the state format
  stay as they are.

A probe (not committed) dumped stage, saved file and full scanner
state for fresh scanners, a test-produced wallet, the old-format
fixture, restores and rollbacks of each, before and after this change:
all 42 outputs identical.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@setavenger

Copy link
Copy Markdown
Owner Author

Merged into integration through #68 on 2026-10-11 (the user live-tested the combined stack first). GitHub's stacked-PR merge rebased the stack, so this PR's commits landed with new IDs and GitHub can't mark it merged itself. The code is identical: integration now has the same tree as the tested branch friglet-deslop-live-test (08bf11d), which contains this PR's head. Closing as merged via #68.

@setavenger setavenger closed this Oct 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant