macula-io/macula

Macula is a BEAM-native mesh networking SDK that enables secure, decentralized communication and distributed Erlang node clustering over QUIC. It provides a comprehensive stack for identity management via Decentralized Identifiers (DIDs) and post-quantum cryptography, alongside a robust pub/sub system with deterministic content-addressed storage. The platform supports multi-hop routing through a Kademlia DHT and offers native Rust-accelerated performance for critical cryptographic and serialization operations.

10 changes.

This period focused on enabling Erlang distribution over the Macula mesh via custom QUIC transports and introducing z-base-32 encoding for DNS-based identity discovery. The work was supported by comprehensive end-to-end and integration test suites for multi-node scenarios, alongside new development scripts and centralized configuration headers to streamline the build and release processes.

21 changes.

The project undertook a comprehensive rewrite of its native layer into Rust, introducing dedicated NIF crates for cryptography, serialization, and identity to replace previous Erlang/Elixir implementations. This period established the foundational V2 peering protocol, deterministic CBOR wire formats, and post-quantum cryptographic profiles, while restructuring the client and overlay systems for improved performance and security.

The SDK now includes a local implementation of content manifest construction, fixed-size chunking, and Merkle-root verification (macula\_manifest). This allows the client to split large data into 256 KiB chunks, compute SHA-384 based MCIDs, and verify content integrity independently, mirroring the station's behavior byte-for-byte. The module also handles robust parsing of manifests received over the wire, ensuring compatibility with the station's RPC layer.

src/content · high confidence

The \macula\_dist\_system\ module now enables Erlang distribution across NATs and firewalls without a VPN, supporting three transport modes: direct QUIC for low-latency LAN clustering, pool-tunneled distribution via the general mesh pool (\macula:join\_mesh/1\), and a dedicated freight relay for raw QUIC stream forwarding (\macula:join\_dist\_relay/1\). This implementation replaces the standard \inet\_tcp\_dist\ carrier with a custom \macula\ driver that handles encrypted, multiplexed streams and includes a supervised bridge system to manage loopback sockets and tunnel lifecycle.

_src/macula\_dist\system · high confidence

Macula now includes a z-base-32 encoder and decoder (\macula\_z32\) to represent 32-byte Ed25519 public keys as 52-character, DNS-label-friendly strings. This enables the use of PKARR (public-key-addressable resource records) and similar DNS-based discovery mechanisms for node identities. The module provides \encode/1\, \decode/1\, and \is\_valid\_label/1\ functions, strictly adhering to the z-base-32 alphabet and length conventions.

src · high confidence

The pubsub subsystem now guarantees per-publisher message ordering by default, buffering out-of-order arrivals and releasing them sequentially to prevent data loss during network reordering or publisher restarts. Subscribers can choose between ordered delivery, latest-only (dropping stale events), or as-arrives modes. Additionally, a new \subscribe\_callback/4\ API allows registering a function to handle events in a separate receiver process, preventing slow handlers from blocking the connection pool, while a new \macula\_subscriber\ behaviour enables stateful, supervised consumer processes integrated into the application's supervision tree.

src/pubsub · high confidence

This change introduces native Rust NIFs to replace or supplement existing Erlang/Elixir implementations for core Macula identity and resource identification logic. The \macula\_did\_nif\ module provides high-performance Decentralized Identifier (DID) operations, including document creation with Ed25519 verification methods, local cache-based resolution, and public key extraction, supporting the \did:macula\ namespace hierarchy. The \macula\_mri\_nif\ module delivers optimized MRI (Macula Resource Identifier) parsing and hierarchy management, featuring a persistent trie-based index for O(d) child and descendant queries, which significantly speeds up service discovery and routing for large-scale deployments. These native components form the foundational layer for Macula's identity and resource resolution capabilities.

_native/macula\_did\_nif, native/macula\_mri\nif · high confidence

The native/macula\_crypto\_nif module introduces high-performance NIF implementations for Ed25519 key generation, signing, and verification, alongside SHA-256 and BLAKE3 hashing, base64 encoding/decoding, and constant-time secure comparison. It also adds a native puzzle-grinding function (nif\_grind\_puzzle) that generates Ed25519 keypairs with SHA-256 public-key hashes meeting a specified difficulty level, running on a dirty CPU scheduler to avoid BEAM scheduler timeouts during intensive search. These operations form the cryptographic foundation for UCAN tokens, DID operations, and content-addressed storage in the Macula mesh.

