bsv_tracker/

state.rs

use crate::{
    ChainEvent, CheckError, CheckedProof, CompactError, Headers, Height, Hint, HintStatus, Proof,
    Timestamp, TxId,
};
use std::sync::Arc;

/// Inclusion backed by an immutable checked capability; height is derived.
///
/// ```compile_fail
/// use bsv_tracker::Word;
/// let _ = Word::Mined { height: 100 };
/// ```
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Mined {
    checked: Arc<CheckedProof>,
}
impl Mined {
    /// The height of the checked proof. It cannot differ from the evidence.
    #[must_use]
    pub fn height(&self) -> Height {
        self.checked.height()
    }
    /// The checked capability behind the word.
    #[must_use]
    pub fn checked(&self) -> &CheckedProof {
        &self.checked
    }
}
/// The nine words. `Mined` needs an unforgeable checked proof.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Word {
    /// Tracked, with no claim from any tier.
    Unknown,
    /// The host built the transaction.
    Built,
    /// A broadcaster accepted the transaction.
    Announced,
    /// A broadcaster reports the transaction seen on the network.
    Seen,
    /// Included, backed by a checked proof against the active headers.
    Mined(Mined),
    /// Was mined in a block that left the active chain.
    Stale,
    /// The host's trusted node rejected the transaction.
    Rejected {
        /// The node's reason.
        reason: String,
    },
    /// A competing transaction is mined or named by the host's trusted node.
    Conflicted {
        /// The competing txids, the most recent at the front.
        competitors: Vec<TxId>,
    },
    /// The host abandoned the transaction before any broadcaster accepted it.
    Abandoned,
}
impl Word {
    /// `Tracker.Word.chain`, ignoring the host and hint tiers.
    #[must_use]
    pub fn chain(&self) -> Option<&Self> {
        match self {
            Self::Mined(_) | Self::Stale | Self::Rejected { .. } | Self::Conflicted { .. } => {
                Some(self)
            }
            _ => None,
        }
    }
    /// A height only when this is an evidenced mined word.
    #[must_use]
    pub fn height(&self) -> Option<Height> {
        if let Self::Mined(m) = self {
            Some(m.height())
        } else {
            None
        }
    }
}
/// A verdict explicitly supplied by the host's trusted node, never a broadcaster.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum NodeVerdict {
    /// The node rejected the transaction.
    Rejected {
        /// The node's reason.
        reason: String,
    },
    /// The node names competing transactions.
    Conflicted {
        /// The competing txids the node names.
        competitors: Vec<TxId>,
    },
}
/// The inputs that may write a chain word.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Evidence {
    /// A proof of this transaction's inclusion.
    Proof(Proof),
    /// A proof of a competing transaction's inclusion.
    Competitor(Proof),
    /// A chain event from the host's header feed.
    Chain(ChainEvent),
    /// A verdict from the host's trusted node.
    Verdict(NodeVerdict),
    /// Recheck a mined word against the current headers.
    Recheck,
}
/// Acts supplied by the host, including its clock and spend guard.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum HostAction {
    /// The host built the transaction.
    Build,
    /// The host abandons the transaction.
    Abandon,
    /// The host is about to spend an output of the transaction.
    SpendAttempt,
    /// The host's clock reads this time.
    Tick(Timestamp),
}
/// One input to `Tracker.step`.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Input {
    /// Evidence that may write a chain word.
    Evidence(Evidence),
    /// A broadcaster's hint, which never writes a chain word.
    Hint(Hint),
    /// An act of the host.
    Host(HostAction),
}
/// A value for the host to execute; the crate never fetches anything.
#[derive(Clone, Debug, PartialEq, Eq)]
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
    /// proof. After a chain event a host fetches only for these, a few a pass;
    /// the pacing is the host's.
    Reorg {
        /// The reorg's fork height when a reorg's recheck found the root
        /// moved; otherwise the mined height (an invalidation, a recheck).
        fork_height: Height,
    },
    /// A fork, or a version-2 split, at or below the mined height; the word
    /// is suspect. A split reuses this re-ask with its `forkHeight`: the host's
    /// act, a recheck at its depth rule, is the same for both.
    Fork {
        /// The height at which the branches diverge (a split's `fork_height`).
        height: Height,
    },
    /// A hint that disagrees with the word; reconcile it.
    Hint(Hint),
    /// A proof or competitor proof failed its check.
    ProofFailed {
        /// The height the failed proof named.
        height: Height,
    },
    /// Recheck the mined word against the current headers.
    Recheck,
    /// The last hint is older than the age threshold.
    Age,
    /// The host is about to spend; recheck before it does.
    Spend,
}
/// Host selected scheduling parameters.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Params {
    /// Seconds after the last hint before an announced or seen word is re-asked.
    pub age_threshold: Timestamp,
}
/// The complete private state of one transaction.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct State {
    txid: TxId,
    word: Word,
    evidence: Option<Arc<CheckedProof>>,
    suspect: bool,
    hints: Vec<Hint>,
    last_hint_at: Option<Timestamp>,
    reask: Option<Reask>,
}
impl State {
    /// Birth with no chain claim or stored evidence, as in `Tracker.State.init`.
    pub fn new(txid: impl Into<TxId>) -> Self {
        Self {
            txid: txid.into().to_ascii_lowercase(),
            word: Word::Unknown,
            evidence: None,
            suspect: false,
            hints: vec![],
            last_hint_at: None,
            reask: None,
        }
    }
    /// The host's tracked transaction.
    #[must_use]
    pub fn txid(&self) -> &str {
        &self.txid
    }
    /// The current word. It is immutable outside the transition function.
    #[must_use]
    pub fn word(&self) -> &Word {
        &self.word
    }
    /// The retained record, including when the word has become stale.
    #[must_use]
    pub fn evidence(&self) -> Option<&CheckedProof> {
        self.evidence.as_deref()
    }
    /// Whether an unresolved fork requires a header recheck before acting.
    #[must_use]
    pub fn suspect(&self) -> bool {
        self.suspect
    }
    /// Observations in newest received order, matching the Lean list.
    #[must_use]
    pub fn hints(&self) -> &[Hint] {
        &self.hints
    }
    /// Time of the most recently received hint, even for out of order clocks.
    #[must_use]
    pub fn last_hint_at(&self) -> Option<Timestamp> {
        self.last_hint_at
    }
    /// The next re-ask, which the host must execute and feed back.
    #[must_use]
    pub fn reask(&self) -> Option<&Reask> {
        self.reask.as_ref()
    }
    /// The compact byte form (bsv-stack-lean #92): a version byte, the txid,
    /// the word, the evidence, the suspect mark, the hints, the last hint time
    /// and the re-ask. The layout is in the source of `src/compact.rs`; the
    /// version byte changes when the layout does, so a later release tells an
    /// earlier layout from its own rather than misreading it.
    #[must_use]
    pub fn to_compact(&self) -> Vec<u8> {
        crate::compact::encode(&crate::compact::Fields {
            txid: &self.txid,
            word: &self.word,
            evidence: self.evidence.as_deref(),
            suspect: self.suspect,
            hints: &self.hints,
            last_hint_at: self.last_hint_at,
            reask: self.reask.as_ref(),
        })
    }
    /// Restore a state from [`State::to_compact`]'s bytes.
    ///
    /// The rule: a restored `mined` word is still suspect until its proof is
    /// re-checked against the host's headers. [`CheckedProof`] has no
    /// deserializer, because bytes are not a check: the chain may have moved
    /// while the state was stored. So the stored proof comes back as the
    /// record (its path reduces for this txid to the stored root, which equals
    /// the stored header's root), the word comes back `mined` on that record,
    /// and the state is marked [`suspect`](State::suspect) with
    /// [`Reask::Recheck`] due when no other re-ask was pending. A
    /// [`Tracker`](crate::Tracker) holding it rechecks it on the next tip,
    /// as it does any suspect word; a host holding the state alone feeds
    /// [`Evidence::Recheck`] before it serves the inclusion.
    ///
    /// Every other field returns exactly: a state whose word is not `mined`,
    /// or that was already suspect with a re-ask pending, restores equal to
    /// the state that wrote the bytes, and a restored state writes bytes that
    /// restore equal to it.
    ///
    /// # Errors
    ///
    /// [`CompactError::UnknownVersion`] for a version this crate does not
    /// read, [`CompactError::Truncated`], [`CompactError::TrailingBytes`] and
    /// [`CompactError::Malformed`] for bytes the encoder never writes (a
    /// `mined` word with no stored proof among them), and
    /// [`CompactError::Evidence`] for a stored proof that does not hold
    /// together.
    pub fn from_compact(bytes: &[u8]) -> Result<Self, CompactError> {
        let parts = crate::compact::decode(bytes)?;
        let evidence = parts.evidence.map(Arc::new);
        let mined = parts.word.is_none();
        let word = if let Some(word) = parts.word {
            word
        } else {
            let checked = evidence
                .as_ref()
                .ok_or(CompactError::Malformed("mined word with no stored proof"))?;
            Word::Mined(Mined {
                checked: Arc::clone(checked),
            })
        };
        let mut state = Self {
            txid: parts.txid,
            word,
            evidence,
            suspect: parts.suspect,
            hints: parts.hints,
            last_hint_at: parts.last_hint_at,
            reask: parts.reask,
        };
        if mined {
            state.suspect = true;
            state.reask.get_or_insert(Reask::Recheck);
        }
        Ok(state)
    }
    /// Execute one Lean transition. Proof and header failures retain the word
    /// and record the re-ask before returning an error to the host.
    ///
    /// # Errors
    ///
    /// The [`CheckError`] of a proof, competitor, chain event or recheck whose
    /// check fails; the word is kept and the re-ask recorded.
    pub fn step<H: Headers + ?Sized>(
        &mut self,
        params: &Params,
        headers: &H,
        input: Input,
    ) -> Result<(), CheckError> {
        match input {
            Input::Hint(hint) => self.on_hint(hint),
            Input::Host(action) => self.on_host(params, &action),
            Input::Evidence(Evidence::Proof(proof)) => self.on_proof(headers, proof)?,
            Input::Evidence(Evidence::Competitor(proof)) => self.on_competitor(headers, proof)?,
            Input::Evidence(Evidence::Chain(event)) => self.on_chain(headers, &event)?,
            Input::Evidence(Evidence::Verdict(verdict)) => self.on_verdict(verdict),
            Input::Evidence(Evidence::Recheck) => self.recheck(headers, None)?,
        }
        Ok(())
    }

