Examples And Tutorials

Examples are useful only when they tell the truth about maturity. A Z00Z example can teach a current workspace workflow, illustrate a target protocol concept, or simulate a future flow. It should not blend those categories into one impressive but misleading tutorial. Builders should always know whether they are running current code, reading a conceptual walk-through, or following a scenario that still needs implementation.

Every example must make its maturity explicit.

The current repository already ships live examples and runnable entrypoints: workspace compile flows, rollup-node CLI inspection, simulator scenarios, wallet binaries, and WASM build scripts. Future examples must keep the boundary visible between those live surfaces and broader corpus-backed target architecture.

What Counts as a Real Example

A real example has four properties:

• It states its maturity: current repo, target architecture, simulation, or future implementation.
• It names concrete files, commands, or source documents that support the tutorial.
• It has an expected outcome that a reader can verify locally or conceptually.
• It avoids implying authority that the demonstrated surface does not have.

For this repository, a current-code example might show how cargo check --workspace validates the tree, how z00z_rollup_node -- --help exposes the current operator contract, how scenario_1 is reached from the simulator crate, or how the wallet crate exposes validation and GUI-facing binaries. A target protocol example might explain how a payment request would move from wallet intent to publication and settlement, but it must label any unimplemented step as target architecture.

Tutorial Composition Flow

The flow starts with scenario selection, not code snippets. The Use Cases paper and appendix B help select examples that exercise important architectural families: wallet-local possession, rights mobility, selective disclosure, policy-bound objects, services, and delayed settlement. A good tutorial suite should cover diverse risk surfaces rather than repeating one easy success path.

Current Repository Examples

Current repo examples should use only files and commands that exist. Good examples include:

• Running cargo check --workspace and explaining which crates are in scope.
• Inspecting cargo run -p z00z_rollup_node -- --help and documenting only the current live CLI contract.
• Inspecting cargo run -p z00z_simulator --bin scenario_1 -- --help and mapping the scenario surface back to its crate.
• Building wallet WASM artifacts with ./scripts/build_wasm.sh --dev and explaining what that proves and what it does not.
• Using crates/z00z_wallets/Cargo.toml to explain live bins, tests, and debug-sensitive features.

These examples should be precise about what they prove. A passing workspace check proves the tree compiles. A CLI help output proves the entrypoint exists. A wallet WASM build proves artifacts can be produced. None of those alone proves full settlement finality, production RPC stability, or the complete whitepaper architecture.

Target Protocol Examples

Target examples can still be valuable. They should be written like design scenarios, not runnable claims. A target wallet example might show the sequence from receiver material to package preparation, publication, watcher status, and settlement maturity. A target storage example might show a key, path, leaf, proof, and root relationship. A target useful-work example might show work evidence, fact consensus, value consensus, reward authorization, and appeal.

Each target step should link to source material in the whitepaper corpus and state what implementation surface is missing. For example: “This step is target architecture until a rollup-node module exposes package intake and tests.” That sentence is more useful than pretending a command exists.

Target examples should also include failure branches. A tutorial that never shows invalid proof, missing data availability, replay, privacy over-disclosure, or unsupported maturity teaches the wrong lessons. Boundary failures are where builders learn the protocol.

Scenario-Based Structure

Use this structure for new tutorials:

1. Scenario and maturity label.
2. Source links from content/whitepapers and local repo files.
3. Actors and roles.
4. Current repo steps, if any.
5. Target architecture steps, if any.
6. Expected evidence.
7. Failure branch.
8. Privacy or authority boundary check.
9. Verification command or conceptual review gate.
10. Read-next links.

This structure prevents examples from becoming isolated snippets. It makes the reader see why the example exists, which authority it uses, and what they can verify.

Source Claim Discipline

Every tutorial step should connect to a source. Local repo steps connect to local files, manifests, tests, or scripts. Protocol steps connect to whitepaper sections. External standards, when used, connect to official specs. If a step has no source, it should either be removed or marked as an open design proposal.

The Main Whitepaper’s current-versus-target framing is the maturity anchor. Use it to keep examples honest. The Use Cases paper is the scenario anchor. Use it to choose examples that cover real product and protocol value rather than only the easiest narrative.

Example Types to Avoid

Avoid examples that:

• Create fake CLI commands for protocol components not present in the repo.
• Treat one crate’s helper surface as the whole protocol API.
• Use generic “mock success” data without naming what is mocked.
• Skip privacy-sensitive fields in wallet, support, or disclosure flows.
• Present soft confirmation as final settlement.
• Collapse useful-work evidence, value judgment, and reward authorization into one service response.
• Use a diagram as proof that implementation exists.

These examples may look friendly, but they create concept drift and make later implementation harder.

Example Review Checklist

Before publishing a tutorial, review it with the same questions a builder will ask while copying it:

• Which files or commands can I run today?
• Which steps are conceptual only?
• Which whitepaper sections justify the protocol terms?
• Which output proves the step succeeded?
• Which privacy or authority boundary could be misunderstood?
• Which failure branch should I test before trusting the happy path?

If a tutorial cannot answer those questions, it needs more structure. The fix is usually not more prose; it is clearer maturity labeling and tighter evidence links. For current-code examples, the expected output should be a command result, file change, build result, or rendered docs behavior. For target architecture examples, the expected output should be a conceptual artifact such as a package, proof reference, maturity label, or evidence record, with the implementation gap stated directly.

Maintaining Examples

Examples need maintenance as the repo changes. When a local path changes, update the tutorial instead of leaving a stale command. When a target component becomes implemented, replace conceptual wording with source-linked implementation wording. When an implementation is removed or postponed, downgrade the example back to target architecture. Do not keep old examples because they read well; keep only examples that point to current evidence.

A final editorial pass should also scan examples for accidental overclaims. The highest-risk phrases are “run the node,” “call the protocol API,” “open the WASM wallet,” “settled,” “final,” “verified,” and “private by default.” Each phrase is acceptable only when the example names the authority and evidence behind it.

Reader-Friendly Formatting

User-friendly examples should be explicit without being noisy. Start with a short goal, show prerequisites, label current versus target steps, then show expected evidence. Use diagrams when they clarify boundaries, not as decoration. Keep long command blocks limited to commands that actually exist. For target flows, prefer structured pseudo-steps over fake terminal output.

Good examples also explain what not to conclude. After a workspace or CLI example, say that it proves a live repo surface, not the entire protocol architecture. After a target payment flow, say which components are missing locally. That negative space prevents the tutorial from becoming misleading. It also keeps future implementation tickets smaller, clearer, and easier to verify against the original source claim. Readers should never have to infer maturity.

Read Next

• Simulator for scenario validation and failure branches.
• API Reference for current and future API layer boundaries.
• Verification And Tests for local gates and review loops.

Evidence and Further Reading

• Use Cases section 3 and appendix B for use-case selection, scenario families, and scoring guidance.
• Main Whitepaper section 12 for current versus target architecture framing.
• github.com/z00z-labs/z00z, README.md, and root Cargo.toml define the live workspace commands and structure used by current-code examples here.
• crates/z00z_rollup_node/Cargo.toml, crates/z00z_simulator/Cargo.toml, and crates/z00z_wallets/Cargo.toml define the live node, scenario, wallet, feature, and bin surfaces used as tutorial anchors here.
• ./.github/skills/z00z-full-verify-gate/scripts/full_verify.sh and ./scripts/build_wasm.sh in the z00z repo define the main broad verify and WASM example paths referenced here.