How to run a tunnel relay

Prerequisites, installation, payment channel setup, and operations for an ADNL tunnel node relay.

Prerequisites

• Go 1.24 or newer, available from the official Go downloads page
• Static public IP address
• UDP port 17330 open for tunnel traffic
• TCP port 18889 open temporarily for automatic IP detection

Install the relay binary

Build from source:

git clone https://github.com/ton-blockchain/adnl-tunnel
cd adnl-tunnel
make binary

The binary is produced at build/tunnel-node. Precompiled binaries are available from the releases page.

Start the relay

./tunnel-node

On first launch the relay:

1. Generates config.json with four Ed25519 key pairs
2. Attempts to detect the external IP via a port checker (TCP 18889 to tonutils.com:9099)
3. Publishes the node in the DHT overlay
4. Prints the ADNL identity:

Tunnel started, listening on 0.0.0.0:17330 ADNL id is: <BASE64_ADNL_ID>

Verify the configuration

Open config.json and check:

• ExternalIP: must contain the public IP. If empty, the port checker failed. Set it manually.
• TunnelListenAddr: defaults to 0.0.0.0:17330. Change if a different bind address is needed.
• TunnelServerKey: the node identity key. Do not modify.

Identity key

Modifying TunnelServerKey changes the ADNL identity of the relay on both TON Mainnet and TON Testnet.

• Risk: existing clients and pinned shared-config files lose connectivity until redistributed.
• Scope: TunnelServerKey in config.json and the DHT entry advertised by the node.
• Mitigation: announce key rotations in advance; keep the previous key until clients migrate.

See the tunnel relay reference for the full list of configuration fields.

Enable payments

1. Edit config.json:

   {
     "PaymentsEnabled": true,
     "Payments": {
       "MinPricePerPacketRoute": 100,
       "MinPricePerPacketInOut": 200
     }
   }

2. Restart the relay. In interactive mode (TTY), the relay prompts for the payment node key:

   No active onchain payment channel found, please input payment node id (pub key) in base64 format, to deploy channel with:

   Enter the base64 public key of the payment node. In non-interactive mode (systemd, Docker), pass the key as a flag:

   ./tunnel-node --payment-node <HEX_PAYMENT_NODE_KEY>

3. The relay deploys the payment channel contract on-chain (timeout 150 s), then waits for state exchange.

   On-chain payment channel

   Deploying a payment channel locks a TON deposit on-chain until the channel is closed.

   • Risk: funds are committed to the channel contract; loss of payments-db/ before settlement can result in unrecoverable balance.
   • Scope: the wallet address displayed at startup and the payments-db/ directory.
   • Mitigation: keep periodic backups of payments-db/; verify settlement before deleting.
   • Environment: validate the flow on TON Testnet before committing mainnet funds.

4. Verify the deployment with the balance interactive command.

Generate a shared configuration

To pin clients to this relay:

./tunnel-node -gen-shared-config <OUTPUT_PATH>

This produces a JSON file containing the node public key and payment parameters. Distribute the file to clients, who reference it via NodesPoolConfigPath in their configuration.

Monitor the relay

Prometheus metrics

Enable the metrics endpoint:

./tunnel-node -metrics-listen-addr 0.0.0.0:9100

Metrics are exported under the tunnel_ namespace. The full metric list is in the tunnel relay reference.

Interactive commands

In TTY mode, the commands speed, stats, balance, capacity, wallet-ton-balance, and wallet-ton-transfer are available; each is documented in the interactive commands reference.

Run as a systemd service

Example unit file:

[Unit]
Description=ADNL Tunnel Relay
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=tunnel
WorkingDirectory=/opt/tunnel-node
ExecStart=/opt/tunnel-node/tunnel-node -v 2 -metrics-listen-addr 127.0.0.1:9100
Restart=on-failure
RestartSec=5
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

Caution

In non-interactive mode, the relay cannot prompt for a payment node key. Pass --payment-node <HEX_KEY> in ExecStart when enabling payments for the first time.

Troubleshoot common issues

Symptom	Cause	Fix
ExternalIP is empty after startup	Port checker cannot reach TCP 18889	Open TCP 18889 temporarily or set ExternalIP manually
skipping dht because no external address known	ExternalIP not configured	Set ExternalIP in config.json
tunnel looks disconnected	No control response for 45 seconds	Check network connectivity and peer availability
more than 33% incoming packets lost	Excessive packet loss on the path	Investigate network quality or relay selection
free packets exceeds rate limit	Unpaid traffic exceeds 10 packets per second	Enable payments or reduce traffic
Relay registers but clients cannot connect	Relay is behind NAT without port forwarding	Set ExternalIP manually in config.json AND forward UDP 17330 on the router

Stop and update the relay

Send SIGTERM to stop the relay. The node commits virtual payment channels before exiting (timeout 15 s).

To update: stop the relay, replace the binary, and restart. Keys in config.json and state in payments-db/ persist across restarts.

Payment state loss

Do not delete payments-db/ while payment channels are open on TON Mainnet or TON Testnet.

• Risk: losing channel state means losing the ability to settle earned balances; deposited funds can become unrecoverable.
• Scope: the payments-db/ directory on the relay host.
• Mitigation: back up payments-db/ before updates; close all channels cleanly before removing the directory.
• Environment: mainnet payment channels hold real funds; testnet channels hold test TON but the failure mode is identical.

Related pages

• Tunnel node: how garlic routing works
• Tunnel relay reference: all configuration fields, CLI flags, and metrics