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)
This commit is contained in:
parent
76b05c7f49
commit
722c5fafba
17
README.md
17
README.md
|
|
@ -68,16 +68,25 @@ The Libertaria SDK provides the foundational L0 (Transport) and L1 (Identity/Cry
|
||||||
## Layers
|
## Layers
|
||||||
|
|
||||||
### L0: Transport Layer
|
### L0: Transport Layer
|
||||||
**Module:** `l0-transport/`
|
**Module:** `l0-transport/` | **Index:** `l0_transport.zig`
|
||||||
|
|
||||||
Implements the core wire protocol:
|
Implements the core wire protocol:
|
||||||
- **LWF Frame Codec** - Encode/decode wire frames
|
- **LWF Frame Codec** - Encode/decode wire frames (RFC-0000, 72-byte header)
|
||||||
- **UTCP** - Reliable transport over UDP (future)
|
- **Sovereign Time** - L0 transport timestamps (u64 nanoseconds)
|
||||||
- **Frame Validation** - Checksum, signature verification
|
- **Frame Validation** - Checksum, signature verification
|
||||||
- **Priority Queues** - Traffic shaping
|
- **Priority Queues** - Traffic shaping (future)
|
||||||
|
|
||||||
**Key Files:**
|
**Key Files:**
|
||||||
|
- `l0_transport.zig` - **Sovereign Index** (re-exports all L0 modules)
|
||||||
- `lwf.zig` - LWF frame structure and codec
|
- `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)
|
- `utcp.zig` - UTCP transport (future)
|
||||||
- `validation.zig` - Frame validation logic
|
- `validation.zig` - Frame validation logic
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
|
|
@ -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());
|
||||||
|
}
|
||||||
|
|
@ -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
|
||||||
|
|
@ -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());
|
||||||
|
}
|
||||||
Loading…
Reference in New Issue