Expand description
StateChronicle: a pure-logic, domain-extensible verifiable state protocol engine.
This is the umbrella crate: the single dependency consumers add to use the whole protocol surface. It re-exports the underlying protocol crates under collision-safe namespaces and surfaces the most-used types directly at the top level.
use statechronicle::domain::intent::{Intent, Operation};
use statechronicle::core::amount::Amount;
use statechronicle::domain::signed::Signed;The ports module holds the eleven trait boundaries consumers implement
to wire their own storage, authority, and transport backends (intent store,
event store, commit store, state index, proof index, trade index, snapshot
store, tenant store, TrustGrant evaluator, transaction manager, event
publisher). Those traits are wired into the engine at the consumer’s
composition root. This crate ships no storage, HTTP, or authority
implementation.
Re-exports§
pub use statechronicle_accumulator as accumulator;pub use statechronicle_commit as commit;pub use statechronicle_core as core;pub use statechronicle_domain as domain;pub use statechronicle_executor as executor;pub use statechronicle_index as index;pub use statechronicle_intent as intent;pub use statechronicle_portable as portable;pub use statechronicle_ports as ports;pub use statechronicle_profiles as profiles;pub use statechronicle_proof as proof;pub use statechronicle_profile as profile;
Modules§
- build
- The pure trade index builder. See
index::build. The pure trade index builder. Pure, deterministic trade index builder (Phase 2 of the trade completion). - history
- The trade history reconstruction. See
index::history. History reconstruction over a trade record. History reconstruction over a trade record. - mutation
- Protected prepared plans, signing, atomic commit outcomes and recovery.
Protected mutation composition: prepare single requests through
crate::mutation::Preparer::prepare_player, bind and sign withcrate::mutation::SignedMutation, commit atomically, and resolve retries throughcrate::mutation::recover. Batches usecrate::mutation::Preparer::prepare_player_batchandcrate::mutation::SignedBatch; every member is retained and recovered as one complete atomic group.
Macros§
- command_
operations - Define a command discriminator and static operation list from one mapping. Defines a native command discriminator and its static operation list together.
Structs§
- Amount
- Exact fixed-point amount. See
core::amount::Amount. An exact fixed-point unsigned amount:mantissa * 10^-scale. - Authority
Proof - Authority proofs and TrustGrant evaluation outcomes. See
domain::authority. Canonical authority proof block embedded in events and proof bundles. - Commit
- A signed batch of events. See
domain::commit::Commit. An ordered batch of validated events (protocol §13.1). - Commit
Id - Prefixed newtype identifiers. See
domain::ids. Identifies a commit (protocol §13.1). - Commit
Scope - A signed batch of events. See
domain::commit::Commit. The declared scope of a commit. - Content
Digest - SHA-256 content digest in canonical
sha256:<hex>form. Seecore::digest::ContentDigest. A validated SHA-256 content digest in canonicalsha256:<lowercase-hex>form. - Custom
State - Domain-separated canonical custom state. A canonical BCS payload whose domain and schema are included in every hash. Payload interpretation must check both tags before decoding. Empty payloads at event version zero are the unborn-state commitment, not a decoded state.
- Event
- A validated, append-only transition. See
domain::event::Event. A validated, append-only state transition (protocol §12.1). - EventId
- Prefixed newtype identifiers. See
domain::ids. Identifies an event (protocol §12.1). - Executor
- The execution engine. See
executor::pipeline::Executor. The execution engine (protocol §18). - Executor
Builder - The execution engine’s fluent builder. See
executor::pipeline::ExecutorBuilder. Fluent builder forExecutor. - Idempotency
Key - A validated intent with its idempotency key. See
intent::validated::ValidatedIntent. The §11.2 idempotency tuple. - Ingest
Batch - The pure trade index
applyentry point. Seeindex::build::IngestBatch. One committed batch for the trade read-side: the events, the settle intents that produced (and, for value-declaring settles, declared) them, and the signing commit that pinned the batch. - Intent
- A requested state transition. See
domain::intent::Intent. A requested state transition (protocol §11.1). - Intent
Builder - A requested state transition. See
domain::intent::Intent. Fluent builder forIntent(protocol §11.1). - Intent
Id - Prefixed newtype identifiers. See
domain::ids. Identifies an intent (protocol §11.1). - KeyId
- A requested state transition. See
domain::intent::Intent. A signing-key identifier (protocol §11.1 signature block). - Nonce
- A requested state transition. See
domain::intent::Intent. A replay-protection nonce in the protocol’sb64u:string form. - Operation
- A requested state transition. See
domain::intent::Intent. A registry-open operation name (profile-defined), e.g.asset.transfer. - Player
Batch Item - One authenticated player request in a durable player batch. One player-originated intent and the principal authenticated for it.
- Ports
- The executor’s injected port bundle. See
executor::pipeline::Ports. The executor’s injected port bundle. - Ports
Builder - The executor’s port-bundle builder. See
executor::pipeline::PortsBuilder. Fluent builder forPorts. - Prepared
Batch - An authenticated, uncommitted event plan with protected inputs. One owned, authenticated, uncommitted single-tenant batch.
- Prepared
Mutation - An authenticated, uncommitted event plan with protected inputs.
An owned event plan produced by
Preparer::prepare_playerorcrate::pipeline::Executor::prepare_player. - Profile
Id - A signed batch of events. See
domain::commit::Commit. A profile registry id (protocol §13.1profilefield). - Profile
Registry - Baseline profile registry. See
profiles::registry::ProfileRegistry. Baseline profile registry. - Proof
Ports - The proof service’s read-side port set. See
proof::service::ProofPorts. Backend-agnostic store set used byProofService. - Proof
Service - Async proof service. See
proof::service::ProofService. Async proof service over the proof lane ports. - Resource
Id - Identifies a resource within a tenant namespace. See
domain::resource::ResourceId. Identifies a resource (asset, balance, stack, entitlement, meter, listing, custody record, …) within a tenant’s namespace. - Signature
- An Ed25519 signature over canonicalized content. See
core::signature::Signature. An Ed25519 signature over BCS canonical bytes. - Signature
Block - A requested state transition. See
domain::intent::Intent. A detached signature block (ADR-004 structural envelope). - Signed
- The ADR-004 signed envelope (
body+ detachedsignature). Seedomain::signed::Signed. A signed protocol body with its detached signature block (ADR-004 §2). - Snapshot
Id - Prefixed newtype identifiers. See
domain::ids. Identifies a snapshot (protocol §15). - State
Accumulator - Sparse-Merkle state accumulator. See
accumulator::sparse_merkle::StateAccumulator. In-memory sparse Merkle tree accumulator (one per tenant). - State
Commitment - A validated, append-only transition. See
domain::event::Event. A before/after state commitment bound into an event. - StateId
- Prefixed newtype identifiers. See
domain::ids. Identifies a state record within a tenant (protocol §9). - State
Key - An opaque SMT state key. See
accumulator::key::StateKey. An opaque 256-bit SMT key derived from domain IDs. - State
Projection - A derived projection of a resource’s current state. See
domain::state::StateProjection. A derived projection of a resource’s current state (protocol §9). - State
Root - Sparse-Merkle state accumulator. See
accumulator::sparse_merkle::StateAccumulator. A 32-byte SHA-256 state root. - State
Update - Sparse-Merkle state accumulator. See
accumulator::sparse_merkle::StateAccumulator. A single leaf update:key → state_digest. - Subject
Id - Identifies a user, account, service, or authority. See
domain::subject::SubjectId. Identifies a user, account, service, organization, game, device, or authority (protocol §7). - Tenant
Id - Identifies an isolated tenant scope. See
domain::tenant::TenantId. Identifies an isolated StateChronicle scope (game, studio, marketplace, organization, world, customer, or environment). - Trade
Event - A full trade event in history. See
domain::trade::TradeEvent. A full trade event as returned by the history read, carrying the tenant it was executed in. - Trade
Event Ref - A reference to a trade event. See
domain::trade::TradeEventRef. A lightweight reference to a trade event, used to order the read-side history before the fullEventis fetched from the event store. - Trade
History - The ordered trade history view. See
domain::trade::TradeHistory. The ordered history view of a trade, reconstructed from the record’s event ordering and the event store. - Trade
Ports - The trade read-side port set. See
index::service::TradePorts. Backend-agnostic port set used byTradeService. - Trade
Proof - A portable trade proof. See
domain::trade::TradeProof. A portable proof of a settled trade (protocol §16, trade extension). - Trade
Proof Leg - One per-tenant trade proof leg. See
domain::trade::TradeProofLeg. One per-tenant leg of aTradeProof: a tenant, its committing commit, and the state proofs of the assets settled in that tenant. - Trade
Record - The accumulated trade read-side record. See
domain::trade::TradeRecord. The accumulated, deterministic projection of a single trade’s lifecycle. - Trade
Service - The async trade read-side service. See
index::service::TradeService. Async trade service over the trade read-side ports. - Trade
Side - One settled tenant leg of a trade. See
domain::trade::TradeSide. One settled leg of a trade within a single tenant scope. - Trade
Summary - The deterministic trade summary. See
domain::trade::TradeSummary. The deterministic summary of a trade (sides + value legs), shared by the history view and embedded in the trade proof. - Trade
Value Leg - One declared fungible value leg. See
domain::trade::TradeValueLeg. One declared fungible value leg of a settled trade. - Trust
Grant Outcome - Authority proofs and TrustGrant evaluation outcomes. See
domain::authority. The outcome of a TrustGrant authority evaluation, bound into an event. - Typed
Profile - Typed adapter for domain registration.
Adapts a native profile into the shared execution/commit/proof pipeline.
Commands are BCS bytes in
inputs.command; operation names select the profile’s public API and remain available to authority evaluators. The profile’s command type must encode its transition discriminator itself. Authority bindings are mandatory by default. Override viawith_optional_authorityonly when the consumer’s submission policy supplies an equivalent boundary. - Validated
Intent - A validated intent with its idempotency key. See
intent::validated::ValidatedIntent. A validated intent: the parsed canonical body plus its idempotency key.
Enums§
- Aggregation
Policy - Authority proofs and TrustGrant evaluation outcomes. See
domain::authority. How the evaluations of a deployment’s authority set are combined for a transition (protocol §18.1 step 8, ADR-006 §36 Q5). - Evaluation
Result - Authority proofs and TrustGrant evaluation outcomes. See
domain::authority. Allow/deny result of a TrustGrant evaluation. - Scope
Kind - A signed batch of events. See
domain::commit::Commit. The scope of a commit: a tenant history or the global checkpoint chain. - Signature
Alg - A requested state transition. See
domain::intent::Intent. Signature algorithm identifiers (ADR-004 §5). - State
Type - A resource state type. See
domain::state_type::StateType. Baseline state types plus consumer-defined domain state. - Trade
Status - Trade lifecycle status. See
domain::trade::TradeStatus. The lifecycle status of a trade, derived deterministically from its event stream (firsttrade.lock->Open; a settle batch ->Settled;trade.unlock->Cancelled).
Constants§
- MAX_
MANTISSA_ DIGITS - Exact fixed-point amount. See
core::amount::Amount. The maximum number of decimal digits in au128mantissa. - MAX_
SCALE - Exact fixed-point amount. See
core::amount::Amount. The maximum supported scale (number of fractional decimal digits). - TRADE_
PROOF_ SCHEMA - The trade proof schema identifier. See
domain::trade::TRADE_PROOF_SCHEMA. Schema identifier for v0 trade proofs.
Traits§
- Durable
Batch Sink - Required composition-root persistence boundary for multi-intent batches. Persistence boundary for multi-intent inventory, market, and settlement batches. Implementations must claim every intent and write all events, projections, commits, and outbox effects in one durable transaction (or reject unsupported cross-tenant atomicity).
- Durable
Mutation Sink - Required composition-root persistence boundary for player mutations. Persistence boundary for player-facing execution.
- Profile
Rules - The gate every state transition passes through. See
profiles::registry::ProfileRules. A rule set governing one profile over a resource state type. - State
Profile - Consumer-defined deterministic transition contract. Consumer-defined deterministic domain semantics.
Functions§
- build_
trade_ proof - Trade proof assembly. See
proof::trade::build_trade_proof. Assembles a portable trade proof from a trade record and per-tenant state proofs of the settled assets. - verify_
trade_ proof - Trade proof verification. See
proof::trade::verify_trade_proof. Verifies a trade proof fail-closed.