Crate bsv_tracker 

bsv-tracker

0.2.2, a transaction evidence state machine on bsv-rs =0.5.0. The tracker owns re-asking: per transaction it keeps a word, the evidence behind it, the hints received and the next re-ask. Checked headers and proofs establish mining and conflicts; broadcaster words only supply hints. A reorg re-asks affected transactions. Hosts provide headers, proofs, hints and time, so wallet, overlay and application hosts can use the same transition logic without giving this crate a network client or a periodic chain scan.

Install

[dependencies]
bsv-tracker = "=0.2.2"

Enable the wasm feature for a wasm host. Cargo.toml disables the SDK’s default features and enables transaction types; it adds no HTTP client or async runtime.

Evidence and host obligations

Headers::check constructs checked proof evidence by binding a merkle path to a transaction and comparing its root with the active header snapshot. Stored proofs must be checked again; deserializing bytes does not create a trusted mined state. Hosts only serve current inclusion evidence from a non-suspect Word::Mined and calculate current depth from their current tip.

An unavailable header or failed check keeps the word and schedules a re-ask. Reorg evidence marks affected inclusion stale. Broadcaster rejection and mempool conflict do not by themselves write Rejected or Conflicted. NodeVerdict is a separate host-supplied authority boundary; a host must not relabel a broadcaster’s refusal as a local node verdict. The host also supplies the fact that a proved competitor spends one of the tracked inputs.

The host supplies Headers, ProofFetcher, HintSource and Clock, executes scheduled re-asks and reports decoding/check errors. The tracker performs pure transitions and indexed event handling. It does not fetch proofs, select the active header chain or run a script evaluator on the host’s behalf.

Events and records

docs/SPEC.md records the specification relationship and docs/CHAIN-EVENTS.md defines the event envelope. Unknown envelope versions, kinds or shapes are errors, not silent tracker inputs. docs/VERIFICATION.md records scoped witnesses; tests contains chain-event vectors and transition tests. Host integration and live transport behavior require their own evidence.

Build and gate

cargo test --locked
cargo fmt --all -- --check
cargo build --locked --target wasm32-unknown-unknown --features wasm

.github/workflows/ci.yml runs test, fmt, clippy, vectors and wasm32 on every PR and main push. The vector job requires the named chain-event and broadcaster-word witnesses to actually execute. RELEASING.md defines tag-based crates.io trusted publishing; CHANGELOG.md records changes. This is a published library, with host adoption controlled separately.

Licensed under MIT OR Apache-2.0, as declared in Cargo.toml.

Structs

ChainEnvelope

The flat version 1 chain-event envelope from rust-chaintracks@a62f9ed.

ChainUpdate

A named result of an event on one affected transaction.

CheckedProof

A capability produced only by Headers::check. There is no unchecked constructor or deserializer; the retained proof and header are immutable.

EventHeader

The eight public header fields and cumulative work in the #32 envelope. [SRC] rust-chaintracks@a62f9ed docs/CHAIN-EVENTS.md:13-23; src/events.rs:13-25 fixes the Rust integer widths. These are wire data, never a checked inclusion capability.

Header

The active header projection retained with a proof, as in Tracker.Header.

HeaderError

A fault reported by the host’s header snapshot.

Hint

An observed hint, carrying its source and host supplied time.

Mined

Inclusion backed by an immutable checked capability; height is derived.

Outpoint

A frozen output’s display-order txid and output index. [SRC] rust-chaintracks@a62f9ed src/events.rs:43-48.

Params

Host selected scheduling parameters.

Proof

An owned, structurally validated SDK path bound to the transaction it proves.

State

The complete private state of one transaction.

Tracker

A host’s tracked transactions, with indexes for targeted chain events. Hints, ages and spend attempts name one transaction. A tip uses only the suspect set; reorgs and forks use only the relevant mined height range.

Verdict

Raw broadcaster metadata. HTTP acceptance is not chain evidence.

Enums

ChainEvent

The six #32 events, serialized and deserialized with v: 1 and kind. [SRC] rust-chaintracks@a62f9ed docs/CHAIN-EVENTS.md:24-35. For typed host faults, use decode_envelope.

CheckError

A failed evidence check. An error is never a transaction word.

DecodeError

A fault the host must report, without feeding an event to the tracker.

Evidence

The inputs that may write a chain word.

HintStatus

A broadcaster’s claim reduced to the Lean hint vocabulary.

HostAction

Acts supplied by the host, including its clock and spend guard.

Input

One input to Tracker.step.

NodeVerdict

A verdict explicitly supplied by the host’s trusted node, never a broadcaster.

Reask

A value for the host to execute; the crate never fetches anything.

VerdictError

An invalid broadcaster body is a reported fault, never chain evidence.

Word

The nine words. Mined needs an unforgeable checked proof.

Traits

Clock

The host’s time source. The tracker never reads a platform clock.

Headers

A host supplied snapshot of fresh, verified active headers. Both methods must answer from the same snapshot and fail closed when it is unavailable.

HintSource

The host’s callbacks, SSE listener, polls or other hint inputs.

ProofFetcher

The host’s proof transport. The crate declares it but never calls it.

Functions

decode_envelope

Pure decoding, with the version gated before the shape, independent of JSON key order. Unknown fields, kinds and versions are reported errors.

Type Aliases

Hash

A display order block hash or merkle root.

Height

The height named by a BRC-74 path.

SpendCheck

An error surface a host may use when rechecking before a spend.

Timestamp

Seconds supplied by the host’s clock.

TxId

A display order transaction identifier.