_native/macula\_crypto\nif · high confidence

The overlay layer now includes a new set of modules implementing the Hecate protocol stack: \hecate\_pubsub\ and \hecate\_pubsub\_server\ handle realm-scoped topic subscriptions and event delivery, while \hecate\_pubsub\_registry\ manages the lifecycle of these servers. \hecate\_plumtree\ provides the push-lazy gossip dissemination layer for publications, and \hecate\_or\_set\ implements an Observed-Remove Set CRDT for convergent state management. Additionally, \macula\_hyparview\_endorsement\ and \macula\_hyparview\_proto\ introduce realm-member endorsement verification and the HyParView protocol logic for node admission and view maintenance.

src/overlay · high confidence

The \src/mri\ area now includes the core \macula\_mri\ module for parsing, validating, and manipulating Macula Resource Identifiers (MRIs), along with a type registry (\macula\_mri\_registry\) that supports built-in and custom types. Storage and graph capabilities are abstracted via behaviours (\macula\_mri\_store\, \macula\_mri\_graph\) with a default in-memory ETS adapter (\macula\_mri\_ets\) and a high-performance NIF-accelerated path index (\macula\_mri\_nif\) for fast hierarchy queries.

src/mri · high confidence

This update introduces a comprehensive set of new visual assets for the Macula project, including multiple logo variants (color, dark, white, and an alternative mesh design) and several architecture diagrams. The diagrams include a Mermaid source file and SVG renderings that illustrate the HTTP/3 mesh network, Kademlia DHT routing, and the platform's support for Line-of-Business, IoT, and TWEANN workloads. These files serve as documentation and branding resources, with the architecture diagrams highlighting key features such as direct P2P communication, NAT traversal, and BEAM-native implementation.

artwork · high confidence

The record layer now uses a native Rust-backed CBOR codec (macula\_cbor\_nif) for deterministic wire serialization, replacing the previous msgpack-based approach, and introduces a BLAKE3 hashing module (macula\_blake3\_nif) that accelerates content-addressed storage via a Rust NIF with a pure Erlang fallback. These changes improve serialization determinism and hashing performance while maintaining compatibility with existing record structures.

src/record · high confidence

The repository now includes a suite of shell and Erlang scripts to support development, testing, and release workflows. These include scripts to verify that the Erlang/OTP version matches the pinned version, check that the git working tree is clean and matches the release tag before publishing, and validate that the published Hex package matches the git tag. Additional scripts automate version bumping, PDF documentation generation, QUIC TLS certificate generation, and performance benchmarking for post-quantum crypto profiles. Utility scripts also handle moving relay-specific documentation and code to a separate repository, stripping the SDK to remove relay modules, and running test coverage reports.

scripts · high confidence

The client layer has been restructured around a new \macula\_client\ pool that manages multiple peering links to stations, replacing direct single-link interactions. This pool provides automatic replication (defaulting to a factor of 2) for publish operations, ensuring messages are sent to multiple links with partial success counting as success. It implements inbound event deduplication using an ETS table keyed on publication hashes to prevent duplicate delivery, and subscription replay to restore subscriptions when a station link respawns. The system also introduces a peer budget to limit new connections per window and a request admission controller to ensure each provider request is executed exactly once, enforcing caller quotas and reply size limits. Additional modules handle relay discovery for geographic-aware routing and refusal reporting for operational visibility.

src/client · high confidence

This change introduces the \macula\_diagnostics\ module for structured event emission and per-process metric accumulation, including a fix to install a logger domain filter so \macula\ events are no longer silently dropped. It also adds the core V2 peering protocol components: \macula\_frame\ for CBOR-encoded wire frames, \macula\_handshake\ for the post-quantum connection handshake, \macula\_peering\ for the connection state machine API, and \macula\_bolt4\ for error taxonomy, establishing the foundation for the new peering layer.

src/peering · high confidence

The build script now prevents loading outdated native libraries by checking source file timestamps against compiled artifacts, ensuring that changes to Rust code or dependencies trigger a rebuild. Additionally, the QUIC and CBOR NIFs are now marked as required; if the Rust toolchain is missing or the build fails for these components, the process exits with an error rather than silently skipping, which previously led to runtime failures due to missing binaries.

