🔥 Crucible Scenarios

STRESS-TEST — the scenario, conformance, adversarial-testing, regression, invariant, privacy, compatibility, and stress-testing layer of the Crucible hybrid system for Stellar/Soroban Confidential Tokens.

📖 Documentation site for all three repositories: https://crucible-docs-flame.vercel.app

▶ Watch the pitch — 4:52

Click the thumbnail to watch the full product pitch. It covers the problem, the three-layer architecture, how the conformance and adversarial harnesses challenge the simulator and the prover, and the limits this project states about itself.

Every frame is a live capture — the deployed documentation site, the public repositories, and the deployed Stellar testnet verifier contract. Nothing in it is a mock-up, and nothing in it is a slide about a roadmap.

            CRUCIBLE
               │
   ┌───────────┼───────────┐
   ▼           ▼           ▼
 SIMULATE     PROVE     STRESS-TEST
crucible-   crucible-  crucible-
simulator    prover     scenarios
   │           │           │
   └───────────┼───────────┘
               ▼
    Confidential Token
        validation

Crucible is three source repositories and one documentation site:

The overall lifecycle is: CONSTRUCT → EXECUTE → PROVE → VERIFY → OBSERVE → ASSERT → STRESS-TEST → REPORT.

What this repository does

crucible-scenarios answers one question:

Given a known initial state, a defined Confidential Token workflow, a proof provider, and expected protocol behavior, does the complete system behave correctly under normal, invalid, adversarial, privacy-sensitive, state-sensitive, concurrent, and high-load conditions?

It never becomes another simulator, another prover, another wallet, another token implementation, or a generic testing framework. It consumes stable interfaces from crucible-simulator and crucible-prover through the adapter crates in crates/adapters/ and orchestrates them into scenarios. It does not own: token contract implementation, Confidential Token cryptography, proof/circuit implementation, wallet or production account management, or production transaction orchestration.

Current status

What exists today is a production-quality orchestration and validation layer validated by passing tests, clean fmt/clippy, six benches, and a working CLI. Both upstream repositories are now wired behind their adapter contracts at pinned revisions: the real crucible-simulator flow engine and the real crucible-prover service, together in one run via MockHarness::run_integration. The remaining substantive gap — re-expressing the registered conformance pack against the real engine’s observation vocabulary — is called out explicitly below. Nothing should be read as existing until it is listed under Implemented today.

Implemented today

• Scenario domain model (scenario-core) — validated definitions, metadata, categories, tags, capabilities, actors, typed operations, expectations, assertions, classified observations, outcomes, and a classified failure model where expected rejection is distinct from failure.
• Deterministic runner (scenario-runner) — lifecycle, isolation, timeout, cancellation, cleanup, hooks, and an explicit retry policy that never retries deterministic failures.
• Registry (scenario-registry) — registration, discovery, and filtering by category, tag, capability, and id prefix.
• Deterministic fixtures (fixtures) — a synthetic, embedded, versioned catalog; no type in it can hold a secret.
• Assertion engine (assertions) — state, balance, ownership, commitment, proof-valid/invalid, event, authorization, and privacy checks with expected/actual diagnostics that never print private values.
• Adapters (crates/adapters/simulator, crates/adapters/prover) — the simulator and prover surfaces behind scenario-core’s provider-neutral contracts. Both surfaces ship two implementations, kept apart so neither borrows the other’s credibility:
  • the simulator surface is wired to the real crucible-simulator flow engine (RealSimulator, compiled from the simulator repository at a pinned revision) and also ships the deterministic in-repo test double (InMemorySimulator) that fixture postures need;
  • the prover surface is wired to the real crucible-prover service machinery (RealProver) and also ships the fixture posture double (FixtureProver) that negative and adversarial scenarios need. Runs exercise orchestration, binding, and the real simulator and prover contracts — never cryptographic validity.

