Simulator · Z00Z

A simulator should prove protocol flows, not merely animate a user interface. For Z00Z, simulation is the bridge between the whitepaper corpus and future implementation tests. It lets builders exercise actors, state transitions, failure branches, evidence outputs, privacy checks, and documentation claims before a production node or wallet surface exists. A good simulator answers: “Under these inputs and adversarial conditions, what evidence should exist, and which claim is allowed to be made?”

The current workspace ships a protocol simulator surface: the z00z_simulator crate, scenario binaries, tests, and examples. The crate does not prove every target validation story in the corpus. Simulator claims need local evidence; the remaining scope stays future hardening.

Simulation Goal

The Use Cases paper frames scenarios through architectural lenses: wallet-local possession, delayed settlement, rights mobility, policy-bound objects, selective disclosure, and service separation. A simulator should turn those lenses into executable scenarios. Each scenario should define actors, initial state, actions, expected evidence, success criteria, privacy expectations, and failure branches.

The purpose is not to show a happy-path demo. A demo can click through a mock flow without proving anything. A simulator should detect when a package is accepted too early, a service becomes authoritative, a privacy field leaks, a right is replayed in the wrong context, a useful-work reward lacks evidence, or a documentation claim overstates maturity.

flowchart TD A[Scenario definition] --> B[Actors and roles] A --> C[Initial state] A --> D[Actions and timing] D --> E[State transition model] E --> F[Expected evidence] E --> G[Failure branches] F --> H[Claim validation] G --> H H --> I[Docs and implementation feedback] style A fill:#ECEFF1,stroke:#546E7A,stroke-width:1px,color:#263238 style B fill:#ECEFF1,stroke:#546E7A,stroke-width:1px,color:#263238 style C fill:#ECEFF1,stroke:#546E7A,stroke-width:1px,color:#263238 style D fill:#ECEFF1,stroke:#546E7A,stroke-width:1px,color:#263238 style E fill:#ECEFF1,stroke:#546E7A,stroke-width:1px,color:#263238 style F fill:#ECEFF1,stroke:#546E7A,stroke-width:1px,color:#263238 style G fill:#FFE0E0,stroke:#D32F2F,stroke-width:1px,color:#B71C1C style H fill:#F3E5F5,stroke:#8E24AA,stroke-width:1px,color:#4A148C style I fill:#ECEFF1,stroke:#546E7A,stroke-width:1px,color:#263238

Scenario Inputs

A useful scenario file should be explicit. It should name the scenario family, source references, actors, object types, network context, maturity assumptions, privacy assumptions, and expected outputs. It should also declare what is simulated versus implemented. For example, a wallet-local possession scenario may simulate cryptographic proofs until protocol code exists, but it should not mark the flow as cryptographically verified.

Core input categories include:

Actors: wallet holder, receiver, publisher, watcher, validator, aggregator, useful-work evaluator, support operator, governance actor, and external integrator.
Objects: AssetLeaf, right, voucher, payment request, claim package, work package, checkpoint artifact, or disclosure package.
State: wallet-local payloads, committed roots, service queues, DA records, maturity labels, disputes, and recovery state.
Rules: replay scope, validation policy, privacy redaction, service authority, useful-work scoring, and governance gates.
Evidence: proof references, logs, receipts, checkpoint links, disclosure artifacts, failure classifications, and docs-source citations.

The Use Cases appendix B can guide scenario selection. It emphasizes selecting families that cover diverse risks rather than only the most visually appealing examples. A simulator should include high-value, high-risk, and boundary scenarios.

Actors and Service Roles

Actors should be modeled by capability, not by vague labels. A wallet can authorize, hold private context, prepare packages, and decide disclosure. A publication service can relay and retry. A watcher can observe and warn. A validator can check rules. A useful-work evaluator can score evidence under a policy. A support operator can request scoped evidence. An external integrator can supply or consume bounded data.

Capabilities should be constrained. A watcher should not spend. A publication service should not finalize. A support operator should not receive full wallet exports by default. A useful-work evaluator should not mint rewards directly. If the simulator permits a role to exceed its boundary, the scenario should fail or mark the behavior as a deliberate attack branch.

