Struct DeferredState 

pub struct DeferredState { /* private fields */ }

In-memory witness for deferred-DAG verification.

The state keeps registered nodes, host-side evaluation memos, and the current deferred root. Evaluation memos are valid only under the same PrecompileRegistry semantics used to populate them. The state is intentionally not serialized directly: partial proofs carry DeferredStateWire, and Self::from_wire rebuilds this state only after registry checks, canonical wire checks, and root evaluation. Final non-empty proofs can instead carry a precompile VM STARK proof for the same deferred root.

Implementations

impl DeferredState

pub fn new( registry: Arc<PrecompileRegistry>, max_elements: usize, ) -> Result<Self, PrecompileError>

pub fn extend_precompiles( &mut self, precompiles: PrecompileRegistry, ) -> Result<(), PrecompileError>

Adds precompiles to this state without discarding existing nodes, evaluation memos, root, or budget accounting.

Registration is additive only: duplicate precompile ids panic via PrecompileRegistry::merge, matching setup-time registry construction behavior. The state is cloned before mutation so failed precompile initialization leaves self unchanged.

pub fn registry(&self) -> &PrecompileRegistry

pub fn root(&self) -> Digest

Returns the current deferred root; super::TRUE_DIGEST means no statements are logged.

pub fn get_node(&self, digest: &Digest) -> Option<&Node>

pub fn get_canonical_digest(&self, digest: Digest) -> Option<Digest>

Returns the already-memoized canonical digest for digest, if present.

This is strictly read-only: it does not evaluate digest, validate deferred nodes, insert canonical results, or mutate the memo table. Missing memos and dangling memos whose canonical node is absent from this state both return None.

pub fn get_canonical_node(&self, digest: Digest) -> Option<(Digest, &Node)>

Returns the already-memoized canonical node for digest, if present.

This is strictly read-only and returns only canonical results that are already memoized and stored in this state.

pub fn require_canonical_node( &self, digest: Digest, ) -> Result<(Digest, &Node), PrecompileError>

Returns the already-memoized canonical node for digest or PrecompileError::MissingNode.

This is strictly read-only and never evaluates or mutates deferred state.

pub fn nodes(&self) -> &BTreeMap<Digest, Node>

pub fn remaining_elements(&self) -> usize

pub fn set_max_elements(&mut self, max_elements: usize)

Updates the remaining deferred-node budget without discarding the installed registry, registered nodes, evaluation memos, or current root.

If the current state already exceeds the new budget, future non-idempotent node insertions will fail because the remaining budget is set to zero. This lets callers tighten execution options without silently dropping proof-relevant deferred state.

pub fn decode(&self, tag: Tag) -> Result<NodeType, PrecompileError>

Recognizes tag under the installed registry and returns its declared outer payload shape.

This does not inspect a payload, validate structural child references, or evaluate precompile semantics. Self::register performs those checks for a complete node.

pub fn register(&mut self, node: Node) -> Result<Digest, PrecompileError>

Registers a PrecompileRegistry-valid node in the DAG and evaluates it immediately.

Registration validates the node shape and child references, stores the original node under its own digest, evaluates it under the current registry, stores the canonical result node, preserves helper nodes registered during evaluation, and records the evaluation memo from original digest to canonical digest. The returned digest is always the original node digest. If evaluation fails, registration returns that error immediately. Re-registering an identical successfully registered node is idempotent and budget-free.

pub fn log_statement( &mut self, statement_digest: Digest, ) -> Result<Digest, PrecompileError>

Logs a statement commitment after proving the current root and statement evaluate to TRUE.

The statement digest must already be registered (present in nodes), unless it is the implicit TRUE_DIGEST. On success, this inserts the framework AND node, advances the deferred root, memoizes the new root as TRUE, and returns the new root.

pub fn log_verified_statement( &mut self, statement_digest: Digest, expected_new_root: Digest, ) -> Result<Digest, PrecompileError>

Logs a statement only if its constrained transition matches expected_new_root.

The VM constrains log_deferred as a Poseidon2 fold over the previous deferred root and the statement digest. This helper binds the in-memory deferred DAG to that constrained transition: it validates the expected root before mutating self, then applies the same semantic checks as Self::log_statement.

pub fn evaluate_digest( &mut self, digest: Digest, ) -> Result<Digest, PrecompileError>

Evaluates a registered node addressed by digest and returns the canonical node digest.

Evaluation memoization is an implementation detail: callers receive the canonical digest whether the result was already known or computed by this call. Use Self::get_node with the returned digest to inspect the canonical node contents.

pub fn to_wire(&self) -> Result<DeferredStateWire, IntegrityError>

Serializes the root-reachable DAG into compact canonical wire form.

Only nodes reachable from root are emitted; registered or memoized orphans are dropped. The installed PrecompileRegistry determines each node’s shape, so graph edges are never inferred from opaque payload bytes.

pub fn from_wire( registry: Arc<PrecompileRegistry>, wire: &DeferredStateWire, max_elements: usize, ) -> Result<Self, IntegrityError>

Rebuilds and verifies a deferred state from untrusted wire data.

The wire root is implicit: empty wire opens TRUE_DIGEST, otherwise the root is the digest of the final entry. Rehydration rejects non-canonical or dangling wire, then evaluates the implicit root to TRUE under the installed precompiles. This is the basis for explicit partial verification: final verification rejects DeferredProof::Wire, while the partial verifier rehydrates it and verifies the VM proof against the resulting root.

Trait Implementations

impl Clone for DeferredState

fn clone(&self) -> DeferredState

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DeferredState

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

Formats the value using the given formatter.

impl Default for DeferredState

fn default() -> Self

Returns the “default value” for a type.