    fn on_hint(&mut self, hint: Hint) {
        match (&self.word, &hint.status) {
            // A node we did not broadcast through holds the bytes, so someone
            // announced it; the chain has no author (ruling (2), bsv-stack-lean
            // docs/RULINGS-2026-10-12.md, 2026-10-20 19:4xZ).
            (Word::Built, HintStatus::Accepted | HintStatus::MempoolPresent { .. }) => {
                self.word = Word::Announced;
            }
            (Word::Built | Word::Announced, HintStatus::Seen) => self.word = Word::Seen,
            _ => {}
        }
        if !agrees(&self.word, &hint.status) {
            self.reask = Some(Reask::Hint(hint.clone()));
        }
        self.last_hint_at = Some(hint.observed);
        self.hints.insert(0, hint);
    }

    fn on_host(&mut self, params: &Params, action: &HostAction) {
        match *action {
            HostAction::Build if self.word == Word::Unknown => self.word = Word::Built,
            HostAction::Abandon if matches!(self.word, Word::Unknown | Word::Built) => {
                self.word = Word::Abandoned;
            }
            HostAction::SpendAttempt => self.reask = Some(Reask::Spend),
            // Lean adds unbounded naturals. Checked addition keeps an
            // overflowing deadline from becoming prematurely due.
            HostAction::Tick(now)
                if matches!(self.word, Word::Announced | Word::Seen)
                    && self
                        .last_hint_at
                        .and_then(|t| t.checked_add(params.age_threshold))
                        .is_some_and(|deadline| deadline <= now) =>
            {
                self.reask = Some(Reask::Age);
            }
            _ => {}
        }
    }

