Struct StateOf 

pub struct StateOf<F: HeaderFamily> { /* private fields */ }

The chain in memory, for header family F.

Implementations

impl<F: HeaderFamily> StateOf<F>

pub fn replay(doc: ChainDocument, dat: &[u8], now: Option<u32>) -> Result<Self>

Replay a mirror’s block file held in memory into a validated state. The first record must be height 0 and is judged as the genesis (StateOf::from_genesis, held to the document’s genesisHash); every later record must be the next height and passes StateOf::apply. now is the clock for the future-time rule (None skips it). An empty file is Error::BlockFile: a chain always has its genesis.

pub fn replay_with( doc: ChainDocument, dat: &[u8], now: Option<u32>, on_block: impl FnMut(Option<&Self>, u32, &F::Block), ) -> Result<Self>

StateOf::replay, calling on_block(before, height, block) for each block ahead of applying it: before is the state at the previous height (None for the genesis). A wallet uses it to read its own history, since which coins a block spends is known only before the block is applied. A block the rules refuse stops the replay with the error; on_block has then seen it, so a caller keeps nothing from a call that returned an error.

impl<F: HeaderFamily> StateOf<F>

pub fn family_of(doc: &ChainDocument) -> Result<F>

The family marker, if the document’s parent hands down the family this state is instantiated for; Error::UnsupportedFamily otherwise. The first thing every constructor checks, before a block is decoded.

pub fn build_genesis_for(doc: &ChainDocument) -> Result<F::Block>

SPEC 5: the genesis block, unsigned, minting the document’s pegs at the document’s time, marker sidestr genesis <chain id> (siding/lib/chain.mjs buildGenesis). A pure function of the document.

pub fn genesis_block_for( doc: &ChainDocument, key: &SecretKey, ) -> Result<F::Block>

The genesis sealed by the signer’s key, deterministically (zero aux), so it is reproducible from document and key (siding/lib/chain.mjs genesisBlock).

pub fn with_key(doc: ChainDocument, key: &SecretKey) -> Result<Self>

A state at its genesis, sealed with the signer’s key.

pub fn from_genesis( doc: ChainDocument, genesis: &F::Block, expect: Option<BlockHash>, ) -> Result<Self>

A state at a sealed genesis. Block 0 is judged first, under every rule that applies at height 0 — the header rules with no previous header (proof of work against bits, the version, the family’s own: knots:rule-header-v2-from-fork, -height, -flags-reserved), the block rules (sidestr:rule-block-signature: the solution against the challenge, or the federation’s leaf), the block-context rules with the pegs as the one subsidy, and RULE_GENESIS_DOCUMENT. A failure is Error::Rejected at height 0 naming the rules. Only then is the hash held to expect when given, and to the document’s genesisHash when the document has one (Error::GenesisMismatch).

Departure: siding/lib/chain.mjs #apply at h === 0 applies the genesis on the hash alone. A hash pin says which block 0 you hold, not that it is well-formed; here an unsigned genesis whose hash the document happens to name is still refused. There is no trusted import.

pub fn add_rule(&mut self, rule: Box<dyn BlockRule<F>>)

Add a block-context rule beyond the core (SPEC 12).

pub fn document(&self) -> &ChainDocument

The document.

pub fn family(&self) -> &F

The header family.

pub fn params(&self) -> &Params

The network parameters.

pub fn bits(&self) -> CompactTarget

The compact target every block carries.

pub fn challenge(&self) -> &Script

The challenge.

pub fn federation(&self) -> Option<&Federation>

The federation the document names (level 2), or None for one signer.

pub fn genesis_hash(&self) -> BlockHash

The genesis hash.

pub fn tip(&self) -> Tip

The tip.

pub fn height(&self) -> u32

The tip’s height.

pub fn hash_at(&self, height: u32) -> Option<BlockHash>

The hash at a height.

pub fn header_at(&self, height: u32) -> Option<&F::Header>

