Architecture

crucible-scenarios is the STRESS-TEST polyrepo of the Crucible hybrid system: a scenario orchestration and validation layer for the Crucible Confidential Token stack. It never defines the system — it tests it.

The three polyrepos

Polyrepo	Layer	Owns
`crucible-simulator`	SIMULATE	deterministic simulation and state execution
`crucible-prover`	PROVE	circuits, witnesses, proving, verification, proof artifacts, proof interfaces
`crucible-scenarios`	STRESS-TEST	scenario definitions/execution, orchestration, fixtures, test vectors, assertions, invariants, failure classification, negative/adversarial/privacy/conformance/regression/compatibility suites, stress/performance/fuzzing orchestration, reports, reproducible replay

What belongs here — and what does not

This repository owns: scenario definitions and execution; test orchestration; deterministic fixtures and versioned test vectors; expected outcomes and reusable assertions; cross-operation invariants; failure classification; regression cases; negative, adversarial, and privacy testing; compatibility and conformance checking; concurrency, stress, performance, and fuzzing orchestration; structured reporting; reproducibility and deterministic replay; integration-test coordination.

It does NOT own: the token contract implementation; Confidential Token cryptographic implementation; proof/circuit generation; wallet or production account management; compliance/sanctions policy; audit dashboards; production transaction orchestration; or any generic blockchain framework functionality. It must never re-implement simulator or prover semantics, never depend on their private internals, never modify production contracts from tests, and never treat mocked proofs as cryptographically valid.

Data flow

 Scenario
    │  (definition: metadata, actors, operations, expectations)
    ▼
 ScenarioContext ──── ScenarioRunner ──── SimulatorService (simulator adapter)
    │                                         │
    │      ProofProviderService (prover       │  operation execution
    │      adapter)  ── witness ──► proof     ▼
    │      VerifierService                    state transition + events
    ▼                                         │
 Observations (classified public/private) ◄───┘
    │
    ▼
 Assertions ──► Invariants ──► ScenarioOutcome ──► Reports (text/JSON/JUnit/Markdown)

The target full integration (real simulator wiring is planned; the real prover service is wired today, see Integration status):

crucible-scenarios
   ├── simulator  (adapter over crucible-simulator interfaces; double today)
   ├── prover     (adapter over crucible-prover; real service today)
   └── soroban    (contract-surface adapter; translation + events, client not wired)
              │
              ▼
      Confidential Token
              │
              ▼
         verification

Crate map and dependency direction

 scenario-core       domain model (definitions, outcomes, classification, phase timings)
 scenario-runner     executes scenarios (lifecycle, invariants, retry, cleanup, hooks)
 scenario-registry   discovers/filters scenarios
 fixtures            deterministic synthetic test data
 assertions          reusable validation over observations
 scenario-format     versioned declarative scenario documents + pre-execution validation
 adapters/simulator  simulator surface; today a labeled in-repo double
 adapters/prover     prover/verifier surface; fixture double + real adapter
                     (crucible-prover service, hermetic mock backend)
 adapters/soroban    Soroban contract-surface adapter (isolated; client not wired)
 adapters/testnet    opt-in testnet adapter (hermetic; network never required)
 flows               reusable protocol workflows + the happy-path catalog
 negative            expected-rejection scenarios            (CT-NEG-*)
 adversarial         assumption-violation scenarios          (CT-ADV-*)
 conformance         protocol-conformance suites             (CT-CONF-*)
 privacy             privacy and report-hygiene scenarios    (CT-PRIV-*)
 concurrency         sequential-composition scenarios        (CT-CONC-*)
 compatibility       version-compatibility scenarios         (CT-COMP-*)
 performance         high-volume correctness-at-scale        (CT-PERF-*)
 invariants          cross-operation properties (7 built-in checks)
 test-vectors        deterministic conformance vector corpus (CT-VEC-*)
 regression          permanent bug regressions               (CT-REG-*)
 fuzz                seeded deterministic fuzzing + finding reduction
 reporting           suite reports: JSON / JUnit XML / Markdown, per-phase timings
 cli                 crucible-scenarios command surface (10 commands)

Ten scenario packs (48 registered scenarios) and one declarative document corpus sit above the harness, all runnable through the CLI. Two of those packs are the same category judged by different systems: conformance asserts the in-memory double’s vocabulary, conformance-real asserts the real crucible-simulator engine’s, and the CLI routes each to the harness its contracts require rather than to one harness for both.

Integration status

The simulator adapter crate defines the provider-neutral contract scenarios consume, but today it is a deterministic in-repo test double: an in-memory ledger with fixture-derived posture. It exists so the orchestration layer can be built and validated hermetically before the real crucible-simulator repository is wired behind the same contract — which is planned and is what will make conformance claims meaningful.

The prover adapter crate implements the prover/verifier contracts two ways: a fixture-driven [FixtureProver] double (statement and state binding over proof-posture fixtures, needed by negative and adversarial scenarios that require a prover able to emit an invalid/tampered proof on demand) and a [RealProver] adapter over the actual crucible-prover service machinery — request preflight against the circuit ABI, provider dispatch, versioned proof envelopes, and a mandatory local verification round-trip — compiled from the crucible-prover repository via a pinned revision and run hermetically in CI on crucible-prover’s deterministic mock backend. Runs over the fixture double exercise orchestration and binding semantics; runs over the real adapter exercise the genuine prover service contract. Neither is cryptographic or on-chain evidence: real UltraHonk/bb proving is a heavyweight opt-in in crucible-prover itself and is exercised there in dedicated CI.

The Soroban adapter exists and is isolated: it defines the contract surface, operation→call translation, and event interpretation, unit-tested hermetically, but is not yet wired to a live deployment client. The testnet adapter exists and is explicitly opt-in: hermetic configuration, rolling, and execution surfaces; ordinary CI never touches a network (spec §30). Scenarios that cannot run honestly in the current environment skip deliberately rather than mis-execute.

Dependency direction stays approximately: scenario-core → runner → scenario implementations, with adapters consuming core’s stable interfaces and reporting consuming results. No crate depends on private internals of another Crucible repository.

Testing model and oracles

Every scenario conceptually follows: 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.

Expected results are derived from declared inputs and protocol rules, never by calling the same internal state-transition function under test. Layered oracles are used:

explicit expected result,
protocol invariant,
independent state comparison,
cross-component comparison.

A single successful return value is never sufficient evidence for an important scenario.

Keyboard shortcuts

Crucible