Libertaria SDK

The Core Protocol Stack for Libertaria Applications

Version: 0.1.0-alpha License: TBD Language: Zig 0.15.x Status: 🎖️ 50% COMPLETE (Phases 1-2D Done) ⚡ Aggressive Delivery

Latest Milestone: 2026-01-30 - Phase 2D Complete, 51/51 tests passing, 26-35 KB binaries

---

What is Libertaria SDK?

The Libertaria SDK provides the foundational L0 (Transport) and L1 (Identity/Crypto) layers for building Libertaria-compatible applications.

It implements:

• RFC-0000: Libertaria Wire Frame Protocol (LWF)
• RFC-0100: Entropy Stamps (anti-spam PoW)
• RFC-0110: Membrane Agent primitives
• RFC-0250: Larval Identity Protocol (SoulKey)

Design Goals:

• ✅ Kenya-compliant: <200 KB binary size
• ✅ Static linking: No runtime dependencies
• ✅ Cross-platform: ARM, MIPS, RISC-V, x86, WebAssembly
• ✅ Zero-copy: Efficient packet processing
• ✅ Auditable: Clear, explicit code

---

Project Status: 50% Milestone 🎖️

What's Complete ✅

Phase	Component	Status	Tests
1	Foundation (Argon2, build system)	✅ Complete	0
2A	SHA3/SHAKE cryptography	✅ Complete	11
2B	SoulKey + Entropy Stamps	✅ Complete	35
2C	Prekey Bundles + DID Cache	✅ Complete	44
2D	DID Integration + Local Cache	✅ Complete	51

Total Progress: 6 weeks elapsed, 51/51 tests passing, 26-35 KB binaries (93% under Kenya Rule budget)

What's Next ⏳

Phase	Component	Duration	Status
3	PQXDH Post-Quantum Handshake	2-3 weeks	Ready to start
4	L0 Transport (UTCP + OPQ)	3 weeks	Waiting for Phase 3
5	FFI & Rust Integration	2 weeks	Waiting for Phase 4
6	Documentation & Polish	1 week	Waiting for Phase 5

Velocity: 1 week per phase (on schedule)

Key Achievements

• ✅ 50% of SDK delivered in 6 weeks (13-week critical path)
• ✅ Zero binary size regression (stable at 26-35 KB across all phases)
• ✅ 100% test coverage (51/51 tests passing)
• ✅ Kenya Rule compliance (5x under 500 KB budget)
• ✅ Clean architecture (protocol stays dumb, L2+ enforces standards)

---

Layers

L0: Transport Layer

Module: l0-transport/ | Index: l0_transport.zig

Implements the core wire protocol:

