Abzu_Technical_Overview_v0.2.html
1 <!DOCTYPE html> 2 <html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang=""> 3 <head> 4 <meta charset="utf-8" /> 5 <meta name="generator" content="pandoc" /> 6 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" /> 7 <meta name="author" content="Adrian Murray" /> 8 <title>Abzu: A Sovereign Mesh Network Protocol</title> 9 <style> 10 /* Default styles provided by pandoc. 11 ** See https://pandoc.org/MANUAL.html#variables-for-html for config info. 12 */ 13 code{white-space: pre-wrap;} 14 span.smallcaps{font-variant: small-caps;} 15 div.columns{display: flex; gap: min(4vw, 1.5em);} 16 div.column{flex: auto; overflow-x: auto;} 17 div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;} 18 /* The extra [class] is a hack that increases specificity enough to 19 override a similar rule in reveal.js */ 20 ul.task-list[class]{list-style: none;} 21 ul.task-list li input[type="checkbox"] { 22 font-size: inherit; 23 width: 0.8em; 24 margin: 0 0.8em 0.2em -1.6em; 25 vertical-align: middle; 26 } 27 .display.math{display: block; text-align: center; margin: 0.5rem auto;} 28 /* CSS for syntax highlighting */ 29 html { -webkit-text-size-adjust: 100%; } 30 pre > code.sourceCode { white-space: pre; position: relative; } 31 pre > code.sourceCode > span { display: inline-block; line-height: 1.25; } 32 pre > code.sourceCode > span:empty { height: 1.2em; } 33 .sourceCode { overflow: visible; } 34 code.sourceCode > span { color: inherit; text-decoration: inherit; } 35 div.sourceCode { margin: 1em 0; } 36 pre.sourceCode { margin: 0; } 37 @media screen { 38 div.sourceCode { overflow: auto; } 39 } 40 @media print { 41 pre > code.sourceCode { white-space: pre-wrap; } 42 pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; } 43 } 44 pre.numberSource code 45 { counter-reset: source-line 0; } 46 pre.numberSource code > span 47 { position: relative; left: -4em; counter-increment: source-line; } 48 pre.numberSource code > span > a:first-child::before 49 { content: counter(source-line); 50 position: relative; left: -1em; text-align: right; vertical-align: baseline; 51 border: none; display: inline-block; 52 -webkit-touch-callout: none; -webkit-user-select: none; 53 -khtml-user-select: none; -moz-user-select: none; 54 -ms-user-select: none; user-select: none; 55 padding: 0 4px; width: 4em; 56 color: #aaaaaa; 57 } 58 pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; } 59 div.sourceCode 60 { } 61 @media screen { 62 pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; } 63 } 64 code span.al { color: #ff0000; font-weight: bold; } /* Alert */ 65 code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */ 66 code span.at { color: #7d9029; } /* Attribute */ 67 code span.bn { color: #40a070; } /* BaseN */ 68 code span.bu { color: #008000; } /* BuiltIn */ 69 code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */ 70 code span.ch { color: #4070a0; } /* Char */ 71 code span.cn { color: #880000; } /* Constant */ 72 code span.co { color: #60a0b0; font-style: italic; } /* Comment */ 73 code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */ 74 code span.do { color: #ba2121; font-style: italic; } /* Documentation */ 75 code span.dt { color: #902000; } /* DataType */ 76 code span.dv { color: #40a070; } /* DecVal */ 77 code span.er { color: #ff0000; font-weight: bold; } /* Error */ 78 code span.ex { } /* Extension */ 79 code span.fl { color: #40a070; } /* Float */ 80 code span.fu { color: #06287e; } /* Function */ 81 code span.im { color: #008000; font-weight: bold; } /* Import */ 82 code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */ 83 code span.kw { color: #007020; font-weight: bold; } /* Keyword */ 84 code span.op { color: #666666; } /* Operator */ 85 code span.ot { color: #007020; } /* Other */ 86 code span.pp { color: #bc7a00; } /* Preprocessor */ 87 code span.sc { color: #4070a0; } /* SpecialChar */ 88 code span.ss { color: #bb6688; } /* SpecialString */ 89 code span.st { color: #4070a0; } /* String */ 90 code span.va { color: #19177c; } /* Variable */ 91 code span.vs { color: #4070a0; } /* VerbatimString */ 92 code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */ 93 </style> 94 <link rel="stylesheet" href="https://cdn.simplecss.org/simple.min.css" /> 95 </head> 96 <body> 97 <header id="title-block-header"> 98 <h1 class="title">Abzu: A Sovereign Mesh Network Protocol</h1> 99 <p class="author">Adrian Murray</p> 100 <p class="date">January 2026</p> 101 </header> 102 <nav id="TOC" role="doc-toc"> 103 <ul> 104 <li><a href="#abzu-a-sovereign-mesh-network-protocol" 105 id="toc-abzu-a-sovereign-mesh-network-protocol">Abzu: A Sovereign Mesh 106 Network Protocol</a> 107 <ul> 108 <li><a href="#abstract" id="toc-abstract">Abstract</a></li> 109 <li><a href="#table-of-contents" id="toc-table-of-contents">Table of 110 Contents</a></li> 111 <li><a href="#vision-motivation" id="toc-vision-motivation">Vision & 112 Motivation</a></li> 113 <li><a href="#threat-model" id="toc-threat-model">Threat Model</a></li> 114 <li><a href="#architecture-overview" 115 id="toc-architecture-overview">Architecture Overview</a></li> 116 <li><a href="#core-components" id="toc-core-components">Core 117 Components</a></li> 118 <li><a href="#cryptographic-foundations" 119 id="toc-cryptographic-foundations">Cryptographic Foundations</a></li> 120 <li><a href="#transport-layer-faketls" 121 id="toc-transport-layer-faketls">Transport Layer: FakeTLS</a></li> 122 <li><a href="#routing-layer-geometric-routing" 123 id="toc-routing-layer-geometric-routing">Routing Layer: Geometric 124 Routing</a></li> 125 <li><a href="#wire-protocol" id="toc-wire-protocol">Wire 126 Protocol</a></li> 127 <li><a href="#content-addressed-storage" 128 id="toc-content-addressed-storage">Content-Addressed Storage</a></li> 129 <li><a href="#control-plane" id="toc-control-plane">Control 130 Plane</a></li> 131 <li><a href="#known-limitations-threat-surface" 132 id="toc-known-limitations-threat-surface">Known Limitations & Threat 133 Surface</a></li> 134 <li><a href="#current-status" id="toc-current-status">Current 135 Status</a></li> 136 <li><a href="#roadmap" id="toc-roadmap">Roadmap</a></li> 137 <li><a href="#design-principles" id="toc-design-principles">Design 138 Principles</a></li> 139 <li><a href="#references-prior-art" 140 id="toc-references-prior-art">References & Prior Art</a></li> 141 <li><a href="#license-philosophy" id="toc-license-philosophy">License 142 Philosophy</a></li> 143 <li><a href="#contact-contribution" 144 id="toc-contact-contribution">Contact & Contribution</a></li> 145 </ul></li> 146 </ul> 147 </nav> 148 <h1 id="abzu-a-sovereign-mesh-network-protocol">Abzu: A Sovereign Mesh 149 Network Protocol</h1> 150 <blockquote> 151 <p><strong>Technical Overview v0.2</strong> — January 2026<br /> 152 <em>A decentralized, censorship-resistant communication protocol built 153 entirely in Rust.</em></p> 154 <p><em>“The system should not depend on secrecy, and it should be 155 possible for it to fall into enemy hands without inconvenience.”</em> — 156 Auguste Kerckhoffs, 1883</p> 157 </blockquote> 158 <hr /> 159 <h2 id="abstract">Abstract</h2> 160 <p>Abzu is a multi-protocol mesh networking engine designed for 161 censorship resistance, privacy, and sovereignty. It combines geometric 162 routing techniques from overlay networks with content-addressed storage, 163 wrapped in a stealth transport layer that evades deep packet 164 inspection.</p> 165 <p>This document describes the architecture, threat model, design 166 decisions, and current implementation status.</p> 167 <hr /> 168 <h2 id="table-of-contents">Table of Contents</h2> 169 <ol type="1"> 170 <li><a href="#vision--motivation">Vision & Motivation</a></li> 171 <li><a href="#threat-model">Threat Model</a></li> 172 <li><a href="#architecture-overview">Architecture Overview</a></li> 173 <li><a href="#core-components">Core Components</a></li> 174 <li><a href="#cryptographic-foundations">Cryptographic 175 Foundations</a></li> 176 <li><a href="#transport-layer-faketls">Transport Layer: FakeTLS</a></li> 177 <li><a href="#routing-layer-geometric-routing">Routing Layer: Geometric 178 Routing</a></li> 179 <li><a href="#wire-protocol">Wire Protocol</a></li> 180 <li><a href="#content-addressed-storage">Content-Addressed 181 Storage</a></li> 182 <li><a href="#control-plane">Control Plane</a></li> 183 <li><a href="#known-limitations--threat-surface">Known Limitations & 184 Threat Surface</a></li> 185 <li><a href="#current-status">Current Status</a></li> 186 <li><a href="#roadmap">Roadmap</a></li> 187 <li><a href="#design-principles">Design Principles</a></li> 188 <li><a href="#references--prior-art">References & Prior Art</a></li> 189 </ol> 190 <hr /> 191 <h2 id="vision-motivation">Vision & Motivation</h2> 192 <h3 id="why-abzu-exists">Why Abzu Exists</h3> 193 <p>The internet was designed for resilience in wartime, but has evolved 194 into a centralized surveillance apparatus. DNS, TLS certificate 195 authorities, BGP, and cloud infrastructure create natural chokepoints 196 that enable both state and corporate censorship.</p> 197 <p>Abzu is designed to operate <strong>beneath</strong> this 198 infrastructure — using the existing internet as a transport substrate 199 while providing:</p> 200 <ul> 201 <li><strong>No central servers</strong> — No single point of failure or 202 coercion</li> 203 <li><strong>No tracking</strong> — No logs, no metadata collection, no 204 user accounts</li> 205 <li><strong>Encrypted tunnels</strong> — End-to-end encryption with 206 forward secrecy</li> 207 <li><strong>Censorship resistance</strong> — Traffic that looks like 208 normal HTTPS</li> 209 </ul> 210 <h3 id="design-philosophy">Design Philosophy</h3> 211 <p>Abzu follows the <strong>Sovereign OS</strong> principle: your 212 communication infrastructure should be something you <em>own</em>, not 213 something you <em>rent</em> from a corporation. It implements the 214 cryptographic equivalent of squatter’s rights on the internet.</p> 215 <h3 id="kerckhoffs-principle-open-design-security">Kerckhoffs’ 216 Principle: Open Design Security</h3> 217 <p>Abzu is designed to be <strong>safe to open-source</strong>. Its 218 security derives entirely from:</p> 219 <ol type="1"> 220 <li><strong>Cryptographic primitives</strong> (Ed25519, 221 ChaCha20-Poly1305, BLAKE3) — publicly audited</li> 222 <li><strong>Protocol design</strong> — documented in this paper</li> 223 <li><strong>Key secrecy</strong> — the <em>only</em> secret is your 224 private key</li> 225 </ol> 226 <p>An adversary with complete access to this document and the full 227 source code gains no advantage. The architecture assumes Kerckhoffs’ 228 Principle: security through obscurity is not security at all.</p> 229 <p>This is not a philosophical position — it’s an operational 230 requirement. The moment a protocol depends on implementation secrecy, it 231 becomes vulnerable to reverse engineering, insider leaks, or simple 232 observation. Abzu’s threat model assumes the adversary has read this 233 document.</p> 234 <hr /> 235 <h2 id="threat-model">Threat Model</h2> 236 <h3 id="who-are-we-defending-against">Who Are We Defending Against?</h3> 237 <table> 238 <colgroup> 239 <col style="width: 29%" /> 240 <col style="width: 32%" /> 241 <col style="width: 37%" /> 242 </colgroup> 243 <thead> 244 <tr> 245 <th>Adversary</th> 246 <th>Capability</th> 247 <th>Abzu Defense</th> 248 </tr> 249 </thead> 250 <tbody> 251 <tr> 252 <td><strong>ISP/Carrier</strong></td> 253 <td>Traffic logging, DNS hijacking, IP blocking</td> 254 <td>FakeTLS masquerade, geometric routing</td> 255 </tr> 256 <tr> 257 <td><strong>State Actor</strong></td> 258 <td>CALEA compliance, metadata analysis, BGP manipulation</td> 259 <td>No central infrastructure, cryptographic addressing</td> 260 </tr> 261 <tr> 262 <td><strong>Passive Observer</strong></td> 263 <td>Traffic pattern analysis, flow correlation</td> 264 <td>Length-prefixed encrypted frames, keepalive noise</td> 265 </tr> 266 <tr> 267 <td><strong>Active Attacker</strong></td> 268 <td>MITM injection, connection hijacking</td> 269 <td>Ed25519 identity verification, ChaCha20-Poly1305 AEAD</td> 270 </tr> 271 </tbody> 272 </table> 273 <h3 id="what-abzu-does-not-defend-against">What Abzu Does NOT Defend 274 Against</h3> 275 <blockquote> 276 <p>[!IMPORTANT] <strong>Honest Limitations — Read This 277 Section</strong></p> 278 </blockquote> 279 <ol type="1"> 280 <li><p><strong>Infrastructure-level attacks</strong>: If your ISP 281 physically disconnects you, or a state actor controls all network egress 282 points in a region, no overlay network can help. Abzu runs <em>over</em> 283 the existing internet, not around it.</p></li> 284 <li><p><strong>Traffic analysis at scale</strong>: A sufficiently 285 powerful adversary monitoring all network traffic globally can perform 286 timing correlation attacks. Abzu adds latency noise but does not 287 implement full mix-network anonymity (see: Nym, Tor).</p></li> 288 <li><p><strong>Endpoint compromise</strong>: If your device is 289 compromised (malware, physical access), the encryption is irrelevant. 290 Abzu assumes a trusted local environment.</p></li> 291 <li><p><strong>IANA/ARIN dependency</strong>: IP addresses are centrally 292 allocated. Abzu traffic still traverses the routed internet and is 293 subject to BGP-level blocking. This is a fundamental constraint of any 294 overlay network.</p></li> 295 <li><p><strong>CALEA and lawful intercept</strong>: While Abzu encrypts 296 traffic end-to-end, carriers in the US are required to provide intercept 297 capability at the network level. Abzu’s defense is that intercepted 298 traffic is encrypted and appears as normal TLS noise.</p></li> 299 </ol> 300 <p><strong>Philosophy</strong>: We are honest about what we can and 301 cannot do. Anyone claiming “total anonymity” is either lying or doesn’t 302 understand the problem space.</p> 303 <hr /> 304 <h2 id="architecture-overview">Architecture Overview</h2> 305 <pre><code>┌─────────────────────────────────────────────────────────────────┐ 306 │ Control Plane │ 307 │ JSON-RPC 2.0 (jsonrpsee) │ 308 └─────────────────────────┬───────────────────────────────────────┘ 309 │ 310 ┌─────────────────────────▼───────────────────────────────────────┐ 311 │ abzu-daemon │ 312 │ (CLI, Config, RPC Server) │ 313 └─────────────────────────┬───────────────────────────────────────┘ 314 │ 315 ┌───────────────┼───────────────┐ 316 │ │ │ 317 ┌─────────▼────┐ ┌───────▼──────┐ ┌─────▼─────────┐ 318 │ abzu-core │ │ abzu-router │ │ abzu-transport│ 319 │ ─────────────│ │ ─────────────│ │ ──────────────│ 320 │ Node Engine │ │ Spanning Tree│ │ AbzuFrame │ 321 │ Switchboard │ │ Coordinates │ │ FakeTLS │ 322 │ ContentStore │ │ Sovereign IP │ │ ChaCha20-Poly │ 323 │ (Sled+BLAKE3)│ │ Derivation │ │ │ 324 └──────────────┘ └──────────────┘ └───────────────┘</code></pre> 325 <h3 id="crate-structure">Crate Structure</h3> 326 <table> 327 <colgroup> 328 <col style="width: 20%" /> 329 <col style="width: 47%" /> 330 <col style="width: 32%" /> 331 </colgroup> 332 <thead> 333 <tr> 334 <th>Crate</th> 335 <th>Responsibility</th> 336 <th>Key Types</th> 337 </tr> 338 </thead> 339 <tbody> 340 <tr> 341 <td><strong>abzu-core</strong></td> 342 <td>Node lifecycle, peer management, event loop, storage</td> 343 <td><code>Node</code>, <code>Switchboard</code>, 344 <code>ContentStore</code></td> 345 </tr> 346 <tr> 347 <td><strong>abzu-router</strong></td> 348 <td>Pure-logic routing decisions (no I/O)</td> 349 <td><code>RoutingTable</code>, <code>TreeCoords</code>, 350 <code>Address</code></td> 351 </tr> 352 <tr> 353 <td><strong>abzu-transport</strong></td> 354 <td>Wire protocol, encryption, DPI evasion</td> 355 <td><code>AbzuFrame</code>, <code>FakeTlsStream</code>, 356 <code>AbzuInterface</code></td> 357 </tr> 358 <tr> 359 <td><strong>abzu-daemon</strong></td> 360 <td>CLI binary, configuration, RPC server</td> 361 <td><code>Config</code>, RPC method handlers</td> 362 </tr> 363 </tbody> 364 </table> 365 <hr /> 366 <h2 id="core-components">Core Components</h2> 367 <h3 id="node-engine-abzu-core">1. Node Engine 368 (<code>abzu-core</code>)</h3> 369 <p>The <code>Node</code> struct is the central state container:</p> 370 <div class="sourceCode" id="cb2"><pre 371 class="sourceCode rust"><code class="sourceCode rust"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">struct</span> Node <span class="op">{</span></span> 372 <span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a> identity<span class="op">:</span> SigningKey<span class="op">,</span> <span class="co">// Ed25519 private key</span></span> 373 <span id="cb2-3"><a href="#cb2-3" aria-hidden="true" tabindex="-1"></a> address<span class="op">:</span> Address<span class="op">,</span> <span class="co">// Derived sovereign IPv6</span></span> 374 <span id="cb2-4"><a href="#cb2-4" aria-hidden="true" tabindex="-1"></a> router<span class="op">:</span> Arc<span class="op"><</span>RwLock<span class="op"><</span>RoutingTable<span class="op">>>,</span></span> 375 <span id="cb2-5"><a href="#cb2-5" aria-hidden="true" tabindex="-1"></a> peers<span class="op">:</span> Arc<span class="op"><</span>Mutex<span class="op"><</span>HashMap<span class="op"><</span>PeerKey<span class="op">,</span> PeerConnection<span class="op">>>>,</span></span> 376 <span id="cb2-6"><a href="#cb2-6" aria-hidden="true" tabindex="-1"></a> store<span class="op">:</span> Db<span class="op">,</span> <span class="co">// Sled embedded database</span></span> 377 <span id="cb2-7"><a href="#cb2-7" aria-hidden="true" tabindex="-1"></a> chats<span class="op">:</span> Tree<span class="op">,</span> <span class="co">// Persistent message storage</span></span> 378 <span id="cb2-8"><a href="#cb2-8" aria-hidden="true" tabindex="-1"></a> contacts<span class="op">:</span> Tree<span class="op">,</span> <span class="co">// Address book</span></span> 379 <span id="cb2-9"><a href="#cb2-9" aria-hidden="true" tabindex="-1"></a> pending_fetches<span class="op">:</span> Arc<span class="op"><</span>DashMap<span class="op"><</span>[<span class="dt">u8</span><span class="op">;</span> <span class="dv">32</span>]<span class="op">,</span> Arc<span class="op"><</span>Notify<span class="op">>>>,</span></span> 380 <span id="cb2-10"><a href="#cb2-10" aria-hidden="true" tabindex="-1"></a> shutdown<span class="op">:</span> Arc<span class="op"><</span>Notify<span class="op">>,</span></span> 381 <span id="cb2-11"><a href="#cb2-11" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code></pre></div> 382 <p><strong>Key Design Decisions</strong>:</p> 383 <ul> 384 <li><strong>Ed25519 identity</strong>: All addressing is derived from 385 public keys. Your identity <em>is</em> your address.</li> 386 <li><strong>Tokio async runtime</strong>: Non-blocking event loop with 387 <code>select!</code> for multiplexed I/O</li> 388 <li><strong>Sled embedded DB</strong>: Local-first persistence with 389 atomic transactions</li> 390 <li><strong>DashMap for pending fetches</strong>: Lock-free concurrent 391 map for content discovery coordination</li> 392 </ul> 393 <h3 id="switchboard-abzu-coreswitchboard.rs">2. Switchboard 394 (<code>abzu-core/switchboard.rs</code>)</h3> 395 <p>Event dispatcher handling all frame types:</p> 396 <table> 397 <colgroup> 398 <col style="width: 66%" /> 399 <col style="width: 33%" /> 400 </colgroup> 401 <thead> 402 <tr> 403 <th>Incoming Frame</th> 404 <th>Action</th> 405 </tr> 406 </thead> 407 <tbody> 408 <tr> 409 <td><code>KeepAlive</code></td> 410 <td>Update peer activity timestamp</td> 411 </tr> 412 <tr> 413 <td><code>Chunk</code></td> 414 <td>Verify BLAKE3 hash, store in Sled, notify waiting fetches</td> 415 </tr> 416 <tr> 417 <td><code>Route</code></td> 418 <td>Check if target is local → process; else → forward to next hop</td> 419 </tr> 420 <tr> 421 <td><code>Request</code></td> 422 <td>Check local store; if found → send <code>Chunk</code> back to 423 requester</td> 424 </tr> 425 <tr> 426 <td><code>Chat</code></td> 427 <td>Decrypt, store in chat history, send <code>ChatAck</code></td> 428 </tr> 429 <tr> 430 <td><code>ChatAck</code></td> 431 <td>Mark corresponding outbound message as delivered</td> 432 </tr> 433 </tbody> 434 </table> 435 <h3 id="peer-connections">3. Peer Connections</h3> 436 <div class="sourceCode" id="cb3"><pre 437 class="sourceCode rust"><code class="sourceCode rust"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">struct</span> PeerConnection <span class="op">{</span></span> 438 <span id="cb3-2"><a href="#cb3-2" aria-hidden="true" tabindex="-1"></a> <span class="kw">pub</span> interface<span class="op">:</span> <span class="dt">Box</span><span class="op"><</span><span class="kw">dyn</span> AbzuInterface<span class="op">>,</span> <span class="co">// Trait object for transport agility</span></span> 439 <span id="cb3-3"><a href="#cb3-3" aria-hidden="true" tabindex="-1"></a> <span class="kw">pub</span> last_activity<span class="op">:</span> <span class="pp">std::time::</span>Instant<span class="op">,</span></span> 440 <span id="cb3-4"><a href="#cb3-4" aria-hidden="true" tabindex="-1"></a> <span class="kw">pub</span> tx_bytes<span class="op">:</span> <span class="dt">u64</span><span class="op">,</span></span> 441 <span id="cb3-5"><a href="#cb3-5" aria-hidden="true" tabindex="-1"></a> <span class="kw">pub</span> rx_bytes<span class="op">:</span> <span class="dt">u64</span><span class="op">,</span></span> 442 <span id="cb3-6"><a href="#cb3-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code></pre></div> 443 <p>The <code>AbzuInterface</code> trait enables transport swapping:</p> 444 <div class="sourceCode" id="cb4"><pre 445 class="sourceCode rust"><code class="sourceCode rust"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="at">#[</span>async_trait<span class="at">]</span></span> 446 <span id="cb4-2"><a href="#cb4-2" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">trait</span> AbzuInterface<span class="op">:</span> <span class="bu">Send</span> <span class="op">+</span> <span class="bu">Sync</span> <span class="op">{</span></span> 447 <span id="cb4-3"><a href="#cb4-3" aria-hidden="true" tabindex="-1"></a> <span class="kw">async</span> <span class="kw">fn</span> send(<span class="op">&</span><span class="kw">self</span><span class="op">,</span> data<span class="op">:</span> <span class="op">&</span>[<span class="dt">u8</span>]) <span class="op">-></span> <span class="dt">Result</span><span class="op"><</span>()<span class="op">,</span> TransportError<span class="op">>;</span></span> 448 <span id="cb4-4"><a href="#cb4-4" aria-hidden="true" tabindex="-1"></a> <span class="kw">async</span> <span class="kw">fn</span> recv(<span class="op">&</span><span class="kw">self</span>) <span class="op">-></span> <span class="dt">Result</span><span class="op"><</span><span class="dt">Vec</span><span class="op"><</span><span class="dt">u8</span><span class="op">>,</span> TransportError<span class="op">>;</span></span> 449 <span id="cb4-5"><a href="#cb4-5" aria-hidden="true" tabindex="-1"></a> <span class="kw">async</span> <span class="kw">fn</span> close(<span class="op">&</span><span class="kw">self</span>) <span class="op">-></span> <span class="dt">Result</span><span class="op"><</span>()<span class="op">,</span> TransportError<span class="op">>;</span></span> 450 <span id="cb4-6"><a href="#cb4-6" aria-hidden="true" tabindex="-1"></a> <span class="kw">fn</span> is_connected(<span class="op">&</span><span class="kw">self</span>) <span class="op">-></span> <span class="dt">bool</span><span class="op">;</span></span> 451 <span id="cb4-7"><a href="#cb4-7" aria-hidden="true" tabindex="-1"></a> <span class="kw">fn</span> local_addr(<span class="op">&</span><span class="kw">self</span>) <span class="op">-></span> <span class="dt">Option</span><span class="op"><</span><span class="dt">String</span><span class="op">>;</span></span> 452 <span id="cb4-8"><a href="#cb4-8" aria-hidden="true" tabindex="-1"></a> <span class="kw">fn</span> peer_addr(<span class="op">&</span><span class="kw">self</span>) <span class="op">-></span> <span class="dt">Option</span><span class="op"><</span><span class="dt">String</span><span class="op">>;</span></span> 453 <span id="cb4-9"><a href="#cb4-9" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code></pre></div> 454 <p>This allows the same node logic to work over TCP, UDP (future), QUIC 455 (future), or even LoRa (aspirational).</p> 456 <hr /> 457 <h2 id="cryptographic-foundations">Cryptographic Foundations</h2> 458 <h3 id="identity-ed25519">Identity: Ed25519</h3> 459 <p>Each node generates or loads an Ed25519 keypair on startup:</p> 460 <ul> 461 <li><strong>Private key</strong>: 32 bytes, never transmitted</li> 462 <li><strong>Public key</strong>: 32 bytes, serves as node 463 identifier</li> 464 <li><strong>Signature</strong>: 64 bytes, used for message 465 authentication</li> 466 </ul> 467 <p><strong>Why Ed25519?</strong></p> 468 <ul> 469 <li>Fast signing and verification (critical for high-throughput 470 routing)</li> 471 <li>Small key sizes</li> 472 <li>Deterministic signatures (no nonce management)</li> 473 <li>Widely audited and trusted</li> 474 </ul> 475 <h3 id="encryption-chacha20-poly1305">Encryption: ChaCha20-Poly1305</h3> 476 <p>All data encryption uses ChaCha20-Poly1305 AEAD:</p> 477 <ul> 478 <li><strong>ChaCha20</strong>: Stream cipher, constant-time, 479 software-friendly</li> 480 <li><strong>Poly1305</strong>: Authenticator tag prevents tampering</li> 481 <li><strong>Nonce</strong>: 12 bytes, unique per message</li> 482 </ul> 483 <p><strong>Why not AES-GCM?</strong></p> 484 <ul> 485 <li>ChaCha20 is faster in software (no AES-NI required)</li> 486 <li>More resistant to timing attacks</li> 487 <li>Preferred for embedded/mobile targets</li> 488 </ul> 489 <h3 id="hashing-blake3">Hashing: BLAKE3</h3> 490 <p>Content addressing uses BLAKE3:</p> 491 <ul> 492 <li><strong>Output</strong>: 32 bytes</li> 493 <li><strong>Speed</strong>: Fastest cryptographic hash available</li> 494 <li><strong>Merkle tree support</strong>: Built-in for chunked 495 content</li> 496 <li><strong>Keyed mode</strong>: Can be used as a MAC</li> 497 </ul> 498 <hr /> 499 <h2 id="transport-layer-faketls">Transport Layer: FakeTLS</h2> 500 <h3 id="problem-statement">Problem Statement</h3> 501 <p>Deep Packet Inspection (DPI) systems can identify and block 502 non-standard protocols. Even encrypted traffic can be fingerprinted by 503 packet sizes, timing, and handshake patterns.</p> 504 <h3 id="solution-tls-1.3-masquerade">Solution: TLS 1.3 Masquerade</h3> 505 <p>Abzu’s <code>FakeTlsStream</code> mimics a legitimate TLS 1.3 506 connection:</p> 507 <p><strong>Connection Phase:</strong></p> 508 <ol type="1"> 509 <li>Client sends a valid TLS 1.3 <code>ClientHello</code> with 510 randomized fields: 511 <ul> 512 <li>Random session ID</li> 513 <li>Legitimate cipher suites (AES-GCM, ChaCha20)</li> 514 <li>SNI extension with plausible hostname</li> 515 </ul></li> 516 <li>Server consumes and discards the <code>ClientHello</code> (we don’t 517 complete real TLS)</li> 518 <li>Both sides switch to Abzu’s encrypted frame protocol</li> 519 </ol> 520 <p><strong>Post-Handshake Frame Format:</strong></p> 521 <pre><code>[4 bytes: length (big-endian)] 522 [12 bytes: nonce] 523 [N bytes: ciphertext] 524 [16 bytes: Poly1305 tag]</code></pre> 525 <p><strong>DPI Evasion Properties:</strong></p> 526 <ul> 527 <li>Initial handshake looks like TLS 1.3</li> 528 <li>Frame lengths are consistent with TLS records</li> 529 <li>No distinguishing protocol headers after handshake</li> 530 <li>Keepalive frames add traffic noise</li> 531 </ul> 532 <h3 id="limitations">Limitations</h3> 533 <ul> 534 <li>Does not provide traffic analysis resistance (timing, volume 535 patterns)</li> 536 <li>Sophisticated adversaries may notice incomplete TLS handshake</li> 537 <li>SNI hostname is visible until encrypted (ECH would help, future 538 work)</li> 539 </ul> 540 <hr /> 541 <h2 id="routing-layer-geometric-routing">Routing Layer: Geometric 542 Routing</h2> 543 <h3 id="conceptual-model">Conceptual Model</h3> 544 <p>Traditional routing requires global coordination (BGP) or centralized 545 infrastructure (DNS). Overlay networks like Tor require directory 546 authorities.</p> 547 <p>Abzu uses <strong>geometric routing</strong> inspired by 548 Yggdrasil:</p> 549 <ol type="1"> 550 <li>The network forms a <strong>spanning tree</strong> rooted at the 551 most stable long-lived node</li> 552 <li>Each node has <strong>tree coordinates</strong>: a path from root 553 (e.g., <code>[2, 5, 1]</code> = “root → child 2 → child 5 → child 554 1”)</li> 555 <li>Routing decisions are made purely from local state — no global 556 knowledge required</li> 557 </ol> 558 <h3 id="sovereign-ip-derivation">Sovereign IP Derivation</h3> 559 <p>Every Ed25519 public key deterministically maps to an IPv6 address in 560 the <code>0200::/7</code> range:</p> 561 <div class="sourceCode" id="cb6"><pre 562 class="sourceCode rust"><code class="sourceCode rust"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="co">// Algorithm (from Yggdrasil):</span></span> 563 <span id="cb6-2"><a href="#cb6-2" aria-hidden="true" tabindex="-1"></a><span class="co">// 1. Invert the public key bytes</span></span> 564 <span id="cb6-3"><a href="#cb6-3" aria-hidden="true" tabindex="-1"></a><span class="co">// 2. Count leading 1 bits in inverted key</span></span> 565 <span id="cb6-4"><a href="#cb6-4" aria-hidden="true" tabindex="-1"></a><span class="co">// 3. Address format:</span></span> 566 <span id="cb6-5"><a href="#cb6-5" aria-hidden="true" tabindex="-1"></a><span class="co">// - Byte 0: PREFIX (0x02)</span></span> 567 <span id="cb6-6"><a href="#cb6-6" aria-hidden="true" tabindex="-1"></a><span class="co">// - Byte 1: Number of leading 1s</span></span> 568 <span id="cb6-7"><a href="#cb6-7" aria-hidden="true" tabindex="-1"></a><span class="co">// - Bytes 2-15: Remaining bits after stripping leading 1s and first 0</span></span> 569 <span id="cb6-8"><a href="#cb6-8" aria-hidden="true" tabindex="-1"></a></span> 570 <span id="cb6-9"><a href="#cb6-9" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> address_for_key(public_key<span class="op">:</span> <span class="op">&</span>VerifyingKey) <span class="op">-></span> Address <span class="op">{</span></span> 571 <span id="cb6-10"><a href="#cb6-10" aria-hidden="true" tabindex="-1"></a> <span class="co">// ... implementation</span></span> 572 <span id="cb6-11"><a href="#cb6-11" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code></pre></div> 573 <p><strong>Properties:</strong></p> 574 <ul> 575 <li><strong>Deterministic</strong>: Same key always produces same 576 address</li> 577 <li><strong>Self-certifying</strong>: The address <em>is</em> derived 578 from the public key</li> 579 <li><strong>Compact</strong>: Fits in standard IPv6 space</li> 580 <li><strong>Collision-resistant</strong>: Inherits cryptographic 581 properties of Ed25519</li> 582 </ul> 583 <h3 id="routing-algorithm">Routing Algorithm</h3> 584 <div class="sourceCode" id="cb7"><pre 585 class="sourceCode rust"><code class="sourceCode rust"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">enum</span> RouteDirection <span class="op">{</span></span> 586 <span id="cb7-2"><a href="#cb7-2" aria-hidden="true" tabindex="-1"></a> Self_<span class="op">,</span> <span class="co">// Destination reached</span></span> 587 <span id="cb7-3"><a href="#cb7-3" aria-hidden="true" tabindex="-1"></a> Up<span class="op">,</span> <span class="co">// Route to parent in tree</span></span> 588 <span id="cb7-4"><a href="#cb7-4" aria-hidden="true" tabindex="-1"></a> Down(<span class="dt">u32</span>)<span class="op">,</span> <span class="co">// Route to child at port N</span></span> 589 <span id="cb7-5"><a href="#cb7-5" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code></pre></div> 590 <p><strong>Tree Routing Priority:</strong></p> 591 <ol type="1"> 592 <li>If target is descendant → route down toward it</li> 593 <li>If target is ancestor → route up toward it</li> 594 <li>If target is neither (different branch) → route up to common 595 ancestor</li> 596 </ol> 597 <p><strong>Greedy Fallback:</strong> When tree routing fails (incomplete 598 tree, dynamic topology), XOR distance on addresses provides a greedy 599 fallback.</p> 600 <hr /> 601 <h2 id="wire-protocol">Wire Protocol</h2> 602 <h3 id="frame-types">Frame Types</h3> 603 <div class="sourceCode" id="cb8"><pre 604 class="sourceCode rust"><code class="sourceCode rust"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a><span class="at">#[</span>derive<span class="at">(</span><span class="bu">Debug</span><span class="op">,</span> <span class="bu">Clone</span><span class="op">,</span> Serialize<span class="op">,</span> Deserialize<span class="at">)]</span></span> 605 <span id="cb8-2"><a href="#cb8-2" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">enum</span> AbzuFrame <span class="op">{</span></span> 606 <span id="cb8-3"><a href="#cb8-3" aria-hidden="true" tabindex="-1"></a> KeepAlive<span class="op">,</span></span> 607 <span id="cb8-4"><a href="#cb8-4" aria-hidden="true" tabindex="-1"></a> Chunk <span class="op">{</span> cid<span class="op">:</span> [<span class="dt">u8</span><span class="op">;</span> <span class="dv">32</span>]<span class="op">,</span> data<span class="op">:</span> <span class="dt">Vec</span><span class="op"><</span><span class="dt">u8</span><span class="op">></span> <span class="op">},</span></span> 608 <span id="cb8-5"><a href="#cb8-5" aria-hidden="true" tabindex="-1"></a> Route <span class="op">{</span> target<span class="op">:</span> [<span class="dt">u8</span><span class="op">;</span> <span class="dv">32</span>]<span class="op">,</span> next_hop<span class="op">:</span> [<span class="dt">u8</span><span class="op">;</span> <span class="dv">32</span>]<span class="op">,</span> payload<span class="op">:</span> <span class="dt">Vec</span><span class="op"><</span><span class="dt">u8</span><span class="op">></span> <span class="op">},</span></span> 609 <span id="cb8-6"><a href="#cb8-6" aria-hidden="true" tabindex="-1"></a> Hello <span class="op">{</span> ephemeral_pub<span class="op">:</span> [<span class="dt">u8</span><span class="op">;</span> <span class="dv">32</span>]<span class="op">,</span> timestamp<span class="op">:</span> <span class="dt">u64</span> <span class="op">},</span></span> 610 <span id="cb8-7"><a href="#cb8-7" aria-hidden="true" tabindex="-1"></a> HelloAck <span class="op">{</span> ephemeral_pub<span class="op">:</span> [<span class="dt">u8</span><span class="op">;</span> <span class="dv">32</span>]<span class="op">,</span> confirmation<span class="op">:</span> <span class="dt">Vec</span><span class="op"><</span><span class="dt">u8</span><span class="op">></span> <span class="op">},</span></span> 611 <span id="cb8-8"><a href="#cb8-8" aria-hidden="true" tabindex="-1"></a> Request <span class="op">{</span> cid<span class="op">:</span> [<span class="dt">u8</span><span class="op">;</span> <span class="dv">32</span>]<span class="op">,</span> requester<span class="op">:</span> [<span class="dt">u8</span><span class="op">;</span> <span class="dv">32</span>] <span class="op">},</span></span> 612 <span id="cb8-9"><a href="#cb8-9" aria-hidden="true" tabindex="-1"></a> Chat <span class="op">{</span> id<span class="op">:</span> <span class="dt">u64</span><span class="op">,</span> to<span class="op">:</span> [<span class="dt">u8</span><span class="op">;</span> <span class="dv">32</span>]<span class="op">,</span> msg<span class="op">:</span> <span class="dt">Vec</span><span class="op"><</span><span class="dt">u8</span><span class="op">>,</span> timestamp<span class="op">:</span> <span class="dt">u64</span> <span class="op">},</span></span> 613 <span id="cb8-10"><a href="#cb8-10" aria-hidden="true" tabindex="-1"></a> ChatAck <span class="op">{</span> id<span class="op">:</span> <span class="dt">u64</span> <span class="op">},</span></span> 614 <span id="cb8-11"><a href="#cb8-11" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code></pre></div> 615 <h3 id="serialization-postcard">Serialization: Postcard</h3> 616 <p>Frames are serialized with <strong>postcard</strong>, a Rust-native 617 <code>no_std</code> compatible binary format:</p> 618 <ul> 619 <li><strong>Minimal overhead</strong>: Variable-length integers, no 620 field names</li> 621 <li><strong>Embedded-friendly</strong>: Works on microcontrollers 622 (future: LoRa mesh)</li> 623 <li><strong>Fast</strong>: Zero-copy deserialization where possible</li> 624 </ul> 625 <p><strong>Size Examples:</strong></p> 626 <ul> 627 <li><code>KeepAlive</code>: 1 byte</li> 628 <li><code>ChatAck { id: 42 }</code>: ~10 bytes</li> 629 <li><code>Chunk</code> with 1KB data: ~1040 bytes</li> 630 </ul> 631 <hr /> 632 <h2 id="content-addressed-storage">Content-Addressed Storage</h2> 633 <h3 id="design">Design</h3> 634 <p>All content is stored by its BLAKE3 hash (Content ID / CID):</p> 635 <div class="sourceCode" id="cb9"><pre 636 class="sourceCode rust"><code class="sourceCode rust"><span id="cb9-1"><a href="#cb9-1" aria-hidden="true" tabindex="-1"></a><span class="co">// Store content, return its CID</span></span> 637 <span id="cb9-2"><a href="#cb9-2" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> store_content(<span class="op">&</span><span class="kw">self</span><span class="op">,</span> data<span class="op">:</span> <span class="op">&</span>[<span class="dt">u8</span>]) <span class="op">-></span> <span class="dt">Result</span><span class="op"><</span>[<span class="dt">u8</span><span class="op">;</span> <span class="dv">32</span>]<span class="op">,</span> NodeError<span class="op">></span> <span class="op">{</span></span> 638 <span id="cb9-3"><a href="#cb9-3" aria-hidden="true" tabindex="-1"></a> <span class="kw">let</span> cid <span class="op">=</span> <span class="op">*</span><span class="pp">blake3::</span>hash(data)<span class="op">.</span>as_bytes()<span class="op">;</span></span> 639 <span id="cb9-4"><a href="#cb9-4" aria-hidden="true" tabindex="-1"></a> <span class="kw">self</span><span class="op">.</span>store<span class="op">.</span>insert(<span class="op">&</span>cid<span class="op">,</span> data)<span class="op">?;</span></span> 640 <span id="cb9-5"><a href="#cb9-5" aria-hidden="true" tabindex="-1"></a> <span class="cn">Ok</span>(cid)</span> 641 <span id="cb9-6"><a href="#cb9-6" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span> 642 <span id="cb9-7"><a href="#cb9-7" aria-hidden="true" tabindex="-1"></a></span> 643 <span id="cb9-8"><a href="#cb9-8" aria-hidden="true" tabindex="-1"></a><span class="co">// Retrieve by CID</span></span> 644 <span id="cb9-9"><a href="#cb9-9" aria-hidden="true" tabindex="-1"></a><span class="kw">pub</span> <span class="kw">fn</span> get_content(<span class="op">&</span><span class="kw">self</span><span class="op">,</span> cid<span class="op">:</span> <span class="op">&</span>[<span class="dt">u8</span><span class="op">;</span> <span class="dv">32</span>]) <span class="op">-></span> <span class="dt">Result</span><span class="op"><</span><span class="dt">Option</span><span class="op"><</span><span class="dt">Vec</span><span class="op"><</span><span class="dt">u8</span><span class="op">>>,</span> NodeError<span class="op">></span></span></code></pre></div> 645 <h3 id="storage-engine-sled">Storage Engine: Sled</h3> 646 <p>Sled is an embedded, pure-Rust key-value database:</p> 647 <ul> 648 <li><strong>ACID transactions</strong>: Atomic commits</li> 649 <li><strong>Lock-free reads</strong>: High concurrency</li> 650 <li><strong>Crash-safe</strong>: Write-ahead logging</li> 651 </ul> 652 <p><strong>Async Hazard Mitigation:</strong> Sled operations are 653 blocking. In async contexts, they’re wrapped with 654 <code>spawn_blocking</code>:</p> 655 <div class="sourceCode" id="cb10"><pre 656 class="sourceCode rust"><code class="sourceCode rust"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a><span class="pp">tokio::task::</span>spawn_blocking(<span class="kw">move</span> <span class="op">||</span> <span class="op">{</span></span> 657 <span id="cb10-2"><a href="#cb10-2" aria-hidden="true" tabindex="-1"></a> store<span class="op">.</span>insert(<span class="op">&</span>cid<span class="op">,</span> <span class="op">&</span>data)</span> 658 <span id="cb10-3"><a href="#cb10-3" aria-hidden="true" tabindex="-1"></a><span class="op">}</span>)<span class="op">.</span><span class="kw">await</span><span class="op">?</span></span></code></pre></div> 659 <h3 id="content-discovery-protocol">Content Discovery Protocol</h3> 660 <p>When a node requests content it doesn’t have locally:</p> 661 <pre><code> Requester Network Holder 662 │ │ │ 663 ├── Request{cid} ──────►│ │ 664 │ (broadcast to peers)│────────────────────────► 665 │ │ │ 666 │ │◄──── Chunk{cid, data} ─┤ 667 │◄── Chunk{cid, data} ──│ │ 668 │ │ │ 669 (verify hash, store locally)</code></pre> 670 <hr /> 671 <h2 id="control-plane">Control Plane</h2> 672 <h3 id="json-rpc-2.0-interface">JSON-RPC 2.0 Interface</h3> 673 <p>The daemon exposes a local RPC interface for integration with UIs and 674 other tools:</p> 675 <table> 676 <colgroup> 677 <col style="width: 24%" /> 678 <col style="width: 36%" /> 679 <col style="width: 39%" /> 680 </colgroup> 681 <thead> 682 <tr> 683 <th>Method</th> 684 <th>Parameters</th> 685 <th>Description</th> 686 </tr> 687 </thead> 688 <tbody> 689 <tr> 690 <td><code>get_info</code></td> 691 <td>—</td> 692 <td>Node identity, address, peer count, store stats</td> 693 </tr> 694 <tr> 695 <td><code>connect</code></td> 696 <td><code>addr: String</code></td> 697 <td>Initiate connection to peer</td> 698 </tr> 699 <tr> 700 <td><code>list_peers</code></td> 701 <td>—</td> 702 <td>Return active peer list with stats</td> 703 </tr> 704 <tr> 705 <td><code>upload_content</code></td> 706 <td><code>data: Base64</code></td> 707 <td>Store content, return CID</td> 708 </tr> 709 <tr> 710 <td><code>download_content</code></td> 711 <td><code>cid: Hex</code></td> 712 <td>Retrieve by CID (network fallback)</td> 713 </tr> 714 <tr> 715 <td><code>send_message</code></td> 716 <td><code>to: Hex, data: Base64</code></td> 717 <td>Route encrypted payload to target</td> 718 </tr> 719 <tr> 720 <td><code>send_chat</code></td> 721 <td><code>to: Hex, msg: String</code></td> 722 <td>Send persistent chat message</td> 723 </tr> 724 <tr> 725 <td><code>get_chat_history</code></td> 726 <td><code>peer: Hex</code></td> 727 <td>Retrieve message history</td> 728 </tr> 729 <tr> 730 <td><code>add_contact</code></td> 731 <td><code>alias: String, pubkey: Hex</code></td> 732 <td>Add to address book</td> 733 </tr> 734 <tr> 735 <td><code>get_contacts</code></td> 736 <td>—</td> 737 <td>List all contacts</td> 738 </tr> 739 <tr> 740 <td><code>shutdown</code></td> 741 <td>—</td> 742 <td>Graceful termination</td> 743 </tr> 744 </tbody> 745 </table> 746 <hr /> 747 <h2 id="known-limitations-threat-surface">Known Limitations & Threat 748 Surface</h2> 749 <h3 id="infrastructure-dependency">Infrastructure Dependency</h3> 750 <p>Abzu runs <em>over</em> the internet, not independently of it. This 751 means:</p> 752 <ul> 753 <li><strong>IANA/ARIN allocation</strong>: IP addresses are centrally 754 controlled</li> 755 <li><strong>ISP-level blocking</strong>: Sufficiently motivated 756 adversaries can block all traffic</li> 757 <li><strong>BGP manipulation</strong>: Route hijacking affects 758 underlying connectivity</li> 759 <li><strong>CALEA compliance</strong>: US carriers must enable lawful 760 intercept</li> 761 </ul> 762 <p><strong>Mitigation Strategy</strong>: Defense in depth. FakeTLS makes 763 traffic hard to identify. Geometric routing makes the network hard to 764 map. But we cannot defeat physics or law.</p> 765 <h3 id="traffic-analysis">Traffic Analysis</h3> 766 <p>Abzu encrypts content but does not fully anonymize traffic 767 patterns:</p> 768 <ul> 769 <li><strong>Timing correlation</strong>: When you send, responses 770 arrive</li> 771 <li><strong>Volume analysis</strong>: Large transfers are 772 noticeable</li> 773 <li><strong>Metadata leakage</strong>: Connection establishment reveals 774 peer relationships</li> 775 </ul> 776 <p><strong>Future Work</strong>: Integrate mix-network techniques 777 (constant-rate traffic, batching, delayed delivery).</p> 778 <h3 id="endpoint-security">Endpoint Security</h3> 779 <p>The weakest link is always the device itself:</p> 780 <ul> 781 <li>Compromised OS → compromised keys</li> 782 <li>Physical access → key extraction</li> 783 <li>Malware → all bets are off</li> 784 </ul> 785 <p><strong>Assumption</strong>: Users have trusted local 786 environments.</p> 787 <hr /> 788 <h2 id="current-status">Current Status</h2> 789 <h3 id="what-works-today-v0.1.0">What Works Today (v0.1.0)</h3> 790 <ul> 791 <li>✅ <strong>Node lifecycle</strong>: Create, run, shutdown 792 gracefully</li> 793 <li>✅ <strong>Peer connections</strong>: Connect, maintain, 794 disconnect</li> 795 <li>✅ <strong>FakeTLS transport</strong>: DPI-resistant encrypted 796 channels</li> 797 <li>✅ <strong>Wire protocol</strong>: All frame types implemented</li> 798 <li>✅ <strong>Content storage</strong>: BLAKE3-addressed local 799 store</li> 800 <li>✅ <strong>Content discovery</strong>: Request/Chunk protocol</li> 801 <li>✅ <strong>Chat messaging</strong>: Persistent encrypted messages 802 with delivery ACKs</li> 803 <li>✅ <strong>Contact management</strong>: Local address book</li> 804 <li>✅ <strong>JSON-RPC interface</strong>: Full control plane</li> 805 <li>✅ <strong>38 passing tests</strong>: Core functionality 806 verified</li> 807 </ul> 808 <h3 id="demonstrated-capability">Demonstrated Capability</h3> 809 <p><strong>First file teleportation</strong> between two nodes with:</p> 810 <ul> 811 <li>FakeTLS encrypted connection</li> 812 <li>Content-addressed storage</li> 813 <li>Verified BLAKE3 hash on retrieval</li> 814 </ul> 815 <hr /> 816 <h2 id="roadmap">Roadmap</h2> 817 <blockquote> 818 <p>[!NOTE] Timelines are intention, not commitment. This project moves 819 at the speed of focused execution.</p> 820 </blockquote> 821 <h3 id="foundation-current-phase">Foundation (Current Phase)</h3> 822 <ul class="task-list"> 823 <li><label><input type="checkbox" /><strong>Multi-hop routing</strong>: 824 Full spanning tree implementation</label></li> 825 <li><label><input type="checkbox" /><strong>Bootstrap nodes</strong>: 826 Well-known entry points for new nodes</label></li> 827 <li><label><input type="checkbox" /><strong>Key exchange 828 protocol</strong>: Perfect forward secrecy per session</label></li> 829 <li><label><input type="checkbox" /><strong>NAT traversal</strong>: 830 STUN/TURN integration for hole punching</label></li> 831 </ul> 832 <h3 id="expansion">Expansion</h3> 833 <ul class="task-list"> 834 <li><label><input type="checkbox" /><strong>UDP transport</strong>: 835 QUIC-style reliability over UDP</label></li> 836 <li><label><input type="checkbox" /><strong>Mobile clients</strong>: 837 iOS/Android via Rust FFI</label></li> 838 <li><label><input type="checkbox" /><strong>Desktop interface</strong>: 839 Native management and visualization</label></li> 840 <li><label><input type="checkbox" /><strong>Group messaging</strong>: 841 Multi-party encrypted chat</label></li> 842 </ul> 843 <h3 id="horizon-research-ready">Horizon (Research-Ready)</h3> 844 <ul class="task-list"> 845 <li><label><input type="checkbox" /><strong>LoRa transport</strong>: 846 Off-grid mesh for disaster/protest scenarios</label></li> 847 <li><label><input type="checkbox" /><strong>Mix-network 848 integration</strong>: Trade latency for stronger anonymity 849 (Nym-style)</label></li> 850 <li><label><input type="checkbox" /><strong>Threshold 851 cryptography</strong>: No single point of key compromise</label></li> 852 <li><label><input type="checkbox" /><strong>Incentive layer</strong>: 853 Optional economics for relay operators (if demand warrants)</label></li> 854 </ul> 855 <hr /> 856 <h2 id="design-principles">Design Principles</h2> 857 <h3 id="pure-logic-routing">1. Pure Logic Routing</h3> 858 <p>The routing layer (<code>abzu-router</code>) performs <strong>no 859 I/O</strong>. It takes state snapshots and returns decisions. This 860 enables:</p> 861 <ul> 862 <li>Deterministic testing</li> 863 <li>Easy reasoning about behavior</li> 864 <li>Separation from transport concerns</li> 865 </ul> 866 <h3 id="transport-agility">2. Transport Agility</h3> 867 <p>The <code>AbzuInterface</code> trait abstracts transport details. The 868 same node logic works over:</p> 869 <ul> 870 <li>TCP (current)</li> 871 <li>UDP (planned)</li> 872 <li>QUIC (planned)</li> 873 <li>LoRa (aspirational)</li> 874 </ul> 875 <h3 id="stealth-first">3. Stealth First</h3> 876 <p>Every design decision considers DPI evasion:</p> 877 <ul> 878 <li>FakeTLS masquerade</li> 879 <li>Randomized keepalive intervals</li> 880 <li>No protocol magic bytes</li> 881 <li>Variable-length frames</li> 882 </ul> 883 <h3 id="content-integrity">4. Content Integrity</h3> 884 <p>All stored and received data is verified against its hash before use. 885 No trust in transit.</p> 886 <h3 id="local-first">5. Local First</h3> 887 <p>Data is stored locally by default. The network is for discovery and 888 synchronization, not primary storage.</p> 889 <h3 id="async-safety">6. Async Safety</h3> 890 <p>All blocking operations (Sled, filesystem) are explicitly wrapped 891 with <code>spawn_blocking</code> to prevent runtime stalls.</p> 892 <hr /> 893 <h2 id="references-prior-art">References & Prior Art</h2> 894 <p>Abzu draws inspiration and techniques from:</p> 895 <table> 896 <thead> 897 <tr> 898 <th>Project</th> 899 <th>Contribution</th> 900 </tr> 901 </thead> 902 <tbody> 903 <tr> 904 <td><strong>Yggdrasil</strong></td> 905 <td>Spanning tree coordinates, sovereign IP derivation</td> 906 </tr> 907 <tr> 908 <td><strong>Iroh</strong></td> 909 <td>Content-addressed networking, BLAKE3 CIDs</td> 910 </tr> 911 <tr> 912 <td><strong>Reticulum</strong></td> 913 <td>Transport abstraction pattern, embedded-first design</td> 914 </tr> 915 <tr> 916 <td><strong>Tor</strong></td> 917 <td>Onion routing concepts (simplified in Abzu)</td> 918 </tr> 919 <tr> 920 <td><strong>Nym</strong></td> 921 <td>Mix-network principles (future integration)</td> 922 </tr> 923 <tr> 924 <td><strong>Automerge</strong></td> 925 <td>CRDT-based sync (planned for collaborative data)</td> 926 </tr> 927 </tbody> 928 </table> 929 <h3 id="academic-background">Academic Background</h3> 930 <ul> 931 <li><strong>Geometric routing</strong>: Kleinberg’s work on greedy 932 routing in small-world networks</li> 933 <li><strong>Spanning tree protocols</strong>: Perlman’s original IEEE 934 802.1D work</li> 935 <li><strong>Content-addressed storage</strong>: Git, IPFS, 936 BitTorrent</li> 937 </ul> 938 <hr /> 939 <h2 id="license-philosophy">License Philosophy</h2> 940 <p><strong>Current</strong>: MIT License — Adrian Murray, 2026</p> 941 <p>The core logic will be open sourced because <strong>this needs to 942 belong to everyone, not just one person</strong>.</p> 943 <h3 id="why-mit-for-now">Why MIT (for now)</h3> 944 <table> 945 <colgroup> 946 <col style="width: 47%" /> 947 <col style="width: 52%" /> 948 </colgroup> 949 <thead> 950 <tr> 951 <th>License</th> 952 <th>Tradeoff</th> 953 </tr> 954 </thead> 955 <tbody> 956 <tr> 957 <td><strong>GPL v3</strong></td> 958 <td>Strong copyleft, but creates friction for embedded/commercial 959 integration. Historically, some projects (e.g., pfSense) moved to BSD 960 specifically to escape GPL constraints.</td> 961 </tr> 962 <tr> 963 <td><strong>BSD/ISC</strong></td> 964 <td>Maximum permissiveness. Risk: adversaries can fork without 965 contributing back.</td> 966 </tr> 967 <tr> 968 <td><strong>MIT</strong></td> 969 <td>Functionally identical to BSD. Simple, widely understood, minimal 970 legal overhead.</td> 971 </tr> 972 </tbody> 973 </table> 974 <p>MIT is the current choice for simplicity and adoption. This may 975 evolve based on community input — particularly around whether a copyleft 976 variant better serves the sovereignty mission.</p> 977 <p>The key principle: <strong>the license should not be a barrier to 978 deployment in hostile environments</strong>. Someone running Abzu in a 979 protest camp shouldn’t need a lawyer.</p> 980 <hr /> 981 <h2 id="contact-contribution">Contact & Contribution</h2> 982 <p>When the repository goes public:</p> 983 <ul> 984 <li>GitHub: [TBD]</li> 985 <li>Threads: <span class="citation" 986 data-cites="adriancmurray">@adriancmurray</span></li> 987 </ul> 988 <p>For security issues, please use responsible disclosure.</p> 989 <hr /> 990 <p><em>“The best way to predict the future is to build it.” — Alan 991 Kay</em></p> 992 </body> 993 </html>