OnionNet is Z00Z’s target anonymous-ingress fabric. Its role is transport and runtime ingress privacy, not settlement authority. It aims to move live topology authority out of discretionary committees, let clients own route construction, keep membership auditable, preserve replay discipline, and prevent transport operators from learning canonical payload meaning where the double-envelope contract can be frozen safely.

This repository does not ship OnionNet. The OnionNet whitepaper itself says the design remains implementation-blocked until several contracts are precise: public-state derivation, witness distribution, replay binding, ingress-recipient confidentiality, challenge evidence, anti-griefing, low-load privacy, and any break-glass authority. This page therefore describes bounded target behavior, not a deployable anonymity claim.

Route Ownership and Boundary

The important move is that the client constructs and validates the route. A bridge or resolver should not hand the client an unverifiable end-to-end path. Public membership is visible enough for auditability, while live adjacency and route intent remain bounded.

Double-Envelope Flow

The double-envelope model matters because generic onion routing often makes the exit the place where transport privacy ends and semantic visibility begins. OnionNet’s target pushes semantic visibility closer to a runtime ingress seam.

Membership and Route Construction

OnionNet separates membership from activation. A node can be registered, probationary, eligible, active, demoted, revoked, or slashed. Activation should be derived deterministically from public inputs such as finalized randomness, eligible membership roots, and policy commitments. That removes hidden topology selection from ordinary operator discretion.

Route construction depends on witness distribution. The client needs enough authenticated public structure to build a route without revealing route intent. If witness lookup is too narrow, lookup patterns can leak. If public topology is too broad, endpoint privacy collapses. The whitepaper therefore treats witness distribution as a central contract, not an optimization.

Transport Roles

OnionNet transport roles include bridge ingress, edge transition, relay strata, exits, and runtime-adjacent decryptors. Each role should learn only what it needs. Bridges bootstrap access. Relays forward hop-local packets. Exits remove the transport wrapper. Runtime ingress handles the narrow approved handoff. Ordering, DA, settlement, business logic, and validator truth stay outside OnionNet.

The Tor specifications are useful external references because they document real onion-routing protocol behavior and hidden-service/rendezvous concepts. They are not Z00Z specifications. The Tor spec site notes that the documents describe how Tor works and are maintained as living protocol specifications. The Tor protocol specification says it aims to specify current Tor behavior, while the rendezvous specification describes hidden service version 3. Z00Z should cite those pages as comparative transport references, not as evidence that OnionNet is implemented here.

Replay Discipline

Replay discipline is a core OnionNet requirement. The inner envelope should be bound to transport context: version, epoch, compatibility generation, traffic class, ingress-recipient key identifier, ciphertext size class, expiry, and canonical replay tag. Without that binding, a payload can escape the route context it was meant to inhabit.

Packet classes also matter. The whitepaper keeps a taxonomy such as data, cover, loop, and control. Packet geometry, padding, queue behavior, and replay state are part of the anonymity contract. They are not merely performance details.

Low-Load Privacy

Sparse traffic is a privacy problem. OnionNet should not pretend anonymity holds when route diversity collapses. The target behavior is fail-closed or contracted operation: fewer live lanes, thicker anonymity sets, larger batching windows where safe, cover floors, loop traffic, or explicit delay. A status page should not say “private” when the privacy floor is not met.

This is a direct non-claim. OnionNet does not promise perfect anonymity against a fully global observer. It does not promise zero public membership metadata. It does not promise unconditional permissionless admission without Sybil cost. It does not promise zero-latency behavior under sparse load.

Safety Gates

Safety gates include public-state contract validation, witness freshness, route diversity, replay binding, ingress-recipient confidentiality, challenge evidence, anti-griefing, and low-load privacy floors. If any gate cannot be validated, OnionNet should refuse, contract, re-probe, or delay rather than forwarding best-effort traffic that weakens privacy.

Transport-Layer Non-Claims

Transport privacy is not settlement privacy by itself. OnionNet can hide route origin and reduce exit-visible payload meaning, but settlement privacy also depends on wallet-local possession, selective disclosure, commitment design, telemetry, support behavior, and public status display. A privacy ingress layer does not make every downstream claim private.

Comparison Discipline

Tor references should be used carefully. Tor’s specification corpus documents the Tor protocol and onion service behavior; it does not define OnionNet. The useful comparison is architectural: onion routing, relay roles, hidden-service style rendezvous concepts, and the need for precise protocol documents. Z00Z should not imply that inheriting Tor vocabulary automatically gives OnionNet Tor’s properties, implementation maturity, or threat model.

The safe way to compare is to state the boundary. Tor is an implemented network with its own specifications and compatibility history. OnionNet is a Z00Z target design for runtime-bound ingress whose contracts remain unfrozen. A future implementation may use Sphinx-compatible ideas, QUIC, TLS or WebSocket bridge ingress, Tor-based ingress, or other carriers, but all carriers must terminate into the same normalized packet and replay discipline.

Implementation Blockers

Before OnionNet can be presented as deployable, several blockers need source and tests: deterministic active-set derivation, witness bundle distribution, route diversity validation, replay-state storage, inner-envelope AAD schema, key separation, challenge proofs, anti-griefing, low-load privacy simulation, and break-glass governance. If any of those are missing, docs should say target architecture.

These blockers are not administrative. They decide whether route ownership, control-plane trust reduction, and exit-visible payload reduction are real. Until then, a docs page can teach the design but must not sell a guarantee.

Privacy Floor Review

A future OnionNet status surface should expose privacy-floor state without leaking route intent. The user needs to know whether the network is operating normally, contracted, delayed, or refusing because diversity is too low. The public should not see enough detail to reconstruct active routes. This is a hard product boundary and should be tested with simulation before launch.

Operational Signals

OnionNet operators need signals that do not reveal routes. Useful aggregate signals include eligible membership size, active-set health, lane contraction state, replay rejection counts, queue pressure, cover budget, and challenge status. Risky signals include exact route paths, live next-hop coordinates, route-specific contact material, and user session timing. The public layer should expose the former only at safe granularity and keep the latter out of ordinary status.

Documentation Readiness

OnionNet docs should remain explicit about blockers until implementation contracts are frozen. The page can teach route ownership, double envelopes, replay binding, and low-load privacy now. It should not provide operator commands, public uptime claims, or anonymity guarantees until source, tests, simulation, and audit evidence exist.

Release Gate

OnionNet release readiness requires simulation evidence for sparse-load privacy, tests for replay binding, tests for route construction, tests for witness freshness, and audit evidence for the confidentiality boundary. Until those exist, the only honest public status is architectural target work.

That status should be visible in examples, diagrams, and operator text.

Reader safety note: OnionNet can reduce ingress and route risks only inside its validated assumptions. It should never be used as shorthand for total privacy or final settlement.

Read Next

• Publication Pipeline for how ingress feeds public artifacts.
• Data Infrastructure for public and private data surfaces.
• Status And Explorer for privacy-safe display.

Evidence and Further Reading

Use the source bullets below as an audit checklist, not decoration: when reusing this page, preserve the named section scope, the responsible actor, and the split between live repository evidence, target architecture, and open design work.

• OnionNet Whitepaper sections 2-12 for thesis, boundary, route construction, transport, replay, low-load privacy, threat model, crypto direction, rollout, blockers, and glossary.
• Privacy Threat Model And Metrics section 8 for service and disclosure privacy boundaries.
• Tor Specifications: https://spec.torproject.org/.
• Tor Protocol Specification: https://spec.torproject.org/tor-spec/.
• Tor Rendezvous Specification v3: https://spec.torproject.org/rend-spec/.