macula_record (macula v3.13.0)

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

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
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
tombstone_opts/0
type_tag/0
version/0

Functions

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)
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)
signature(_)
storage_key(_)
tombstone(SupersededKey, SupersededType, Reason)
tombstone(SupersededKey, SupersededType, Reason, Opts)
type(_)
verify(Record)
version(_)

Types

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()}.

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>>}.

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

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(<<type, key, subject_id>>). 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().

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

signature(_)

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()}.

version(_)