Crate themelio_stf

This crate contains the data structures and core algorithms that comprise Themelio’s core state machine. Any piece of software needing to parse Themelio data, validate Themelio transactions, or answer questions like “what happens to the Themelio state if transactions A, B, and C happen” can use this minimal-depedency crate.

Roughly, the structs in this crate are organized as follows:

• State represents a full Themelio world-state and it’s not directly serializable. It includes all the information needed to validate new transactions and blocks, such as a SMT of all outstanding coins, Melmint parameters, etc. It has methods taking Transactions etc that advance the state, as well as others to produce serializable blocks, headers, etc.
• Transaction represents a serializable Themelio transaction. It has some helper methods to count coins, estimate fees, etc, largely to help build wallets.
• StakeDoc, which every State includes, encapsulates the Symphonia epoch-based stake information.
• SmtMapping represents a type-safe SMT-backed mapping that is extensively used within the crate.

Modules

melpow	melpow is the crate that implements MelPoW, Themelio’s version of non-interactive proofs of sequential work, which are just “Interactive Proofs of Sequential Work” by Cohen and Pietrzak subjected to a Fiat-Shamir transformation. MelPoW is used as the core mechanism behind Melmint, the algorithmic monetary policy system that stabilizes the mel.
melvm

Structs

AbbrBlock	An abbreviated block
Block	A (serialized) block.
CoinData	The data bound to a coin ID. Contains the “contents” of a coin, i.e. its constraint hash, value, and coin type.
CoinDataHeight	A CoinData but coupled with a block height. This is what actually gets stored in the global state, allowing constraints and the validity-checking algorithm to easily access the age of a coin.
CoinID	A coin ID, consisting of a transaction hash and index. Uniquely identifies a coin in Themelio’s history.
ConfirmedState	ConfirmedState represents a fully confirmed state with a consensus proof.
GenesisConfig	Configuration of a genesis state. Serializable via serde.
Header	A block header, which commits to a particular SealedState.
HexBytes	A type that wraps a bytevector, serializing as hexadecimal for JSON.
PoolState
ProposerAction	ProposerAction describes the standard action that the proposer takes when proposing a block.
SealedState	SealedState represents an immutable state at a finalized block height. It cannot be constructed except through sealing a State or restoring from persistent storage.
SmtMapping	SmtMapping is a type-safe, constant-time cloneable, imperative-style interface to a sparse Merkle tree.
StakeDoc	StakeDoc is a stake document. It encapsulates all the information needed to verify consensus proofs.
State	World state of the Themelio blockchain
Transaction	Transaction represents an individual, serializable Themelio transaction.
TxHash	A newtype representing the hash of a transaction.

Enums

Denom
NetID	Identifies a network.
ParseCoinIDError
StateError	A error that happens while applying a transaction to a state
TxKind	An enumeration of all the different possible transaction kinds. Currently contains a “faucet” kind that will be (obviously) removed in production.

Constants

COVHASH_DESTROY	Coin destruction covhash
MAX_COINVAL	Maximum coin value
MICRO_CONVERTER	1e6
STAKE_EPOCH	A stake epoch is 200,000 blocks.

Functions

calculate_reward	Reward calculator. Returns the value in real DOSC.
dosc_inflate_r2n	DOSC inflation calculator.
dosc_inflator	DOSC inflation ratio.
liq_token_denom	Denomination for a particular liquidity token
preseal_melmint	Presealing function that is called before a state is sealed to apply melmint actions.

Type Definitions

ConsensusProof
StakeMapping	A stake mapping