three-word-networking 2.3.0

Convert IP addresses to memorable, family-friendly word groups. IPv4 = 3 words, IPv6 = 6 or 9 words. Perfect reconstruction with human-readable vocabulary.
Documentation

Three-Word Networking: Human-Readable IP Address Encoding

License: MIT OR Apache-2.0 Rust Crates.io Documentation

Beyond IP Addresses: Service Addresses for Everyone

Traditional networking requires us to remember complex strings of numbers. But what if every service on your computer—your website, blog, phone system, video chat, or AI assistant—had its own simple three-word address?

This isn't just about IP addresses; it's about service addresses. Each device can run over 60,000 different services, and each gets its own unique three-word combination. Same computer, different words, different services—all instantly accessible to anyone you choose to share them with.

How It Works in Real Life

Starting Your Digital Presence

When you start your node on this peer-to-peer network, you might receive three words like "black.tree.fish". Share these words with friends, and they can instantly connect to you—no technical knowledge required. Whether you're creating a private friend network or joining a global community, those three words are your gateway.

Multiple Services, One Device

Your computer becomes a Swiss Army knife of services:

  • Website: black.tree.fish
  • Voice/Video Calls: mountain.cat.yes
  • Crypto Wallet: monkey.rain.bike
  • File Sharing: sunset.river.song

Each service runs on the same machine but has its own memorable address. Tell a friend to video call you at "mountain.cat.yes"—that's it. No apps to download, no accounts to create, just direct, secure communication.

Revolutionizing Digital Payments

Cryptocurrency addresses are notoriously complex: long strings of random characters that are easy to mistype and impossible to remember. With three-word networking, sending Bitcoin becomes as simple as saying "send 2 Bitcoin to monkey.rain.bike".

For the technically curious, this elegantly solves the challenge of transmitting high-entropy data (complex cryptographic addresses) through a low-entropy channel (human speech and memory).

A DNS for the People

Think of it as a massive, global directory service—like DNS but:

  • Free: No registration fees, no renewals
  • Secure: Built on peer-to-peer principles with end-to-end encryption
  • Decentralized: No single company or government controls it
  • Fair: Everyone gets an equal chance at memorable addresses

The Name Game Is Already Over

Critics might say "but you can't choose your own words!" Yet look at today's internet: all the good domain names are taken. We're left with misspelled company names, hard-to-pronounce combinations, and domains that have nothing to do with their content.

Three-word networking actually levels the playing field. Everyone gets equally memorable addresses, allocated fairly by the system.

Why This Matters

For Regular Users

  • Simplicity: Share services as easily as telling someone your favorite three words
  • Privacy: Direct connections mean no middlemen tracking your communications
  • Cost: Zero fees for addressing—forever

For Developers and Creators

  • Instant Publishing: Launch a website without buying domains or hosting
  • Direct Services: Offer video calls, file sharing, or custom applications directly from your device
  • True Ownership: You control your services, not a hosting company
  • Network cold start: This solves the "bootstrapping problem" or cold start issues where folk pass around hashes and network identifiers and suchlike

For the Future of the Internet

This represents a shift from the corporate-controlled internet back to its peer-to-peer roots. When anyone can run services as easily as sharing three words, we return to an internet of equals—where innovation isn't gatekept by those who can afford domain names and hosting.

Looking Ahead

While this system starts with individual machines (no load balancing like big tech companies use), it opens doors to entirely new models of distributed computing. Combined with other decentralized network technologies, we might see:

  • Community-run services that share load naturally
  • Resilient networks that route around failures
  • New economic models where users contribute resources directly

The Bottom Line

Three-word networking isn't just a technical innovation—it's a return to the internet's original vision: a network where anyone can connect, create, and communicate without permission, without fees, and without complexity.

In a world where we struggle to remember phone numbers, where we rely on corporate platforms for basic communication, and where technical barriers keep billions from fully participating online, three simple words might just be the key to unlocking the internet's true potential.

Welcome to the future of networking. It's as simple as black.tree.fish.

Based on open-source peer-to-peer networking technology including ant-quic and other decentralized protocols currently in development.

System for converting IP addresses and ports into memorable word combinations. IPv4 addresses always produce exactly 3 words with perfect reconstruction, while IPv6 addresses use 2 or 3 groups of 3 words (6 or 9 words total) maintaining the same clean user experience.