This role modeling is a direct guard against concept drift. As docs pages grow, it is easy to write “the service verifies” when the intended meaning is “the service transports evidence to a verifier.” Simulated roles force the page to name the actual authority.

State and Failure Branches

State should be visible enough for tests. A simulator should capture initial state, intermediate state, final state, and rejected state. It should record which data is canonical, which data is wallet-local, which data is service-only, and which data is evidence for a later verifier. That separation matters because Z00Z intentionally keeps private wallet payloads distinct from committed state.

Failure branches are not optional. Each scenario should include at least one negative path when the source material implies a risk. Examples include wrong network identifier, replayed package, missing DA record, invalid proof, privacy over-disclosure, unsupported maturity claim, conflicting right transfer, stale receiver material, unavailable watcher, and useful-work evidence dispute.

The Main Whitepaper’s section on current versus target architecture is relevant because simulator outputs must not imply that a future component already exists. A failed simulation of a target rollup behavior should not be reported as a generic docs or build failure. Conversely, a passing docs build should not be reported as a passing protocol simulation.

Expected Evidence

Every scenario should define expected evidence before it runs. Evidence can be a root, proof reference, checkpoint artifact, publication record, structured failure, privacy redaction record, user consent event, useful-work evaluation record, or documentation citation. The simulator should compare actual evidence against expected evidence and explain mismatches.

Implementation claims require local anchors. Documentation that names a simulator bin or scenario test must be checked against crates/z00z_simulator/Cargo.toml and nearby source. A claim of a stable public protocol RPC fails unless the workspace proves that interface. A future wallet flow described as target architecture must retain bounded wording.

Privacy Checks

The Privacy Threat Model calls for simulations and tests around wallet UX, telemetry, disclosure, and support behavior. A simulator should treat privacy as an observable property. It should check whether a scenario leaks stable identifiers, raw wallet metadata, recovery material, policy text, timing correlation, or unneeded support artifacts. It should also check that user prompts appear before disclosure-sensitive actions.

Privacy checks need negative cases. A support flow that requests a full wallet export should fail unless the scenario explicitly marks it as unsafe. A status service that publishes wallet-specific timing should fail. A disclosure flow that reveals more fields than the stated claim requires should fail.

Current Repo Validation Path

For this repository today, scenario-driven validation is partly live implementation validation and partly documentation discipline. The simulator crate provides real bins, tests, and examples. Documentation work may add stricter local checks around frontmatter, source anchors, Read Next, evidence sections, and review loops. Those checks improve documentation integrity, while the crate provides real simulator evidence instead of prose alone.

Future simulator implementation should keep adding deterministic test harnesses, fixtures, and scenario schema beside the simulator crate. Those checks should run separately from docs rendering while still feeding corrections back into the public documentation.

Scenario Review Criteria

A scenario is ready only when a reviewer can trace every expected outcome to a source. If the expected outcome is a current workspace behavior, the source should be a local file, manifest, test, or command. If it is a target protocol behavior, the source should be a whitepaper section and the scenario should say that implementation is pending. If the expected outcome is privacy-related, the scenario should name the sensitive field or metadata class being protected.

Reviewers should also check adversarial completeness. A wallet flow should have an invalid or declined authorization branch. A publication flow should have a missing or delayed data branch. A disclosure flow should have an over-reveal branch. A useful-work flow should have a disputed evidence branch. If a scenario has only one successful route, it is probably a demo rather than a simulator test.

Simulator outputs should be versioned with their source assumptions. When a whitepaper section changes, the scenario should be re-reviewed instead of silently inheriting old expectations. This makes simulator evidence useful for docs maintenance as well as implementation planning.

Evidence and Further Reading

Use Cases sections 2-3 and appendix B for scenario lenses, use-case selection, and family scoring.
Main Whitepaper section 12 for current versus target architecture framing.
Privacy Threat Model And Metrics section 10 for privacy simulation and validation expectations.
github.com/z00z-labs/z00z, README.md, and crates/z00z_simulator/Cargo.toml define the live simulator, bin, test, and example surfaces referenced here.