priv · high confidence

This change introduces new header files to the include directory to standardize application settings and data structures. macula\_config.hrl defines global constants for network timeouts (such as a 30-second QUIC connection timeout), retry limits, DHT parameters, and default ports, while also providing legacy aliases for backward compatibility. macula\_connection.hrl establishes the shared state record for connection management, including fields for peer identification, connection status, and retry delays. Additionally, macula\_quic\_error\_codes.hrl centralizes named QUIC application error codes (e.g., CANCELLED, REFUSED, STREAM\_PROTOCOL\_ERROR) to replace magic numbers in the codebase.

include · high confidence

The \macula\_cluster\_system\ module now provides a dedicated LAN clustering solution that is separate from the mesh distribution system. It introduces two discovery strategies: \macula\_cluster\_gossip\ for zero-config, same-subnet discovery via UDP multicast, which now requires a shared secret of at least 32 bytes to authenticate packets via HMAC-SHA256; and \macula\_cluster\_static\ for connecting to a predefined list of nodes. The system no longer manages Erlang distribution cookies, relying instead on the node's release configuration or environment for authentication. This change allows applications like \bc\_gitops\ to delegate cluster formation to Macula while remaining usable standalone.

_src/macula\_cluster\system · high confidence

The identity subsystem now uses Rust NIFs for cryptographic primitives, delivering significant performance improvements for Ed25519 key generation, signing, verification, and hashing (BLAKE3, SHA-256). This native acceleration extends to the S/Kademlia Sybil-resistance puzzle, allowing the configured difficulty to scale the cost of the search itself rather than the BEAM scheduler. The identity module enforces a puzzle difficulty limit of 0–16 bits, checked at startup and on every generation, and key files are now persisted with strict owner-only permissions (0600) to prevent unauthorized access.

src/identity · high confidence

The application now supports configurable post-quantum security profiles, specifically \pq\_pure\ (CNSA 2.0 algorithms) and \pq\_hybrid\ (hybrid key exchange). Nodes must explicitly set one of these profiles in the \macula\ application environment under \crypto\_profile\ at startup; the application will refuse to start if no profile is defined, if multiple are provided, or if an unknown profile is specified.

_config, src/crypto\profile · high confidence

The native serialization layer in \native/macula\_cbor\_nif\ has been replaced to use deterministic CBOR (RFC 8949) instead of the previous MessagePack implementation. This change introduces a new Rust-based codec that ensures byte-for-byte deterministic encoding—specifically sorting map keys bytewise and enforcing strict integer/float widths—which is required for signed payloads and compatibility with UCAN/DID standards. The new decoder includes safety limits, capping element counts at 131,072 items and running on a dirty CPU scheduler to prevent blocking, while explicitly handling malformed input as errors rather than crashes. Existing non-deterministic CBOR paths remain available but are distinct from this new deterministic wire format.

_native/macula\_cbor\nif · high confidence

The macula\_quic native interface has been replaced with a new Rust implementation based on the Quinn QUIC library, replacing the previous quicer/MsQuic backend. This rewrite introduces a dedicated Tokio runtime for QUIC operations, enabling asynchronous dialing, stream opening, and data sending without blocking the BEAM scheduler. It adds support for pubkey-anchored TLS verification (pinning Ed25519 public keys against self-signed certificates) for sovereign overlay peering, alongside standard system-CA and skip-verification modes. The new NIF exposes detailed connection and stream lifecycle events, application error codes, and configurable flow-control windows (16 MB stream, 64 MB connection) to improve throughput for multiplexed peering traffic.

_native/macula\quic · high confidence

A bug in the \macula\_ucan\_nif\ module caused the \exp\ (expiration), \nbf\ (not before), and \fct\ (facts) fields in UCAN tokens to be silently corrupted when serialized to and deserialized from JSON. This fix ensures that these optional payload fields are correctly preserved during token creation and verification, preventing unexpected token validity errors or metadata loss.

src/auth · high confidence

