BlockchainVPN: Decentralized VPN Marketplace

BlockchainVPN is a peer-to-peer VPN marketplace built on top of the OrdexCoin blockchain. It allows anyone to become a VPN provider by announcing their service on-chain, and allows clients to discover, pay for, and connect to these services in a decentralized, permissionless manner.

Current version: 0.8.2

0. Support the development

This project is done in my spare time and will be available for free, so donating and supporting the project will help me finish and polish it to a working and stable point.

* BTC: bc1qkmzc6d49fl0edyeynezwlrfqv486nmk6p5pmta
* ETH/ERC-20: 0xC13D012CdAae7978CAa0Ef5B1E30ac6e65e6b17F
* LTC: ltc1q0ahxru7nwgey64agffr7x89swekj7sz8stqc6x
* SOL: HB2o6q6vsW5796U5y7NxNqA7vYZW1vuQjpAHDo7FAMG8
* XRP: rUW7Q64vR4PwDM3F27etd6ipxK8MtuxsFs

To help me test the current implementation with ordexcoin, you can help donate tokens that will be used for testing and refining the payment model(s).

* OXC: oxc1q3psft0hvlslddyp8ktr3s737req7q8hrl0rkly
* OXG: oxg1q34apjkn2yc6rsvuua98432ctqdrjh9hdkhpx0t

All donations will be direclty used to develop and maintain the blockchain VPN package and system, as well as expand to support multiple chains and connection methods such as native Bitcoin and Socks5 proxy vpns.

Donators and supports will be immortalized in the applications about and readme sections. You can also use the following link to support me with any token of your choice: https://nestex.one/pay/Black-Spirited-174344 or buy me a coffee/beer: https://buymeacoffee.com/timhbergsta

1. Architecture Overview

The system utilizes the blockchain as an immutable, censorship-resistant bulletin board for service discovery and a settlement layer for payments.

Components

OrdexCoin Layer (Consensus & Data):
- Used to broadcast service advertisements via OP_RETURN outputs.
- Used for payment settlement (subscription or pay-as-you-go).
VPN Provider (Go Application):
- Runs alongside an ordexcoind node (or connects to a remote one).
- Publishes "Service Announcement" transactions to the blockchain.
- Listens for incoming TLS connections over TCP and forwards traffic via a TUN interface.
- Monitors the blockchain for incoming payments.
- Manages a UDP echo server for latency testing.
VPN Client (Go Application):
- Connects to an ordexcoind node to scan for Service Announcements.
- Maintains a local cache of available providers.
- Performs active probing (UDP Echo) to determine availability and speed.
- Performs GeoIP lookups to estimate country of origin.
- Facilitates payment and configures the local network interface to tunnel traffic.

2. Protocol Specification

Service Announcement (Provider -> Network)

To announce a VPN service, the Provider broadcasts a transaction containing a specific OP_RETURN output. This output holds the metadata required for clients to connect.

Payload Structure (Max 80 bytes):

Field	Size (Bytes)	Description
Magic Bytes	4	`0x56504E01` ("VPN" v1)
IP Type	1	`0x04` for IPv4, `0x06` for IPv6.
IP Address	4 or 16	The public IP of the VPN endpoint.
Port	2	The TCP listening port for TLS connections (uint16, Big Endian).
Price	8	Cost in Satoshis per session (uint64, Big Endian).
Public Key	33	Provider's compressed `secp256k1` Public Key.

Note: If the IP address changes, the provider simply broadcasts a new transaction. Clients always prioritize the most recent transaction from a specific provider identity.

Payment & Authorization (Client -> Provider)

Clients purchase access by sending a transaction to the provider's address (derived from the announcement transaction inputs). This transaction must include an OP_RETURN output with the client's public key. This key is then used to generate a client certificate to authorize the TLS connection.

Payload Structure:

Field	Size (Bytes)	Description
Magic Bytes	4	`0x50415901` ("PAY" v1)
Public Key	33	Client's compressed `secp256k1` Public Key.

3. Application Logic

A. VPN Provider

Initialization:
- Generates or loads a secp256k1 private/public key (btcec).
- Detects public IP address (automatically or via config).
- Sets up a TUN interface and applies runtime networking configuration (platform-dependent backend).
Announcement:
- Constructs a raw transaction using ordexcoind RPC.
- Adds an output with OP_RETURN containing the service payload.
- Signs and broadcasts the transaction.
- Re-announces periodically (e.g., every 24 hours).
Service Loop:
- Listens on the specified TCP port for TLS connections.
- Runs a UDP echo server for latency checks.
- Payment Monitor: Scans the blockchain for transactions paying the service price to the provider's address containing a valid "PAY" OP_RETURN payload.
- Access Control: Verifies the client's TLS certificate against a list of authorized public keys derived from valid payments.

