s5_core

Core types and traits for the S5 protocol. This crate defines the wire-stable primitives and shared abstractions used across the S5 ecosystem.

Key Components

Protocol Types (Wire-Stable)

These types define the on-the-wire format and persistent metadata structure. Changes here are protocol-breaking.

• Hash: The fundamental content addressing primitive (BLAKE3, 32 bytes).
• BlobId: The user-facing identifier for a blob. Encoded as a multibase string containing the Hash and the blob size (u64).
• BlobLocation: A CBOR-encoded enum describing how to retrieve a blob. Supports:
  • Inline: Raw bytes embedded directly in the location.
  • Network: Url (HTTP), Iroh (NodeID + Tag), SiaFile (renterd metadata).
  • Transforms: Encryption (XChaCha20-Poly1305), Compression (Zstd, Brotli).
• StreamMessage: The atomic unit of the S5 Registry/Stream layer. Contains a StreamKey, revision number, payload, and Ed25519 signature.

Abstractions (Traits & Helpers)

These are Rust-level abstractions for building S5 applications and nodes.

• Store: The low-level async storage trait. Implement this to add new backends (e.g., S3, Local FS, Memory).
  • Methods: put_stream, open_read_stream, list, delete, rename.
• BlobStore: The high-level facade over a Store.
  • Handles BlobId verification (hash checking).
  • Manages BlobLocation resolution.
  • Implements BlobsRead and BlobsWrite for ergonomic byte streaming.
• RegistryApi: Trait for interacting with mutable pointers (S5 Registry).
  • RedbRegistry: A provided local implementation using redb.
• Pins: Trait for preventing garbage collection of blobs.
  • RegistryPinner: An implementation that pins blobs referenced by local registry entries.

Usage

use s5_core::{BlobId, Hash};

// Create a BlobId from raw data
let data = b"hello world";
let hash = Hash::new(data);
let id = BlobId::new(hash, data.len() as u64);

println!("Blob ID: {}", id);