Terminology reference for the Macula SDK
Applies to: the current SDK — see CHANGELOG.md for version history
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.
The federated network of relays that route messages between nodes. Relays peer with each other via Kademlia DHT for cross-relay discovery.
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.
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.
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.
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.
Request/response pattern. Providers advertise procedures; consumers call them. The relay mesh handles discovery via Kademlia DHT. Calls return {ok, Result} or {error, Reason}.
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).
A named pub/sub channel (e.g., orders.placed). Subscribed via macula:subscribe/5, published via macula:publish/5.
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.
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.
Capability token based on JWT. Contains issuer, audience, capabilities, and optional proof chain. Used for delegated authorization without a central authority.
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.
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).
Typed, hierarchical resource identifier. Format: mri:{type}:{realm}/{path}.
Examples:
mri:realm:io.macula-- a realmmri:app:io.macula/acme/counter-- an applicationmri: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).
Runtime registry for MRI types. Built-in types are always valid. Custom types can be registered per-realm via macula_mri_registry.
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.
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.
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.
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.
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.
| Topic | Description |
|---|---|
_mesh.node.up |
Node connected to relay |
_mesh.node.down |
Node disconnected |
_mesh.node.reroute |
Node switched relay (failover) |
_mesh.site.up |
First node of a site connected |
_mesh.site.down |
Last node of a site disconnected |
_mesh.relay.up |
Relay identity enabled |
_mesh.relay.down |
Relay identity disabled |
_mesh.relay.ping |
RTT measurement between relay and node |
For relay-specific terminology (DHT internals, peering, SWIM, bloom filters, relay boxes, virtual identities), see macula-station documentation.