Search documentation of macula

# macula_record (macula v4.4.9)

View Source

PKARR-compatible signed records (envelope + node_record + tombstone).

A record is a map carrying:

- `type` (uint) — record type tag (`0x01` = node_record, `0x0C` = tombstone)
- `key` (32B) — owning Ed25519 pubkey
- `version` (16B) — UUIDv7
- `created_at` / `expires_at` (ms since epoch)
- `payload` (map) — type-specific
- `signature` (64B) — Ed25519 signature; present after `sign/2`

On the wire records are CBOR maps with single-letter keys (`t`, `k`, `v`, `c`, `x`, `p`, `s`) per `Part 6 §9`. Signatures are Ed25519 over `"macula-v2-record\0" ++ canonical_cbor(unsigned)`.

# Summary

## Types

address_pubkey_map_opts/0
content_announcement_opts/0
foundation_parameter_opts/0
foundation_parameter_value/0
foundation_realm_trust_list_opts/0
foundation_seed/0
foundation_seed_list_opts/0
foundation_t3_attestation_opts/0
host_delegation/0
hosted_address_map_opts/0
node_record_opts/0
procedure_advertisement_opts/0
realm_directory_opts/0
realm_member_endorsement_opts/0
realm_station_entry/0
realm_stations_opts/0
record/0
station_endpoint_opts/0
tombstone_opts/0
type_tag/0
version/0

## Functions

address_pubkey_map(StationPubkey, Addr)
address_pubkey_map(StationPubkey, Addr, Opts)
content_announcement(AnnouncerNode, MCID, Endpoint)
content_announcement(AnnouncerNode, MCID, Endpoint, Opts)
created_at(_)
decode(Bin)
encode(Record)
envelope(Type, Key, Payload, Opts)

Generic record builder. Used internally by every typed constructor and exposed publicly for domain-defined record types in the 0x20-0xFF tag range. Returns an UNSIGNED record map; pair with `sign/2`.

expires_at(_)
foundation_parameter(FoundationKey, Name, Value)
foundation_parameter(FoundationKey, Name, Value, Opts)
foundation_realm_trust_list(FoundationKey, Trusted)
foundation_realm_trust_list(FoundationKey, Trusted, Opts)
foundation_seed_list(FoundationKey, Seeds)
foundation_seed_list(FoundationKey, Seeds, Opts)
foundation_t3_attestation(FoundationKey, StationId, AuditDate)
foundation_t3_attestation(FoundationKey, StationId, AuditDate, Opts)
host_delegation(DaemonPk, HostPk, Realm, NotBeforeMs, NotAfterMs)

Build an unsigned host_delegation. Pair with `sign_host_delegation/2`.

host_delegation(DaemonPk, HostPk, Realm, NotBeforeMs, NotAfterMs, Opts)
hosted_address_map(HostPk, DaemonAddr, Delegation)

Build a host-signed redirect from a daemon address to its hosting station. Pair with `sign/2` (signed by the host's key, NOT the daemon's). Caller is responsible for embedding a delegation that's already been daemon-signed.

hosted_address_map(HostPk, DaemonAddr, Delegation, Opts)
key(_)
node_record(NodeId, Realms, Capabilities)
node_record(NodeId, Realms, Capabilities, Opts)
payload(_)
procedure_advertisement(AdvertiserNode, ProcedureUri, ServingStation)
procedure_advertisement(AdvertiserNode, ProcedureUri, ServingStation, Opts)
realm_directory(RealmId, Name, AdminKey)
realm_directory(RealmId, Name, AdminKey, Opts)
realm_member_endorsement(RealmId, Spec)
realm_member_endorsement(RealmId, Spec, Opts)
realm_stations(RealmId, Entries)
realm_stations(RealmId, Entries, Opts)
refresh(Record, Identity)

Rebuild a record with a fresh UUIDv7 version and a new `created_at` / `expires_at` pair (preserving the original TTL), then re-sign with `Identity`. Used by the owner's tRepublish loop (Part 3 §11) to keep a record alive across churn without changing its type, key, or payload.

sign(Record, Identity)
sign_host_delegation(Delegation, Identity)

Sign the delegation with the daemon's keypair (the daemon authorises the host). Adds `daemon_sig`.

signature(_)
station_endpoint(StationPubkey, QuicPort)
station_endpoint(StationPubkey, QuicPort, Opts)
storage_key(_)
tombstone(SupersededKey, SupersededType, Reason)
tombstone(SupersededKey, SupersededType, Reason, Opts)
type(_)
verify(Record)
verify_host_delegation(Delegation)

