Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,26 @@

## [Unreleased]

Room for the three rows of the rulings of 2026-11-17 (bsv-stack-lean `docs/RULINGS-2026-10-12.md`, 16:1xZ; `docs/DECISIONS-2026-10-19.md` 28.8.1 (c) with its three additions, and the keeper's reading of 17:1xZ for `VerdictError`): finality (#45), the status code (#46) and `conflicted` keeping its proof (#47) land after the 0.9.0 cut as minors, each behind its Lean, and none of them is built here. Five public types turn `#[non_exhaustive]`, so a host's exhaustive `match` on `HostAction`, `Reask`, `HintStatus` or `VerdictError`, and a `Verdict` built by literal, stop compiling: a break on this line, by the semver note of 0.3.0. No behaviour moves: every test of the base keeps its name and its answer, and the compact bytes are unchanged, pinned by `tests/compact_golden.rs`, which landed on the base before any other change.

### Changed

- `#[non_exhaustive]` on the enums `HostAction`, `Reask`, `HintStatus` and `VerdictError` and on the struct `Verdict`: the type alone, no variant marked, `Verdict`'s four fields still public to read and to assign. A `compile_fail` doctest on each pins the break (E0004 for a match outside the crate, E0639 for the literal).

### Added

- `Verdict::new(status)`: a verdict holding the word as given (not trimmed, not checked), with no height, no reason and no competitors; the fields are assigned after it, and `Verdict::from_arc_body` stays the checked reader.
- `HintStatus::label` and `Reask::label`: each kind's stable word, the payload not in it (`accepted`, `seen`, `mined`, `stale_block`, `rejected`, `double_spend`, `orphan_mempool`, `unknown`, `mempool_present`; `reorg`, `fork`, `hint`, `proof_failed`, `recheck`, `age`, `spend`). `HintStatus::LABELS` and `Reask::LABELS`: every word in declaration order, which is the compact form's tag order. A word never changes and is never reused; a later minor only appends.
- The serde form of `HintStatus`, the crate's stored form of a status: internally tagged by its word under `status`, the payload beside it as `height`, `reason`, `competitors` (left out when empty) and `courier` (`MempoolPresent`'s `source`), so `{"status":"mined","height":900}`. A word this release does not know, and a kind whose payload is missing, are refused, never read as `Unknown`. `Reask` has the words alone; `Hint`, `Verdict` and `HostAction` have no serde.
- Tests: `tests/compact_golden.rs` (the compact bytes of ten states that hold every word, a checked proof, every status with and without a verdict and every re-ask), `tests/labels.rs` (the words, both lists, every status's text round-tripped, the refusals, and the host's shape below), and two unit tests that `LABELS[i]` is the word of the kind the compact writer tags `i`.

### Hosts

- A match on `HostAction`, `Reask`, `HintStatus` or `VerdictError` gains a wildcard arm that keeps and surfaces what the host does not name: a re-ask by `Reask::label`, an error as the fault it is. Never an arm that maps to `HintStatus::Unknown` or drops the value.
- A `Verdict` built by literal becomes `Verdict::new(status)` with its other fields assigned after it.
- A host that stores hints stores the serde form of `HintStatus` and reads it back by it, never by a hand map, and surfaces a status the reader refuses.
- bsv-wallet-cli's stored rows read as they are: a struct with the status flattened between `source` and `observed` reads every text its `StoredHint::of` writes (beta at 108f80e) and writes it back identical (`tests/labels.rs`). Its pin of the next prerelease replaces its two hand maps with these words.

## [0.9.0-beta.8] - 2026-11-17

### Changed: the pin to bsv-rs 0.9.0-beta.8
Expand Down
15 changes: 15 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,21 @@ 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.

## Kinds a later release adds

`HostAction`, `Reask`, `HintStatus`, `VerdictError` and `Verdict` are
`#[non_exhaustive]`: a later minor may add a kind, an error or a field, so a
host's match on one of the four enums carries a wildcard arm, and a host
builds a `Verdict` with `Verdict::new` and assigns its fields after it. That
arm keeps and surfaces what the host does not name. A re-ask of a kind the
host does not name is kept and surfaced by `Reask::label`, never dropped by a
wildcard arm. A hint status is stored by its serde form
(`{"status":"mined","height":900}`) and read back by it, never mapped by hand,
and a status the reader refuses is surfaced, never read as
`HintStatus::Unknown`. Each kind's word (`label`, and `LABELS` for every word
in declaration order, the compact form's tag order) never changes and is
never reused; a later minor only appends.

