Struct ChainManager 

pub struct ChainManager { /* private fields */ }

Thread-safe chain manager.

Wraps a local chain with mutex protection for concurrent access from multiple kernel subsystems. Optionally holds an Ed25519 signing key for cryptographic chain signing.

Implementations

impl ChainManager

pub fn new(chain_id: u32, checkpoint_interval: u64) -> Self

Create a new chain manager with genesis event.

pub fn default_local() -> Self

Create with default settings.

pub fn with_signing_key(self, key: SigningKey) -> Self

Attach an Ed25519 signing key for RVF segment signing.

pub fn verifying_key(&self) -> Option<VerifyingKey>

Get the verifying (public) key, if a signing key is set.

pub fn set_signing_key(&mut self, key: SigningKey)

Set the signing key (mutable borrow — use with Arc::get_mut() before sharing the manager across tasks).

pub fn has_signing_key(&self) -> bool

Whether this chain manager has a signing key attached.

pub fn set_ml_dsa_key(&mut self, key: MlDsa65Key)

Set the ML-DSA-65 key for post-quantum dual signing.

pub fn has_dual_signing(&self) -> bool

Whether dual signing (Ed25519 + ML-DSA-65) is enabled.

pub fn load_or_create_key( path: &Path, ) -> Result<SigningKey, Box<dyn Error + Send + Sync>>

Load an Ed25519 signing key from file, or generate and persist a new one.

pub fn append( &self, source: &str, kind: &str, payload: Option<Value>, ) -> ChainEvent

Append an event to the chain.

pub fn checkpoint(&self) -> ChainCheckpoint

Create a checkpoint.

pub fn len(&self) -> usize

Get the current chain length.

pub fn is_empty(&self) -> bool

Check if the chain is empty (should never be after genesis).

pub fn sequence(&self) -> u64

Get the current sequence number.

pub fn last_hash(&self) -> [u8; 32]

Get the last hash.

pub fn chain_id(&self) -> u32

Get the chain ID.

pub fn tail(&self, n: usize) -> Vec<ChainEvent>

Get recent events (last n, or all if n=0).

pub fn tail_from(&self, after: u64) -> Vec<ChainEvent>

Return events with sequence strictly greater than after. Used for incremental replication in K6.4 chain sync.

pub fn head_sequence(&self) -> u64

Get the current head sequence number (sequence of the last event). Returns 0 when the chain is empty.

pub fn head_hash(&self) -> [u8; 32]

Get the current head hash (hash of the last event). Returns the all-zero hash when the chain is empty.

pub fn checkpoints(&self) -> Vec<ChainCheckpoint>

Get all checkpoints.

pub fn witness_count(&self) -> usize

Get the number of witness entries.

pub fn verify_witness(&self) -> Result<usize, Box<dyn Error + Send + Sync>>

Serialize the witness chain and verify it.

Returns Ok(entry_count) if the witness chain is valid, or Err if verification fails.

pub fn verify_integrity(&self) -> ChainVerifyResult

Verify the integrity of the entire chain.

Walks all events and verifies:

1. Each event’s prev_hash matches the prior event’s hash
2. Each event’s payload_hash matches the recomputed payload hash
3. Each event’s hash matches the recomputed event hash

pub fn save_to_file( &self, path: &Path, ) -> Result<(), Box<dyn Error + Send + Sync>>

Save the chain to a file (line-delimited JSON).

Writes all events as newline-delimited JSON to the given path. Creates parent directories if they don’t exist.

pub fn load_from_file( path: &Path, checkpoint_interval: u64, ) -> Result<Self, Box<dyn Error + Send + Sync>>

Load a chain from a file (line-delimited JSON).

Reads events, verifies integrity, and restores state so that new events continue from the last sequence number.

pub fn save_to_rvf( &self, path: &Path, ) -> Result<(), Box<dyn Error + Send + Sync>>

Save the chain as a concatenation of RVF segments.

Each event is serialized as an ExochainEvent segment (subtype 0x40) containing a 64-byte ExoChainHeader + CBOR payload. A trailing ExochainCheckpoint segment (subtype 0x41) records the final chain state for external verification.