Verify a signed delegation. Returns the delegation map on success.

version(_)

# Types

# address_pubkey_map_opts/0

    -type address_pubkey_map_opts() :: #{ttl_ms => pos_integer()}.

# content_announcement_opts/0

    -type content_announcement_opts() ::
              #{name => binary(),
                size => non_neg_integer(),
                chunk_count => non_neg_integer(),
                ttl_ms => pos_integer()}.

# foundation_parameter_opts/0

    -type foundation_parameter_opts() ::
              #{valid_from => pos_integer(),
                valid_until => pos_integer(),
                prior_version => <<_:128>> | undefined,
                ttl_ms => pos_integer()}.

# foundation_parameter_value/0

    -type foundation_parameter_value() :: integer() | binary() | [integer() | binary()] | boolean().

# foundation_realm_trust_list_opts/0

    -type foundation_realm_trust_list_opts() ::
              #{realms_revoked => [macula_identity:pubkey()],
                valid_until => pos_integer(),
                ttl_ms => pos_integer()}.

# foundation_seed/0

    -type foundation_seed() :: #{node_id := macula_identity:pubkey(), addresses := [map()], tier := 3 | 4}.

# foundation_seed_list_opts/0

    -type foundation_seed_list_opts() ::
              #{valid_from => pos_integer(), valid_until => pos_integer(), ttl_ms => pos_integer()}.

# foundation_t3_attestation_opts/0

    -type foundation_t3_attestation_opts() ::
              #{valid_until => pos_integer(), notes => binary(), ttl_ms => pos_integer()}.

# host_delegation/0

    -type host_delegation() ::
              #{daemon_pubkey := <<_:256>>,
                host_pubkey := <<_:256>>,
                realm_pubkey := <<_:256>>,
                not_before_ms := pos_integer(),
                not_after_ms := pos_integer(),
                daemon_sig => <<_:512>>}.

# hosted_address_map_opts/0

    -type hosted_address_map_opts() :: #{ttl_ms => pos_integer()}.

# node_record_opts/0

    -type node_record_opts() ::
              #{station_id => macula_identity:pubkey(),
                caps_hint => binary(),
                display_name => binary(),
                ttl_ms => pos_integer(),
                hostname => binary(),
                endpoint => binary(),
                city => binary(),
                country => binary(),
                lat => float() | integer(),
                lng => float() | integer(),
                kind => binary(),
                peers => [macula_identity:pubkey()]}.

# procedure_advertisement_opts/0

    -type procedure_advertisement_opts() ::
              #{session_token_hint => binary(),
                rate_limit_qps => non_neg_integer(),
                max_concurrency => non_neg_integer(),
                ttl_ms => pos_integer()}.

# realm_directory_opts/0

    -type realm_directory_opts() :: #{policy_url => binary(), ttl_ms => pos_integer()}.

# realm_member_endorsement_opts/0

    -type realm_member_endorsement_opts() ::
              #{valid_from => pos_integer(), valid_until => pos_integer(), ttl_ms => pos_integer()}.

# realm_station_entry/0

    -type realm_station_entry() :: #{station_id := macula_identity:pubkey(), roles := [binary()]}.

# realm_stations_opts/0

    -type realm_stations_opts() :: #{ttl_ms => pos_integer()}.

# record/0

    -type record() ::
              #{type := type_tag(),
                key := <<_:256>>,
                version := version(),
                created_at := pos_integer(),
                expires_at := pos_integer(),
                payload := map(),
                signature => <<_:512>>}.

# station_endpoint_opts/0

    -type station_endpoint_opts() ::
              #{host_advertised => [binary()], alpn => binary(), ttl_ms => pos_integer()}.

# tombstone_opts/0

    -type tombstone_opts() :: #{detail => binary(), ttl_ms => pos_integer()}.

# type_tag/0

    -type type_tag() :: 1..255.

# version/0

    -type version() :: <<_:128>>.

# Functions

# address_pubkey_map(StationPubkey, Addr)

    -spec address_pubkey_map(macula_identity:pubkey(), Addr :: <<_:128>>) -> record().

# address_pubkey_map(StationPubkey, Addr, Opts)

    -spec address_pubkey_map(macula_identity:pubkey(), Addr :: <<_:128>>, address_pubkey_map_opts()) ->
                                record().

