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 exit-bound packet

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

Parameter	Default
Enabled	false
MisbehaviorFine	12 USDT
ExcessFeeTon	0.35 TON
WithdrawWhenAmountReached	15 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
MaxPricePerPacket	uint64	0	Maximum nanoTON per packet, 0 = no limit

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 stall detection	45 s	Time without control response before reconfiguration
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: linux-amd64, linux-arm64, darwin-amd64, darwin-arm64, windows-amd64

Related pages

• Tunnel node: how garlic routing works
• How to run a tunnel relay: deployment and operation guide