From 722c5fafba33c9cb253d680c9e7d2bedf8c5188e Mon Sep 17 00:00:00 2001 From: Markus Maiwald Date: Fri, 30 Jan 2026 22:28:55 +0100 Subject: [PATCH] docs: Add Panopticum Phase 1 - Sovereign Indexes and layer docs Non-breaking changes to align with Panopticum repository architecture: - Add Sovereign Indexes (l0_transport.zig, l1_identity.zig) - Single import point for each layer - Re-export all layer modules - Add layer README files - l0-transport/README.md: LWF and Time documentation - l1-identity/README.md: All L1 components documented - AI-friendly, colocated documentation - Update root README.md - Add Sovereign Index usage examples - Update L0 component list Benefits: - Simplified imports: `const l0 = @import("l0_transport.zig");` - Self-contained layer documentation for AI agents - Zero breaking changes (existing imports still work) Phase 1 complete. Deferred: Feature folders, colocated tests (Phase 2-3) --- README.md | 17 ++++-- l0-transport/README.md | 78 ++++++++++++++++++++++++ l0_transport.zig | 11 ++++ l1-identity/README.md | 131 +++++++++++++++++++++++++++++++++++++++++ l1_identity.zig | 17 ++++++ 5 files changed, 250 insertions(+), 4 deletions(-) create mode 100644 l0-transport/README.md create mode 100644 l0_transport.zig create mode 100644 l1-identity/README.md create mode 100644 l1_identity.zig diff --git a/README.md b/README.md index f63619c..3c9a77e 100644 --- a/README.md +++ b/README.md @@ -68,16 +68,25 @@ The Libertaria SDK provides the foundational L0 (Transport) and L1 (Identity/Cry ## Layers ### L0: Transport Layer -**Module:** `l0-transport/` +**Module:** `l0-transport/` | **Index:** `l0_transport.zig` Implements the core wire protocol: -- **LWF Frame Codec** - Encode/decode wire frames -- **UTCP** - Reliable transport over UDP (future) +- **LWF Frame Codec** - Encode/decode wire frames (RFC-0000, 72-byte header) +- **Sovereign Time** - L0 transport timestamps (u64 nanoseconds) - **Frame Validation** - Checksum, signature verification -- **Priority Queues** - Traffic shaping +- **Priority Queues** - Traffic shaping (future) **Key Files:** +- `l0_transport.zig` - **Sovereign Index** (re-exports all L0 modules) - `lwf.zig` - LWF frame structure and codec +- `time.zig` - Time primitives + +**Quick Start:** +```zig +const l0 = @import("l0_transport.zig"); +var frame = try l0.lwf.LWFFrame.init(allocator, 1024); +frame.header.timestamp = l0.time.nowNanoseconds(); +``` - `utcp.zig` - UTCP transport (future) - `validation.zig` - Frame validation logic diff --git a/l0-transport/README.md b/l0-transport/README.md new file mode 100644 index 0000000..23453c8 --- /dev/null +++ b/l0-transport/README.md @@ -0,0 +1,78 @@ +# L0 Transport Layer + +**Layer:** L0 (Transport) +**Purpose:** Wire protocols, frame encoding, time primitives +**RFCs:** RFC-0000 (LWF), RFC-0105 (Time L0 component) + +--- + +## Overview + +The L0 Transport layer provides low-level wire protocol implementations for the Libertaria network. It handles packet framing, serialization, and transport-layer timestamps. + +## Components + +### LWF (Libertaria Wire Frame) - `lwf.zig` +**RFC:** RFC-0000 +**Size:** 72-byte header + payload + 36-byte trailer + +Wire protocol implementation with: +- Fixed 72-byte header (24-byte DID hints, u64 nanosecond timestamp) +- Variable payload (1092-8892 bytes depending on frame class) +- 36-byte trailer (Ed25519 signature + CRC32 checksum) +- Frame classes (Constrained, Standard, Ethernet, Bulk, Jumbo) + +**Key Types:** +- `LWFHeader` - 72-byte fixed header +- `LWFTrailer` - 36-byte signature + checksum +- `LWFFrame` - Complete frame wrapper +- `FrameClass` - Size negotiation enum + +### Time - `time.zig` +**RFC:** RFC-0105 (L0 component) +**Precision:** u64 nanoseconds (584-year range) + +Transport-layer time primitives: +- `u64` nanosecond timestamps for drift detection +- Monotonic clock access +- Replay protection timestamps + +**Note:** L1 uses full `SovereignTimestamp` (u128 attoseconds) for causal ordering. + +--- + +## Usage + +```zig +const l0 = @import("l0_transport.zig"); + +// Create LWF frame +var frame = try l0.lwf.LWFFrame.init(allocator, 1024); +defer frame.deinit(allocator); + +// Set header fields +frame.header.service_type = 0x0700; // Vector message +frame.header.timestamp = l0.time.nowNanoseconds(); + +// Encode for transport +const encoded = try frame.encode(allocator); +defer allocator.free(encoded); +``` + +--- + +## Testing + +Run L0 tests: +```bash +zig test l0-transport/lwf.zig +zig test l0-transport/time.zig +``` + +--- + +## Dependencies + +- `std.mem` - Memory management +- `std.crypto` - CRC32, hashing +- `std.time` - System time access diff --git a/l0_transport.zig b/l0_transport.zig new file mode 100644 index 0000000..dc4d24b --- /dev/null +++ b/l0_transport.zig @@ -0,0 +1,11 @@ +const std = @import("std"); + +// Re-export LWF (Libertaria Wire Frame) +pub const lwf = @import("l0-transport/lwf.zig"); + +// Re-export Time primitives +pub const time = @import("l0-transport/time.zig"); + +test { + std.testing.refAllDecls(@This()); +} diff --git a/l1-identity/README.md b/l1-identity/README.md new file mode 100644 index 0000000..7a0e870 --- /dev/null +++ b/l1-identity/README.md @@ -0,0 +1,131 @@ +# L1 Identity Layer + +**Layer:** L1 (Identity) +**Purpose:** Decentralized identity, cryptography, trust graphs, vectors +**RFCs:** RFC-0105 (Sovereign Time), RFC-0120 (QVL) + +--- + +## Overview + +The L1 Identity layer provides cryptographic identity primitives, trust relationship management, and the QuasarVector Lattice (QVL) for event-driven consensus. + +## Components + +### DID (Decentralized Identifiers) - `did.zig` +**Spec:** `did:libertaria:...` format + +DID generation and parsing: +- Blake3-based DID derivation from public keys +- 24-byte routing hints (192-bit) +- Base58 encoding for human readability + +### SoulKey (Identity Keys) - `soulkey.zig` +**Crypto:** Ed25519 + +Core identity keypair management: +- Key generation, storage, derivation +- Signing and verification +- Seed phrase support + +### QuasarVector - `vector.zig` +**RFC:** RFC-0120 + +Event lattice vectors: +- Ed25519 signatures +- `SovereignTimestamp` (u128 attoseconds) +- Proof-of-Path integration +- Vector validation pipeline + +### TrustGraph - `trust_graph.zig` +**Pattern:** Web-of-trust + +Decentralized trust relationships: +- Trust grant/revoke operations +- Path finding (Dijkstra) +- Trust weight calculation +- Graph serialization + +### ProofOfPath - `proof_of_path.zig` +**RFC:** RFC-0120 + +Trust path verification: +- Multi-hop signature chains +- Path expiration checking +- Hop limit enforcement + +### Entropy - `entropy.zig` +**RFC:** RFC-0100 + +Entropy stamps for Sybil resistance: +- Blake3-based proof-of-work +- Difficulty calibration (0-255) +- Verification logic + +### Crypto - `crypto.zig` +Cryptographic primitives wrapper: +- Ed25519 (signing) +- X25519 (key exchange) +- Blake3 (hashing) +- XChaCha20-Poly1305 (encryption) + +### Argon2 - `argon2.zig` +**FFI:** C library wrapper + +Password hashing: +- Argon2id for SoulKey seed derivation +- Memory-hard KDF + +### PQXDH - `pqxdh.zig` +**Protocol:** Post-Quantum Extended Diffie-Hellman + +Future-proof key exchange: +- Hybrid classical + PQ security +- X25519 + Kyber integration (planned) + +### PreKey - `prekey.zig` +**Protocol:** X3DH prekey bundles + +Asynchronous messaging: +- Prekey bundle generation +- Signal-style forward secrecy + +--- + +## Usage + +```zig +const l1 = @import("l1_identity.zig"); + +// Generate identity +const soulkey = try l1.soulkey.SoulKey.generate(allocator); +const did = try l1.did.fromPublicKey(&soulkey.public_key); + +// Create vector +var vector = try l1.vector.QuasarVector.create(allocator, soulkey, payload_data); +defer vector.deinit(allocator); + +// Sign and verify +try vector.sign(soulkey); +const valid = vector.verifySignature(); +``` + +--- + +## Testing + +Run L1 tests: +```bash +zig build test +# Or individual modules: +zig test l1-identity/vector.zig +zig test l1-identity/trust_graph.zig +``` + +--- + +## Dependencies + +- `std.crypto` - Ed25519, X25519, Blake3 +- `vendor/argon2/` - Argon2 C library +- L0 Time (`time.zig`) - SovereignTimestamp diff --git a/l1_identity.zig b/l1_identity.zig new file mode 100644 index 0000000..a44ae7e --- /dev/null +++ b/l1_identity.zig @@ -0,0 +1,17 @@ +const std = @import("std"); + +// Re-export Identity modules +pub const did = @import("l1-identity/did.zig"); +pub const soulkey = @import("l1-identity/soulkey.zig"); +pub const vector = @import("l1-identity/vector.zig"); +pub const trust_graph = @import("l1-identity/trust_graph.zig"); +pub const proof_of_path = @import("l1-identity/proof_of_path.zig"); +pub const entropy = @import("l1-identity/entropy.zig"); +pub const crypto = @import("l1-identity/crypto.zig"); +pub const argon2 = @import("l1-identity/argon2.zig"); +pub const pqxdh = @import("l1-identity/pqxdh.zig"); +pub const prekey = @import("l1-identity/prekey.zig"); + +test { + std.testing.refAllDecls(@This()); +}