libertaria
/
libertaria-stack
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
libertaria-stack/README.md

8.0 KiB
Raw Blame History

Libertaria SDK

The Core Protocol Stack for Libertaria Applications

Version: 0.1.0-alpha License: TBD Language: Zig 0.15.x Status: Alpha (L0+L1 Foundation)

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

Layers

L0: Transport Layer

Module: l0-transport/

Implements the core wire protocol:

  • LWF Frame Codec - Encode/decode wire frames
  • UTCP - Reliable transport over UDP (future)
  • Frame Validation - Checksum, signature verification
  • Priority Queues - Traffic shaping

Key Files:

  • lwf.zig - LWF frame structure and codec
  • utcp.zig - UTCP transport (future)
  • validation.zig - Frame validation logic

L1: Identity & Cryptography Layer

Module: l1-identity/

Implements identity and cryptographic primitives:

  • SoulKey - Ed25519 signing, X25519 key agreement
  • Entropy Stamps - Proof-of-work anti-spam
  • AEAD Encryption - XChaCha20-Poly1305
  • Post-Quantum - Kyber-768 KEM (future)

Key Files:

  • soulkey.zig - Identity keypair management
  • entropy.zig - Entropy Stamp creation/verification
  • crypto.zig - Encryption primitives

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...",
        },
    },
}

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

Related Documents

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: Alpha - L0+L1 foundation complete Next: UTCP transport, OPQ, post-quantum crypto

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