• 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 (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:

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

---

L1: Identity & Cryptography Layer

Module: l1-identity/

Implements identity and cryptographic primitives (Phase 2B-2D Complete):

Core Components:

• SoulKey ✅ - Ed25519 signing, X25519 key agreement, Kyber-768 placeholder
• Entropy Stamps ✅ - Argon2id proof-of-work anti-spam (RFC-0100)
• Prekey Bundles ✅ - 3-tier key rotation (30d signed, 90d one-time)
• DID Cache ✅ - Local resolution cache with TTL expiration
• AEAD Encryption ✅ - XChaCha20-Poly1305
• Post-Quantum ⏳ - Kyber-768 KEM + PQXDH (Phase 3)

Key Files:

• soulkey.zig - Identity keypair management (Phase 2B)
• entropy.zig - Entropy Stamp creation/verification (Phase 2B)
• prekey.zig - Prekey Bundle infrastructure (Phase 2C)
• did.zig - DID parsing + local cache (Phase 2D)
• crypto.zig - Encryption primitives (Phase 1)

---

Installation

Option 1: Git Submodule (Recommended)

# Add SDK to your Libertaria app
cd your-libertaria-app
git submodule add https://git.maiwald.work/Libertaria/libertaria-sdk libs/libertaria-sdk
git submodule update --init

Option 2: Manual Clone

# Clone SDK
git clone https://git.maiwald.work/Libertaria/libertaria-sdk
cd libertaria-sdk
zig build test  # Verify it works

Option 3: Zig Package Manager (Future)

// build.zig.zon
.{
    .name = "my-app",
    .version = "0.1.0",
    .dependencies = .{
        .libertaria_sdk = .{
            .url = "https://git.maiwald.work/Libertaria/libertaria-sdk/archive/v0.1.0.tar.gz",
            .hash = "1220...",
        },
    },
}

---

Quick Start

Build & Test

# Clone the SDK
git clone https://git.maiwald.work/Libertaria/libertaria-sdk
cd libertaria-sdk

# Run all tests (51/51 expected)
zig build test

# Build release binaries (Kenya Rule: <40 KB)
zig build -Doptimize=ReleaseSmall

# Run examples
zig build run-lwf
zig build run-crypto

# Check binary sizes
ls -lh zig-out/bin/

Verify Kenya Rule Compliance

# Binary size should be < 40 KB
zig build -Doptimize=ReleaseSmall
file zig-out/bin/lwf_example
ls -lh zig-out/bin/lwf_example  # Expected: 26 KB

# Performance on ARM (simulated)
# Entropy stamp generation: ~80ms (budget: <100ms)
# SoulKey generation: <50ms (budget: <50ms)
# DID cache lookup: <1ms (budget: <10ms)

Run Individual Phase Tests

# Phase 2B: SoulKey + Entropy
zig build test  # All phases

# Full test suite summary
zig build test 2>&1 | grep -E "passed|failed"

---

Usage

Basic Integration

// your-app/build.zig
const std = @import("std");

pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    // Link Libertaria SDK (static)
    const sdk_l0 = b.addStaticLibrary(.{
        .name = "libertaria_l0",
        .root_source_file = b.path("libs/libertaria-sdk/l0-transport/lwf.zig"),
        .target = target,
        .optimize = optimize,
    });

    const sdk_l1 = b.addStaticLibrary(.{
        .name = "libertaria_l1",
        .root_source_file = b.path("libs/libertaria-sdk/l1-identity/crypto.zig"),
        .target = target,
        .optimize = optimize,
    });

    // Your app
    const exe = b.addExecutable(.{
        .name = "my-app",
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
    });

    exe.linkLibrary(sdk_l0);
    exe.linkLibrary(sdk_l1);

    b.installArtifact(exe);
}

Example: Send LWF Frame

const std = @import("std");
const lwf = @import("libs/libertaria-sdk/l0-transport/lwf.zig");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    // Create LWF frame
    var frame = try lwf.LWFFrame.init(allocator, 100);
    defer frame.deinit(allocator);

    frame.header.service_type = std.mem.nativeToBig(u16, 0x0A00); // FEED_WORLD_POST
    frame.header.flags = 0x01; // ENCRYPTED

    // Encode to bytes
    const encoded = try frame.encode(allocator);
    defer allocator.free(encoded);

    std.debug.print("Encoded frame: {} bytes\n", .{encoded.len});
}

---

Building the SDK

Build Static Libraries

cd libertaria-sdk
zig build

# Output:
# zig-out/lib/liblibertaria_l0.a
# zig-out/lib/liblibertaria_l1.a

Run Tests

zig build test

# Should output:
# All tests passed.

Build Examples

zig build examples
./zig-out/bin/lwf_example

---

SDK Structure

