macula_yggdrasil (macula v4.0.0)
View SourceYggdrasil-network helpers — pubkey-derived IPv6 addressing and self-signed Ed25519 cert generation.
Phase 1 (Tier 3) of the sovereign-overlay rollout. See the plan at PLAN_SOVEREIGN_OVERLAY_PHASE1.md (in macula-architecture) — §4.2 for the address derivation algorithm and §4.3 for the self-signed cert path.
Pure functions only. No network I/O. The Yggdrasil sidecar (yggdrasilnetwork/yggdrasil-go) is what actually routes the packets through the overlay; this module is the pubkey/address bridge and the cert generator.
Addressing matches the upstream yggdrasil-go reference implementation (src/address/address.go, AddrForKey):
1. Take a 32-byte Ed25519 public key. 2. Bitwise invert it. 3. Count leading 1-bits (call it N) — this becomes byte 1 of the IPv6 address. 4. Skip those N 1-bits and the single 0-bit that terminates the run. 5. Take the next 112 bits — these are the low 14 bytes of the IPv6 address. 6. Prepend 0x02 (Yggdrasil node-address prefix; subnet uses 0x03).
The resulting 200::/7 address is the routable IPv6 of the Yggdrasil node owning that keypair.
Summary
Functions
Derive the Yggdrasil IPv6 address (16 raw bytes) for an Ed25519 public key.
Generate a self-signed X.509 cert wrapping an Ed25519 identity keypair, with the derived Yggdrasil IPv6 as the sole Subject Alternative Name. Used by stations seeding their sovereign-overlay listener.
Same as cert_for/1, plus extra DNS Subject Alternative Names (e.g. the macula.io hostname for compatibility with existing hostname-based dial code paths).
Format a 16-byte IPv6 binary as the canonical colon-separated string. Useful for logs and config.
Types
Functions
-spec address_for(macula_identity:pubkey()) -> ipv6().
Derive the Yggdrasil IPv6 address (16 raw bytes) for an Ed25519 public key.
Generate a self-signed X.509 cert wrapping an Ed25519 identity keypair, with the derived Yggdrasil IPv6 as the sole Subject Alternative Name. Used by stations seeding their sovereign-overlay listener.
Same as cert_for/1, plus extra DNS Subject Alternative Names (e.g. the macula.io hostname for compatibility with existing hostname-based dial code paths).
Format a 16-byte IPv6 binary as the canonical colon-separated string. Useful for logs and config.