RPC is a transport boundary. It can carry requests, responses, errors, notifications, and evidence references, but it does not create settlement authority. 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 website repository does not expose a production Z00Z protocol RPC. The live local API surface is limited and explicit: src/app/api/dev/content-version/route.ts returns a development-only content version response and returns 404 outside development. The docs content pipeline lives under src/lib/content/. This page therefore describes RPC design discipline for future protocol implementations while naming the real repo surfaces that exist today.

Current Repository Scope

The only concrete route handler in the current docs context is a development helper. It is useful because it shows the kind of discipline future endpoints should preserve: explicit environment gating, a narrow response shape, and cache-control headers. It is not a settlement API, wallet API, node API, or public protocol gateway. Builders should not infer that /api/dev/content-version is a model for live asset submission, proof exchange, or wallet recovery.

The content modules are also not protocol RPC. src/lib/content/docs.ts reads Markdown files and frontmatter, builds domain navigation, and returns rendered page content. src/lib/content/markdown.ts configures Markdown rendering. src/lib/content/html.ts sanitizes HTML and controls script behavior. These are website internals. They are relevant because they prove the documentation system has a real code surface, not because they implement protocol transport.

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

When reviewing an RPC doc, check every endpoint, method name, and command against source files. Today, the only local route in this scope is the development content-version route. Any page that lists production node methods, wallet methods, or settlement calls must mark them as future API concepts. If a future implementation adds route handlers or generated schemas, this page should be updated to cite those files and remove the 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.
• src/app/api/dev/content-version/route.ts for the current repo’s explicit development-only route handler.
• src/lib/content/ for the current website content-loading surface.
• JSON-RPC 2.0 Specification: https://www.jsonrpc.org/specification.
• RFC 8259 JSON: https://datatracker.ietf.org/doc/html/rfc8259.