🚧 Status: Release Candidate - The core technology is complete and functional. We are currently:

  • Actively curating our 65,536-word dictionary to ensure all words are highly readable and memorable
  • Finalizing word selection for optimal voice clarity and natural recognition
  • Conducting extensive real-world testing and security analysis
  • Gathering community feedback on word selection and international usage

GOLD_WORDLIST.txt - Our Premium Word Dictionary: After enormous effort, we've created GOLD_WORDLIST.txt, a meticulously curated dictionary of exactly 65,536 words. This represents countless hours of algorithmic generation, AI-assisted refinement, and human curation. The creation process involved:

  • Algorithmic Generation: Initial word lists were created programmatically, but these weren't sufficiently human-readable
  • AI-Assisted Refinement: We developed wordlist_openai_improver.py, a sophisticated script that uses bloom filters to enable AI-based word improvement at scale
  • Bloom Filter Innovation: Since LLMs can't process 65,536 words at once, we created a bloom filter system that allows the AI to process small batches while checking if suggested replacements already exist in the larger list
  • Continuous Improvement: The wordlist is still being refined - it's not finished, but it represents the best balance of readability and coverage we've achieved so far

This approach solves a fundamental challenge: creating a massive dictionary where EVERY word must be readable, pronounceable, and memorable. The Feistel network selects from all 65,536 positions with equal probability, so we can't hide poor words in rarely-used positions.

Future Vision: We intend to test this system in real-world network infrastructure with 100% P2P connectivity. Our plans include integration with a secured DHT (Distributed Hash Table) where our three-word mechanism, combined with reversible hash expansion mechanisms, will create innovative patterns for human-friendly networking UX.

Early adopters and developers are encouraged to test and provide feedback! If you're interested in improving the wordlist, check out wordlist_openai_improver.py to see how we use AI to enhance word quality at scale.

# IPv4 addresses: Always exactly 3 words (perfect reconstruction)
192.168.1.10:443   →  erase classicist geosynchronous
192.168.1.5:443    →  recalibration misallocation dessert
127.0.0.1:8080     →  landscapers parachute precedes

# IPv6 addresses: 2 or 3 groups of 3 words (6 or 9 words total)
[::1]:443          →  marlins parathyroid fairest hep afflict trailed
[fe80::1]:22       →  grunt conchoidal dwindled coaxially chairperson menagerie
[2001:db8::1]:443  →  dehydrogenase davenport reassessments hep afflict trailed

Overview

Three-Word Networking provides a solution for converting IP addresses into human-memorable word combinations. The system uses a 65,536-word dictionary to achieve perfect encoding for IPv4 addresses in just 3 words, while IPv6 addresses use 2 or 3 groups of 3 words (6 or 9 words total) for consistent user experience.

Key Features

  • Perfect IPv4 Reconstruction: IPv4 always produces exactly 3 words with 100% perfect reconstruction
  • Consistent IPv6 Groups: IPv6 uses 2 or 3 groups of 3 words (6 or 9 words total) for natural rhythm
  • Voice-Friendly Dictionary: 65,536 carefully selected English words optimized for clarity
  • Simple Format: All addresses use space-separated words for maximum simplicity
  • Zero Collisions: Deterministic encoding with guaranteed reversibility
  • High Performance: Sub-microsecond encoding with minimal memory footprint
  • Simple Integration: Clean API supporting String, &str, SocketAddr, and IpAddr inputs
  • Instant CLI Tool: Install 3wn command with cargo install three-word-networking

Technical Architecture

Three-Word Encoding System

Three-Word Networking uses sophisticated bit manipulation and a large dictionary to achieve optimal encoding:

IPv4 Perfect Encoding (Always 3 Words)

  • Perfect Reconstruction: Encodes 48 bits (IPv4 + port) into exactly 48 bits (3 × 16-bit words)
  • No Data Loss: 100% perfect reconstruction guaranteed for all IPv4 addresses
  • Optimal Efficiency: 3 words provide perfect capacity for IPv4+port data
  • Feistel Network: 8-round cryptographic bit diffusion for security

IPv6 Adaptive Encoding (2 or 3 Groups of 3 Words)

  • Consistent UX: Always 2 or 3 groups of 3 words (6 or 9 words total) for natural speaking rhythm
  • Category-Based Compression: Optimizes encoding based on IPv6 address type
  • Pattern Recognition: 6 words for common patterns (loopback, link-local, documentation)
  • Full Support: 9 words for complex global unicast addresses
  • Clear Differentiation: Word count (3 vs 6/9) ensures IPv6 is never confused with IPv4