## Events and records

`docs/SPEC.md` records the specification relationship and
Expand Down
62 changes: 62 additions & 0 deletions src/compact.rs
Original file line number Diff line number Diff line change
Expand Up @@ -538,3 +538,65 @@ fn raw_id(s: &str) -> Option<[u8; 32]> {
}
Some(raw)
}

#[cfg(test)]
mod tests {
use super::Writer;
use crate::{Hint, HintStatus, Reask};

/// The tag the compact writer gives a status, read from its leading byte.
fn status_tag(status: &HintStatus) -> usize {
let mut w = Writer(Vec::new());
w.status(status);
usize::from(w.0[0])
}
fn reask_tag(reask: &Reask) -> usize {
let mut w = Writer(Vec::new());
w.reask(reask);
usize::from(w.0[0])
}

#[test]
fn hint_status_labels_are_the_compact_tag_order() {
let every = [
HintStatus::Accepted,
HintStatus::Seen,
HintStatus::Mined { height: 1 },
HintStatus::StaleBlock,
HintStatus::Rejected { reason: "r".into() },
HintStatus::DoubleSpend {
competitors: vec![],
},
HintStatus::OrphanMempool,
HintStatus::Unknown,
HintStatus::MempoolPresent { source: "c".into() },
];
assert_eq!(every.len(), HintStatus::LABELS.len());
let mut tags: Vec<usize> = every.iter().map(status_tag).collect();
for status in &every {
assert_eq!(HintStatus::LABELS[status_tag(status)], status.label());
}
tags.sort_unstable();
assert_eq!(tags, (0..HintStatus::LABELS.len()).collect::<Vec<_>>());
}

#[test]
fn reask_labels_are_the_compact_tag_order() {
let every = [
Reask::Reorg { fork_height: 1 },
Reask::Fork { height: 1 },
Reask::Hint(Hint::new("s", HintStatus::Accepted, 0)),
Reask::ProofFailed { height: 1 },
Reask::Recheck,
Reask::Age,
Reask::Spend,
];
assert_eq!(every.len(), Reask::LABELS.len());
let mut tags: Vec<usize> = every.iter().map(reask_tag).collect();
for reask in &every {
assert_eq!(Reask::LABELS[reask_tag(reask)], reask.label());
}
tags.sort_unstable();
assert_eq!(tags, (0..Reask::LABELS.len()).collect::<Vec<_>>());
}
}
126 changes: 124 additions & 2 deletions src/hints.rs
Original file line number Diff line number Diff line change
@@ -1,9 +1,49 @@
use crate::{Height, Timestamp, TxId};
use serde::Deserialize;
use serde::{Deserialize, Serialize};
use std::fmt;

