ADNL Tunnel

A secure, decentralized tunneling service built on The Open Network (TON) blockchain, providing encrypted communication channels with integrated payment capabilities.

Features

Secure Communication: Implements ADNL (Abstract Datagram Network Layer) protocol for encrypted data transmission
Decentralized Architecture: Utilizes TON blockchain's DHT for node discovery
Payment Integration: Built-in TON payment channels for service monetization
Garlic Routing: Multi-layer encryption for enhanced privacy
Dynamic Routing: Automatic route optimization and load balancing
External IP Support: Ability to serve as an exit node with white IP address
DDoS Protection: Built-in rate limiting and protection mechanisms
Cross-Platform Support:
- Linux (amd64, arm64)
- macOS (amd64, arm64)
- Windows (amd64)
- BSD systems

System Architecture

Overview

The ADNL Tunnel implements a multi-layer architecture:

Transport Layer: ADNL protocol implementation
Routing Layer: DHT-based node discovery and routing
Payment Layer: TON blockchain integration
Security Layer: Encryption and access control

Architecture Diagrams

Component Diagram

graph TB
    subgraph Client
        CC[Client Core]
        CP[Payment Module]
        CT[Tunnel Interface]
    end

    subgraph Server
        SG[ADNL Gateway]
        ST[Tunnel Manager]
        SP[Payment System]
        SD[DHT Client]
        SS[Security Layer]
    end

    subgraph External
        TON[TON Blockchain]
        DHT[DHT Network]
    end

    CC --> CT
    CP --> CT
    CT --> SG
    SG --> ST
    ST --> SS
    ST --> SP
    SG --> SD
    SD --> DHT
    SP --> TON

Sequence Diagram

sequenceDiagram
    participant C as Client
    participant G as Gateway
    participant D as DHT
    participant T as Tunnel Manager
    participant P as Payment System
    participant B as Blockchain

    C->>G: Initialize Connection
    G->>D: Discover Routes
    D-->>G: Return Available Routes
    G->>T: Create Tunnel
    T->>P: Check Payment Required
    P->>B: Verify Channel
    B-->>P: Channel Status
    P-->>T: Payment Status
    T-->>G: Tunnel Ready
    G-->>C: Connection Established

    rect rgb(200, 200, 200)
        Note over C,B: Data Transfer Phase
        C->>G: Send Data
        G->>T: Process Data
        T->>P: Update Payment
        P->>B: Process Payment
    end

Data Flow Diagram

graph LR
    subgraph Input
        Client[Client Data]
        Config[Configuration]
    end

    subgraph Processing
        Encrypt[Encryption]
        Route[Routing]
        Pay[Payment Processing]
    end

    subgraph Output
        Tunnel[Tunnel Data]
        Logs[System Logs]
        Stats[Statistics]
    end

    Client --> Encrypt
    Config --> Route
    Encrypt --> Route
    Route --> Pay
    Pay --> Tunnel
    Route --> Stats
    Pay --> Logs

Communication Flow

Client initiates connection
Route discovery and optimization
Payment channel establishment (if enabled)
Encrypted tunnel creation
Data transmission with payment tracking

Prerequisites

Go 1.20 or higher
TON Wallet (if using payment features)
External IP address (optional, for exit nodes)
Open ports for tunnel and payment services

Installation

Clone the repository:

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

Build the project:

go build

Configuration

The configuration file (config.json) will be automatically generated on first run. Here's a sample configuration:

Configuration File Locations

Default: ./config.json (in the current working directory)
Linux/macOS: $HOME/.config/adnl-tunnel/config.json
Windows: %APPDATA%\adnl-tunnel\config.json

You can override the default location using the -config flag.

{
  "TunnelServerKey": "<auto-generated>",
  "TunnelListenAddr": "0.0.0.0:17330",
  "TunnelThreads": 4,
  "NetworkConfigUrl": "https://ton-blockchain.github.io/global.config.json",
  "ExternalIP": "",
  "Payments": {
    "Enabled": false,
    "PaymentsServerKey": "<auto-generated>",
    "WalletPrivateKey": "<auto-generated>",
    "PaymentsListenAddr": "0.0.0.0:17331",
    "DBPath": "./payments-db/",
    "SecureProofPolicy": false,
    "ChannelConfig": {
      "VirtualChannelProxyFee": "0.01",
      "QuarantineDurationSec": 600,
      "MisbehaviorFine": "0.15",
      "ConditionalCloseDurationSec": 180
    },
    "MinPricePerPacketRoute": 1000,
    "MinPricePerPacketInOut": 1000
  }
}

Configuration Parameters

TunnelServerKey: ED25519 private key for the tunnel server
TunnelListenAddr: Address to listen for tunnel connections
TunnelThreads: Number of worker threads (defaults to CPU count)
NetworkConfigUrl: TON network configuration URL
ExternalIP: External IP address (if available)
Payments: Payment system configuration
- Enabled: Enable/disable payment system
- PaymentsListenAddr: Address for payment service
- SecureProofPolicy: Use secure proof checking policy
- MinPricePerPacketRoute: Minimum price per packet for routing
- MinPricePerPacketInOut: Minimum price per packet for in/out operations

