Macula SDK Glossary

Terminology reference for the Macula SDK

Applies to: the current SDK — see CHANGELOG.md for version history

Architecture

Relay

A stateless message router. Nodes connect outbound via QUIC. Relays route pub/sub events, RPC calls, and Erlang distribution traffic between nodes. Relays are run by macula-station.

Relay Mesh

The federated network of relays that route messages between nodes. Relays peer with each other via Kademlia DHT for cross-relay discovery.

Node

Any BEAM application using the Macula SDK. Connects outbound to a relay over QUIC. A node can subscribe to topics, publish events, advertise RPC procedures, and call remote procedures.

Realm

An isolated namespace for multi-tenant applications. Format: reverse domain notation (e.g., io.macula, io.example.myapp). All communication is scoped to a realm.

Cluster

A logical group of nodes that form an Erlang cluster. Can be formed via gossip (UDP multicast), static configuration, or DHT-based discovery (strategy => dht or mdns — both currently route through the same DHT-based discovery; see the Clustering Guide). LAN clustering works independently of relay connections.

Communication

Pub/Sub

Topic-based event distribution. Publishers send events to topics; all subscribers on the mesh receive them. Topics are the canonical five-segment slash-separated shape ({realm}/{org}/{app}/{domain}/{name}_v{N}, e.g. io.macula/acme/counter/orders/placed_v1), built via macula_topic, never hand-typed. Entity IDs go in payloads, not topic names. See the Topic Naming Guide.

RPC (Remote Procedure Call)

Request/response pattern. Providers advertise procedures; consumers call them. The relay mesh handles discovery via Kademlia DHT. Calls return {ok, Result} or {error, Reason}.

Procedure

A named RPC endpoint (e.g., math.add, weather.get_current). Registered via macula:advertise/5, invoked via macula:call/5 (any of the caller's own connected stations) or macula:call_station/6,7 (direct-dial — a specific, resolved station, one hop; see below).

Topic

A named pub/sub channel (e.g., orders.placed). Subscribed via macula:subscribe/5, published via macula:publish/5.

Direct-Dial

Resolving a specific provider's station from a signed DHT record (procedure_advertisement for RPC/streaming, content_announcement for content) and dialing it directly in one hop, instead of relying on advertise-gossip having propagated a route between arbitrary stations. Available for all four supervised primitive pairs — macula_request/macula_response, macula_stream_sink/macula_streamer, macula_download/macula_feeder — via each pair's start_link_direct/advertise_direct. Trust is enforced at the application layer, not by pinning the TLS connection: a production station's certificate is terminated by an unrelated PKI (e.g. Let's Encrypt) and cannot be pinned, so the CONNECT/HELLO handshake's own signature check does the real work instead. See the RPC Guide.

Identity

DID (Decentralized Identifier)

W3C-standard identifier for entities. Macula uses did:macula: method with hierarchical names (e.g., did:macula:io.macula.acme). Each level is controlled by its parent.

UCAN (User Controlled Authorization Network)

Capability token based on JWT. Contains issuer, audience, capabilities, and optional proof chain. Used for delegated authorization without a central authority.

Ed25519

Elliptic curve signature scheme used for all Macula cryptographic operations: node identity, UCAN signing, DID verification.

BLAKE3

Fast cryptographic hash function used for content addressing (MCID). 32-byte output, ~20x faster than SHA-256 via Rust NIF.

Resource Identification

MRI (Macula Resource Identifier)

Typed, hierarchical resource identifier. Format: mri:{type}:{realm}/{path}.

Examples:

• mri:realm:io.macula -- a realm
• mri:app:io.macula/acme/counter -- an application
• mri:device:io.macula/acme/sensor-1 -- a device

24 built-in types: realm, org, user, app, service, artifact, instance, license, cert, key, topic, proc, content, device, cluster, location, zone, network, model, dataset, config, class, taxonomy, station (the last is self-rooted by Ed25519 pubkey, not realm-scoped).

MRI Type Registry

Runtime registry for MRI types. Built-in types are always valid. Custom types can be registered per-realm via macula_mri_registry.

Transport

QUIC

UDP-based transport protocol (RFC 9000) with built-in TLS 1.3. NAT-friendly (single UDP port), firewall-friendly (outbound only). Macula uses Quinn (Rust NIF) for QUIC transport.

Wire Protocol

Binary message format using CBOR encoding (RFC 8949). Message types include CONNECT, HELLO, SUBSCRIBE, PUBLISH, EVENT, CALL, RESULT, CALL_ERROR, ADVERTISE/UNADVERTISE, and PING/PONG — see macula_frame for the full set, including stream and SWIM/HyParView frames.

Tunnel

An encrypted Erlang distribution channel between two nodes routed through the relay mesh. Uses AES-256-GCM encryption (key derived from distribution cookie). The relay cannot read ETF content.

Clustering

Gossip Strategy

UDP multicast-based node discovery on 230.1.1.251:45892. Nodes periodically announce themselves; peers join the cluster automatically. Optional HMAC authentication via shared secret.

Cookie

Erlang distribution cookie. In Macula, also used as the AES-256-GCM key for tunnel encryption. Managed via macula:get_cookie/0 and macula:set_cookie/1.

System Topics

For relay-specific terminology (DHT internals, peering, SWIM, bloom filters, relay boxes, virtual identities), see macula-station documentation.