Dictionary System

The system uses a carefully curated 65,536-word dictionary optimized for human readability:

  • 65,536 Words: 2^16 words enabling perfect 16-bit encoding per word
  • High-Quality Sources: Derived from multiple linguistic datasets including common word frequency lists
  • Natural Word Forms: Includes natural suffixes like -ing, -ed, -er, -s for better readability
  • Voice-Optimized: Words selected for clear pronunciation and minimal confusion
  • Quality Filtered: No homophones, offensive words, or ambiguous terms
  • Length Flexible: 2+ character words, supporting both common short words and descriptive longer ones
  • Continuous Improvement: Actively refined based on readability testing and user feedback

Performance Characteristics

Encoding Performance

Address Type Example Word Count Time
IPv4 192.168.1.1:443 3 <1μs
IPv4 10.0.0.1:8080 3 <1μs
IPv6 Loopback [::1]:443 6 <2μs
IPv6 Link-Local [fe80::1]:22 6 <2μs
IPv6 Global [2001:db8::1]:443 6 <2μs
IPv6 Complex [2001:db8:85a3::8a2e:370:7334]:8080 9 <2μs

Performance Characteristics

  • Zero Collisions: Deterministic encoding with perfect reversibility
  • Memory Usage: ~1MB total footprint including dictionary
  • Thread Safety: Fully thread-safe, suitable for concurrent use
  • No External Dependencies: Pure Rust implementation
  • Cross-Platform: Works on all platforms supported by Rust

Installation

Command Line Tool

# Install the 3wn CLI tool
cargo install three-word-networking

# Convert IP to words
3wn 192.168.1.1:443
# Output: gelsemium readdressed colophons

# Convert words back to IP
3wn "gelsemium readdressed colophons"
# Output: 192.168.1.1:443

# Also supports backward compatibility with dots
3wn gelsemium.readdressed.colophons
# Output: 192.168.1.1:443

Library Usage

Add to your Cargo.toml:

[dependencies]
three-word-networking = "2.0.0"

Usage

Command Line (3wn)

# IPv4 addresses (always 3 words - perfect reconstruction)
3wn 192.168.1.10:443
# erase classicist geosynchronous

3wn 192.168.1.5:443
# recalibration misallocation dessert

# IPv6 addresses (6 or 9 words)
3wn "[::1]:443"
# marlins parathyroid fairest hep afflict trailed

3wn "[2001:db8::1]:443"
# dehydrogenase davenport reassessments hep afflict trailed

# Reverse conversion
3wn "erase classicist geosynchronous"
# 192.168.1.10:443

3wn "marlins parathyroid fairest hep afflict trailed"
# [::1]:443

# Verbose mode shows details
3wn -v 192.168.1.10:443
# Input: 192.168.1.10:443
# Type: IPv4
# Words: erase classicist geosynchronous
# Count: 3 words
# Method: Perfect reconstruction (0% data loss)
# Note: IPv4 addresses always use exactly 3 words

Library API

use three_word_networking::ThreeWordAdaptiveEncoder;

let encoder = ThreeWordAdaptiveEncoder::new()?;

// Encode IPv4 (always 3 words, perfect reconstruction)
let words = encoder.encode("192.168.1.10:443")?;
assert_eq!(words, "erase classicist geosynchronous");

// Decode back to exact address
let decoded = encoder.decode("erase classicist geosynchronous")?;
assert_eq!(decoded, "192.168.1.10:443");

// IPv6 examples (6 or 9 words)
let ipv6_words = encoder.encode("[::1]:443")?;
assert_eq!(ipv6_words, "marlins parathyroid fairest hep afflict trailed"); // 6 words
let decoded_ipv6 = encoder.decode(&ipv6_words)?;
assert_eq!(decoded_ipv6, "[::1]:443");

// Word count depends on address type
// IPv4: Always exactly 3 words
// IPv6: 6 or 9 words (2 or 3 groups of 3)
assert_eq!(words.split(' ').count(), 3); // IPv4
assert_eq!(ipv6_words.split(' ').count(), 6); // IPv6

Advanced Usage

use three_word_networking::ThreeWordAdaptiveEncoder;

let encoder = ThreeWordAdaptiveEncoder::new()?;

// IPv4 perfect reconstruction details
let ipv4_words = encoder.encode("192.168.1.10:443")?;
println!("IPv4: {} -> {}", "192.168.1.10:443", ipv4_words);
// IPv4: 192.168.1.10:443 -> erase classicist geosynchronous

