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 = 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}).

RPC (Request/Response)

%% Register a procedure handler
ok = macula:register(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

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.19.2"}
]}.

Or in Elixir mix.exs:

defp deps do
  [
    {:macula, "~> 0.19.2"}
  ]
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
macula:subscribe(Peer, <<"events.orders">>, fun(Order) ->
    process_order(Order)
end).

%% Make RPC calls
{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_routing_server (Kademlia DHT)
├── macula_nat_system (NAT traversal)
├── macula_bootstrap_system (mesh discovery)
├── macula_gateway_system (QUIC transport)
├── macula_bridge_system (hierarchical mesh)
├── macula_platform_system (CRDT coordination)
├── macula_registry_system (package distribution)
├── macula_content_system (P2P content transfer)
└── macula_dist_system (Erlang distribution)

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}