Crate macula_rust 

Rust port of macula’s SDK (client/leaf) protocol — see plans/PLAN_WIRE_PROTOCOL.md for the full wire-format spec this crate is built against, traced directly to macula-io/macula source.

Mobile (iOS/Android via UniFFI) is the flagship consumer driving this work, not the ceiling on it — nothing below the eventual FFI binding layer is mobile-specific.

Modules

bolt4

BOLT#4-style error taxonomy for CALL failures, ported from src/peering/macula_bolt4.erl (macula-io/macula) — see plans/PLAN_WIRE_PROTOCOL.md §9. Adapted from Lightning Network’s BOLT#4 onion-failure codes: a small, specific taxonomy that prevents retry loops and enables post-mortem, rather than an open-ended error string. Codes are stable across V2 minor versions; new codes append at the next free integer.

cbor

Deterministic CBOR encode/decode, byte-for-byte compatible with macula’s own wire codec.

cert

TLS trust for dialing a macula-station: pubkey-pin verification, ported from native/macula_quic/src/cert.rs (macula-io/macula).

cert_chain

Direct-dial dual-trust (Slice 7c Direction B) — X.509 cert chain.

connection

The CONNECT/HELLO handshake and the application-frame stream abstraction, ported from src/peering/macula_peering_conn.erl (macula-io/macula) — see plans/PLAN_WIRE_PROTOCOL.md §3.

content

Content sharing (§12 of plans/PLAN_WIRE_PROTOCOL.md): put/get by content-address, over a dedicated QUIC stream — ordinary CALL/RESULT (§6.4) against four well-known _content.* procedures, ported from macula_content_transfer.erl. Not a separate wire protocol: nothing here is new frame types, just calls a normal crate::connection::Session could already make, sent on a stream opened via Session::open_dedicated_stream instead of the control stream.

dht

The subset of Macula’s signed DHT records that direct-dial resolution needs: procedure_advertisement and station_endpoint construction, signing, verification, and storage-key derivation, plus thin wrappers around the mesh’s _dht.* RPC procedures.

direct_dial

Direct-dial resolve-and-call: resolving a signed procedure_advertisement DHT record and its serving station’s own signed station_endpoint, then dialing that station in one hop — instead of depending on ordinary advertise-gossip having propagated a route between whichever two stations happen to be involved.

frame

The macula application-frame envelope: construction, Ed25519 signing/verification, and the length-prefixed wire codec. Ported from src/peering/macula_frame.erl (macula-io/macula).

identity

Ed25519 identity and the S/Kademlia crypto puzzle, matching macula’s own macula_identity.erl (macula-io/macula).

keystore

Overridable, per-platform secure storage for a persisted identity seed.

manifest

Fixed-size chunking, Merkle-root computation, and manifest construction for content larger than one storage block. Ported from macula’s own macula_manifest (SDK) — see plans/PLAN_WIRE_PROTOCOL.md §12.2.

pool

A multi-station connection pool: dials several Sessions concurrently (bootstrap seeds, optionally grown by discovering more via hecate_stations.list_stations) and gives Pool::call/ Pool::publish a choice of which connected one to use, instead of a caller managing a single Session by hand.

stream

General-purpose streaming RPC, caller/consumer role (§13.1 of plans/PLAN_WIRE_PROTOCOL.md), ported from macula_stream_sink.erl. Like content transfer (src/content.rs), this is not a separate wire mechanism: it runs the frame types built in src/frame.rs §13 over a dedicated QUIC stream, opened via Session::open_dedicated_stream rather than the control stream.

transport

QUIC transport: dialing a macula-station, ported from native/macula_quic/src/config.rs (macula-io/macula).

ucan

Macula’s UCAN (User Controlled Authorization Networks) tokens: creation, verification, and introspection, plus the policy layer a provider gates an inbound CALL through.