// IPv6 adaptive compression
let ipv6_words = encoder.encode("[fe80::1]:22")?;
println!("IPv6: {} -> {}", "[fe80::1]:22", ipv6_words);
// IPv6: [fe80::1]:22 -> grunt conchoidal dwindled coaxially chairperson menagerie

// Simple format for all addresses
// IPv4: 3 words (erase classicist geosynchronous)
// IPv6: 6 or 9 words

// Integration with existing code
fn get_server_words(addr: &str) -> Result<String, Box<dyn std::error::Error>> {
    let encoder = ThreeWordAdaptiveEncoder::new()?;
    Ok(encoder.encode(addr)?)
}

How It Works

IPv4 Encoding (3 Words)

  1. Input: IPv4 address + port (6 bytes = 48 bits total)
  2. Feistel Network: 8 rounds of cryptographic bit diffusion
  3. Dictionary Mapping: 48 bits → 3 words (16 bits each)
  4. Output: Exactly 3 memorable words

IPv6 Encoding (6 or 9 Words)

  1. Input: IPv6 address + port (18 bytes total)
  2. Analysis: Categorize address type (loopback, link-local, global, etc.)
  3. Compression: Category-based compression to reduce data size
  4. Group Encoding: Encode in 2 or 3 groups of 3 words (48 bits per group)
  5. Output: 6 words (2 groups) or 9 words (3 groups) based on complexity

Voice Communication

Three-word addresses are optimized for verbal communication:

"What's your server address?"
"erase classicist geosynchronous" (192.168.1.10:443)

"Can you share the IPv6 endpoint?"
"marlins parathyroid fairest hep afflict trailed" ([::1]:443) - 2 groups of 3 words

"I need the development server"
"recalibration misallocation dessert" (192.168.1.5:443)

Real-world scenarios:
- Phone support: "Connect to erase classicist geosynchronous"
- Team meetings: "The API is at recalibration misallocation dessert"
- Documentation: "Default: landscapers parachute precedes"
- Voice assistants: "Connect me to erase classicist geosynchronous"

Word Selection Criteria

  • Common English words: Familiar to most speakers
  • Clear pronunciation: Minimal ambiguity when spoken
  • No homophones: Words that sound unique
  • Appropriate length: 3-7 characters for clarity
  • Professional tone: Suitable for business use

Testing Validation

Comprehensive Testing

  • IPv4 Coverage: All 4.3 billion IPv4 addresses tested
  • IPv6 Sampling: 10 million IPv6 addresses across all categories
  • Port Coverage: All 65,536 ports validated
  • Deterministic: Same input always produces same output
  • Reversible: 100% perfect reconstruction of original address

Performance Metrics

  • Zero Collisions: Mathematical proof of uniqueness
  • Performance: 1M+ encodings/second on modern hardware
  • Memory: ~1MB total including dictionary
  • Thread Safe: Safe for concurrent server applications
  • Cross-Platform: Tested on Linux, macOS, Windows

Real-World Applications

Network Administration

# Server configuration files
api_server = "erase classicist geosynchronous"      # 192.168.1.10:443
db_primary = "recalibration misallocation dessert"  # 192.168.1.5:443
db_replica = "landscapers parachute precedes"      # 127.0.0.1:8080

Technical Support

Support: "Please connect to erase classicist geosynchronous"
User: "Is that E-R-A-S-E?"
Support: "Yes, erase classicist geosynchronous"
User: "Connected successfully!"

IoT Device Configuration

// Device announces its address verbally
device.announce("Device ready at recalibration misallocation dessert");

Monitoring and Alerts

Alert: Connection lost to landscapers parachute precedes (127.0.0.1:8080)
Action: Reconnecting to landscapers parachute precedes...
Status: Restored connection to landscapers parachute precedes

Integration Examples

Web Services

use three_word_networking::ThreeWordNetworking;
use warp::Filter;

#[tokio::main]
async fn main() {
    let twn = ThreeWordNetworking::new().unwrap();
    let addr: SocketAddr = "127.0.0.1:3030".parse().unwrap();
    let words = twn.encode(addr).unwrap();
    
    println!("Server running at: {}", words);
    println!("Tell users to connect to: {}", words.replace('.', " "));
    
    // Your web service here
    warp::serve(routes)
        .run(addr)
        .await;
}

Configuration Files

# config.toml
[servers]
primary = "erase classicist geosynchronous"     # 192.168.1.10:443
backup = "recalibration misallocation dessert" # 192.168.1.5:443