# content_announcement(AnnouncerNode, MCID, Endpoint)

    -spec content_announcement(macula_identity:pubkey(), binary(), binary()) -> record().

# content_announcement(AnnouncerNode, MCID, Endpoint, Opts)

    -spec content_announcement(macula_identity:pubkey(), binary(), binary(), content_announcement_opts()) ->
                                  record().

# created_at(_)

# decode(Bin)

    -spec decode(binary()) -> {ok, record()} | {error, term()}.

# encode(Record)

    -spec encode(record()) -> binary().

# envelope(Type, Key, Payload, Opts)

    -spec envelope(type_tag(), <<_:256>>, map(), map()) -> record().

Generic record builder. Used internally by every typed constructor and exposed publicly for domain-defined record types in the 0x20-0xFF tag range. Returns an UNSIGNED record map; pair with `sign/2`.

The `key` field is always the signer's 32-byte Ed25519 public key (`verify/1` looks it up there). For facts where one signer publishes about many subjects (e.g., a realm admin signing many license records), pass a `subject_id` opt — `storage_key/1` derives a per-subject 32-byte slot via `BLAKE3(&lt;&lt;type, key, subject_id&gt;&gt;)`. Without `subject_id` the storage key is `key` verbatim (one DHT slot per signer).

Domain code names its own payload fields. Single-letter wire keys (Part 6 §9) are an envelope-level concern; payloads use whatever naming makes sense in the domain.

# expires_at(_)

# foundation_parameter(FoundationKey, Name, Value)

    -spec foundation_parameter(macula_identity:pubkey(), binary(), foundation_parameter_value()) -> record().

# foundation_parameter(FoundationKey, Name, Value, Opts)

    -spec foundation_parameter(macula_identity:pubkey(),
                               binary(),
                               foundation_parameter_value(),
                               foundation_parameter_opts()) ->
                                  record().

# foundation_realm_trust_list(FoundationKey, Trusted)

    -spec foundation_realm_trust_list(macula_identity:pubkey(), [macula_identity:pubkey()]) -> record().

# foundation_realm_trust_list(FoundationKey, Trusted, Opts)

    -spec foundation_realm_trust_list(macula_identity:pubkey(),
                                      [macula_identity:pubkey()],
                                      foundation_realm_trust_list_opts()) ->
                                         record().

# foundation_seed_list(FoundationKey, Seeds)

    -spec foundation_seed_list(macula_identity:pubkey(), [foundation_seed()]) -> record().

# foundation_seed_list(FoundationKey, Seeds, Opts)

    -spec foundation_seed_list(macula_identity:pubkey(), [foundation_seed()], foundation_seed_list_opts()) ->
                                  record().

# foundation_t3_attestation(FoundationKey, StationId, AuditDate)

    -spec foundation_t3_attestation(macula_identity:pubkey(), macula_identity:pubkey(), pos_integer()) ->
                                       record().

# foundation_t3_attestation(FoundationKey, StationId, AuditDate, Opts)

    -spec foundation_t3_attestation(macula_identity:pubkey(),
                                    macula_identity:pubkey(),
                                    pos_integer(),
                                    foundation_t3_attestation_opts()) ->
                                       record().

# host_delegation(DaemonPk, HostPk, Realm, NotBeforeMs, NotAfterMs)

    -spec host_delegation(DaemonPk :: <<_:256>>,
                          HostPk :: <<_:256>>,
                          Realm :: <<_:256>>,
                          NotBeforeMs :: pos_integer(),
                          NotAfterMs :: pos_integer()) ->
                             host_delegation().

Build an unsigned host_delegation. Pair with `sign_host_delegation/2`.

# host_delegation(DaemonPk, HostPk, Realm, NotBeforeMs, NotAfterMs, Opts)

    -spec host_delegation(<<_:256>>, <<_:256>>, <<_:256>>, pos_integer(), pos_integer(), map()) ->
                             host_delegation().

# hosted_address_map(HostPk, DaemonAddr, Delegation)

    -spec hosted_address_map(HostPk :: <<_:256>>, DaemonAddr :: <<_:128>>, Delegation :: host_delegation()) ->
                                record().

Build a host-signed redirect from a daemon address to its hosting station. Pair with `sign/2` (signed by the host's key, NOT the daemon's). Caller is responsible for embedding a delegation that's already been daemon-signed.

