The wallet role is where the Z00Z no-reusable-public-balance-account model becomes concrete. Public settlement can verify roots, proofs, replay artifacts, and checkpoint evidence. It should not become the primary public place where ownership meaning, receiver history, decrypted amounts, and local labels live. Those belong to the wallet until a specific flow chooses to publish or disclose bounded evidence.
The wallet role is an integral part of the Z00Z architecture. The
z00z_wallets crate is the project’s open-source Rust reference and
demonstration implementation of that role. It illustrates the current API
shape and expected capabilities; it does not require every compatible wallet
to use the same language, modules, storage model, user interface, or internal
architecture.
Reference Implementation And Interoperability
Anyone may implement a custom Z00Z wallet. They may also fork, modify, extend,
or redistribute z00z_wallets under its MIT OR BSD-3-Clause license. A custom
wallet is interoperable when it implements the published network-facing
contract relevant to its workflows, including canonical transaction and
package encodings, cryptographic domains and version rules, replay and policy
evidence, and the validation conditions required for settlement.
The interoperability boundary is protocol behavior and accepted data, not a
copy of the reference crate’s physical program structure. The current Rust
crate exports reference types and helpers such as TxPackage,
ClaimTxPackage, digest builders, and verification paths. Those exports are
implementation evidence, but they do not imply that every wallet-facing Rust
surface is already a permanently stable public SDK contract. Builders should
track the release-specific format and validator definitions they target.
These are wallet-role responsibilities. In a self-custodial flow, the user controls keys, settings, history, backups, receipts, and disclosures and remains responsible for the user’s own conduct and duties. The wallet is not a legal person and does not absorb that responsibility. Z00Z and any custom-wallet or service operator retain duties arising from what they distribute, operate, maintain, or control. Self-custody does not shift those operator duties to the user. See the Compliance Framework for the canonical rule.
User-Configured Jurisdiction Policy Profiles
The network-facing wallet contract does not require one universal legal or compliance configuration. A reference or custom wallet may expose country, regional, business-use, or fully custom policy profiles above the protocol. A user may select a supplied profile, fork its settings, or create a profile for the jurisdiction or region the user intends to follow without changing Z00Z transaction compatibility.
A profile may configure transaction-history retention, receipts, encrypted backups, accounting and tax exports, value or velocity limits, delayed-settlement risk, asset and counterparty warnings, screening inputs, and scoped disclosure templates. The user selects, validates, updates, and applies the profile; keeps local transaction history and supporting records; provides disclosures required from the user by competent authorities; and remains responsible for legal, financial, tax, reporting, and duties applicable to the user’s own conduct. A profile cannot certify compliance, override a prohibition, or transfer that responsibility to wallet software. The actor supplying or maintaining a profile remains responsible for its claims, updates, security, disclosures, and controls applicable to the functions it operates.
The reference crate currently provides spend-policy validation, a canonical file-backed transaction-history store, receipts, and backup/export building blocks. It is not represented as shipping persisted jurisdiction profiles or a maintained legal-rule catalogue for every country. Builders may implement such profiles above those local-data surfaces, but product copy must distinguish the implemented mechanism from current jurisdiction-specific legal review.
Wallet Responsibilities
The wallet role covers more than keys. It covers the local interpretation of spendable objects, the preparation of transfer material, the receiver experience, disclosure decisions, backup warnings, and publication-facing behavior. A server can assist with routing or publication. It should not become the controller of user possession.
Wallet-Local Possession
Wallet-local possession means the holder controls private material and interprets committed public objects locally. A public observer may see settlement leaves, commitments, proof bytes, deltas, and checkpoints. The wallet decides which leaves are relevant, how they map to local inventory, and which secrets are needed to spend or disclose them.
This model rejects the ordinary account-chain assumption that the public ledger is the best place to ask “what does this user own?” A wallet may present a balance-like view for usability, but that view is derived. The protocol works through objects, packages, roots, and checkpoints.
| Wallet-local item | Why it stays local |
|---|---|
| Receiver material | Reuse can weaken receiver privacy |
| Ownership recognition and scan results | Public state should not reveal holder meaning |
| Decrypted payloads and memos | They may contain user or business context |
| Openings and private proof inputs | They are sensitive authorization material |
| Local labels and history | They can reconstruct the user’s economic graph |
| Draft packages | They may reveal intent before publication |
Good wallet APIs should make local possession explicit rather than hiding it behind a public-account metaphor.
Receiver Surface
Z00Z receive flows should be receiver-native, not account-native. A ReceiverCard is a receiver-facing routing and approval input. A PaymentRequest is a receive-intent object for a scoped handoff. Neither should be described as a permanent public account address.
A wallet should help users create fresh, scoped receive material when possible. It should warn when reuse becomes risky. It should distinguish a request that is well-formed from a request that is final. It should also keep transport details separate from trust. A QR code, deep link, file, or API payload can carry request material, but the transport is not the settlement boundary.
The receiver UX should answer:
- What is being requested?
- Which asset, voucher, right, or policy family is involved?
- What expires or can be rejected?
- Which parts remain wallet-local?
- When does checkpoint settlement become authoritative?
If the UX cannot answer those questions, it is probably importing an account-chain mental model.
Payment Requests And Package Assembly
The wallet prepares packages and request responses before public finality. It may build a TxPackage, claim-related package, voucher transfer, or future right transition. That local package can be checked, shared, or submitted, but it is not final settlement until the checkpoint boundary accepts the transition.
For builders, that means wallet APIs should expose state names carefully:
| State | Safer label |
|---|---|
| Drafted by wallet | Prepared locally |
| Shared with counterparty | Presented or offered |
| Accepted by receiver | Locally accepted or validated |
| Submitted for publication | Published or handed off |
| Included in checkpoint artifact | Checkpointed |
| Reflected in accepted roots | Settled |
This state vocabulary protects users from confusing convenience with finality. It also protects support teams from promising reversal, recovery, or settlement control that the protocol does not give them.
Scoped Disclosure Controller
A wallet implementation should provide a disclosure controller that supports user-directed disclosure where lawful and bounded disclosure required by a valid contractual, audit, regulatory, authority, or legal process. This is a user tool: the user decides which lawful disclosure to make and is responsible for preserving and providing records required in the user’s jurisdiction. Every request remains limited by authority, purpose, data possession, and the Compliance Framework.
Useful wallet disclosure modes include:
| Mode | Purpose |
|---|---|
| Present | Show a bounded proof or receipt to a counterparty |
| Redacted | Export only the fields needed for the current review |
| Selective audit | Produce an evidence package for an enterprise or auditor |
| Liability reveal | Reveal domain-specific evidence under proven conflict or policy trigger |
| Unavailable | Refuse exports that would over-disclose wallet history; never export seeds, private keys, or unrelated history, and use a narrower lawful disclosure when one is required and technically available |
The wallet should not use “auditable” as a synonym for “export everything.” A broad export can become a more complete ownership ledger than public settlement itself.
Backup And Recovery Boundary
Backups are not only a UX feature. They are a security boundary. A backup may include receiver material, recovery metadata, suite generation, scan information, encrypted packs, labels, and local history. Losing it can make objects hard to recognize. Leaking it can expose more than public settlement ever did.
The post-quantum migration paper adds another backup rule: recovery files must carry enough suite metadata for wallets to know whether recovered material belongs to a legacy, hybrid, or migration lane. A recovery process should not silently restore a user into a deprecated lane without warning.
Wallet docs and support copy should avoid three bad promises:
- “Support can restore your funds” when possession is self-custodial.
- “The server can recover your wallet history” when history is wallet-local.
- “Migration is automatic forever” when suite cutoff and rewrap require explicit evidence.
Safer wording says the wallet can help users maintain backups, warn about suite generation, and explain recovery limits.
Publication Client, Not Finality Authority
A wallet may submit packages, retry publication, show pending state, and observe provider or checkpoint status. It should not present itself as finality authority. Finality belongs to checkpointed settlement evidence.
This is especially important when a wallet integrates with relays, aggregators, bridges, lockers, or third-party services. Those services may provide admission, ordering, custody, redemption, or operational context. They do not redefine Z00Z settlement truth. The wallet UI should make that distinction visible enough that a pending or accepted service message is not mistaken for settled value.
What Wallets Must Never Ask Servers Or Support To Do
| Request | Why it is wrong |
|---|---|
| “Tell me my full private ownership graph” | The server should not own wallet-local possession meaning |
| “Decrypt my payloads for support” | That over-discloses sensitive wallet material |
| “Reverse settled state by customer-service action” | Checkpointed settlement is not a support ticket |
| “Turn every receiver request into a reusable public address” | That breaks receiver-native privacy |
| “Export all history for a narrow audit” | Disclosure should be bounded and purpose-specific |
| “Hide that this is only target architecture” | Developer docs must keep maturity language honest |
These are product requirements, not just engineering preferences. They preserve the no-reusable-public-balance-account architecture and the legal/privacy boundary around software designed for user-controlled possession.
Read Next
Continue to Payment Requests for receiver intent flows, Crypto Facade for proof and migration boundaries, and Wallet Local Possession for the protocol-facing explanation.
Evidence and Further Reading
- Main Whitepaper sections 3 and 5 define canonical objects, wallet-local possession, offline ownership, wallet responsibilities, and no-account settlement framing.
- Main Whitepaper appendix D defines operator and recovery boundaries that prevent wallet support from becoming finality authority.
- Smart Cash sections 4 through 8 define smart cash, client-side FSM objects, public settlement surfaces, proof boundaries, rights, fee objects, liability objects, and supported object families.
- Privacy Threat Model And Metrics section 7 defines wallet and UX requirements, safe defaults, and privacy QA hooks.