    fn on_proof<H: Headers + ?Sized>(
        &mut self,
        headers: &H,
        proof: Proof,
    ) -> Result<(), CheckError> {
        let height = proof.height();
        if proof.txid() != self.txid {
            self.reask = Some(Reask::ProofFailed { height });
            return Err(CheckError::TxidMismatch);
        }
        match crate::evidence::check_snapshot(headers, proof) {
            Ok(checked) => {
                let checked = Arc::new(checked);
                self.word = Word::Mined(Mined {
                    checked: Arc::clone(&checked),
                });
                self.evidence = Some(checked);
                self.suspect = false;
                self.reask = None;
                Ok(())
            }
            Err(error) => {
                self.reask = Some(Reask::ProofFailed { height });
                Err(error)
            }
        }
    }

    fn on_competitor<H: Headers + ?Sized>(
        &mut self,
        headers: &H,
        proof: Proof,
    ) -> Result<(), CheckError> {
        let height = proof.height();
        let competitor = proof.txid().to_owned();
        match crate::evidence::check_snapshot(headers, proof) {
            Ok(_) => {
                match &mut self.word {
                    Word::Mined(_) => self.reask = Some(Reask::Recheck),
                    Word::Conflicted { competitors } => competitors.insert(0, competitor),
                    _ => {
                        self.word = Word::Conflicted {
                            competitors: vec![competitor],
                        }
                    }
                }
                Ok(())
            }
            Err(error) => {
                self.reask = Some(Reask::ProofFailed { height });
                Err(error)
            }
        }
    }