B. VPN Client

Discovery:
- Queries ordexcoind for recent blocks.
- Scans transactions for outputs starting with OP_RETURN + Magic Bytes.
- Decodes payload to extract IP, Port, Price, and Key.
Enrichment & Filtering:
- Availability/Speed: Sends a UDP ping to the IP:Port to measure RTT.
- GeoIP: Uses a local GeoLite2 database to map the IP to a Country Code.
Selection:
- User selects a provider from a sorted list (by Country, Speed, or Cost).
Connection:
- Generates a temporary secp256k1 key pair.
- Sends a payment transaction with the generated public key.
- Creates a local TUN interface and establishes a TLS connection to the provider, forwarding traffic between them.

4. Getting Started

Prerequisites

Go 1.25+ installed.
OrdexCoin Core (ordexcoind) running and fully synced.
- RPC must be enabled (server=1).
- Transaction indexing (txindex=1) is recommended for faster scanning but not strictly required for basic operation.
Elevated privileges are required on Linux/macOS/Windows to configure TUN, routes, DNS, and provider NAT features.
Optional: GeoIP Database (GeoLite2-Country.mmdb) for country detection. If not present, country data will be unavailable.
See docs/INSTALL.md for OS-specific installation and privilege setup.

Installation

Build the CLI:

go build -o bcvpn ./cmd/bcvpn

Or use Makefile targets:

make build

Note: Only the CLI (bcvpn) is actively maintained. GUI/TUI interfaces have been moved to the _attic folder and are not supported.

Configuration

Generate a default configuration file:

./bcvpn generate-config

Edit config.json to match your environment:

rpc: Connection details for your local ordexcoind node.
logging: Runtime log output format (text or json).
security: Key storage backend, revocation cache, TLS policy, and metrics auth (key_storage_mode, revocation_cache_file, tls_min_version, tls_profile, metrics_auth_token).
provider: Settings if you intend to sell VPN service (IP, Port, Price, max_consumers, enable_egress_nat, nat_outbound_interface, isolation_mode, allowlist_file, denylist_file, cert_lifetime_hours, cert_rotate_before_hours, health_check_enabled, health_check_interval).
client: Settings for connecting to others (Interface Name).
By default, the app stores config.json, provider.key, and history.json in your OS user config directory under BlockchainVPN (for example ~/.config/BlockchainVPN on Linux).

Sample config.json:

{
  "rpc": {
    "host": "localhost:25173",
    "user": "yourrpcuser",
    "pass": "yourrpcpassword",
    "network": "mainnet",
    "token_symbol": "OXC",
    "min_relay_fee": 1000,
    "default_fee_kb": 1000
  },
  "logging": {
    "format": "text",
    "level": "info"
  },
  "security": {
    "key_storage_mode": "file",
    "key_storage_service": "BlockchainVPN",
    "revocation_cache_file": "",
    "tls_min_version": "1.3",
    "tls_profile": "modern",
    "metrics_auth_token": ""
  },
  "provider": {
    "interface_name": "bcvpn0",
    "listen_port": 51820,
    "auto_rotate_port": false,
    "announce_ip": "",
    "country": "",
    "price_sats_per_session": 1000,
    "max_consumers": 0,
    "private_key_file": "<APP_CONFIG_DIR>/provider.key",
    "bandwidth_limit": "10mbit",
    "bandwidth_auto_test": false,
    "dns_servers": ["1.1.1.1", "8.8.8.8"],
    "enable_nat": true,
    "enable_egress_nat": false,
    "nat_outbound_interface": "",
    "nat_traversal_method": "auto",
    "isolation_mode": "none",
    "allowlist_file": "",
    "denylist_file": "",
    "cert_lifetime_hours": 720,
    "cert_rotate_before_hours": 24,
    "health_check_enabled": true,
    "health_check_interval": "30s",
    "metrics_listen_addr": "127.0.0.1:9090",
    "bandwidth_monitor_interval": "30s",
    "announcement_interval": "24h",
    "tun_ip": "10.10.0.1",
    "tun_subnet": "24",
    "max_session_duration_secs": 0,
    "announcement_fee_target_blocks": 0,
    "announcement_fee_mode": "conservative",
    "address_type": "auto",
    "throughput_probe_port": 0,
    "websocket_fallback_port": 0,
    "heartbeat_interval": "5m",
    "payment_monitor_interval": "1m",
    "payment_required_confirmations": 1,
    "shutdown_timeout": "10s",
    "pid_file": "",
    "pricing_method": "session",
    "billing_time_unit": "hour",
    "billing_data_unit": "GB"
  },
  "client": {
    "interface_name": "bcvpn1",
    "tun_ip": "10.10.0.2",
    "tun_subnet": "24",
    "enable_kill_switch": false,
    "metrics_listen_addr": "127.0.0.1:9091",
    "strict_verification": false,
    "verify_throughput_after_connect": true,
    "auto_reconnect_enabled": false,
    "auto_reconnect_max_attempts": 0,
    "auto_reconnect_interval": "5s",
    "auto_reconnect_max_interval": "5m"
  },
  "demo_mode": false
}