The header at a height.

pub fn utxo(&self) -> &Utxo

The UTXO set.

pub fn records(&self) -> &Records

The overlay’s records: claims and burns.

pub fn mempool(&self) -> impl Iterator<Item = &Transaction>

Transactions waiting for a block, in arrival order.

pub fn claimed(&self, txid: &str, vout: u32) -> bool

Whether a parent outpoint is claimed on this chain (SPEC 6).

pub fn pegouts(&self) -> Vec<Burn>

Every burn the chain has validated, oldest first (SPEC 7).

pub fn pegout_min(&self) -> u64

The least a burn may carry (siding/lib/chain.mjs pegoutMin).

pub fn min_fee_rate(&self) -> u64

The producer’s fee floor, sat/vB (siding/lib/chain.mjs minFeeRate).

pub fn coins(&self, script_pubkey: &Script) -> Vec<CoinRef>

The coins paying a script, in no particular order (siding/lib/chain.mjs coins).

pub fn spendable(&self, coin: &Coin) -> bool

Whether a coin may be spent in the next block: not a coinbase, or a mature one.

pub fn vsize(tx: &Transaction) -> u64

A transaction’s virtual size: weight over four, rounded up.

pub fn fees(&self, tx: &Transaction) -> Option<u64>

The fee a transaction pays, from the UTXO set. None if an input is not an unspent coin, if the outputs exceed the inputs, or if either total overflows — the transaction is untrusted, so every sum is checked and no amount is assumed to be under max money.

pub fn apply( &mut self, height: u32, block: &F::Block, expect: Option<BlockHash>, now: Option<u32>, ) -> Result<Applied>

Validate and apply block height (must be the tip plus one) (node.mjs applyNext + siding/lib/chain.mjs #apply). expect is the hash a mirror’s index promised; now is the clock for the future-time rule (None skips it). Every failed rule is named in the error.

pub fn judge( &self, height: u32, block: &F::Block, now: Option<u32>, ) -> (Verdict, Records)

Every phase’s verdict on a candidate for height, and the records it would leave, without applying anything. At height 0 there is no previous header, so the rules that need one are skipped; a height beyond the tip sees whatever headers exist below it.

pub fn add_block( &mut self, block: &F::Block, expect: Option<BlockHash>, now: Option<u32>, ) -> Result<Applied>

Accept a block from elsewhere (a mirror): its height read from it, validated, applied (siding/lib/chain.mjs addBlock).

pub fn add_block_bytes( &mut self, bytes: &[u8], expect: Option<BlockHash>, now: Option<u32>, ) -> Result<Applied>

StateOf::add_block from consensus bytes.

pub fn submit(&mut self, tx: Transaction) -> Result<Submitted>

SPEC 11: a transaction reaches the producer; it is included when it validates (siding/lib/chain.mjs submit). The mempool’s policy, in order: the transaction rules; every input an unspent, unreserved, mature coin; outputs at most inputs; a burn well-formed and at least pegoutMin (SPEC 7); the fee at least minFeeRate sat/vB; every input’s signature under the sighash rules the next block is judged by.

pub fn build_next(&self, next: &NextBlock) -> Result<(F::Block, u64, usize)>

The next block, unsigned: the mempool in order, fees to the challenge, the claims (SPEC 4, 6) (siding/lib/chain.mjs buildNext). A claim pays the peg’s amount to the script the peg-in named, followed by its marker.

pub fn produce( &mut self, key: &SecretKey, next: &NextBlock, now: Option<u32>, ) -> Result<(Applied, F::Block)>

One signer: build, sign, add (siding/lib/chain.mjs produce). Returns the report and the sealed block, for the caller to write down. A federated chain is refused: its blocks are sealed by k signatures gathered above this crate and enter through StateOf::add_block.

Trait Implementations

impl<F: Debug + HeaderFamily> Debug for StateOf<F>

where F::Header: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.