Tunnel node
ADNL tunnels add a privacy layer to the TON network. They are multi-hop tunnels with onion-like (multi-layer) encryption of routing instructions. A single packet can carry a garlic structure (multiple instructions for different nodes along the path), while the user payload is encrypted once end-to-end between the source and the out node. Each node decrypts only its own instructions and forwards the rest, so the client and destination are never visible to the same node. The implementation is adnl-tunnel.
How the tunnel works
Section titled “How the tunnel works”The client (Node 0, the source) builds the tunnel message inside-out, from the out node (Node N) back to the first hop (Node 1). 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 source and the out node.
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 |
|---|---|---|---|
First hop (Node 1) | Yes | No | No |
| Intermediate node | No | No | No |
Out node (Node N) | 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.
Stall detection and rerouting
Section titled “Stall detection and rerouting”If the tunnel stops receiving control responses, the client first tries to reconfigure through the same nodes after 15 seconds without a checkpoint. If the stall persists to 45 seconds (and at least 60 seconds have passed since the last rerouting attempt), the client calls AskReroute(); if the application accepts, the tunnel is rebuilt through an alternate path.
Payment channels
Section titled “Payment channels”Relays can charge per packet in nanoTON via the PricePerPacket field of BuildRouteInstruction and BindOutInstruction. Payments flow through virtual off-chain channels provided by ton-payment-network, so no on-chain transaction is required per packet. The underlying payment channel contract is deployed on-chain once during setup and then reused to settle many off-chain packets. The client prepays in batches of 200,000 packets (ChannelPacketsToPrepay).
Every route applies a rate limit of 10 packets per second (burst 20) to unpaid packets (FreePacketsMaxPS, FreePacketsMaxPSBurst). Paid packets bypass this limit. On a free relay all traffic is unpaid, so the cap applies to every client.
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.