CJDNS Support

Configure Bitcoin Core to run on CJDNS, an encrypted IPv6 network with distributed routing

Overview

CJDNS is an encrypted IPv6 network that uses public-key cryptography for address allocation and a distributed hash table (DHT) for routing. It provides end-to-end encryption and protection from traffic analysis while maintaining the speed of direct connections.

CJDNS support was added to Bitcoin Core in version 23.0. It provides a complementary privacy option alongside Tor and I2P.

What is CJDNS?

CJDNS operates like a distributed, shared VPN:

• Encrypted routing: All traffic is end-to-end encrypted
• Public-key addresses: IPv6 addresses derived from public keys
• DHT routing: Decentralized routing via distributed hash table
• fc00::/8 range: Uses reserved IPv6 address space
• Multiple entry points: Connect through any peer
• Reach any participant: Direct connectivity to all network members

How CJDNS Differs from Other Networks

Feature	CJDNS	Tor	I2P
Speed	Fast (direct routing)	Medium	Slow
Encryption	End-to-end	Layered (onion)	Garlic routing
Anonymity	Source visible	Source hidden	Source visible
Centralization	Fully distributed	Directory authorities	Fully distributed
Traffic analysis	Protected	Protected	Protected
Filtering resistance	High	High	High

CJDNS is fast but does not hide the sender and recipient from intermediate routers. It’s best used for encrypted, censorship-resistant connectivity rather than anonymity.

Installation

1. Install CJDNS

   Follow the official installation guide:

   # Clone repository
   git clone https://github.com/cjdelisle/cjdns.git
   cd cjdns
   
   # Build
   ./do
   
   # Generate configuration
   ./cjdroute --genconf > cjdroute.conf
   

   Full instructions: How to Install CJDNS

2. Find a Peer

   You need to connect to at least one CJDNS peer. Use the Hyperboria peer finder:

   # Clone peer database
   git clone https://github.com/hyperboria/peers hyperboria-peers
   cd hyperboria-peers
   
   # Test available peers
   ./testAvailable.py
   

   The script will show available peers with ping results.

3. Configure Peer Connection

   Copy peer credentials from test results into your cjdroute.conf:

   // In cjdroute.conf, find the connectTo section:
   "connectTo":
   {
       "192.0.2.1:12345":
       {
           "login": "default-login",
           "password": "peer-password-here",
           "publicKey": "peer-public-key.k",
           "peerName": "peer-name"
       }
   }
   
4. Launch CJDNS

   As root (default):

   sudo ./cjdroute < cjdroute.conf
   

   As unprivileged user:

   Follow non-root user guide

5. Verify Connection

   # Check peer connections
   ./tools/peerStats
   
   # Should show connected peers with stats
   

Bitcoin Core Configuration

Once CJDNS is running, enabling Bitcoin Core support is simple:

bitcoind -cjdnsreachable

This single flag tells Bitcoin Core that:

• fc00::/8 addresses are CJDNS network addresses
• Not RFC4193 IPv6 local network addresses
• Should be treated as reachable Internet addresses

Why -cjdnsreachable is Required

The fc00::/8 range is normally reserved for IPv6 local networks (RFC4193). The -cjdnsreachable flag instructs Bitcoin Core to:

1. Treat incoming fc00::/8 connections as CJDNS (not local IPv6)
2. Gossip your fc00::/8 address to peers if you have one
3. Perform proper address management for CJDNS peers

Without this flag, Bitcoin Core would ignore CJDNS addresses as unreachable local addresses.

Configuration Options

Basic Configuration

# Enable CJDNS support
-cjdnsreachable

# CJDNS-only mode
-onlynet=cjdns

# Multiple privacy networks
-cjdnsreachable -onlynet=cjdns -onlynet=i2p -onlynet=onion

Example Configurations

CJDNS Only:

bitcoin.conf

cjdnsreachable=1
onlynet=cjdns

All Privacy Networks:

bitcoin.conf

# Tor
proxy=127.0.0.1:9050

# I2P
i2psam=127.0.0.1:7656

# CJDNS
cjdnsreachable=1

# Privacy networks only
onlynet=onion
onlynet=i2p
onlynet=cjdns

Multi-Network with CJDNS:

bitcoin.conf

cjdnsreachable=1
# No onlynet = use all available networks

Bridge Node:

bitcoin.conf

cjdnsreachable=1
listen=1
# Accessible from both CJDNS and clearnet

Monitoring and Verification

Check Your CJDNS Address

# CLI method
bitcoin-cli -netinfo

# RPC method  
bitcoin-cli getnetworkinfo

# Look for addresses starting with fc00::

Example CJDNS address: fc12:3456:789a:bcde:f012:3456:789a:bcde

View CJDNS Peers

# Detailed network info
bitcoin-cli -netinfo 4

# All peer info
bitcoin-cli getpeerinfo

# Known CJDNS addresses
bitcoin-cli getnodeaddresses 10 "cjdns"

# Address counts by network
bitcoin-cli -addrinfo

Verify CJDNS Connectivity

# From CJDNS directory
./tools/peerStats

# Should show active connections with bandwidth stats

Network Characteristics

