macula_record (macula v4.2.4)

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(_)