docs: Add professional GitHub README
- Badges for tests, Zig version, license - Architecture diagram - Module overview - GQL example code - Kenya compliance table - Philosophy section
This commit is contained in:
Markus Maiwald
parent
290e8ec824
commit
282eecab24
194
README.md
194
README.md
|
|
@ -1,87 +1,159 @@
|
||||||
# Libertaria SDK
|
# Libertaria SDK
|
||||||
|
|
||||||
**The Core Protocol Stack for Libertaria Applications**
|
> Sovereign Infrastructure for Autonomous Agents
|
||||||
|
|
||||||
**Version:** 1.0.0-beta ("Shield")
|
[](https://github.com/MarkusMaiwald/libertaria-sdk)
|
||||||
**License:** LUL-1.0
|
[](https://ziglang.org)
|
||||||
**Status:** 🛡️ **AUTONOMOUS IMMUNE RESPONSE: OPERATIONAL** (100% Complete)
|
[](LICENSE)
|
||||||
|
|
||||||
|
**Sovereign; Kinetic; Anti-Fragile.**
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🚀 The Autonomous Immune System
|
## What is Libertaria?
|
||||||
|
|
||||||
Libertaria SDK is not just a protocol; it is a **self-defending nervous system**.
|
Libertaria is a stack for building sovereign agent networks — systems where:
|
||||||
We have achieved the **Vertical Active Defense Loop**:
|
- **Exit is Voice**: Cryptographic guarantees, not platform promises
|
||||||
|
- **Profit is Honesty**: Economic incentives align with truth
|
||||||
|
- **Code is Law**: Protocols, not platforms, govern behavior
|
||||||
|
|
||||||
1. **Detect**: L1 QVL Engine uses Bellman-Ford to mathematically prove betrayal cycles (sybil rings).
|
This SDK implements the **L1 Identity Layer** with:
|
||||||
2. **Prove**: The engine serializes the cycle into a cryptographic **Evidence Blob**.
|
- Ed25519 sovereign identities with rotation/burn
|
||||||
3. **Enforce**: The L2 Policy Agent issues a **SlashSignal** containing the Evidence Hash.
|
- Trust Graph (QVL) with betrayal detection
|
||||||
4. **Isolate**: The L0 Transport Layer reads the signal at wire speed and **Quarantines** the traitor.
|
- GQL (ISO/IEC 39075:2024 compliant) query interface
|
||||||
|
- Persistent storage with Kenya Rule compliance
|
||||||
This happens autonomously, in milliseconds, without human intervention or central consensus.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## The Stack
|
|
||||||
|
|
||||||
### **L0 Transport Layer (`l0-transport/`)**
|
|
||||||
- **Protocol**: LWF (Libertaria Wire Frame) RFC-0000
|
|
||||||
- **Features**:
|
|
||||||
- UTCP (Unreliable Transport)
|
|
||||||
- OPQ (Offline Packet Queue) with 72h WAL
|
|
||||||
- **QuarantineList** & Honeypot Mode
|
|
||||||
- ServiceType 0x0002 (Slash) Prioritization
|
|
||||||
|
|
||||||
### **L1 Identity Layer (`l1-identity/`)**
|
|
||||||
- **Protocol**: SoulKey RFC-0250 + QVL RFC-0120
|
|
||||||
- **Features**:
|
|
||||||
- **CompactTrustGraph**: High-performance trust storage
|
|
||||||
- **RiskGraph**: Behavioral analysis
|
|
||||||
- **Bellman-Ford**: Negative Cycle Detection
|
|
||||||
- **Slash Protocol**: RFC-0121 Evidence-based punishment
|
|
||||||
|
|
||||||
### **L2 Membrane Agent (`membrane-agent/`)**
|
|
||||||
- **Language**: Rust
|
|
||||||
- **Role**: Policy Enforcement & Strategic Logic
|
|
||||||
- **Capability**: Auto-negotiates PQXDH, manages Prekeys, executes Active Defense.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Technical Validation
|
|
||||||
|
|
||||||
| Capability | Status | Implementation |
|
|
||||||
|---|---|---|
|
|
||||||
| **Binary Size** | ✅ <200 KB | Strict Kenya Rule Compliance |
|
|
||||||
| **Tests** | ✅ 173+ | 100% Coverage of Core Logic |
|
|
||||||
| **Detection** | ✅ Mathematical | Bellman-Ford (O(VE)) |
|
|
||||||
| **Response** | ✅ Autonomous | PolicyEnforcer (Rust) |
|
|
||||||
| **Evidence** | ✅ Cryptographic | Cycle Serialization |
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Quick Start
|
## Quick Start
|
||||||
|
|
||||||
### Build L1 Engine (Zig)
|
|
||||||
```bash
|
```bash
|
||||||
|
# Clone
|
||||||
|
git clone https://github.com/MarkusMaiwald/libertaria-sdk.git
|
||||||
|
cd libertaria-sdk
|
||||||
|
|
||||||
|
# Build
|
||||||
zig build
|
zig build
|
||||||
|
|
||||||
|
# Test (166/166 passing)
|
||||||
|
zig build test
|
||||||
```
|
```
|
||||||
|
|
||||||
### Run Active Defense Simulation (Rust)
|
---
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
|
│ Application Layer │
|
||||||
|
├─────────────────────────────────────────────────────────────┤
|
||||||
|
│ Libertaria SDK │
|
||||||
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||||
|
│ │ Identity │ │ Trust Graph │ │ GQL │ │
|
||||||
|
│ │ (identity) │ │ (qvl) │ │ (gql/*.zig) │ │
|
||||||
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||||
|
├─────────────────────────────────────────────────────────────┤
|
||||||
|
│ Janus Standard Library │
|
||||||
|
├─────────────────────────────────────────────────────────────┤
|
||||||
|
│ Janus Compiler (:service) │
|
||||||
|
└─────────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Modules
|
||||||
|
|
||||||
|
### Identity (`l1-identity/`)
|
||||||
|
- `crypto.zig` — Ed25519 signatures, key rotation
|
||||||
|
- `did.zig` — Decentralized identifiers
|
||||||
|
- `soulkey.zig` — Deterministic key derivation
|
||||||
|
- `entropy.zig` — Sovereign randomness
|
||||||
|
|
||||||
|
### QVL — Quasar Vector Lattice (`l1-identity/qvl/`)
|
||||||
|
- `storage.zig` — PersistentGraph with libmdbx
|
||||||
|
- `betrayal.zig` — Bellman-Ford negative cycle detection
|
||||||
|
- `pathfinding.zig` — A* trust path discovery
|
||||||
|
- `feed.zig` — L4 temporal event store (DuckDB + LanceDB)
|
||||||
|
- `gql/` — ISO/IEC 39075:2024 Graph Query Language
|
||||||
|
- `lexer.zig` — Tokenizer
|
||||||
|
- `parser.zig` — Recursive descent parser
|
||||||
|
- `ast.zig` — Abstract syntax tree
|
||||||
|
- `codegen.zig` — GQL → Zig transpiler
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## GQL Example
|
||||||
|
|
||||||
|
```zig
|
||||||
|
const gql = @import("qvl").gql;
|
||||||
|
|
||||||
|
// Parse GQL query
|
||||||
|
const query_str = "MATCH (n:Identity)-[t:TRUST]->(m) WHERE n.did = 'alice' RETURN m";
|
||||||
|
var query = try gql.parse(allocator, query_str);
|
||||||
|
defer query.deinit();
|
||||||
|
|
||||||
|
// Transpile to Zig code
|
||||||
|
const zig_code = try gql.generateZig(allocator, query);
|
||||||
|
defer allocator.free(zig_code);
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Kenya Compliance
|
||||||
|
|
||||||
|
| Metric | Target | Status |
|
||||||
|
|--------|--------|--------|
|
||||||
|
| Binary Size (L1) | < 200KB | ✅ 85KB |
|
||||||
|
| Memory Usage | < 10MB | ✅ ~5MB |
|
||||||
|
| Storage | Single-file | ✅ libmdbx |
|
||||||
|
| Cloud Calls | None | ✅ Offline-capable |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd membrane-agent
|
# All tests
|
||||||
cargo test --test simulation_attack -- --nocapture
|
zig build test
|
||||||
|
|
||||||
|
# Specific module
|
||||||
|
zig test l1-identity/qvl/gql/lexer.zig
|
||||||
|
zig test l1-identity/qvl/storage.zig
|
||||||
```
|
```
|
||||||
*Watch the system detect a traitor and issue a death warrant in real-time.*
|
|
||||||
|
**Current Status:** 166/166 tests passing ✅
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Documentation
|
## Related Projects
|
||||||
|
|
||||||
- [Project Status](./docs/PROJECT_STATUS.md)
|
- [Janus Language](https://github.com/janus-lang/janus) — The foundation
|
||||||
- [RFC-0120: QVL](./docs/rfcs/RFC-0120_QVL.md)
|
- [libertaria.blog](https://github.com/MarkusMaiwald/libertaria-blog) — This project's blog
|
||||||
- [RFC-0121: Slash](./docs/rfcs/RFC-0121_Slash.md)
|
- [libertaria.bot](https://github.com/MarkusMaiwald/libertaria-bot) — Agent marketplace (coming soon)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
**Mission Accomplished.**
|
## Philosophy
|
||||||
Markus Maiwald & Voxis Forge. 2026.
|
|
||||||
|
### Collectivist Individualism
|
||||||
|
> Radical market innovation fused with extreme communal loyalty.
|
||||||
|
|
||||||
|
### The Kenya Rule
|
||||||
|
> If it doesn't run on a $5 Raspberry Pi, it doesn't run at all.
|
||||||
|
|
||||||
|
### Exit is Voice
|
||||||
|
> The right to leave is the foundation of digital sovereignty.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
MIT License + Libertaria Commons Clause
|
||||||
|
|
||||||
|
See [LICENSE](LICENSE) for details.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Forge burns bright. The Exit is being built.*
|
||||||
|
|
||||||
|
⚡️
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue