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?”
This website repository does not ship a protocol simulator. It ships content, configuration, rendering, and verification for the docs site. Therefore, this page defines simulator requirements as target architecture and ties docs claims back to local evidence where possible. The current repo can validate that docs pages cite sources, build, render, and pass search coverage. It cannot validate settlement correctness, wallet cryptography, data availability, useful-work evidence, or cross-chain behavior.
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.
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 failing website build. Conversely, a passing website 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.
For documentation claims, evidence includes local anchors. If a docs page says
npm run verify is the local verification wrapper, the simulator or docs-check
can compare that claim to package.json and scripts/verify.sh. If a page says
the website has a public protocol RPC, the check should fail because the current
repo only exposes a development content-version route in this scope. If a page
says a future wallet flow is target architecture, the check should confirm that
the wording is bounded.
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 mostly documentation
validation. npm run verify invokes scripts/verify.sh, which runs lint,
search coverage, and build. Phase 002 adds stricter local checks around
frontmatter, word counts, source anchors, Read Next, evidence sections, and
review loops. Those checks improve documentation integrity but are not a
protocol simulator.
Future simulator implementation should add its own deterministic test harness,
fixtures, and scenario schema. It should run separately from website rendering
while still feeding docs corrections back into content/docs.
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 website behavior, the source should be a local file 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.
Read Next
- Examples And Tutorials for turning scenarios into tutorials without overclaiming maturity.
- Verification And Tests for local docs gates and future protocol test separation.
- Runtime Services for actor boundaries.
Evidence and Further Reading
- Use Cases Whitepaper 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.
package.jsonandscripts/verify.shfor the current docs repository verification path.