Tunnel relay reference

Reference for the tunnel-node binary from the adnl-tunnel repository. Deployment and operation are covered in How to run a tunnel relay.

Server configuration

The file config.json is generated automatically on first launch.

Main fields

Field	Type	Default	Description
TunnelServerKey	bytes	auto-generated	Ed25519 private key seed. Defines the ADNL identity.
TunnelListenAddr	string	0.0.0.0:17330	UDP listen address
TunnelThreads	uint	CPU count	Packet processing threads
NetworkConfigUrl	string	https://ton-blockchain.github.io/global.config.json	TON network configuration URL
ExternalIP	string	auto-detected	Public IP announced to DHT
PaymentsEnabled	bool	false	Enable payment channel support

Payment fields (Payments object)

Field	Type	Default	Description
ADNLServerKey	bytes	auto-generated	Ed25519 seed for the payment ADNL server
PaymentsNodeKey	bytes	auto-generated	Ed25519 seed for the payment node identity
WalletPrivateKey	bytes	auto-generated	Ed25519 seed for the TON wallet
DBPath	string	./payments-db/	LevelDB path for payment state
SecureProofPolicy	bool	false	Use secure (slower) proof verification instead of fast
MinPricePerPacketRoute	uint64	0	Minimum nanoTON per routed packet
MinPricePerPacketInOut	uint64	0	Minimum nanoTON per packet traversing the out node (ingress/egress)

Channel configuration (Payments.ChannelsConfig)

Field	Default	Description
BufferTimeToCommit	10,800 s (3 h)	Buffer time before committing channel state
QuarantineDurationSec	21,600 s (6 h)	Quarantine period after channel dispute
ConditionalCloseDurationSec	10,800 s (3 h)	Conditional close window
MinSafeVirtualChannelTimeoutSec	300 s (5 min)	Minimum virtual channel lifetime

TON payment defaults

Parameter	Server	Client
MisbehaviorFine	3 TON	3 TON
ExcessFeeTon	0.25 TON	0.25 TON
WithdrawWhenAmountReached	5 TON	0 TON
DepositWhenAmountLessThan	0 TON	1 TON
DepositUpToAmount	0 TON	3 TON

USDT jetton support

Disabled by default.

Parameter	Value
Jetton master address	EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs
Decimals	6
Symbol	USDT

Parameter	Server	Client
Enabled	false	false
MisbehaviorFine	12 USDT	12 USDT
ExcessFeeTon	0.35 TON	0.35 TON
WithdrawWhenAmountReached	15 USDT	0 USDT
DepositWhenAmountLessThan	0 USDT	5 USDT
DepositUpToAmount	0 USDT	10 USDT

Client configuration

Used by the C library and external integrations.

Field	Type	Default	Description
TunnelServerKey	bytes	auto-generated	Ed25519 private key seed
TunnelThreads	uint	CPU count	Packet processing threads
TunnelSectionsNum	uint	1	Number of relay hops
NodesPoolConfigPath	string	empty	Path to shared configuration file
PaymentsEnabled	bool	false	Enable payment support
Payments	object		Client payment configuration (see below)

Client payment fields (Payments object)

Field	Type	Default	Description
ADNLServerKey	bytes	auto-generated	Ed25519 seed for the payment ADNL server
PaymentsNodeKey	bytes	auto-generated	Ed25519 seed for the payment node identity
WalletPrivateKey	bytes	auto-generated	Ed25519 seed for the TON wallet
DBPath	string	./payments-db/	LevelDB path for payment state
SecureProofPolicy	bool	false	Secure (slower) proof verification
ChannelsConfig	object		Same structure as the server Payments.ChannelsConfig, with client-specific balance-control defaults

CLI flags

Flag	Default	Description
-config	config.json	Configuration file path
-v	2	Verbosity level
-payment-node	empty	Hex-encoded payment node public key for channel deployment
-gen-shared-config	empty	Generate a shared configuration file at the given path and exit
-metrics-listen-addr	disabled	Prometheus metrics endpoint
-profile-listen-addr	disabled	pprof profiling endpoint
-log-filename	tunnel.log	Log file path
-log-max-size	1024	Maximum log file size (MB) before rotation
-log-max-backups	16	Maximum number of rotated log files to keep
-log-max-age	180	Maximum age (days) for rotated log files
-log-compress	false	Compress rotated log files
-log-disable-file	false	Disable file logging, write to console only