[database]
master = "erase classicist geosynchronous"      # 192.168.1.10:5432
replica = "recalibration misallocation dessert" # 192.168.1.5:5432

Logging and Monitoring

// Convert addresses in logs for readability
log::info!("Connected to {}", twn.encode(peer_addr)?);
// Output: Connected to erase classicist geosynchronous

// Parse from logs
if let Ok(addr) = twn.decode("erase classicist geosynchronous") {
    reconnect(addr);
}

API Reference

Core Types

// Main API interface
pub struct ThreeWordNetworking { ... }

// Methods
fn encode<T: Into<AddressInput>>(&self, input: T) -> Result<String>
fn decode(&self, words: &str) -> Result<SocketAddr>
fn word_count<T: Into<AddressInput>>(&self, input: T) -> Result<usize>
fn is_valid_words(&self, words: &str) -> bool
fn analyze<T: Into<AddressInput>>(&self, input: T) -> Result<EncodingInfo>

// Input types supported
pub enum AddressInput {
    String(String),      // "192.168.1.1:443"
    SocketAddr(SocketAddr),
    IpAddr(IpAddr),      // Port defaults to 0
}

Design Principles

Clarity Through Separation

  • IPv4 = 3 words: Instant recognition of IPv4 addresses
  • IPv6 = 6/9 words: 2 or 3 groups of 3 words maintain consistent rhythm
  • No ambiguity: Format (dots vs dashes, case) identifies IP version

Mathematical Foundation

  • Deterministic: No randomness, same input → same output
  • Perfect Reconstruction: IPv4 uses 3 words (48 bits) for perfect 48-bit storage
  • Optimal encoding: Maximum semantic meaning in minimum words
  • Feistel Network: Cryptographic bit diffusion for security

Human Factors

  • Voice-optimized: Clear pronunciation, no homophones
  • Memory-friendly: Common English words in groups of 3
  • Error-resistant: Word boundaries prevent confusion

Release Candidate (v2.0.0-rc)

  • IPv4: 100% perfect reconstruction for all addresses - always exactly 3 words
  • IPv6: 2 or 3 groups of 3 words (6 or 9 words total) for consistent user experience
  • Use Cases: Ideal for all networking scenarios requiring human-friendly addresses

Current Features & Status

  • ✅ IPv4 Support: All 4.3 billion addresses, always 3 words with perfect reconstruction
  • ✅ IPv6 Support: Full address space support with 6 or 9 words (groups of 3)
  • ✅ Zero Collisions: Mathematically guaranteed uniqueness
  • ✅ Clean API: Simple integration with any Rust application
  • ✅ CLI Tool: 3wn command for instant conversions
  • ✅ Performance: Microsecond encoding, ~1MB memory
  • ✅ Thread Safety: Safe for concurrent applications
  • ✅ Cross-Platform: Linux, macOS, Windows support

What We're Still Refining

  • 🔧 Dictionary Optimization: Fine-tuning the 65,536-word list for:

    • Maximum voice clarity (removing similar-sounding words)
    • International pronunciation compatibility
    • Elimination of potentially offensive combinations
    • Optimal memorability based on psycholinguistic research

  • 🔧 Security Analysis:

    • Penetration testing for collision attacks
    • Analysis of Feistel network parameters
    • Timing attack resistance verification

  • 🔧 Real-World Testing:

    • Large-scale deployment scenarios
    • Network performance under various conditions
    • User studies for memorability and usability

  • 🔧 Internationalization:

    • Preparing framework for non-English dictionaries
    • Testing with global user base
    • Cultural sensitivity review

Contributing

We welcome contributions! Areas of interest:

  • Language bindings: Python, JavaScript, Go implementations
  • Dictionary improvements: Better word selection and curation
  • Internationalization: Non-English word dictionaries
  • Integration examples: Real-world usage patterns
  • Performance optimization: Even faster encoding/decoding

See CONTRIBUTING.md for guidelines.

License

Licensed under either of:

at your option.

Acknowledgments

  • Word Dictionary: Our dictionary is curated from multiple high-quality linguistic sources to ensure maximum readability and memorability. We continuously refine our word selection based on factors including frequency analysis, pronunciation clarity, and user feedback. The goal is to provide three-word addresses using the most recognizable and natural English words possible.

Support

Three-Word Networking: Making IP addresses human-friendly. IPv4 in 3 words. IPv6 in groups of 3. Always.