RPC

RPC carries evidence; it does not create settlement authority. It can carry requests, responses, errors, notifications, and evidence references. In Z00Z terminology, an RPC endpoint may help a wallet submit a package, ask a watcher for status, query a content or node surface, or retrieve proof material. The authority still comes from canonical objects, accepted roots, checkpoint artifacts, and verification rules.

The current workspace includes network-facing crates, but it does not yet publish one complete generated public Z00Z protocol RPC catalog. The live local surfaces are the workspace network crates, node crate, manifests, and tests. The RPC guidance therefore describes design discipline for future protocol implementations while naming the repository surfaces that exist today.

Current Repository Scope

The current workspace scope is concrete, but narrower than a full public RPC program. The z00z_networks/rpc and onionnet crates prove that transport surfaces exist. The node crate proves that operator-facing entrypoints exist. None of that yet implies a stable settlement API, wallet API, or public method registry that downstream integrators should treat as finalized.

The transport crates are also not by themselves a finished public RPC program. They are relevant because they prove live implementation lanes, not because they already imply a full stable method catalog, auth story, or operator-facing API contract.

Request and Response Shape

Future protocol RPC should use explicit message shapes. The JSON-RPC 2.0 specification is a useful external baseline because it defines a request object with a protocol version marker, method name, optional parameters, and optional identifier; it also distinguishes responses, errors, notifications, and batches. Z00Z does not need to copy every JSON-RPC convention blindly, but it should keep the same discipline: a caller must know which method is being requested, which parameters are accepted, and whether a response is expected.

RFC 8259 is the JSON data-interchange baseline. It matters because protocol messages should not depend on ambiguous parser behavior. Future RPC surfaces should define numeric ranges, string encodings, binary encodings, null handling, array ordering, object key expectations, and canonicalization rules where a message becomes evidence. A JSON payload that is harmless for a status UI may be unsafe as a signed or hashed protocol object unless its serialization rules are stable.

The transport boundary is the middle of the diagram, not the right side. Settlement truth must be verified after transport.

Validation Boundary

Every future RPC method should validate before it touches state. Validation includes method names, payload structure, version identifiers, parameter types, object domains, length limits, encoding constraints, and replay-sensitive fields. A request that cannot be parsed deterministically should fail closed before any settlement adapter sees it.

Validation also needs to preserve the difference between syntactic acceptance and semantic acceptance. A request can be valid JSON and still be invalid for Z00Z because it targets the wrong network, references an unsupported object type, omits a domain separator, attempts to reuse a nullifier, or asks the service to reveal data it should not have. Error messages should explain the class of failure without exposing secrets or unnecessary private context.

For JSON-RPC-style designs, errors should be predictable and machine-readable. The error response should identify invalid request shape, missing method, invalid parameters, unauthorized access, unsupported maturity, rate limiting, internal failure, and protocol rejection as separate classes. Avoid returning raw exceptions, stack traces, private paths, wallet identifiers, or user behavioral data.

Authentication and Authority

Authentication proves who can use an endpoint. It does not prove that the requested state transition is valid. A wallet owner, service operator, watcher, or integrator may authenticate successfully and still submit an invalid package. Future endpoint implementations should therefore keep authentication and protocol verification as separate gates.

Authorization should be capability-based where possible. A watcher query, publication request, support export, and wallet recovery action do not need the same powers. An endpoint that can publish data should not automatically read private wallet metadata. A status endpoint should not become an administrative control plane. A useful-work evaluator should not become the source of token issuance authority unless a separate settlement or governance process accepts its evidence.

The Main Whitepaper’s object vocabulary helps here: a TxPackage or ClaimTxPackage is a protocol artifact with a specific role, not a generic RPC body. RPC should move it across a boundary, validate its envelope, and hand it to the correct verifier. It should not reinterpret object semantics to make transport easier.

Privacy-Sensitive Fields

The Privacy Threat Model warns that privacy failures often come from metadata, telemetry, timing, support workflows, and user-interface defaults rather than from a single cryptographic break. RPC design must therefore minimize sensitive fields and make disclosure explicit. A wallet request can reveal network timing, object interest, recovery behavior, device details, IP-derived context, or repeated identifiers even when the payload is encrypted.

Future RPC surfaces should avoid stable cross-context identifiers unless they are required by protocol rules. If a request needs a correlation identifier, it should be scoped and short-lived. If a service needs logs, it should define log retention and redaction. If support tooling needs evidence, it should prefer selective disclosure packages over full wallet exports. If rate limiting needs abuse signals, it should avoid turning those signals into a tracking layer.

Notifications are especially sensitive. In JSON-RPC, a notification does not expect a response. In a wallet protocol, one-way messages can still leak state or trigger irreversible local actions. Treat notifications as transport events, not settlement events. They should not silently spend, reveal, rotate, or publish without a separate wallet or protocol decision.

Error Hygiene

Error hygiene is a security feature. A good RPC error helps the caller repair their request without exposing private material. Avoid errors such as “failed” when the caller can safely know that the object type is unsupported. Avoid errors that include raw commitments, private notes, stack traces, local file paths, server secrets, or full request bodies. Keep protocol rejections distinguishable from service outages and authentication failures.

Future implementations should test error behavior. Invalid JSON, oversized payloads, duplicate identifiers, unknown methods, malformed proof references, wrong network identifiers, replay attempts, unauthorized calls, and privacy redaction cases should each have deterministic outcomes. Website verification cannot prove those cases today; protocol implementation tests must.

Versioning and Maturity Labels

Every future RPC method should expose version and maturity explicitly. A method that exists only on a testnet, local simulator, or operator-only service should say so in its schema and docs. A response that describes a package as submitted, queued, published, available, soft_confirmed, checkpointed, challenged, or settled should define the evidence behind that label. Without maturity labels, UI code and integrators tend to flatten the pipeline into a single “success” state.

Versioning also protects replay and upgrade paths. A client should know whether it is sending a request for the current object schema, an older compatibility schema, or a future unsupported schema. If serialization changes, error responses should identify unsupported version rather than silently coercing the payload into a shape the verifier never intended.

Documentation Checks

Review every endpoint, method name, and command against source files. The safest live anchors are manifests, source crates, tests, and CLI entrypoints. Documentation that lists production node methods, wallet methods, or settlement calls must mark them as future API concepts unless the workspace proves them. If a future implementation adds generated schemas or stable method catalogs, update the cited sources and remove target-only language where tests prove behavior.

Read Next

• Storage And HJMT for roots, proof boundaries, and replay protection.
• Runtime Services for service roles that should not become authoritative.
• API Reference for the current and future API layer map.

Evidence and Further Reading

• Main Whitepaper sections 3-4 for protocol object and rollup authority boundaries.
• Privacy Threat Model And Metrics sections 7 and 10 for wallet UX, telemetry, simulation, and privacy validation guidance.
• github.com/z00z-labs/z00z, root Cargo.toml, and the crates/z00z_networks/rpc, crates/z00z_networks/onionnet, and crates/z00z_rollup_node surfaces define the live transport and integration lanes referenced here.
• JSON-RPC 2.0 Specification: https://www.jsonrpc.org/specification.
• RFC 8259 JSON: https://datatracker.ietf.org/doc/html/rfc8259.