Tunnel node
ADNL tunnels add a privacy layer to the TON network. Each relay decrypts only its own routing instructions and forwards the rest, so the client and destination are never visible to the same node. The relay implementation is adnl-tunnel.
How garlic routing works
Section titled “How garlic routing works”The client builds the tunnel message inside-out, from exit relay to entry relay. Each layer serializes an InstructionsContainer, prepends it to the already-encrypted inner layers, and encrypts the result with AES-256-CTR. Key agreement uses Ed25519-to-X25519 ECDH per tunnel section. The user payload is encrypted with a separate key shared only between the client and the exit relay.
Each relay maintains a 512-bit sliding-window replay filter (8 × uint64), which rejects duplicate packets and prevents replaying captured traffic against the same section.
Knowledge separation
Section titled “Knowledge separation”| Node position | Sees sender IP | Sees destination | Reads payload |
|---|---|---|---|
| Entry relay | Yes | No | No |
| Intermediate relay | No | No | No |
| Exit relay | No | Yes | No |
Relay discovery
Section titled “Relay discovery”Relays register in a DHT overlay keyed by OverlayKey{PaymentNode}. Free relays set PaymentNode to 32 zero bytes; paid relays set it to their payment node public key. Each overlay holds up to 5 entries with a 20-minute TTL, refreshed every 5 minutes. Clients query the overlay with FindOverlayNodes.
Payment channels
Section titled “Payment channels”If one or more relays on the active path drop, the client detects the stall after 45 seconds without a control response and rebuilds the tunnel through an alternate path.
Relays can charge per packet in nanoTON. Payments flow through virtual off-chain channels (ton-payment-network), so no on-chain transaction is required per packet. The client pre-pays in batches of 200,000 packets. Free relays allow 10 packets per second (burst 20) before dropping traffic. The tunnel relay reference lists all payment configuration fields.
Running a relay
Section titled “Running a relay”The relay binary is built from the adnl-tunnel repository and requires Go 1.24+. Precompiled binaries are available from the releases page. For step-by-step deployment instructions, see How to run a tunnel relay. The tunnel relay reference documents all configuration fields, CLI flags, and Prometheus metrics.
Related components
Section titled “Related components”- ADNL: the abstract datagram network layer that tunnels operate on.
- TON DHT: distributed hash table used for relay discovery and address resolution.
- TON Proxy: HTTP-to-ADNL bridge for browser access to TON Sites, with built-in tunnel client support.
- TON Sites: web services hosted over ADNL.
- TON DNS: human-readable domain names for ADNL addresses.
- How to run a tunnel relay: deployment and operation guide.
- Tunnel relay reference: configuration, CLI flags, and metrics.