API Reference macula v#13.2.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).

The legacy-application bridge: an unmodified TCP application (a database client, ssh, a web dashboard) reaches an unmodified TCP service across the mesh, one bidi stream per TCP connection.

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.

Fetches content from the node that shares it (D27): content is available while its sharer is online, and stations only relay.

How a sharing node answers a fetch on its content procedure (D27). One content id per stream, a server_stream: the stream's args name the content id (mcid) and what is wanted (want), root for the content id a fetcher was given or block for a chunk of a manifest it holds. The answer is one DATA body, then the end of the stream

Shares a pool's content (D27): the node keeps what it shares and serves it itself, and stations only relay. One sharer per pool, ending with the pool.

Supervises the content sharers, one per pool (macula_content_sharer). A sharer is temporary: it ends with its pool and is not restarted. sharer/1 finds a pool's sharer or starts it; the supervisor serializes the start, so two callers sharing on one pool at once get the same sharer.

The content a node shares, held by the node itself (D27: a station keeps no content; the sharing node keeps it and serves it). A pure value: the owner keeps it and threads it through.

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.

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.

A distribution tunnel that names its peer.

The socket a distribution tunnel's TLS session runs on.

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

Factory supervisor for macula_download children.

Behaviour for supervised content feeders (the 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).

A sealed group's epochs (plans/DESIGN_E2E_SEALED_PUBSUB.md §4).

An event sealed under a sealed group's epoch (plans/DESIGN_E2E_SEALED_PUBSUB.md §7, test/vectors/E2E_SEAL_V1.md).

A node's keyring for the sealed groups it joined (plans/DESIGN_E2E_SEALED_PUBSUB.md §4, §6, §7).

A sealed group's distributor (plans/DESIGN_E2E_SEALED_PUBSUB.md §3, §5): the handler of <org>/group_keys_v1 and the epochs of every group it serves.

The process that opens a sealed group's events for one subscription (plans/DESIGN_E2E_SEALED_PUBSUB.md §6, §7).

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.

A node's KEM keys (E2E design, Amendment A1), one current key per node identity, shared by every pool of that identity in the VM.

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.

Which handshake version a client dials each node with, and the node-wide handshake counters (plans/DESIGN_NEIGHBOUR_CHANNEL_BINDING.md sections 3, 4 and 6).

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.

End-to-end payload sealing, scheme 1: what a node needs to seal a payload so that the stations relaying it cannot read it (plans/DESIGN_E2E_PAYLOAD_CONFIDENTIALITY.md). The byte-exact construction is test/vectors/E2E_SEAL_V1.md, and every function here reproduces that file's vectors, which an independent Rust implementation generated.

A sealed call (E2E seal scheme 1, design §5.1), one level above macula_seal: the caller seals a request to the provider's KEM key and opens the reply, and the provider opens the request and seals the reply.

How many handshake v5 session proofs this station signs: by default at most 30 a minute for one client node, and 30 a second for all clients together (plans/DESIGN_NEIGHBOUR_CHANNEL_BINDING.md section 3, "Signing cost as an attack surface"). A composite session proof costs 6 to 10 ms of signing, so the total bounds this station's signing to about a quarter of one core, and a reconnect storm of 1000 clients is admitted in about 30 seconds. The station asks only after the client's CONNECT proof has verified, so a refusal here costs the client a composite signature of its own. Past either limit the station refuses CONNECT with session_proof_rate, and the refusal names the limit.

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.

The TLS posture handshake v5 depends on, checked before peering starts (plans/DESIGN_NEIGHBOUR_CHANNEL_BINDING.md sections 3 and 6). v5 lets QUIC's AEAD authenticate every frame after the session proofs, which holds only if the session's keys come from a hybrid ML-KEM exchange and no frame travels in replayable 0-RTT. So both ends offer exactly SecP384r1MLKEM1024 then SecP256r1MLKEM768, neither offers nor accepts early data or sends tickets, a second handshake between the same configurations is a full one, and the dialler's own setting holds too: against a listener that does issue tickets, its second handshake is also full.

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 tokens in the node's crypto profile (plan decision D7), and a provider's authorization of one (D7 check 2).

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.