Core Protocol API

Builders need an implementation-shaped mental model, not a generated reference for every exported workspace function. The current z00z repo can prove real crates, manifests, tests, bins, and corpus content. The protocol API families below are corpus-backed architecture that keeps implementation surfaces separate.

The core design starts from a no-reusable-public-balance-account premise. Public settlement should not become a reusable balance table. Wallets can know ownership, prepare packages, and interpret private rights locally; public state should see committed objects, typed paths, replay artifacts, and checkpoint evidence.

The API Families

A future core implementation should expose API boundaries around seven families:

None of those families should become one giant doEverything() API. Z00Z’s safety comes from making boundaries explicit.

Conceptual Surface Diagram

The diagram is deliberately conceptual. It teaches the boundary between wallet preparation, package validation, checkpoint finality, and state roots. It does not assert that these exact labels are already frozen as exported public module names in the current workspace.

For implementation planning, read each box as a responsibility seam. A concrete project might choose different package names, modules, or crate boundaries, but it still needs a way to keep wallet-local possession, package transport, validation, checkpoint evidence, and state roots from collapsing into one ambiguous API.

Object Model

The object model is the first API boundary. Asset is final value. Voucher is conditional value. Right is authority without value. The terminology paper also names live structural settlement terms such as AssetLeaf, RightLeaf, VoucherLeaf, SettlementLeaf, and SettlementPath. A developer API should preserve those distinctions because each object answers a different question.

This is where many fake API designs fail. They start by asking for account balances and token transfer endpoints. Z00Z needs object inventory, possession, package construction, policy classification, and checkpoint evidence instead.

Commitments And Roots

Commitments are the API layer that keeps public state narrow. A committed amount is not a plaintext balance. A policy hash is not a mutable rule document. An action root is not an off-chain operator promise. A settlement path is the place where committed state lives or disappears under a checkpointed transition.

The root boundary is equally important. A public root is useful only because it binds a precise state view and can be checked against typed deltas and checkpoint artifacts. It is not a marketing anchor. It is not proof that every local wallet story is true. Developers should design root APIs so callers can ask specific questions: what root was used, which paths were consumed, which leaves were created, which proof bytes were checked, and which replay artifacts were accepted or rejected.

Checkpoints And Validation

Checkpoints are the public finality boundary. A wallet-prepared package can be useful before settlement, but it is not final state. An aggregator can admit or order work, but admission is not settlement. A validation API should make those states impossible to confuse.

At minimum, a checkpoint-facing implementation needs to separate:

Claims such as “payment sent” or “right accepted” must identify the state they mean. User experience can be friendly, but developer APIs need precise states.

Policy And Action APIs

The Assets/Rights/Vouchers paper gives the cleanest policy split. Native cash should have a fixed CashPolicy. Vouchers may carry a bounded VoucherPolicy and committed ActionPool. Rights may carry a RightPolicy or dedicated policy commitments for transition, revocation, challenge, disclosure, and retention behavior. Those policy names are semantic contract surfaces; the page must not imply that every current crate or local file already exports exactly those type names.

The API lesson is that policy should compile into verifiable evidence. A wallet can assemble a package and gather signatures. A validator can check state inclusion, policy commitments, action membership, value conservation, and delta correctness. An external service can attest or maintain a registry only when that trust boundary is explicit.

Disclosure And Evidence

The core API should not make privacy depend on silence or vibes. It needs evidence channels. Ordinary public settlement should expose roots, deltas, proofs, and replay artifacts. Wallet-local possession should hold secrets, decrypted payloads, labels, and private decision history. Selective audit should export a bounded evidence package for a specific reviewer. Liability reveal should stay tied to a fraud or dispute domain, not become public transparency by default.

This is why a future developer API should distinguish “export settlement evidence” from “export wallet history.” They are not the same operation, and conflating them would undo the protocol’s privacy story.

Live Repo Boundary

In the live z00z repository, you can inspect the owning crates, tests, manifests, and verification scripts that back parts of these API families. You can verify the workspace with cargo gates and the shared full_verify.sh sweep. Those sources cannot prove a full protocol API surface by themselves. The local claim is narrower: the conceptual map keeps implementation and documentation boundaries coherent. Current code evidence establishes crate ownership, executable paths, and tested behavior; it does not establish API stability, complete coverage, or external compatibility beyond those surfaces.

Read Next

Continue to Crypto Facade for cryptographic boundaries, Wallet SDK for wallet-local possession, and Payment Requests for receiver intent flows.

Evidence and Further Reading

• Main Whitepaper sections 3 and 4 define canonical state objects, cryptographic proof discipline, checkpoints, rollup ordering, publication, and verification boundaries.
• Assets, Rights, And Vouchers sections 3 through 9 define the Asset, Voucher, and Right triad, policies, action semantics, receiver safety, and settlement storage split.
• Corpus Terminology And Abbreviations Reference section 3 defines canonical protocol and wallet terms such as SettlementLeaf, SettlementPath, Checkpoint, TxPackage, ReceiverCard, and PaymentRequest.
• github.com/z00z-labs/z00z, root Cargo.toml, and the z00z_core, z00z_storage, z00z_wallets, and z00z_rollup_node crate manifests are the live repo anchors relevant to the conceptual surface described here.