The UCAN token creation function now correctly rejects malformed options JSON instead of silently discarding critical fields like expiration (exp), not-before (nbf), and facts (fct). Previously, if the options JSON was invalid, the system would fall back to an empty object, resulting in tokens that never expired or lacked intended validity constraints without raising an error. This change ensures that any issue with the options input causes the token creation to fail explicitly, preventing the generation of insecure or incorrectly configured authorization tokens.

_native/macula\_ucan\nif · high confidence

Added EUnit tests for overlay components; Added comprehensive test coverage for the distribution system; Added integration test suite for multi-mode deployment; Added regression tests for the pubsub link connect watchdog self-heal; Added tests for gossip discovery security and static cluster strategies; Expanded test fixtures for cross-SDK frame validation; New end-to-end test suite for multi-node mesh scenarios.

The native Rust layer has been reorganized into distinct, focused crates for specific capabilities: \macula\_cbor\_nif\ (CBOR serialization), \macula\_crypto\_nif\ (Ed25519 and hashing), \macula\_did\_nif\ (DID operations), \macula\_mri\_nif\ (MRI hierarchy), \macula\_quic\ (QUIC transport), and \macula\_ucan\_nif\ (UCAN tokens). All NIFs now use \rustler\ 0.34, and cryptographic dependencies have been updated to \ed25519-dalek\ 3.0 and \base64\ 0.23.

(dependencies) · high confidence

A new \.tool-versions\ file pins the development environment to Erlang/OTP 28.4.2 and Elixir 1.18.4-otp-28, ensuring consistent builds and runtime behavior across the project.

(repo-wide) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 72.

• Code Health 92
• Architecture 100
• Maturity 75
• Readiness 62
• Security 77
• Event Sourcing 100

• 300 commits — 297 feature/other, 3 fixes

• (root) — 61 commits
• src/client — 35 commits
• plans/DESIGN_PQ_SIGNED_FRAMES_AND_RECORDS.md — 11 commits
• src/peering — 11 commits
• docs/guides — 10 commits
• test/macula_client_pool_keys_tests.erl — 10 commits
• test/overlay — 9 commits
• test/macula_dist_system — 8 commits
• plans/DESIGN_PQ_DHT_SLOTS_AND_BUDGET.md — 7 commits
• src/overlay — 7 commits
• src/record — 6 commits
• test/macula_identity_tests.erl — 6 commits
• native/macula_quic — 5 commits
• test/fixtures — 5 commits
• test/macula_frame_malformed_tests.erl — 5 commits
• (repo) — 4 commits
• test/macula_frame_received_tests.erl — 4 commits
• plans/PLAN_11_ORG_NAMESPACE_MIGRATION.md — 3 commits
• plans/PLAN_POST_QUANTUM_SECURITY.md — 3 commits
• plans/PLAN_POST_QUANTUM_SECURITY_DECISIONS.md — 3 commits

• fix: record: a node record's coordinate is fixed-point text within its range, written and read alike
• fix: test: a fixed zero-dropped composite that every stack refuses
• fix: test: storage keys of records named by their signer match fixed vectors
• change: Merge branch 'post-quantum' into merge-11.0.0
• change: On pluto-11-link: pluto-11-calls uncommitted at integration start 20260916
• change: build: the test profile relaxes the deprecated-catch warning, like nowarn_export_all
• change: build: xref fails on undefined and deprecated calls and unused locals, and a gate script runs it before a push
• change: cbor: unpack_deterministic/1 decodes at most 131,072 items, on a dirty CPU scheduler
• change: changelog: the release 2 entries sit under Unreleased
• change: chore: release v10.25.0
• change: chore: release v11.0.0
• change: chore: release v11.1.0
• change: chore: release v11.2.0
• change: client tests: link limits seeds name the node_id they expect
• change: client, content: the ensure_content_link rename reaches the source
• change: client, link, test: the last four gate reds — loader refusals nest their reasons, the pool signs bounded records through the custody path, EVENTs carry their publication hash and expiry, and the unsubscribe test speaks the signed-wire
• change: client, link: a pool runs one request admission, and each link holds it and its share
• change: client, stations: sign_node_record/3 under a not_after bound, and macula:parse_stations/1
• change: client: a child spec holds only a loader, and a pool counts the issuers it loses
• change: client: a loader's args say where the key is, and a failed supervised start logs no key
• …and 280 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

macula-io/macula was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.