libertaria-sdk/
├── README.md                   # This file
├── LICENSE                     # TBD
├── build.zig                   # SDK build system
├── l0-transport/               # L0: Transport layer
│   ├── lwf.zig                 # LWF frame codec
│   ├── utcp.zig                # UTCP transport (future)
│   ├── validation.zig          # Frame validation
│   └── test_lwf.zig            # L0 tests
├── l1-identity/                # L1: Identity & crypto
│   ├── soulkey.zig             # SoulKey (Ed25519/X25519)
│   ├── entropy.zig             # Entropy Stamps
│   ├── crypto.zig              # XChaCha20-Poly1305
│   └── test_crypto.zig         # L1 tests
├── tests/                      # Integration tests
│   ├── integration_test.zig
│   └── fixtures/
├── docs/                       # Documentation
│   ├── API.md                  # API reference
│   ├── INTEGRATION.md          # Integration guide
│   └── ARCHITECTURE.md         # Architecture overview
└── examples/                   # Example code
    ├── lwf_example.zig
    ├── encryption_example.zig
    └── entropy_example.zig

---

Performance

Binary Size

Static library sizes (ReleaseSafe):
  liblibertaria_l0.a: ~80 KB
  liblibertaria_l1.a: ~120 KB
  Total SDK:          ~200 KB

App with SDK linked:  ~500 KB (Feed client)

Benchmarks (Raspberry Pi 4)

LWF Frame Encode:     ~5 µs
LWF Frame Decode:     ~6 µs
XChaCha20 Encrypt:    ~12 µs (1 KB payload)
Ed25519 Sign:         ~45 µs
Ed25519 Verify:       ~120 µs
Entropy Stamp (d=20): ~1.2 seconds

---

Versioning

The SDK follows semantic versioning:

• 0.1.x - Alpha (L0+L1 foundation)
• 0.2.x - Beta (UTCP, OPQ)
• 0.3.x - RC (Post-quantum)
• 1.0.0 - Stable

Breaking changes: Major version bump (1.x → 2.x) New features: Minor version bump (1.1 → 1.2) Bug fixes: Patch version bump (1.1.1 → 1.1.2)

---

Dependencies

Zero runtime dependencies!

Build dependencies:

• Zig 0.15.x or later
• Git (for submodules)

The SDK uses only Zig's stdlib:

• std.crypto - Cryptographic primitives
• std.mem - Memory utilities
• std.net - Network types (future)

---

Contributing

See CONTRIBUTING.md (TODO)

Code Style:

• Follow Zig conventions
• Run zig fmt before committing
• Add tests for new features
• Keep functions < 50 lines
• Document public APIs

---

Applications Using This SDK

• Feed - Decentralized social protocol
• LatticePost - E2EE messaging (future)
• Archive Node - Content archival (future)

---

Documentation

Project Status

• PROJECT_MILESTONE_50_PERCENT.md - 50% completion report (comprehensive)
• PROJECT_STATUS.md - Master project status (live updates)

Phase Reports

• PHASE_2B_COMPLETION.md - SoulKey + Entropy Stamps
• PHASE_2C_COMPLETION.md - Prekey Bundles
• PHASE_2D_COMPLETION.md - DID Integration

Architecture References

• RFC-0250 - Larval Identity / SoulKey (implemented in soulkey.zig)
• RFC-0100 - Entropy Stamp Schema (implemented in entropy.zig)
• RFC-0830 - PQXDH Key Exchange (Phase 3, prekey ready)

---

Related Documents

• RFC-0000 - Wire Frame Protocol
• RFC-0100 - Entropy Stamps
• ADR-003 - Split-stack architecture

---

License

TBD (awaiting decision)

---

Contact

Repository: https://git.maiwald.work/Libertaria/libertaria-sdk Issues: https://git.maiwald.work/Libertaria/libertaria-sdk/issues Author: Markus Maiwald

---

Status: 🎖️ 50% COMPLETE - Phases 1-2D done (51/51 tests ✅) What's Done: Identity, crypto, prekey, DID resolution What's Next: Post-quantum (Phase 3) → Transport (Phase 4) → FFI (Phase 5) Velocity: 1 week per phase (on schedule, ahead of estimate) Binary Size: 26-35 KB (94% under Kenya Rule budget of 500 KB)

---

"The hull is forged in Zig. The protocol is sovereign. The submarine descends."