    /// The local recheck: the stored proof's root against the active header's
    /// root at the word's height, a header read and never a fetch. Equal, the
    /// word stands and the marks clear; different, the word is stale with
    /// [`Reask::Reorg`] at `fork_height` (the word's height when none is
    /// given); no header, the word stands with [`Reask::Recheck`].
    fn recheck<H: Headers + ?Sized>(
        &mut self,
        headers: &H,
        fork_height: Option<Height>,
    ) -> Result<(), CheckError> {
        let Word::Mined(mined) = &self.word else {
            return Ok(());
        };
        let height = mined.height();
        let answer = headers.header_at(height);
        match answer {
            Ok(Some(header)) if header.merkle_root == mined.checked().root() => {
                self.suspect = false;
                self.reask = None;
            }
            Ok(Some(_)) => self.stale(fork_height.unwrap_or(height)),
            Ok(None) => {
                self.reask = Some(Reask::Recheck);
                return Err(CheckError::Unavailable(height));
            }
            Err(error) => {
                self.reask = Some(Reask::Recheck);
                return Err(CheckError::Headers(error));
            }
        }
        Ok(())
    }

    fn stale(&mut self, fork_height: Height) {
        self.word = Word::Stale;
        self.suspect = false;
        self.reask = Some(Reask::Reorg { fork_height });
    }

    /// A chain event names the words to recheck; only the headers move one.
    ///
    /// The rule by the root (ruling (5), bsv-stack-lean
    /// docs/RULINGS-2026-10-12.md, 2026-10-20 19:4xZ): 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 at or below
    /// the word's height and an invalidation of its checked header both run
    /// the local recheck; the event's numbers are the bound of that recheck,
    /// never the stale mark. The word is suspect while the recheck is open, so
    /// a missing header leaves it suspect with [`Reask::Recheck`] (fail
    /// closed) and the next tip rechecks it. A fork or a split marks the word
    /// suspect with [`Reask::Fork`]; a resolved split and a tip recheck the
    /// suspect words.
    pub(crate) fn on_chain<H: Headers + ?Sized>(
        &mut self,
        headers: &H,
        event: &ChainEvent,
    ) -> Result<(), CheckError> {
        match event {
            ChainEvent::Tip { .. } if self.suspect => self.recheck(headers, None)?,
            ChainEvent::Fork { height, .. } if self.word.height().is_some_and(|h| *height <= h) => {
                self.suspect = true;
                self.reask = Some(Reask::Fork { height: *height });
            }
            ChainEvent::Reorg { fork_height, .. }
                if self.word.height().is_some_and(|h| *fork_height <= h) =>
            {
                self.suspect = true;
                self.recheck(headers, Some(*fork_height))?;
            }
            // A split is an observation, not a reorg: the service still answers
            // its most-work chain and depth is the host's (bsv-stack-lean
            // docs/RULINGS-2026-10-12.md:323-329, 2026-10-16 19:3xZ). It writes no word.
            ChainEvent::Split { fork_height, .. }
                if self.word.height().is_some_and(|h| *fork_height <= h) =>
            {
                self.suspect = true;
                self.reask = Some(Reask::Fork {
                    height: *fork_height,
                });
            }
            // A resolved split moves a word only through the checked snapshot.
            ChainEvent::SplitResolved { fork_height, .. }
                if self.suspect && self.word.height().is_some_and(|h| *fork_height <= h) =>
            {
                self.recheck(headers, None)?;
            }
            ChainEvent::Invalidated { block_hash } if self.checked_against(block_hash) => {
                self.suspect = true;
                self.recheck(headers, None)?;
            }
            _ => {}
        }
        Ok(())
    }

    fn checked_against(&self, block_hash: &str) -> bool {
        matches!(&self.word, Word::Mined(m) if m.checked().header().hash == block_hash)
    }

    fn on_verdict(&mut self, verdict: NodeVerdict) {
        if matches!(self.word, Word::Mined(_)) {
            self.reask = Some(Reask::Recheck);
            return;
        }
        self.word = match verdict {
            NodeVerdict::Rejected { reason } => Word::Rejected { reason },
            NodeVerdict::Conflicted { mut competitors } => {
                if let Word::Conflicted {
                    competitors: previous,
                } = &self.word
                {
                    competitors.extend(previous.iter().cloned());
                }
                Word::Conflicted { competitors }
            }
        };
    }
}

fn agrees(word: &Word, status: &HintStatus) -> bool {
    match (word, status) {
        (
            Word::Announced | Word::Seen,
            HintStatus::Accepted | HintStatus::MempoolPresent { .. },
        )
        | (Word::Seen, HintStatus::Seen)
        | (Word::Stale, HintStatus::StaleBlock)
        | (Word::Rejected { .. }, HintStatus::Rejected { .. })
        | (Word::Conflicted { .. }, HintStatus::DoubleSpend { .. }) => true,
        (Word::Mined(mined), HintStatus::Mined { height }) => mined.height() == *height,
        _ => false,
    }
}