Usage

Starting the Server

Basic start:

./adnl-tunnel

With custom configuration:

./adnl-tunnel -config=custom_config.json

With verbose logging:

./adnl-tunnel -v=3

Client Usage Examples

# Basic client connection
./adnl-tunnel -node <server-adnl-id>

# With custom configuration
./adnl-tunnel -config custom_config.json -node <server-adnl-id>

Command Line Arguments

-config: Path to configuration file (default: "config.json")
-payment-node: Payment node to open channel with (optional)
-v: Verbosity level (0-5, default: 2)
- 0: Error
- 1: Warning
- 2: Info
- 3: Debug
- 4: Trace
- 5: DHT Debug

Runtime Commands

The following commands are available while the tunnel is running:

balance: Check current TON balance in payment channels
capacity: Check remaining capacity in payment channels

Technical Specifications

Protocol Details

ADNL Protocol Version: 1.0
Encryption: ED25519 + AES-256-GCM
DHT Protocol: Kademlia-based
Network Layer: UDP
Maximum Packet Size: 2048 bytes
Default Port Range: 17330-17331

Performance Metrics

Maximum Connections: Based on system resources
Throughput: Up to network capacity
Latency Overhead: ~10-20ms per hop
Payment Processing Time: ~2-5 seconds
DHT Lookup Time: ~1-2 seconds

System Requirements

Minimum Requirements

CPU: 2 cores
RAM: 2 GB
Storage: 1 GB
Network: 10 Mbps

Recommended Requirements

CPU: 4+ cores
RAM: 4+ GB
Storage: 10+ GB
Network: 100+ Mbps
External IP address

Supported Platforms

OS	Architecture	Status
Linux	amd64	✅ Stable
Linux	arm64	✅ Stable
macOS	amd64	✅ Stable
macOS	arm64	✅ Stable
Windows	amd64	⚠️ Beta
BSD	amd64	⚠️ Beta

Security Considerations

All private keys are stored locally
Multi-layer encryption for all communications
Rate limiting for DDoS protection
Secure payment channels
Optional secure proof policy for payments
Regular security audits recommended
Firewall configuration guidelines available

Performance Tuning

Adjust TunnelThreads based on server capacity
Configure appropriate rate limits
Monitor channel capacity and balance
Optimize payment channel parameters
Network buffer size optimization
Connection pooling settings

Troubleshooting

Common issues and solutions:

Connection Failed
- Check network configuration
- Verify external IP settings
- Ensure ports are open
- Check firewall rules
- Verify DHT connectivity
Payment Issues
- Verify wallet balance
- Check payment channel status
- Confirm minimum price settings
- Validate blockchain connectivity
- Check payment node availability
Performance Problems
- Adjust thread count
- Monitor system resources
- Check network capacity
- Optimize route selection
- Review logging levels

Development Guide

Project Structure

adnl-tunnel/
├── config/         # Configuration management
├── tunnel/         # Core tunnel implementation
│   ├── gateway.go  # ADNL gateway
│   ├── section.go  # Tunnel sections
│   └── payment.go  # Payment integration
├── main.go        # Entry point
└── docs/          # Documentation

Building from Source

Install dependencies:

go mod download

Run tests:

go test ./...

Build:

go build -o adnl-tunnel

Development Setup

Install development tools:

# Install golangci-lint
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin

# Install mockgen
go install github.com/golang/mock/mockgen@latest

Set up pre-commit hooks:

git config core.hooksPath .githooks/
chmod +x .githooks/pre-commit

Code Style

Follow Effective Go guidelines
Use gofmt for code formatting
Maximum line length: 100 characters
Add comments for exported functions and types

Testing

Write unit tests for new features
Maintain test coverage above 80%
Use table-driven tests when appropriate
Mock external dependencies

Debugging

Enable debug logging:

./adnl-tunnel -v=5

Use pprof for profiling:

# CPU profile
go tool pprof http://localhost:6060/debug/pprof/profile

# Memory profile
go tool pprof http://localhost:6060/debug/pprof/heap

Common Development Tasks

Adding a new command:
- Add command handler in main.go
- Update command documentation
- Add unit tests
Modifying tunnel behavior:
- Update relevant files in tunnel/ package
- Consider backward compatibility
- Update tests and documentation
Changing configuration:
- Modify config/config.go
- Update sample configuration
- Update configuration documentation

Contributing

Fork the repository
Create your feature branch
Commit your changes
Push to the branch
Create a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Important Notes

⚠️ Implementation Status: Some features described in this documentation are planned but not yet fully implemented. Please check the source code or open issues for the latest implementation status.

Acknowledgments

TON Blockchain team
TON Payment Network contributors
ADNL protocol developers
Open source community

Disclaimer

This software is provided "as is", without warranty of any kind. Use at your own risk. Users are responsible for ensuring compliance with local laws and regulations.

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
config		config
tunnel		tunnel
.gitignore		.gitignore
architecture.drawio		architecture.drawio
go.mod		go.mod
go.sum		go.sum
main.go		main.go
readme.md		readme.md
tunnel.drawio		tunnel.drawio

awesome-doge/adnl-tunnel

Folders and files

Latest commit

History

Repository files navigation