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, through gossip (UDP multicast) or a static node list; 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/8 (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) and dialing it directly in one hop, instead of relying on advertise-gossip having propagated a route between arbitrary stations. Available for the supervised primitive pairs macula_request/macula_response, macula_stream_sink/macula_streamer and macula_pusher/macula_upload 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. A UCAN token names its issuer as a did:key, the multicodec of its ML-DSA-87 public key in base58btc (macula_ucan). The hierarchical did:macula: method is retired (plan decision D7), and nothing builds or parses one.

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.

ML-DSA-87

The post-quantum signature scheme (FIPS 204) every Macula signature uses: node identity, CONNECT proofs, UCAN tokens, records and the TLS certificate a listener presents. In the pq_hybrid profile it is paired with RSA-PSS in the IETF LAMPS composite id-MLDSA87-RSA4096-PSS-SHA512. Ed25519 signs nothing in Macula any more.

SHA-384

The hash behind content addressing: an MCID is tag 2 and a 48-byte SHA-384 digest, and an id of any other shape is refused (plan decision D24).

BLAKE3

Fast cryptographic hash, ~20x SHA-256 through the Rust NIF (macula_blake3_nif), with an Erlang fallback. No module in macula calls it today, and it is not what addresses content: that is SHA-384 above.

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 node_id, 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 with Erlang's own erlang:get_cookie() and erlang:set_cookie/1; the SDK wrappers were removed in 11.0.0.

System Topics

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