pub fn load_from_rvf( path: &Path, checkpoint_interval: u64, ) -> Result<Self, Box<dyn Error + Send + Sync>>

Load a chain from an RVF segment file.

Reads concatenated RVF segments, validates each segment’s content hash, decodes ExoChainHeader + CBOR payload, and reconstructs the chain events. Checkpoint segments (subtype 0x41) are skipped.

pub fn record_lineage( &self, child_id: [u8; 16], parent_id: [u8; 16], parent_hash: [u8; 32], derivation_type: DerivationType, mutation_count: u32, description: &str, ) -> ChainEvent

Record a lineage derivation event in the chain.

Creates a LineageRecord from the given parameters, serializes it, adds a lineage witness entry, and appends a lineage.derivation chain event with the full record in the payload.

• child_id: UUID of the derived entity (agent, resource)
• parent_id: UUID of the parent entity (zero for root)
• parent_hash: hash of the parent’s state at derivation time
• derivation_type: how the child was produced
• mutation_count: number of mutations/changes applied
• description: human-readable description (max 47 chars)

pub fn verify_lineage(&self) -> Result<usize, Box<dyn Error + Send + Sync>>

Extract lineage records from chain events and verify the chain.

Returns Ok(count) if all lineage records form a valid chain, or Err describing the verification failure.

pub fn record_witness_bundle( &self, bundle_bytes: &[u8], header: &WitnessHeader, policy_violations: u32, rollback_count: u32, ) -> ChainEvent

Record a completed witness bundle as a chain event.

Takes the raw bundle bytes and parsed header produced by WitnessBuilder::build(), stores them as a witness.bundle chain event with the bundle hex-encoded in the payload.

pub fn aggregate_scorecard(&self, n: usize) -> Scorecard

Aggregate witness bundles from recent chain events into a scorecard.

Scans the last n events (0 = all) for witness.bundle events, parses each bundle, and produces an aggregate Scorecard.

pub fn last_tree_root_hash(&self) -> Option<String>

Find the most recent tree root hash recorded in chain events.

Scans backwards through the event log looking for payloads that contain tree_root_hash (shutdown, boot.ready, boot.manifest) or root_hash on tree-sourced events (tree.checkpoint, checkpoint).

Returns the hash as a hex string if found.

pub fn status(&self) -> ChainStatus

Get a status summary.

pub fn verify_rvf_signature( path: &Path, verifying_key: &VerifyingKey, ) -> Result<bool, Box<dyn Error + Send + Sync>>

Verify the Ed25519 signature on an RVF chain file.

Reads the file, locates the checkpoint segment and trailing signature footer, and verifies the signature against the provided public key.

Returns Ok(true) if signature is valid, Ok(false) if invalid, and Err if the file has no signature or can’t be read.

pub fn verify_rvf_dual_signature( path: &Path, ed_key: &VerifyingKey, ml_key: &MlDsa65VerifyKey, ) -> Result<bool, Box<dyn Error + Send + Sync>>

Verify dual (Ed25519 + ML-DSA-65) signatures on an RVF chain file.

Returns Ok(true) if both signatures are valid, Ok(false) if either is invalid, and Err if the file has no dual signature.

pub fn dual_sign(&self, data: &[u8]) -> Option<DualSignature>

Sign data with both Ed25519 and ML-DSA-65 (if configured).

Returns Some(DualSignature) when at least the Ed25519 key is present. The ML-DSA-65 half is populated only when the ML-DSA key has been set via [set_ml_dsa_key].

pub fn verify_dual_signature( data: &[u8], sig: &DualSignature, ed25519_pubkey: &VerifyingKey, ml_dsa_pubkey: Option<&MlDsa65VerifyKey>, ) -> bool

Verify a dual signature against the given data and public keys.

Ed25519 verification is mandatory. ML-DSA-65 verification is performed only when both the signature and verification key are present. Returns false if any present signature is invalid.

impl ChainManager

pub fn append_loggable(&self, event: &dyn ChainLoggable) -> ChainEvent

Append an event from any ChainLoggable implementor.

Trait Implementations

impl Debug for ChainManager

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

Formats the value using the given formatter.