Macula

BEAM-native HTTP/3 mesh networking for decentralized applications

What is Macula?

Macula is an Erlang/OTP library that provides a complete distributed mesh networking stack over HTTP/3 (QUIC). It enables BEAM applications to form self-organizing networks with:

• Zero configuration clustering via UDP multicast gossip
• NAT-friendly transport using QUIC (single UDP port)
• Decentralized service discovery via Kademlia DHT
• Capability-based security with DID identities and UCAN tokens

Features

Mesh Networking

Pub/Sub Messaging

%% Subscribe to a topic
{ok, SubRef} = macula:subscribe(Peer, <<"sensors.temperature">>, fun(Msg) ->
    io:format("Received: ~p~n", [Msg])
end).

%% Publish to subscribers
ok = macula:publish(Peer, <<"sensors.temperature">>, #{value => 23.5}).

%% Unsubscribe when done
ok = macula:unsubscribe(Peer, SubRef).

RPC (Request/Response)

%% Advertise a procedure handler
{ok, _Ref} = macula:advertise(Peer, <<"math.add">>, fun(#{a := A, b := B}) ->
    {ok, #{result => A + B}}
end).

%% Call the procedure (discovers provider via DHT)
{ok, #{result := 5}} = macula:call(Peer, <<"math.add">>, #{a => 2, b => 3}).

NAT Traversal

Gossip Clustering

Zero-configuration cluster formation using UDP multicast:

%% Start gossip-based clustering
ok = macula_cluster:start_cluster(#{
    strategy => gossip,
    secret => <<"my_cluster_secret">>  %% Optional HMAC authentication
}).

%% Nodes auto-discover via multicast 230.1.1.251:45892

Erlang Distribution Over Relay Mesh

Full OTP distribution tunneled through the relay mesh — nodes only need outbound connectivity. No VPNs, no open ports.

%% Enable relay distribution
os:putenv("MACULA_DIST_MODE", "relay"),
macula_dist_relay:register_mesh_client(Client),
macula_dist_relay:advertise_dist_accept(),

%% Now standard OTP distribution works across firewalls
net_adm:ping('other@remote-host').  %% => pong
gen_server:call({Name, 'other@remote-host'}, Request).  %% works

See Distribution Over Mesh Guide for details.

Content Transfer (P2P Artifacts)

Content-addressed storage and transfer for distributing OTP releases across the mesh:

%% Publish a file to the mesh
{ok, MCID} = macula_content:publish("/path/to/release.tar.gz").

%% Fetch from any provider
{ok, Binary} = macula_content:fetch(MCID).

Authorization (DID + UCAN)

Decentralized capability-based authorization:

Hierarchical DHT (Bridge System)

Fractal mesh hierarchy with query escalation:

Cluster → Street → Neighborhood → City → Province → Country → Region → Global

When a DHT query fails locally, it escalates to parent levels with results cached at lower levels.

Quick Start

Installation

Add to your rebar.config:

{deps, [
    {macula, "0.42.7"}
]}.

Or in Elixir mix.exs:

defp deps do
  [
    {:macula, "~> 0.42.7"}
  ]
end

Basic Usage

%% Start macula application
application:ensure_all_started(macula).

%% Connect to the mesh
{ok, Peer} = macula:connect(<<"quic://seed.example.com:9443">>, #{
    realm => <<"io.example.myapp">>,
    node_id => <<"node-001">>
}).

%% Subscribe to events
{ok, _SubRef} = macula:subscribe(Peer, <<"events.orders">>, fun(Order) ->
    process_order(Order)
end).

%% Advertise an RPC procedure
{ok, _AdvRef} = macula:advertise(Peer, <<"inventory.check">>, fun(#{sku := Sku}) ->
    {ok, check_inventory(Sku)}
end).

%% Call an RPC procedure (discovers provider via DHT)
{ok, Result} = macula:call(Peer, <<"inventory.check">>, #{sku => <<"ABC123">>}).

Configuration

Environment Variables

Application Config

{macula, [
    {quic_port, 9443},
    {realm, <<"io.example.myapp">>},
    {tls_mode, production},
    {tls_cacertfile, "/etc/ssl/certs/ca-certificates.crt"}
]}.

Documentation

Version History

See CHANGELOG.md for full history.

Architecture

Macula follows an always-on architecture where every node has all capabilities:

macula_root (application supervisor)
├── macula_gateway_system (QUIC transport + relay handler)
├── macula_pubsub_system (pub/sub messaging)
├── macula_rpc_system (RPC request/response)
├── macula_routing_system (Kademlia DHT)
├── macula_nat_system (NAT traversal + hole punching)
├── macula_bootstrap_system (mesh discovery)
├── macula_membership_system (gossip clustering)
├── macula_bridge_system (hierarchical mesh escalation)
├── macula_platform_system (CRDT coordination)
├── macula_registry_system (package distribution)
├── macula_content_system (P2P content transfer)
├── macula_cert_system (TLS certificate management)
└── macula_dist_system (Erlang distribution)
    ├── macula_dist_bridge_sup (relay tunnel bridges)
    ├── macula_dist_discovery (DHT node discovery)
    └── macula_cluster_strategy (optional auto-clustering)

Related Projects

Community

• Hex.pm: hex.pm/packages/macula
• GitHub: github.com/macula-io/macula
• Issues: github.com/macula-io/macula/issues

License

Apache 2.0 - See LICENSE for details.

_{Built with the BEAM}