Usage

For VPN Providers

To start selling bandwidth:

./bcvpn start-provider

Non-interactive key unlock for automation (file mode):

export BCVPN_KEY_PASSWORD='your-password'
./bcvpn start-provider --key-password-env BCVPN_KEY_PASSWORD

This command will:
1. Set up the provider TUN interface (requires elevated privileges on most systems).
2. Announce your service on the blockchain (requires wallet funds).
3. Start a payment monitor to listen for incoming customers.
4. Start a UDP echo server for latency testing.
5. Automatically verify connecting clients based on valid payments.

For VPN Clients

Scan for Providers: Find available VPNs, with filters/sorting for latency, price, country, bandwidth, and capacity.

./bcvpn scan --sort=score --country=US --max-price=2000 --min-bandwidth-kbps=25000 --max-latency-ms=80 --min-available-slots=2

Connect: Follow the interactive prompts in the scan command to select a provider. The tool will:
- Generate a temporary key pair.
- Send the payment transaction.
- Configure a local TLS-over-TUN tunnel to the provider.
Payment History: View a log of past payments.
```
./bcvpn history
```
Rotate Provider Key: Rotate the encrypted provider key file and generate a new provider identity.
```
./bcvpn rotate-provider-key
./bcvpn rotate-provider-key --old-password-env BCVPN_OLD_PASS --new-password-env BCVPN_NEW_PASS
```
Important: Rotating the provider key creates a new blockchain identity. Any existing subscriptions or payments made to your old provider address will no longer work. Clients will need to re-authorize with your new provider key. Consider this operation carefully if you have active subscribers.
Status (Human or JSON): Inspect current config/runtime readiness for automation or diagnostics (including networking privilege readiness).
```
./bcvpn status
./bcvpn status --json
```

CLI Config Management: Read, update, and validate settings from the CLI.

./bcvpn config get provider.listen_port
./bcvpn config set provider.listen_port 51820
./bcvpn config set client.enable_kill_switch true
./bcvpn config validate

Security-related keys are also exposed:

./bcvpn config set security.key_storage_mode auto
./bcvpn config set security.revocation_cache_file /path/to/revoked_keys.txt
./bcvpn config set security.tls_profile compat
./bcvpn config set client.strict_verification true

Import/export are also supported:

./bcvpn config export ./my-profile.json
./bcvpn config import ./my-profile.json --validate

Runtime Metrics Endpoint (Optional): Set provider.metrics_listen_addr or client.metrics_listen_addr to expose:
```
curl http://127.0.0.1:9090/metrics.json
```
To require auth, set security.metrics_auth_token and send:
```
curl -H "X-BCVPN-Metrics-Token: <token>" http://127.0.0.1:9090/metrics.json
```
Structured Logs (Optional): Set logging.format (text/json) and logging.level (debug/info/warn/error) in config.json, or override at runtime:
```
BCVPN_LOG_FORMAT=json ./bcvpn status --json
BCVPN_LOG_LEVEL=warn ./bcvpn start-provider
```
Version Info: Print semantic version and build metadata:
```
./bcvpn version
./bcvpn version --json
```
Runtime Doctor Checks: Run startup diagnostics for config, privileges, key storage backend, and platform tools:
```
./bcvpn doctor
./bcvpn doctor --json
```

Event Timeline and Diagnostics:

./bcvpn events --limit=100
./bcvpn events --json
./bcvpn diagnostics
./bcvpn diagnostics --out ./diag.json

5. Using Other Blockchains

While designed for OrdexCoin, this software is compatible with most Bitcoin-derived blockchains (Bitcoin, Litecoin, Dogecoin, etc.) that support OP_RETURN and the standard RPC interface.

To adapt this for another chain:

RPC Configuration: Update config.json with the RPC credentials and port of the target blockchain's daemon (e.g., 8332 for Bitcoin).
Address Format: The code dynamically detects the chain (Mainnet, Testnet, Regtest) from the RPC connection and adjusts address decoding accordingly.
Fees: Fee selection uses node-reported dynamic estimates (estimatesmartfee, relay fee fallback).

6. Project Status

Feature Checklist (Implemented)

Known Limitations (Post-Beta)