/// A broadcaster's claim reduced to the Lean hint vocabulary.
#[derive(Clone, Debug, PartialEq, Eq)]
///
/// `#[non_exhaustive]` (the room made before 0.9.0, bsv-stack-lean
/// `docs/DECISIONS-2026-10-19.md` 28.8.1 (c)): a later minor may add a kind,
/// so a host's match outside this crate carries a wildcard arm. A hint status
/// is stored by its serde form and read back by it, never mapped by hand, and
/// a status the reader refuses is surfaced, never read as
/// [`HintStatus::Unknown`].
///
/// ```compile_fail,E0004
/// use bsv_tracker::HintStatus;
/// fn kind(status: &HintStatus) -> u8 {
/// match status {
/// HintStatus::Accepted => 0,
/// HintStatus::Seen => 1,
/// HintStatus::Mined { .. } => 2,
/// HintStatus::StaleBlock => 3,
/// HintStatus::Rejected { .. } => 4,
/// HintStatus::DoubleSpend { .. } => 5,
/// HintStatus::OrphanMempool => 6,
/// HintStatus::Unknown => 7,
/// HintStatus::MempoolPresent { .. } => 8,
/// }
/// }
/// ```
///
/// **The stored form.** The serde form below is this crate's stored form of
/// a status: an object whose key `status` holds the kind's word
/// ([`HintStatus::label`]) and whose payload sits beside it under its
/// field's name: `height` for `mined`, `reason` for `rejected`,
/// `competitors` for `double_spend` (left out when there are none) and
/// `courier` for `mempool_present` (the courier that answered, so a status
/// sits beside a hint's own `source` in one object). So
/// `{"status":"accepted"}`, `{"status":"mined","height":900}` and
/// `{"status":"mempool_present","courier":"c"}`. The reader refuses a word it
/// does not know and a kind whose payload is missing; it never reads either
/// as [`HintStatus::Unknown`]. The tag key, the words and the field names are
/// stable under the rule of [`HintStatus::LABELS`]: a word never changes and
/// is never reused, and a later minor only appends.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "status", rename_all = "snake_case")]
#[non_exhaustive]
pub enum HintStatus {
/// The broadcaster accepted the transaction.
Accepted,
Expand All @@ -24,6 +64,7 @@ pub enum HintStatus {
/// The broadcaster reports a double spend.
DoubleSpend {
/// The competing txids the broadcaster names.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
competitors: Vec<TxId>,
},
/// The broadcaster reports the transaction in its orphan mempool.
Expand All @@ -42,9 +83,43 @@ pub enum HintStatus {
/// hint's re-ask. [`Verdict::into_hint`] never produces it.
MempoolPresent {
/// The courier that answered the presence (the host's name for it).
/// Its stored form's field is `courier`.
#[serde(rename = "courier")]
source: String,
},
}
impl HintStatus {
/// Every kind's word, in declaration order, which is the order of the
/// compact form's status tags (tag `i` is `LABELS[i]`). A word never
/// changes and is never reused; a later minor only appends.
pub const LABELS: &'static [&'static str] = &[
"accepted",
"seen",
"mined",
"stale_block",
"rejected",
"double_spend",
"orphan_mempool",
"unknown",
"mempool_present",
];
/// The kind's stable word, the payload not in it: `mined` for
/// `Mined { height: 900 }`. It is the `status` of the stored form.
#[must_use]
pub fn label(&self) -> &'static str {
match self {
Self::Accepted => "accepted",
Self::Seen => "seen",
Self::Mined { .. } => "mined",
Self::StaleBlock => "stale_block",
Self::Rejected { .. } => "rejected",
Self::DoubleSpend { .. } => "double_spend",
Self::OrphanMempool => "orphan_mempool",
Self::Unknown => "unknown",
Self::MempoolPresent { .. } => "mempool_present",
}
}
}
/// An observed hint, carrying its source and host supplied time.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Hint {
Expand All @@ -70,7 +145,23 @@ impl Hint {
}
}
/// Raw broadcaster metadata. HTTP acceptance is not chain evidence.
///
/// `#[non_exhaustive]` (bsv-stack-lean `docs/DECISIONS-2026-10-19.md`
/// 28.8.1 (c)): a later minor may add a field, so a host outside this crate
/// builds one with [`Verdict::new`] and assigns the fields after it; the
/// four fields stay public to read and to assign.
///
/// ```compile_fail,E0639
/// use bsv_tracker::Verdict;
/// let _ = Verdict {
/// status: "SEEN_ON_NETWORK".into(),
/// height: None,
/// reason: None,
/// competitors: vec![],
/// };
/// ```
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub struct Verdict {
/// The `txStatus` word, trimmed and upper-cased by [`Verdict::from_arc_body`].
pub status: String,
Expand All @@ -82,6 +173,19 @@ pub struct Verdict {
pub competitors: Vec<TxId>,
}
impl Verdict {
/// A verdict holding `status` as given, not trimmed and not checked, with
/// no height, no reason and no competitors. A host assigns the other
/// fields after it. [`Verdict::from_arc_body`] stays the checked reader
/// of a broadcaster's body; this constructor checks nothing.
#[must_use]
pub fn new(status: impl Into<String>) -> Self {
Self {
status: status.into(),
height: None,
reason: None,
competitors: Vec::new(),
}
}
/// Read an ARC body as metadata, checking its echoed txid and the bounded
/// status vocabulary at bsv-rs@7bc623c. HTTP status is never consulted.
///
Expand Down Expand Up @@ -243,7 +347,25 @@ impl Verdict {
}

/// An invalid broadcaster body is a reported fault, never chain evidence.
///
/// `#[non_exhaustive]` (bsv-stack-lean `docs/DECISIONS-2026-10-19.md`
/// 28.8.1 (c), the keeper's reading of 2026-11-17 17:1xZ): a later minor's
/// reader may add a variant, so a host's match outside this crate carries a
/// wildcard arm that reports the fault.
///
/// ```compile_fail,E0004
/// use bsv_tracker::VerdictError;
/// fn kind(error: &VerdictError) -> u8 {
/// match error {
/// VerdictError::Shape(_) => 0,
/// VerdictError::TxidMismatch => 1,
/// VerdictError::InvalidMetadata => 2,
/// VerdictError::UnknownStatus(_) => 3,
/// }
/// }
/// ```
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum VerdictError {
/// The expected fields cannot be decoded.
Shape(String),
Expand Down
66 changes: 66 additions & 0 deletions src/state.rs
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,24 @@ pub enum Evidence {
Recheck,
}
/// Acts supplied by the host, including its clock and spend guard.
///
/// `#[non_exhaustive]` (bsv-stack-lean `docs/DECISIONS-2026-10-19.md`
/// 28.8.1 (c)): a later minor may add an act, so a host's match outside this
/// crate carries a wildcard arm.
///
/// ```compile_fail,E0004
/// use bsv_tracker::HostAction;
/// fn kind(action: &HostAction) -> u8 {
/// match action {
/// HostAction::Build => 0,
/// HostAction::Abandon => 1,
/// HostAction::SpendAttempt => 2,
/// HostAction::Tick(_) => 3,
/// }
/// }
/// ```
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum HostAction {
/// The host built the transaction.
Build,
Expand All @@ -126,7 +143,28 @@ pub enum Input {
Host(HostAction),
}
/// A value for the host to execute; the crate never fetches anything.
///
/// `#[non_exhaustive]` (bsv-stack-lean `docs/DECISIONS-2026-10-19.md`
/// 28.8.1 (c)): a later minor may add a kind, so a host's match outside this
/// crate carries a wildcard arm. A re-ask of a kind the host does not name is
/// kept and surfaced by [`Reask::label`], never dropped by a wildcard arm.
///
/// ```compile_fail,E0004
/// use bsv_tracker::Reask;
/// fn kind(reask: &Reask) -> u8 {
/// match reask {
/// Reask::Reorg { .. } => 0,
/// Reask::Fork { .. } => 1,
/// Reask::Hint(_) => 2,
/// Reask::ProofFailed { .. } => 3,
/// Reask::Recheck => 4,
/// Reask::Age => 5,
/// Reask::Spend => 6,
/// }
/// }
/// ```
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum Reask {
/// The root moved: the active header at the mined height no longer
/// carries the stored proof's root, so the word is stale; fetch a fresh
Expand Down Expand Up @@ -158,6 +196,34 @@ pub enum Reask {
/// The host is about to spend; recheck before it does.
Spend,
}
impl Reask {
/// Every kind's word, in declaration order, which is the order of the
/// compact form's re-ask tags (tag `i` is `LABELS[i]`). A word never
/// changes and is never reused; a later minor only appends.
pub const LABELS: &'static [&'static str] = &[
"reorg",
"fork",
"hint",
"proof_failed",
"recheck",
"age",
"spend",
];
/// The kind's stable word, the payload not in it: `reorg` for
/// `Reorg { fork_height: 10 }`, `hint` for any `Hint(_)`.
#[must_use]
pub fn label(&self) -> &'static str {
match self {
Self::Reorg { .. } => "reorg",
Self::Fork { .. } => "fork",
Self::Hint(_) => "hint",
Self::ProofFailed { .. } => "proof_failed",
Self::Recheck => "recheck",
Self::Age => "age",
Self::Spend => "spend",
}
}
}
/// Host selected scheduling parameters.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Params {
Expand Down
Loading
Loading