Crate bsv_tracker 

bsv-tracker

0.7.0, a transaction evidence state machine on bsv-rs ^0.7. The tag v0.7.0 is the release of record, and crates.io carries the same version, 0.7.0; the repository’s Releases page has a Release for each tag.

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 only the transactions whose proof’s root left the active headers. 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.7.0"

The crate needs Rust 1.88 or newer (rust-version in Cargo.toml). 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. CheckedProof has no other constructor and no deserializer, so stored proofs must be checked again; deserializing bytes does not create a trusted mined state. State::to_compact and State::from_compact (0.5.0) store and restore one state as versioned bytes for a host that keeps no memory between requests; a restored Word::Mined comes back suspect with Reask::Recheck due, and a Tracker that holds it through Tracker::restore rechecks it on the next tip. 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. 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 and check errors. After a chain event a host fetches a proof only for a Reask::Reorg, the words whose root moved, a few a pass; the pacing is the host’s, and the recheck that decides which words those are is the crate’s. 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.

Broadcaster hints

Verdict::from_arc_body reads an ARC body as metadata and never consults the HTTP status. The txStatus word is trimmed and upper-cased before the vocabulary check; extraInfo is text kept on Verdict::reason and never moves the status. A word outside the vocabulary is VerdictError::UnknownStatus. Every hint, HintStatus::Mined included, writes no chain word. HintStatus::MempoolPresent { source } (0.5.0) records a courier’s mempool presence, a node the host did not broadcast through holding the bytes. Since 0.7.0 it moves built to announced, as an acceptance does: someone announced the transaction, and the same hint gives the same word whether or not this host did. It writes no chain word.

Events and records

docs/SPEC.md records the specification relationship and docs/CHAIN-EVENTS.md defines the event envelope. ChainEvent carries the six kinds of envelope version 1 (tip, fork, reorg, invalidated, frozen, tip age) and the two kinds of version 2 (split, splitResolved); each kind selects its version. The reorg rule is by the root (0.7.0): a mined word is stale when, and only when, its stored proof’s root is not the active header’s root at its height in the host’s headers. A reorg selects the mined words at or above its fork height and an invalidation the words checked against its block; each selected word is rechecked against the host’s headers, a header read and never a fetch. The same root, the word stands and its marks clear; a moved root, Word::Stale with Reask::Reorg; no header, the word stands suspect with Reask::Recheck. A split marks the mined words at or above its fork height suspect and writes no word; a resolved split rechecks them against the host’s headers. decode_envelope returns UnknownVersion, UnknownKind or UnknownShape for an envelope it does not know, never a silent tracker input. docs/VERIFICATION.md records scoped witnesses; tests contains chain-event and ARC vectors, the Arcade bodies, and transition, split and property tests. Host integration and live transport behavior require their own evidence.

Build and gate

cargo test --locked
cargo fmt --all -- --check
cargo clippy --locked --all-targets -- -D warnings
RUSTDOCFLAGS=-Dwarnings cargo doc --locked --no-deps
cargo build --locked --target wasm32-unknown-unknown --features wasm

.github/workflows/ci.yml runs test, fmt, clippy, vectors and wasm32, the five checks main requires, on every PR and main push, with msrv, machete (non-blocking), secrets and actionlint beside them. The vectors job runs the eight chain-event envelope vectors and the ARC status vector by name and fails unless each one executes. Dependabot moves the stack’s crates daily at 18:00Z under .github/dependabot.yml. 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 chain-event envelope: version 1 from rust-chaintracks@a62f9ed, version 2 from chaintracks-cloudflare@v0.4.1.

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.

SplitTip

One tip of a split, as the header service observed it over its rungs. [SRC] chaintracks-cloudflare@v0.4.1 src/events.rs:50-57, docs/SPLITS.md:75-92. These are wire data: neither chain_work nor rungs is checked here.

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, forks and splits use only the relevant mined height range.

Verdict

Raw broadcaster metadata. HTTP acceptance is not chain evidence.

Enums

ChainEvent

The six #32 events of version 1 and the two split events of version 2, serialized and deserialized with v and kind; each kind selects its version. [SRC] rust-chaintracks@a62f9ed docs/CHAIN-EVENTS.md:24-35; chaintracks-cloudflare@v0.4.1 src/events.rs:59-108, docs/SPLITS.md:68-83. For typed host faults, use decode_envelope.

CheckError

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

CompactError

Bytes State::from_compact refuses. A refusal restores nothing; the host re-tracks the transaction.

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.

Constants

COMPACT_VERSION

The version byte State::to_compact writes.

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.