Verbosity levels

-v value	Level	Notes
0	Error
1	Warn
2	Info	Default
3	Debug
4	Debug	Enables chain scanner debug output
5	Debug	Enables DHT debug logs
6	Debug	Enables raw ADNL packet logs

Prometheus metrics

Exposed when -metrics-listen-addr is set. Namespace: tunnel_.

Metric	Type	Labels	Description
tunnel_active_inbound_sections	Gauge		Active inbound tunnel sections
tunnel_active_routes	GaugeVec	paid	Active routing paths
tunnel_active_out_gateways	GaugeVec	paid	Active outbound gateways
tunnel_packets_counter	CounterVec	type (routed, in, out)	Packets processed (in thousands)
tunnel_packets_paid_counter	CounterVec	type (route, out)	Prepaid packets consumed

Packet counters are updated every 5 seconds and reported in units of 1,000.

Interactive commands

Available in TTY mode. In non-interactive mode (systemd, Docker), the relay blocks without a command prompt.

Command	Description
speed	Toggle per-section packets-per-second display (run again to stop)
stats	Show cumulative routing statistics per section
balance	Show earned balance across all payment channels
capacity	Show remaining deposit from payment node
wallet-ton-balance	Show on-chain wallet balance
wallet-ton-transfer	Interactive TON transfer from the relay wallet (3-second confirmation delay)

Operational constants

Constant	Value	Description
Default UDP port	17330	Relay listen port
Section inactivity timeout	120 s	Idle sections are closed
Peer inactivity timeout	10 s	Idle peer connections are dropped
Ping interval	3 s	Keep-alive frequency
Tunnel reconfigure threshold	15 s	Idle time before the client silently reconfigures the same path
Tunnel reroute threshold	45 s	Idle time after which the client calls AskReroute() (60 s cooldown)
Free packet rate	10 packets/s (burst 20)	Rate limit for unpaid traffic per route
Free startup allowance	20,000 packets	Packets allowed before payment enforcement
Max routes per section	3	Maximum concurrent routes on a single section
Prepay batch size	200,000 packets	Client payment batch size
Channel capacity multiplier	30 payments	Virtual channel sized for 30 prepay cycles
Replay window	512 bits	Sliding-window replay filter per section (8 × uint64)

Get-methods

The tunnel-node binary exposes no on-chain get-methods. All interaction is via the CLI flags, config.json, and the interactive TTY commands listed above.

C library API

Build with make library to produce build/libtunnel.a.

PrepareTunnel

Initializes a tunnel client. Reads ClientConfig from the given path, connects to relays listed in SharedConfig, and starts routing.

Parameters: logger callback, receive-batch callback, reinit callback, config path, TON network config JSON.

Returns a Tunnel struct:

typedef struct {
    size_t index;
    int ip;
    int port;
} Tunnel;

The receive callback fires when 100 packets accumulate or after 10 ms, whichever comes first.

WriteTunnel

Sends a batch of packets through the tunnel.

Parameters: tunnel index, data buffer, packet count. Returns 1 on success, 0 if the index is invalid, -1 on write error.

Packet format

Each packet in a batch is prefixed with a 16-byte sockaddr_in structure (AF_INET, port in big-endian, IPv4 address) followed by a 2-byte big-endian size field and the payload bytes.

Build targets

Target	Output	Description
make binary	build/tunnel-node	Server binary for the host platform
make library	build/libtunnel.a	C static library
make all	5 binaries	Cross-compile: tunnel-node-linux-amd64, tunnel-node-linux-arm64, tunnel-node-mac-amd64, tunnel-node-mac-arm64, tunnel-node-x64.exe

Related pages

• Tunnel node: multi-hop tunnels with onion-like encryption and garlic structure
• How to run a tunnel relay: deployment and operation guide