Search documentation of macula

# macula_resolve_address (macula v4.4.1)

View Source

Resolve a macula-net IPv6 address to its hosting station's QUIC endpoint via the DHT.

Phase 2 (PLAN_MACULA_NET_PHASE2.md §4.2). Two DHT lookups:

1. `address_pubkey_map` record keyed by `sha256("address_pubkey_map" || addr)` — returns the station pubkey that owns the address.
2. `station_endpoint` record keyed by `sha256("station_endpoint" || pubkey)` — returns `{quic_port, host_advertised}`.

Both records are signature-verified. The redirect record is also address-bound: `derive_address(realm, record.key) == addr` MUST hold, otherwise the answer is rejected. This makes the cheapest spoof (sign a record claiming someone else's address) detectable without consulting any external trust authority — the address derivation IS the proof of ownership.

The DHT is decoupled via a `find_fn` callback. Production wires `fun(Key) -> macula:find_record(Client, Key) end`; tests pass a capture function.

# Summary

## Types

endpoint/0
error_reason/0
find_fn/0

## Functions

resolve(Addr, Realm, FindFn)

Resolve a macula-net address. `Realm` is the 32-byte realm pubkey used for address derivation; the binding check rejects any redirect whose signer doesn't derive to `Addr` under that realm.

# Types

# endpoint/0

    -type endpoint() ::
              #{station_pubkey := <<_:256>>,
                quic_port := 1..65535,
                host_advertised := [binary()],
                alpn := binary() | undefined,
                expires_at := pos_integer(),
                hosted_daemon => <<_:256>>}.

# error_reason/0

    -type error_reason() ::
              not_found | bad_signature | bad_address_binding | bad_delegation | delegation_expired |
              malformed_record |
              term().

# find_fn/0

    -type find_fn() :: fun((Key :: <<_:256>>) -> {ok, macula_record:record()} | {error, not_found | term()}).

# Functions

# resolve(Addr, Realm, FindFn)

    -spec resolve(Addr :: <<_:128>>, Realm :: <<_:256>>, find_fn()) ->
                     {ok, endpoint()} | {error, error_reason()}.

Resolve a macula-net address. `Realm` is the 32-byte realm pubkey used for address derivation; the binding check rejects any redirect whose signer doesn't derive to `Addr` under that realm.