Performance

CJDNS offers near-native performance:

• Speed: Comparable to direct Internet connections
• Latency: Low overhead from encryption
• Throughput: Not significantly limited by network
• Scalability: DHT routing scales well

CJDNS is the fastest privacy network option, making it ideal for bandwidth-intensive operations like initial blockchain download.

Privacy Properties

What CJDNS provides:

• End-to-end encryption
• Traffic analysis protection
• Censorship resistance
• Network filtering resistance

What CJDNS does NOT provide:

• Sender anonymity (intermediate routers see source)
• Receiver anonymity (intermediate routers see destination)
• Hiding communication patterns

CJDNS provides encryption and censorship resistance, not anonymity. Intermediate routers can see who is communicating with whom (but not the content).

Use Cases

Recommended Scenarios

1. Censorship circumvention: Access Bitcoin network despite filtering
2. Fast privacy option: Encrypted connections with minimal overhead
3. Multi-network redundancy: Fallback if other networks fail
4. Bridge operations: Connect privacy and clearnet networks
5. Initial sync: Faster than Tor/I2P for blockchain download

When to Combine Networks

Network Combinations:

• CJDNS + Tor: Speed + Anonymity
• CJDNS + I2P: Redundancy between fast and slow networks
• CJDNS + Clearnet: Bridge node with encryption option
• All privacy nets: Maximum redundancy and reach

Advanced Configuration

Multi-Network Privacy Node

bitcoin.conf

# Tor support
proxy=127.0.0.1:9050
listenonion=1

# I2P support
i2psam=127.0.0.1:7656
i2pacceptincoming=1

# CJDNS support
cjdnsreachable=1

# Privacy networks only
onlynet=onion
onlynet=i2p  
onlynet=cjdns

# Enable listening
listen=1

# Debug logging
debug=net
debug=tor
debug=i2p

CJDNS-Only Node

bitcoin.conf

cjdnsreachable=1
onlynet=cjdns
listen=1
bind=fc00::1  # Your CJDNS address

CJDNS + Clearnet Bridge

bitcoin.conf

cjdnsreachable=1
listen=1
discover=1
# No onlynet = accept all network types
# Acts as bridge between CJDNS and clearnet

Troubleshooting

CJDNS Not Running

Couldn't connect to fc00:: addresses

Solution:

# Check if CJDNS is running
ps aux | grep cjdroute

# Verify TUN interface exists
ip addr show | grep tun

# Check peer stats
cd /path/to/cjdns && ./tools/peerStats

No CJDNS Peers Found

# Check known CJDNS addresses
bitcoin-cli -addrinfo

# If zero, Bitcoin Core may not have discovered peers yet
# Try connecting to a known CJDNS Bitcoin node:
bitcoin-cli addnode "fc00::..." "add"

Permission Issues

If CJDNS fails to start:

# Run as root (default)
sudo ./cjdroute < cjdroute.conf

# Or configure for non-root user
# See: https://github.com/cjdelisle/cjdns/blob/master/doc/non-root-user.md

TUN Interface Issues

# Check TUN support
ls -la /dev/net/tun

# Should exist and be accessible
# If not, enable TUN module:
sudo modprobe tun

Security Considerations

Best Practices:

1. Keep CJDNS updated: Regular security updates
2. Monitor peer connections: Use peerStats regularly
3. Firewall rules: Ensure CJDNS ports are properly configured
4. Backup config: Save cjdroute.conf securely
5. Peer selection: Connect to trusted, reliable peers

Network Exposure Considerations

Running bridge nodes (CJDNS + clearnet) may allow correlation of identities through:

• Timing analysis
• Shared runtime characteristics
• Connection pattern analysis

Only use bridge mode if you don’t require strict identity separation.

Performance Tuning

CJDNS performance is generally good by default, but you can optimize:

Router Configuration

In cjdroute.conf:

// Increase peer connections for better routing
"maxConnections": 20,

// Enable beacon for local peer discovery (LAN only)
"beacon": 2,

// Security level (0-4, higher = slower but more secure)
"security": 2

Bitcoin Core Settings

bitcoin.conf

# More connections for CJDNS peers
maxconnections=150

# Enable CJDNS
cjdnsreachable=1

# Prioritize CJDNS (optional)
onlynet=cjdns

Resources and Documentation

CJDNS Documentation

• CJDNS GitHub
• Hyperboria Docs
• Hyperboria Peers
• Non-Root User Setup

Bitcoin Core Integration

• Bitcoin CJDNS Documentation
• Tor Integration
• I2P Integration

Comparison with Other Privacy Networks

When to Choose CJDNS

Choose CJDNS if you need:

• Fast encrypted connections
• Censorship resistance
• Low-latency operations
• Mesh network architecture

Choose Tor if you need:

• Strong sender anonymity
• Hidden services
• Widely deployed network

Choose I2P if you need:

• Fully decentralized architecture
• Long-lived connections
• Complementary to Tor

Best approach: Use multiple networks for redundancy and maximum reach.

See Also

• P2P Network - General network configuration
• Tor Support - Tor privacy network
• I2P Support - I2P privacy network
• ZMQ Notifications - Event notification system