Heartbeat announcements lack cryptographic signature
Reputation scores not signature-verified (trust through network effect)
Direct connect command is stub-only (use scan to connect)
Refund flow not implemented
NAT traversal method selection via config not implemented
WebSocket origin validation not implemented
STUN integration for NAT type detection not implemented
GeoIP database not bundled (must be downloaded separately from MaxMind)

How It Works

Provider starts (start-provider), optionally opens NAT mappings, announces endpoint to chain, and serves TLS-over-TUN sessions.
Client scans chain (scan), enriches candidates with latency/GeoIP, and selects a provider.
Client sends on-chain payment containing a temporary public key.
Provider payment monitor authorizes that key until session expiry and enforces optional max active sessions.
Client connects over TLS, receives a dynamic TUN IP, traffic is forwarded through provider, and post-connect security checks run.

Networking notes: docs/NETWORKING.md
End-to-end user guide: docs/USER_GUIDE.md
Troubleshooting by OS: docs/TROUBLESHOOTING.md
Packaging and installer guidance: docs/PACKAGING.md
Security model: docs/SECURITY.md
Provider operations runbook: docs/OPERATIONS.md
Automation JSON examples: docs/AUTOMATION.md
Versioning policy and release progression: docs/VERSIONING.md
Version history and notable changes: docs/CHANGELOG.md

7. Project File Layout

The project is organized into the following directory structure:

.
├── Makefile              # Build/test targets
├── README.md
├── VERSION               # Semantic version
├── CHANGELOG.md
├── AGENTS.md             # Guidelines for agentic tools
├── TODO.md               # Implementation plan
├── docs/                 # Documentation
├── cmd/
│   └── bcvpn/            # CLI entrypoint
│       └── main.go
├── internal/
│   ├── auth/             # Authorization & cert management
│   ├── blockchain/       # Blockchain RPC, provider, scanner, payment
│   ├── config/           # Configuration loading and validation
│   ├── crypto/           # Keystore & encryption
│   ├── geoip/            # GeoIP lookups (optional)
│   ├── history/          # Payment history
│   ├── nat/              # UPnP & NAT-PMP
│   ├── obs/              # Observability (logging, metrics)
│   ├── protocol/         # VPN protocol encoding/decoding
│   ├── tunnel/           # Core VPN logic (TUN, TLS, networking)
│   └── util/             # Utilities
└── go.mod

. ├── Makefile ├── README.md ├── docs/ ├── cmd/ │ ├── bcvpn/ │ │ └── main.go // Main CLI application entrypoint ├── internal/ │ ├── auth/ // Authorization management │ ├── blockchain/ // Blockchain interaction (payment, provider, scanner) │ ├── config/ // Configuration loading and management │ ├── crypto/ // Encryption/decryption logic │ ├── geoip/ // GeoIP and latency enrichment │ ├── history/ // Payment history management │ ├── nat/ // UPnP and NAT-PMP logic │ ├── protocol/ // On-chain data structures and encoding │ ├── tunnel/ // Core VPN logic (TUN, TLS, Networking) │ └── util/ // Miscellaneous utility functions └── go.mod



## License

General open source, source available but the copyright holder keeps the right to commercial use.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

BlockchainVPN: Decentralized VPN Marketplace

0. Support the development

1. Architecture Overview

Components

2. Protocol Specification

Service Announcement (Provider -> Network)

Payment & Authorization (Client -> Provider)

3. Application Logic

A. VPN Provider

B. VPN Client

4. Getting Started

Prerequisites

Installation

Configuration

Usage

For VPN Providers

For VPN Clients

5. Using Other Blockchains

6. Project Status

Feature Checklist (Implemented)

Known Limitations (Post-Beta)

How It Works

7. Project File Layout

About

Uh oh!

Releases 11

Sponsor this project

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 182 Commits
.github		.github
cmd		cmd
docs		docs
functional_tests		functional_tests
internal		internal
resources		resources
scripts		scripts
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
Makefile		Makefile
README.md		README.md
TODO.md		TODO.md
VERSION		VERSION
go.mod		go.mod
go.sum		go.sum

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

BlockchainVPN: Decentralized VPN Marketplace

0. Support the development

1. Architecture Overview

Components

2. Protocol Specification

Service Announcement (Provider -> Network)

Payment & Authorization (Client -> Provider)

3. Application Logic

A. VPN Provider

B. VPN Client

4. Getting Started

Prerequisites

Installation

Configuration

Usage

For VPN Providers

For VPN Clients

5. Using Other Blockchains

6. Project Status

Feature Checklist (Implemented)

Known Limitations (Post-Beta)

How It Works

7. Project File Layout

About

Resources

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 11

Sponsor this project

Uh oh!

Contributors

Uh oh!

Languages