API Reference macula v#11.1.0

Observed-Remove Set CRDT (Part 3 §7.4).

Plumtree push-lazy gossip (Leitão, Pereira, Rodrigues 2007, Part 3 §7.2).

Realm-scoped PubSub state + dispatch (Part 6 §6).

Per-identity registry for hecate_pubsub_server processes.

PubSub gen_server wrapping hecate_pubsub state for one realm namespace.

Macula SDK — Public API for mesh applications.

macula public API

BLAKE3 hashing with NIF acceleration and Erlang fallback.

BOLT#4-style error taxonomy for CALL failures (Part 4 §6.1).

Generic LRU cache implementation. Provides least-recently-used eviction with configurable max size.

CBOR (RFC 8949) pack/unpack for the Macula mesh wire protocol.

macula_client — the canonical pool client.

Cluster management utilities for Macula platform.

Macula UDP Multicast Gossip Cluster Strategy.

Macula Static Cluster Strategy.

Addressable content-store put/get, with a real, peer-visible abort, real pause/resume, and (for chunked content) parallel multi-stream chunk transfer — the foundation macula_feeder/ macula_download (and, later, macula_pusher/macula_upload) build on. See PLAN_PUSH_UPLOAD.md, Phases 1-3.

Correlation-id registry for macula_content_transfer handles.

Core type definitions and encoding/decoding for Macula. Provides fundamental types like node IDs, realm IDs, and addresses.

Cryptographic operations for Macula mesh.

The post-quantum crypto profile a node runs.

Structured event emission + per-process metric accumulation.

The bound behind macula_diagnostics:bounded_event/3: a diagnostics event goes to the log at most once per window, 10 seconds, per event name, node-wide.

Decentralized Identifier (DID) operations for Macula mesh.

Direct-dial resolve-and-call: shared internals for macula_request/macula_response, macula_streamer/ macula_stream_sink, and macula_feeder/macula_download.

QUIC Distribution Carrier for Erlang.

Supervised bridge process for relay distribution tunnels.

Supervisor for distribution relay bridge processes.

Relay-routed Erlang distribution.

Client for the Macula dist relay (macula-io/macula-dist-relay).

Control protocol encoder/decoder for dist relay.

Behaviour for supervised content downloads (the get/fetch side).

Factory supervisor for macula_download children.

Behaviour for supervised content feeders (the put/share side).

Factory supervisor for macula_feeder children.

Foundation trust anchor: the key ids of the foundation keys a node trusts, and the check of a foundation record against them.

CBOR-encoded wire frames for Macula V2 (Part 6 §3 canonical wire).

The post-quantum connection handshake, as plans/DESIGN_PQ_HANDSHAKE_FRAMES.md lays it out: the opener, challenge, CONNECT, HELLO and status frames, built as deterministic CBOR bytes and checked as received.

Realm-join handshake helpers (Phase 5.6).

HyParView protocol orchestrator (Part 3 §7.1).

HyParView active + passive partial-view data structure (Leitão, Pereira, Rodrigues 2007 — implementation of Part 3 §7.1).

ID generation utilities for Macula. Provides functions for generating various types of IDs.

Ed25519 identities and the S/Kademlia crypto puzzle.

Bindings of a node's TLS and CONNECT keys to its identity key, and the status statements that keep a binding in force, as plans/DESIGN_PQ_HANDSHAKE_FRAMES.md lays them out (decisions D16 and D22).

Announces a supervised wrapper's start fact and its end fact from a process of its own.

Fixed-size chunking, Merkle-root computation, and manifest construction for content larger than one storage block.

Macula Resource Identifier (MRI) - Core Module

MRI ETS Storage Adapter

MRI Graph Behaviour

MRI (Macula Resource Identifier) operations for Macula mesh.

MRI Type Registry

MRI Storage Behaviour

Shared naming utilities for hierarchical dot-separated names. Used by both pub/sub topics and RPC procedure names. Supports DNS-style reverse notation: org.domain.service.method

Node identity and metadata management. Represents a single node in the Macula mesh.