• Flows (flows) — reusable register, deposit, merge, transfer, withdraw, and full-lifecycle workflows, each asserting against independently computed expected values (never the surface’s own answers).
• Registered scenario packs — happy-path (6 flows), negative (11), conformance (5, stated against the in-memory double), conformance-real (5, stated against and judged by the real crucible-simulator engine), adversarial (4), privacy (4), concurrency (4), regression (3), compatibility (3), and performance (3) — 48 scenarios across ten packs, all runnable through the CLI and gated per family in CI (Level-2 scenarios.yml plus dedicated conformance, adversarial, regression, performance, and security workflows).
• Privacy pack (privacy) — success-path and failure-path privacy scenarios (CT-PRIV-001..004) asserting that confidential amounts and witness material never reach public observations or reports; plus definition-time enforcement: scenario-core rejects proof-generation steps whose public inputs name a confidential field.
• Concurrency pack (concurrency) — sequential-composition scenarios (CT-CONC-001..004): no lost updates across same-account spends, no interference between independent accounts, merge/transfer commitment bookkeeping, and order-independent, side-effect-free proof pipelines.
• Test vectors (test-vectors) — a deterministic, machine-readable corpus of 24 vectors (CT-VEC-001..024) covering register, deposit, merge, transfer, withdraw, proof verification, and cross-operation sequences, each naming its input state, expected result and classification, proof behavior, and state transition; validated structurally and for coherence.
• Regression catalog (regression) — permanent regression cases (CT-REG-001..003) converted from real bugs found during development, each pairing the issue reference, affected component, fixed version, and a minimal scenario that pins the fixed behavior; never deleted.
• Fuzzing (fuzz) — seeded, deterministic mutation fuzzing (SplitMix64 PRNG, no external dependency) over operation parameters, negative controls, proof references, and public inputs; every finding records its seed and iteration, shrinks to a minimal case, and converts into a permanent regression test.
• Invariants (invariants) — seven cross-operation checks (balance conservation, ownership, commitment consistency, proof binding, public input binding, replay protection, privacy) recomputed independently from the scenario definition and fixtures.
• Privacy by construction — private/sensitive observations are classified and redacted at serialization; no code path renders witness material; the privacy invariant scans every public observation for confidential field names; pack tests serialize whole outcomes and assert the confidential literals are absent from the JSON.
• Compatibility pack (compatibility) — circuit-version match and mismatch plus artifact reproducibility (CT-COMP-001..003).
• Performance pack (performance) — configurable high-volume correctness-at-scale scenarios (CT-PERF-001..003).
• Phase metrics — every scenario outcome carries per-phase timings (setup/simulation/assert/invariants/…); reports decompose time instead of collapsing it (spec §67).
• Reporting crate (reporting) — suite aggregates rendered as JSON, JUnit XML (CI xUnit ingestion), and Markdown with per-phase timing tables; all renderers consume redacted summaries only.
• Declarative format (scenario-format) — versioned JSON scenario documents with strict envelope validation and the same semantic validator the builder uses, all gated before execution (spec §33, §68); canonical examples in examples/declarative/, schemas in schemas/.
• Parallel execution — run --parallel / report --parallel run independent scenarios over worker harnesses with byte-identical results (spec §71); concurrency-category scenarios always stay serial.
• Soroban adapter (adapters/soroban) — contract-surface vocabulary, operation↔call translation, and event interpretation, isolated and hermetic; not yet wired to a live deployment client.
• Testnet adapter (adapters/testnet) — explicit opt-in configuration, polling, and execution surfaces; never required by ordinary CI (spec §30).
• CLI (cli, binary crucible-scenarios) — list, run, validate, inspect, report (--format text|json|junit|markdown), vectors, and fuzz, plus --parallel and --json, with CI-usable exit codes.
• Benches (benches/) — six stable-Rust benches (scenario execution, assertion evaluation, fixture loading, proof flow, concurrency, reporting) asserting correctness properties while measuring mock-harness cost.
• Scripts (scripts/) — test-all.sh (full local CI mirror), per-family run scripts, validation and generation helpers.
• Contributor surface — 11 workflows (Level-1/2 gates, conformance, adversarial, regression, performance, security, opt-in testnet, release), eight issue templates, and a PR template encoding the boundary checklist (DoD #31).

DoD status

A line-by-line audit against the spec’s §76 Definition of Done lives in docs/dod-audit.md. The prover-side items are closed by the real prover wiring; the remaining open item is the real simulator wiring below.

Planned (designed, not yet implemented)

• Real simulator wiring (DoD 5–6, the substantive gap) — the simulator adapter is an in-repo test double; the prover adapter is wired to the real crucible-prover service (see docs/prover-integration.md). Wiring the real crucible-simulator ledger behind the simulator contract is what will make conformance claims fully meaningful, and it cannot be completed inside this repository alone.
• Live Soroban execution — the adapter is ready; a deployment client is not wired.
• Agent scenarios — deferred by design (see docs/agent-scenarios.md): no agent protocol exists in the underlying implementation, and the project does not invent protocol semantics.

Repository layout

crates/
  scenario-core       domain model, outcomes, phase timings   (implemented)
  scenario-runner     deterministic execution + invariants    (implemented)
  scenario-registry   registration/discovery/filtering        (implemented)
  fixtures            deterministic synthetic fixtures        (implemented)
  assertions          observation assertions                  (implemented)
  scenario-format     declarative documents + validation      (implemented)
  adapters/simulator  simulator surface (test double today)   (implemented)
  adapters/prover     prover/verifier surface (fixture double
                      + real crucible-prover service)          (implemented)
  adapters/soroban    Soroban contract-surface adapter        (implemented, client not wired)
  adapters/testnet    opt-in testnet adapter                  (implemented)
  flows               happy-path workflows + catalog          (implemented)
  negative            expected-rejection scenarios (11)       (implemented)
  adversarial         assumption-violation scenarios (4)      (implemented)
  conformance         conformance scenarios vs the double (5) (implemented)
  conformance-real    conformance scenarios vs the real engine (5) (implemented)
  privacy             privacy and report-hygiene (4)          (implemented)
  concurrency         sequential-composition scenarios (4)    (implemented)
  compatibility       version-compatibility scenarios (3)     (implemented)
  performance         high-volume correctness-at-scale (3)    (implemented)
  invariants          cross-operation invariant checks (7)    (implemented)
  test-vectors        deterministic conformance vectors (24)  (implemented)
  regression          permanent bug regressions (3)           (implemented)
  fuzz                seeded deterministic fuzzing            (implemented)
  reporting           JSON/JUnit/Markdown suite reports       (implemented)
cli/                  crucible-scenarios command surface      (implemented)
benches/              six correctness-with-timings benches    (implemented)
scripts/              gate, validation, generation scripts    (implemented)
schemas/              versioned JSON schemas                  (implemented)
examples/declarative/ canonical declarative documents         (implemented)
docs/                 architecture + per-suite documentation  (implemented)
.github/              layered CI + issue/PR surfaces          (implemented)

See docs/architecture.md for the detailed design.

Scenario lifecycle

Every scenario conceptually follows:

Scenario Definition → Initial State → Actor Setup → Token Setup
→ Operation Construction → Simulator Execution → Witness/Proof Request
→ Proof Generation → Proof Verification → State Transition → Event Capture
→ Assertion → Invariant Validation → Result Classification → Report

Quick start

Requires a stable Rust toolchain (see rust-toolchain.toml).

cargo build --workspace
cargo test  --workspace

Using the CLI

# Build once, then drive the catalog:
cargo build -p cli
cargo run -p cli --bin crucible-scenarios -- list
cargo run -p cli --bin crucible-scenarios -- list --category conformance
cargo run -p cli --bin crucible-scenarios -- validate
cargo run -p cli --bin crucible-scenarios -- run CT-NEG-002
cargo run -p cli --bin crucible-scenarios -- run --tag proof --json
cargo run -p cli --bin crucible-scenarios -- run --category happy-path --parallel
cargo run -p cli --bin crucible-scenarios -- inspect CT-CONF-002
cargo run -p cli --bin crucible-scenarios -- vectors --json
cargo run -p cli --bin crucible-scenarios -- fuzz --seed 42 --iterations 100
cargo run -p cli --bin crucible-scenarios -- report
cargo run -p cli --bin crucible-scenarios -- report --format junit
cargo run -p cli --bin crucible-scenarios -- report --parallel
# The full local CI mirror:
scripts/test-all.sh

run/report exit non-zero when anything actually failed, so they gate CI; expected-failure scenarios (negative/adversarial) pass when the system failed exactly as declared. Machine output (--json) is emitted over the domain types, whose serialization redacts private values.

How to think about the tests in this repository

The repository deliberately separates claims:

• Unit tests exercise one crate’s own contract.
• Mocked integration runs (the flows::MockHarness path) exercise the full orchestration stack against deterministic test doubles. They validate that the scenario layer behaves and that expected values are derived independently — never that the system under test is cryptographically correct.
• Real simulator validation runs through flows::MockHarness::run_real_simulator, which drives the actual crucible-simulator flow engine behind the adapter contract.
• Full real-stack validation runs through flows::MockHarness::run_integration, which drives the real simulator engine and the real crucible-prover service in a single run.
• Real prover validation runs through flows::MockHarness::run_real against crucible-prover’s actual service (hermetic mock backend) behind the adapter contracts and is labeled as such.

All three real paths are labeled where they appear: the adapters report which repository they drive, and the run entry points are distinct from the mocked run. What is still future work is repointing the registered conformance pack at the real engine (the pack asserts on the double’s invented public-balance vocabulary), plus real UltraHonk/bb proving and real Soroban/testnet validation.

Mocked runs must never be presented as cryptographic or on-chain evidence.

Relationship to the other Crucible repositories

• crates/adapters/simulator and crates/adapters/prover define the provider-neutral surfaces through which scenarios consume crucible-simulator and crucible-prover, and both now reach the real repositories behind those contracts at pinned revisions. The in-repo doubles remain for fixture postures a real engine does not model. What cannot happen inside this repository alone is re-expressing the registered packs against the real engine’s observation vocabulary, since that vocabulary is defined by the simulator repository.
• crates/adapters/soroban (contract surface, translation, events) and crates/adapters/testnet (explicit opt-in) exist and are hermetic; live-contract and network execution stay isolated and opt-in.

Documentation

The documentation in this repository is rendered together with crucible-simulator and crucible-prover at https://crucible-docs-flame.vercel.app. The markdown files here are the source; the site is a build of them. Rebuilds are nightly and on demand — a push here does not itself trigger one — so a change appears on the site within a day, or immediately if the documentation-site workflow is dispatched. To change a published page, change the file that owns it in this repository.

docs/error-codes.md lists every failure code the harness can raise and what it means. That table is a public interface: outcome classification, the JUnit and Markdown renderers, and scenario assertions branch on these codes rather than on message text, so the document is what lets a consumer interpret a report without reading this source. It is kept honest by scripts/check-error-codes.py, which runs in CI and fails when the document and the code disagree in either direction. It also records how these UPPER_SNAKE_CASE harness codes relate to the snake_case domain codes that pass through from crucible-simulator.

Contributing

Scenarios must validate externally observable behavior, derive expected values from declared inputs and protocol rules (never from the same internal function under test), and must not leak private witnesses. See CONTRIBUTING.md and docs/.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option, matching crucible-simulator and crucible-prover.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this repository by you, as defined in the Apache License, shall be dual licensed as above, without any additional terms or conditions.