Skip to main content

statechronicle/
lib.rs

1//! StateChronicle: a pure-logic, domain-extensible verifiable state protocol
2//! engine.
3//!
4//! This is the **umbrella crate**: the single dependency consumers add to use
5//! the whole protocol surface. It re-exports the underlying protocol
6//! crates under collision-safe namespaces and surfaces the most-used types
7//! directly at the top level.
8//!
9//! ```rust
10//! use statechronicle::domain::intent::{Intent, Operation};
11//! use statechronicle::core::amount::Amount;
12//! use statechronicle::domain::signed::Signed;
13//! ```
14//!
15//! The [`ports`] module holds the eleven trait boundaries consumers implement
16//! to wire their own storage, authority, and transport backends (intent store,
17//! event store, commit store, state index, proof index, trade index, snapshot
18//! store, tenant store, TrustGrant evaluator, transaction manager, event
19//! publisher). Those traits are wired into the engine at the consumer's
20//! composition root. This crate ships no storage, HTTP, or authority
21//! implementation.
22
23#![deny(unsafe_code)]
24#![allow(clippy::must_use_candidate)]
25
26/// Sparse-Merkle state accumulator and state roots.
27pub use statechronicle_accumulator as accumulator;
28/// Commit formation, deterministic ordering, and signing.
29pub use statechronicle_commit as commit;
30/// Protocol primitives: amounts, digests, signatures, limits, canonicalization.
31pub use statechronicle_core as core;
32/// Canonical domain objects: tenants, resources, intents, events, commits,
33/// proofs, and state projections.
34pub use statechronicle_domain as domain;
35/// The ยง18.1 execution pipeline that runs validated intents through the port
36/// gates and emits events.
37pub use statechronicle_executor as executor;
38/// The trade read-side vertical slice (index, history, proof serving).
39pub use statechronicle_index as index;
40/// Intent parsing and validation into `ValidatedIntent`.
41pub use statechronicle_intent as intent;
42/// Allocation-free codecs and integrity verification for bounded consumers.
43pub use statechronicle_portable as portable;
44/// The eleven backend-agnostic port traits consumers implement.
45pub use statechronicle_ports as ports;
46/// Baseline resource profiles and their rule sets.
47pub use statechronicle_profiles as profiles;
48/// Proof serving and verification (state, ownership, inclusion, non-membership).
49pub use statechronicle_proof as proof;
50
51/// Protected prepared plans, signing, atomic commit outcomes and recovery.
52pub mod mutation;
53
54// ---- Curated top-level facade ----
55//
56// The most-used protocol types, re-exported directly. Everything here resolves
57// to the exact canonical module path in the corresponding crate; consumers can
58// use either the flat names or the namespaced forms interchangeably.
59
60/// Exact fixed-point amount. See [`core::amount::Amount`].
61pub use statechronicle_core::amount::{Amount, MAX_MANTISSA_DIGITS, MAX_SCALE};
62/// SHA-256 content digest in canonical `sha256:<hex>` form. See [`core::digest::ContentDigest`].
63pub use statechronicle_core::digest::ContentDigest;
64/// An Ed25519 signature over canonicalized content. See [`core::signature::Signature`].
65pub use statechronicle_core::signature::Signature;
66
67/// Authority proofs and TrustGrant evaluation outcomes. See [`domain::authority`].
68pub use statechronicle_domain::authority::{
69    AggregationPolicy, AuthorityProof, EvaluationResult, TrustGrantOutcome,
70};
71/// A signed batch of events. See [`domain::commit::Commit`].
72pub use statechronicle_domain::commit::{Commit, CommitScope, ProfileId, ScopeKind};
73/// A validated, append-only transition. See [`domain::event::Event`].
74pub use statechronicle_domain::event::{Event, StateCommitment};
75/// Prefixed newtype identifiers. See [`domain::ids`].
76pub use statechronicle_domain::ids::{CommitId, EventId, IntentId, SnapshotId, StateId};
77/// A requested state transition. See [`domain::intent::Intent`].
78pub use statechronicle_domain::intent::{
79    Intent, IntentBuilder, KeyId, Nonce, Operation, SignatureAlg, SignatureBlock,
80};
81/// Identifies a resource within a tenant namespace. See [`domain::resource::ResourceId`].
82pub use statechronicle_domain::resource::ResourceId;
83/// The ADR-004 signed envelope (`body` + detached `signature`). See [`domain::signed::Signed`].
84pub use statechronicle_domain::signed::Signed;
85/// A derived projection of a resource's current state. See [`domain::state::StateProjection`].
86pub use statechronicle_domain::state::StateProjection;
87/// A resource state type. See [`domain::state_type::StateType`].
88pub use statechronicle_domain::state_type::StateType;
89/// Identifies a user, account, service, or authority. See [`domain::subject::SubjectId`].
90pub use statechronicle_domain::subject::SubjectId;
91/// Identifies an isolated tenant scope. See [`domain::tenant::TenantId`].
92pub use statechronicle_domain::tenant::TenantId;
93
94/// The trade proof schema identifier. See [`domain::trade::TRADE_PROOF_SCHEMA`].
95pub use statechronicle_domain::trade::TRADE_PROOF_SCHEMA;
96/// A full trade event in history. See [`domain::trade::TradeEvent`].
97pub use statechronicle_domain::trade::TradeEvent;
98/// A reference to a trade event. See [`domain::trade::TradeEventRef`].
99pub use statechronicle_domain::trade::TradeEventRef;
100/// The ordered trade history view. See [`domain::trade::TradeHistory`].
101pub use statechronicle_domain::trade::TradeHistory;
102/// A portable trade proof. See [`domain::trade::TradeProof`].
103pub use statechronicle_domain::trade::TradeProof;
104/// One per-tenant trade proof leg. See [`domain::trade::TradeProofLeg`].
105pub use statechronicle_domain::trade::TradeProofLeg;
106/// The accumulated trade read-side record. See [`domain::trade::TradeRecord`].
107pub use statechronicle_domain::trade::TradeRecord;
108/// One settled tenant leg of a trade. See [`domain::trade::TradeSide`].
109pub use statechronicle_domain::trade::TradeSide;
110/// Trade lifecycle status. See [`domain::trade::TradeStatus`].
111pub use statechronicle_domain::trade::TradeStatus;
112/// The deterministic trade summary. See [`domain::trade::TradeSummary`].
113pub use statechronicle_domain::trade::TradeSummary;
114/// One declared fungible value leg. See [`domain::trade::TradeValueLeg`].
115pub use statechronicle_domain::trade::TradeValueLeg;
116/// The pure trade index builder. See [`index::build`].
117pub use statechronicle_index::build;
118/// The pure trade index `apply` entry point. See [`index::build::IngestBatch`].
119pub use statechronicle_index::build::IngestBatch;
120/// The trade history reconstruction. See [`index::history`].
121pub use statechronicle_index::history;
122/// The trade read-side port set. See [`index::service::TradePorts`].
123pub use statechronicle_index::service::TradePorts;
124/// The async trade read-side service. See [`index::service::TradeService`].
125pub use statechronicle_index::service::TradeService;
126
127/// Required composition-root persistence boundary for multi-intent batches.
128pub use statechronicle_executor::pipeline::DurableBatchSink;
129/// Required composition-root persistence boundary for player mutations.
130pub use statechronicle_executor::pipeline::DurableMutationSink;
131/// The execution engine. See [`executor::pipeline::Executor`].
132pub use statechronicle_executor::pipeline::Executor;
133/// The execution engine's fluent builder. See [`executor::pipeline::ExecutorBuilder`].
134pub use statechronicle_executor::pipeline::ExecutorBuilder;
135/// One authenticated player request in a durable player batch.
136pub use statechronicle_executor::pipeline::PlayerBatchItem;
137/// The executor's injected port bundle. See [`executor::pipeline::Ports`].
138pub use statechronicle_executor::pipeline::Ports;
139/// The executor's port-bundle builder. See [`executor::pipeline::PortsBuilder`].
140pub use statechronicle_executor::pipeline::PortsBuilder;
141/// An authenticated, uncommitted event plan with protected inputs.
142pub use statechronicle_executor::preparation::{PreparedBatch, PreparedMutation};
143/// A validated intent with its idempotency key. See [`intent::validated::ValidatedIntent`].
144pub use statechronicle_intent::validated::{IdempotencyKey, ValidatedIntent};
145
146/// An opaque SMT state key. See [`accumulator::key::StateKey`].
147pub use statechronicle_accumulator::key::StateKey;
148/// Sparse-Merkle state accumulator. See [`accumulator::sparse_merkle::StateAccumulator`].
149pub use statechronicle_accumulator::sparse_merkle::{StateAccumulator, StateRoot, StateUpdate};
150
151/// Baseline profile registry. See [`profiles::registry::ProfileRegistry`].
152pub use statechronicle_profiles::registry::ProfileRegistry;
153/// The gate every state transition passes through. See [`profiles::registry::ProfileRules`].
154pub use statechronicle_profiles::registry::ProfileRules;
155
156/// The proof service's read-side port set. See [`proof::service::ProofPorts`].
157pub use statechronicle_proof::service::ProofPorts;
158/// Async proof service. See [`proof::service::ProofService`].
159pub use statechronicle_proof::service::ProofService;
160/// Trade proof assembly. See [`proof::trade::build_trade_proof`].
161pub use statechronicle_proof::trade::build_trade_proof;
162/// Trade proof verification. See [`proof::trade::verify_trade_proof`].
163pub use statechronicle_proof::trade::verify_trade_proof;
164
165/// Domain-separated canonical custom state.
166pub use statechronicle_domain::custom::CustomState;
167/// Portable consumer-defined domain transition contracts.
168pub use statechronicle_profile as profile;
169/// Consumer-defined deterministic transition contract.
170pub use statechronicle_profile::StateProfile;
171/// Typed adapter for domain registration.
172pub use statechronicle_profiles::custom::TypedProfile;
173
174/// Define a command discriminator and static operation list from one mapping.
175pub use statechronicle_profiles::command_operations;