# hosted_address_map(HostPk, DaemonAddr, Delegation, Opts)

    -spec hosted_address_map(<<_:256>>, <<_:128>>, host_delegation(), hosted_address_map_opts()) -> record().

# key(_)

# node_record(NodeId, Realms, Capabilities)

    -spec node_record(macula_identity:pubkey(), [macula_identity:pubkey()], non_neg_integer()) -> record().

# node_record(NodeId, Realms, Capabilities, Opts)

    -spec node_record(macula_identity:pubkey(),
                      [macula_identity:pubkey()],
                      non_neg_integer(),
                      node_record_opts()) ->
                         record().

# payload(_)

# procedure_advertisement(AdvertiserNode, ProcedureUri, ServingStation)

    -spec procedure_advertisement(macula_identity:pubkey(), binary(), macula_identity:pubkey()) -> record().

# procedure_advertisement(AdvertiserNode, ProcedureUri, ServingStation, Opts)

    -spec procedure_advertisement(macula_identity:pubkey(),
                                  binary(),
                                  macula_identity:pubkey(),
                                  procedure_advertisement_opts()) ->
                                     record().

# realm_directory(RealmId, Name, AdminKey)

    -spec realm_directory(macula_identity:pubkey(), binary(), macula_identity:pubkey()) -> record().

# realm_directory(RealmId, Name, AdminKey, Opts)

    -spec realm_directory(macula_identity:pubkey(),
                          binary(),
                          macula_identity:pubkey(),
                          realm_directory_opts()) ->
                             record().

# realm_member_endorsement(RealmId, Spec)

    -spec realm_member_endorsement(macula_identity:pubkey(),
                                   #{realm := macula_identity:pubkey(),
                                     member_node := macula_identity:pubkey(),
                                     roles := [binary()]}) ->
                                      record().

# realm_member_endorsement(RealmId, Spec, Opts)

    -spec realm_member_endorsement(macula_identity:pubkey(),
                                   #{realm := macula_identity:pubkey(),
                                     member_node := macula_identity:pubkey(),
                                     roles := [binary()]},
                                   realm_member_endorsement_opts()) ->
                                      record().

# realm_stations(RealmId, Entries)

    -spec realm_stations(macula_identity:pubkey(), [realm_station_entry()]) -> record().

# realm_stations(RealmId, Entries, Opts)

    -spec realm_stations(macula_identity:pubkey(), [realm_station_entry()], realm_stations_opts()) ->
                            record().

# refresh(Record, Identity)

    -spec refresh(record(), macula_identity:key_pair() | macula_identity:privkey()) -> record().

Rebuild a record with a fresh UUIDv7 version and a new `created_at` / `expires_at` pair (preserving the original TTL), then re-sign with `Identity`. Used by the owner's tRepublish loop (Part 3 §11) to keep a record alive across churn without changing its type, key, or payload.

The new signature replaces any prior signature; callers can safely pass an already-signed record — the prior signature is stripped before re-signing.

# sign(Record, Identity)

    -spec sign(record(), macula_identity:key_pair() | macula_identity:privkey()) -> record().

# sign_host_delegation(Delegation, Identity)

    -spec sign_host_delegation(host_delegation(), macula_identity:key_pair() | macula_identity:privkey()) ->
                                  host_delegation().

Sign the delegation with the daemon's keypair (the daemon authorises the host). Adds `daemon_sig`.

# signature(_)

# station_endpoint(StationPubkey, QuicPort)

    -spec station_endpoint(macula_identity:pubkey(), QuicPort :: 1..65535) -> record().

# station_endpoint(StationPubkey, QuicPort, Opts)

    -spec station_endpoint(macula_identity:pubkey(), QuicPort :: 1..65535, station_endpoint_opts()) ->
                              record().

# storage_key(_)

    -spec storage_key(record()) -> <<_:256>>.

# tombstone(SupersededKey, SupersededType, Reason)

    -spec tombstone(macula_identity:pubkey(), type_tag(), atom()) -> record().

# tombstone(SupersededKey, SupersededType, Reason, Opts)

    -spec tombstone(macula_identity:pubkey(), type_tag(), atom(), tombstone_opts()) -> record().

# type(_)

# verify(Record)

    -spec verify(record()) -> {ok, record()} | {error, term()}.

# verify_host_delegation(Delegation)

    -spec verify_host_delegation(host_delegation()) -> {ok, host_delegation()} | {error, term()}.

Verify a signed delegation. Returns the delegation map on success.

# version(_)