A node's keys, one per purpose, in the node's crypto profile, stored as plan decision D6 describes, and signing with them as decisions D4 and D7 describe.

The user a node runs as.

Files only their owner can read, written atomically.

Macula peering — connection state machine API.

Per-peer connection state machine.

simple_one_for_one supervisor for macula_peering_conn workers.

Top supervisor for macula_peering.

The seq counter of the publications a node signs, one per key.

Behaviour for supervised content publishers.

Pubsub surface for the V2 SDK.

Per-subscription delivery ordering for pubsub events.

Behaviour for supervised content pushes (the sender side of a push-initiated upload — PLAN_PUSH_UPLOAD.md Phase 6).

Macula QUIC transport — Quinn-based Rust NIF.

Realm management and validation. Realms provide logical isolation boundaries in the mesh. Realm names follow reverse DNS notation (e.g., "org.example.mesh").

What a reason is called when it leaves this node, and how much of it the local log prints.

Records in the signed-object format of DESIGN_PQ_SIGNED_FRAMES_AND_RECORDS.md.

Deterministic CBOR encoder/decoder.

UUIDv7 (RFC 9562, section 5.7): random ids, and record versions that strictly increase on a node.

Relay Discovery — geographic-aware relay selection.

Behaviour for supervised RPC requests.

Factory supervisor for macula_request children.

Behaviour for supervised RPC responses.

Factory supervisor for macula_response children.

Macula SDK Root Supervisor.

The signed objects of the post-quantum records and frames, as DESIGN_PQ_SIGNED_FRAMES_AND_RECORDS.md lays them out.

Source-route header codec (Part 6 §11).

A node's status statement issuer (DESIGN_PQ_HANDSHAKE_FRAMES.md, Binding and Status statement; D22).

The statement issuers of this node's pools, one for each pool.

Parse the MACULA_STATIONS seed list into the pinned seeds a pool takes: comma-separated <node id>@<host>:<port> entries, the node id as 64 lowercase hexadecimal characters, the host a DNS name, an IPv4 address or an IPv6 address in brackets, the port 1 to 65535. A station becomes the seed the pool takes, pinned to its node id, with its host as given. A refusal names the entry's position and what is wrong with it, and carries neither the value, nor a node id, nor a host.

A caller-side bucket of record bytes per connection, so a node that writes many records stays under the station's STORE allowance (D28, 3.5): 16 MiB at once, refilled at 1 MiB per second. await/2 sleeps in the calling process until the bucket allows Bytes and records them, so a put path that paces here never runs into a station's stored` 0 for the byte allowance. The bucket is recomputed lazily on each check, like `macula_dht_budget`s, so an idle connection's bucket never grows past its capacity and there is no timer per connection.

Macula streaming RPC — single-stream state machine.

Local registry + dispatcher for streaming RPC.

The node's count of served stream sessions, and of the bytes their streams keep unread.

Holds the table of the node's served stream sessions.

Behaviour for supervised streaming RPC consumers.

Behaviour for supervised streaming RPC providers.

Factory supervisor for macula_streamer children.

Behaviour for supervised, stateful PubSub consumers.

Time utilities for Macula. Provides functions for timestamps, durations, and timeouts.

TLS certificate management and TLS options for Macula QUIC.

Mesh topic construction and validation.

Segment-wise wildcard matching for hierarchical mesh addresses — pubsub topics, RPC procedure names, capability advertisements — shared by any caller that needs "does this pattern match this concrete address" without committing to one fixed segment count.

UCAN (User Controlled Authorization Networks) token operations.

Behaviour for supervised content uploads (the receiver side of a push-initiated upload — PLAN_PUSH_UPLOAD.md Phase 6, the recipient macula_pusher pushes at).

Macula URI parsing and construction. Format: macula://realm/node_id Example: macula://org.example.mesh/0123456789abcdef...

z-base-32 codec (Phil Zimmermann's "Human-Oriented Base-32 Encoding"). Alphabet: ybndrfg8ejkmcpqxot1uwisza345h769.