Module tracker_host 

The CLI as a host of the transaction tracker (bsv-tracker).

The tracker holds one word per transaction, the evidence behind it, the hints it has heard and the next re-ask. Only headers and proofs change a word; every broadcaster word is a hint that schedules a re-ask. The crate fetches nothing, reads no clock and stores nothing: the host supplies the four things below, runs the re-asks, and keeps the state.

The four host things

the tracker’s trait	here	what it is
Headers	HeaderSnapshot	the header service’s tip and the headers at the heights a pass needs, read once per pass through the wallet’s services; a height not read is “no answer”, a fault is a fault
ProofFetcher	Courier	get_merkle_path for one named transaction; what it carries is a raw path, checked by the tracker against the snapshot
HintSource	MemoryHints	the broadcast memory rows of the wallet’s storage (what a broadcaster answered, what Arcade pushed over SSE or the webhook), each word fed once
Clock	SystemClock	seconds since the epoch

The tracker’s traits are synchronous and the wallet’s transports are not, so a pass reads first (headers, memory rows, proofs for the re-asks that are due) and steps second.

The state, in the CLI’s storage

One row per tracked transaction in tracker_states, in the wallet’s own database. A row holds inputs, never a trusted word: whether the host built it, the hints in the order heard, and the raw merkle path. Loading a row replays those inputs, so a stored path is checked again against the active header every time it is read (the tracker has no deserializer for a checked proof, by design). The word, height and reask columns are what the tracker said at the last step, kept for reading and for the indexes; nothing is decided from them.

What a pass asks, and what it never asks

A pass (tick) names transactions; it never walks the chain and never asks a chain index. It loads the rows that are not yet mined, feeds the new hints, ticks the clock, and runs the re-asks that are due: one proof request for one transaction, with a doubling pause between two requests for the same transaction. A mined row is read again only when the header at or below its height moved (the last twelve tips are kept to see that) or when a spend names it (spend_guard).

One re-ask is an announce, not a proof request: a transaction a broadcaster called not final (a forced gift-claim before its lock time) is kept with its BEEF and handed to the broadcasters again at the lock time (heard, and the re-announce step of tick).

Structs

Courier

The host’s proof transport: get_merkle_path for the transactions whose re-ask is due, read before the tracker steps. What it hands over is a raw path bound to its txid; the tracker checks it.

HeaderSnapshot

One pass’s view of the active chain: the tip and the headers at the heights the pass named, read from the header service through the wallet’s services. Fails closed: a height that was not read has no answer, a read that failed is a fault, and with no tip nothing checks.

MemoryHints

The hints of one pass: the broadcast memory rows of the tracked transactions whose (provider, word) the row has not heard yet. A word a broadcaster repeats every minute is one hint, so a refreshed seen never resets the age clock.

Reannounce

A BEEF to hand to the broadcasters again, and when.

SystemClock

The host’s clock: seconds since the epoch.

TickOptions

The host’s parameters of a pass.

TickReport

What one pass did.

Enums

PostAnswer

The broadcasters’ answer to one post, read as a hint.

Constants

DEFAULT_AGE_SECS

Default seconds without a new hint before an announced or seen transaction is asked for its proof (TRACKER_AGE_SECS): one block interval.

DEFAULT_MAX_ASKS

Default re-asks one pass runs (TRACKER_MAX_ASKS).

Functions

heard

Track a transaction this wallet built and just handed to a broadcaster, and feed what the broadcaster said, as a hint. not_before holds every re-ask until that time (a transaction that cannot be mined before its lock time has no proof to ask for before it); reannounce keeps the BEEF to hand over again then. Returns the tracker’s word and its pending re-ask.

read_post

Read the results of one post_beef.

record_accepted

Record in the wallet what a pass’s re-announces got accepted (E4): the wallet’s storage is the verdict for its own actions, so a claim the wallet made is internalized from the BEEF it already holds, and nothing scans the chain for it. Each outcome is added to report.stored.

says_not_final

Does a broadcaster’s refusal say “not final”? The node’s word is non-final; ARC and Arcade carry it under code 476, which the toolbox reads as retryable (bsv-wallet-toolbox-rs ARCADE_CODE_NON_FINAL).

spend_guard

Run the spend guard for a coin of the tracked transaction txid, as the host: the row is loaded (its stored path checked against a fresh header), the README’s guard runs on it, and the row is stored again. Ok(true) only for a checked, non-suspect mined; Err when the header service could not answer. A transaction the host does not track is not mined.

stored_word

What the storage holds for txid: the word, the mined height and the pending re-ask the tracker gave at its last step. A view for a person; nothing is decided from it.

tick

One pass of the host. See the module docs.

word_label

The tracker’s word, as one lowercase label.