1  # Abzu Wire Protocol Reference
 2  
 3  > **Transport Layer — Frames, Versioning, and Encoding**
 4  > *Source: WIRE_PROTOCOL_API.md*
 5  
 6  ---
 7  
 8  ## 1. The Stack
 9  
10  The Abzu wire protocol is designed for high-throughput, low-overhead encrypted mesh networking.
11  
12  | Layer | Technology | Role |
13  |-------|------------|------|
14  | **Data** | Rust Enums | Type-safe logic |
15  | **Serialization** | `postcard` | `no_std` zero-copy varint encoding (smaller than Protobuf) |
16  | **Security** | ChaCha20-Poly1305 | Authenticated Encryption (AEAD) |
17  | **Transport** | FakeTLS | 0-RTT Session Setup (`0x17 0x03 0x03` record masking) |
18  
19  ---
20  
21  ## 2. The Frame: `AbzuFrame`
22  
23  Every packet on the wire decodes to an `AbzuFrame` enum.
24  
25  ```rust
26  pub enum AbzuFrame {
27      // 1. Core
28      KeepAlive,
29      
30      // 2. Handshake (Versioning)
31      Hello { version_major: u16, ephemeral_pub: [u8; 32] },
32      HelloAck { version_major: u16, confirmation: Vec<u8> },
33  
34      // 3. Routing
35      Route { target: [u8; 32], payload: Vec<u8> }, // Onion skin
36  
37      // 4. Content
38      Chunk { cid: [u8; 32], data: Vec<u8> },
39      
40      // 5. Social
41      Chat { msg: Vec<u8> },
42      CircleMessage { circle_id: [u8; 32], content: Vec<u8> },
43  
44      // 6. Privacy
45      Cover { noise: Vec<u8> }, // Ghost Mode padding
46  }
47  ```
48  
49  ---
50  
51  ## 3. Protocol Versioning
52  
53  Abzu uses a "Negotiate-Down" strategy.
54  
55  1. **Initiator** sends `Hello(v1.2)`.
56  2. **Responder** checks compatibility.
57      - If compatible: Responds `HelloAck(v1.2)`.
58      - If too old: Responds `HelloAck(v1.0)`.
59      - If incompatible: Responds `HelloAck(v0.0)` (Force close).
60  
61  ---
62  
63  ## 4. Onion Routing (The `Route` Frame)
64  
65  Routing is recursive. A node receiving a `Route` frame:
66  
67  1. Checks `target`.
68  2. If `target == self`: Decrypts `payload` as inner `AbzuFrame` and processes it.
69  3. If `target != self`: Forwards `payload` to `target`.
70  
71  This allows nested "Onion Wrapping" for multi-hop privacy.
72  
73  ---
74  
75  ## 5. Security & Size Limits
76  
77  - **Max Frame Size**: 65,535 bytes (u16 max).
78  - **Encryption**: All frames are encrypted. The wire sees no cleartext types.
79  - **Padding**: Variable length padding hides exact content size (Ghost Mode).