Architecture

The three Crucible repositories

                         CRUCIBLE
                            |
              ┌─────────────┼─────────────┐
              │             │             │
              ▼             ▼             ▼
       crucible-       crucible-     crucible-
       simulator        prover       scenarios
              │             │             │
              │             │             │
              │     ProofProvider         │
              │◄────────────┘             │
              │                           │
              ▼                           │
         Flow Engine                      │
              │                           │
              ▼                           │
         State Engine                     │
              │                           │
              ▼                           │
        Deterministic API ◄───────────────┘

Repository	Property	Responsibility
`crucible-simulator`	Simulate	Reproduce Confidential Token flows and state transitions
`crucible-prover`	Prove	Generate and verify mock/real cryptographic proofs
`crucible-scenarios`	Stress-Test	Execute conformance, failure, and adversarial scenarios

crucible-simulator is the execution foundation the other two build on. It defines the interfaces (ProofProvider, the deterministic API, the fixture contracts); it never imports a prover.

Inside crucible-simulator

                 crucible-simulator
                         │
        ┌────────────────┼────────────────┐
        ▼                ▼                ▼
      CORE             FLOWS            STATE
        │                │                │
        │          ┌─────┼─────┐          │
        │          │     │     │          │
        │          ▼     ▼     ▼          │
        │       Deposit Merge Transfer    │
        │          │     │     │          │
        │          └─────┼─────┘          │
        │                │                │
        └────────────────┼────────────────┘
                         ▼
                    TRANSACTION
                         │
                         ▼
                       EVENT

Pure data model with no dependencies on the engines. Owns accounts, tokens, commitments, balances, operations, transactions, events, the error taxonomy, plus the deterministic foundation primitives (typed IDs, LedgerContext, DeterministicRng, domain-separated hashing).

`crucible-state`

The deterministic state engine. StateStore keeps every piece of state in sorted BTree collections and computes a canonical state-root digest. Every mutation is explicit: flows record StateTransitions audited against the store fingerprint, spend lifecycle is enforced through commitment status + nullifiers, and checkpoints/TransactionScope/snapshots make every change reversible.

`crucible-flows`

The lifecycle engine. The validation pipeline (structure → authorization → state → proof) runs before anything touches state; apply happens inside a rollback scope; record_success writes the transaction, event, and transition. The ProofProvider trait is the only place proofs enter.

`crucible-simulator`

The developer-facing API: Configuration (serializable, reproducible), Environment (config + store + RNG + ledger), Simulator (setup, flows, snapshots, inspection). All flow calls go through Simulator::execute, which dispatches on the operation and supplies a deterministic mock proof provider for confidential transfers.

`crucible-fixtures`

Versioned, machine-readable fixtures (accounts, tokens, environments, scenarios) plus the loader and the scenario runner. The canonical corpus lives at the repository root under fixtures/, mirrored by JSON Schemas in schemas/.

Dependency rules

One dependency direction: core → state → flows → simulator → fixtures.
core never references the other crates.
No crate imports a proving system. ProofProvider is implemented by crucible-prover and mocked here.
Fixture data contracts are stable; crucible-scenarios consumes them without importing simulator internals.

What deliberately does NOT belong here

No production wallet, frontend, compliance/sanctions/KYC engine, production prover or full Noir stack, scenario catalog (that is crucible-scenarios), blockchain explorer, or general-purpose Soroban test framework. The repository is specifically a deterministic Confidential Token flow simulator and state environment.

Keyboard shortcuts

Crucible