coracle-rust/book/research/addresses.md

Research: Addresses

Topic Summary

Create an Address struct representing a nostr event address (kind:pubkey:d-tag). It should:

• Be constructable from an event via from_event
• Encode/decode to the naddr NIP-19 bech32 format (TLV-based)
• Encode/decode to the kind:pubkey:identifier string format
• Provide convenient property access (kind, pubkey, identifier)

The reader already understands kind ranges and addressable events from the kinds chapter.

Philosophy

From ref/building-nostr:

• Events are content-addressable via their ID (hash), giving referential transparency. But replaceability broke this — a replaceable event's ID changes on every update, so you need a stable reference.
• An "address" is kind:pubkey:identifier, pointing to all events sharing the same kind, pubkey, and d-tag.
• The a tag carries this triple as its value, with an optional relay hint in position 2.
• Design principle: "you should have a slight bias towards regular, non-replaceable events because they don't break referential transparency."
• The address includes the author's pubkey, which enables outbox-model relay lookup — unlike a bare event ID.

Reference Implementation Analysis

applesauce

• No custom Address struct — re-exports AddressPointer from nostr-tools: { kind, pubkey, identifier, relays? }
• Also has AddressPointerWithoutD for replaceable (non-addressable) events
• createReplaceableAddress(kind, pubkey, identifier?) concatenates with :
• parseReplaceableAddress(str) splits on :, handles identifiers containing colons by joining remaining parts
• getAddressPointerForEvent(event, relays?) extracts d-tag: event.tags.find(t => t[0] === "d")?.[1] ?? ""
• Delegates naddr encoding to nostr-tools

ndk

• No dedicated Address type — handles addresses on NDKEvent directly
• tagAddress() returns "${kind}:${pubkey}:${dTag ?? ""}"
• dTag getter/setter on NDKEvent
• Auto-generates d-tag for param replaceable events if missing (random string)
• filterFromId(id) handles three input forms: raw address string, naddr bech32, or event ID
• Regex: NIP33_A_REGEX = /^(\d+):([0-9A-Fa-f]+)(?::(.*))?$/
• Delegates nip19 to nostr-tools

nostr-gadgets

• No dedicated Address type — addresses are plain kind:pubkey:d-tag strings
• isATag(input) validates via regex: /^\d+:[0-9a-f]{64}:[^:]+$/
• Imports AddressPointer from nostr-tools when needed
• Inline parsing by splitting on :
• d-tag defaults to empty string

nostrlib (Go)

• Type: EntityPointer { PublicKey, Kind, Identifier, Relays []string }
• AsTagReference(): fmt.Sprintf("%d:%s:%s", ep.Kind, ep.PublicKey.Hex(), ep.Identifier)
• ParseAddrString(addr): splits on : (max 3 parts)
• Tags.GetD() returns first d tag value or ""
• MatchesEvent checks kind + pubkey + identifier
• NIP-19 TLV: identifier=TLV0, relays=TLV1, author=TLV2(32 bytes), kind=TLV3(u32 BE)
• No separate from_event — caller assembles EntityPointer

nostr-tools

• AddressPointer = { identifier: string, pubkey: string, kind: number, relays?: string[] }
• naddr TLV: 0=identifier(UTF-8), 1=relay(multiple), 2=pubkey(32 bytes), 3=kind(u32 BE)
• Strict decode: TLV 0, 2, 3 required; relays default to []
• a tag parsed as tag[1].split(':')

rust-nostr

• Coordinate { kind: Kind, public_key: PublicKey, identifier: String }
• Nip19Coordinate { coordinate: Coordinate, relays: Vec<RelayUrl> } (separate from core Coordinate)
• from_kpi_format(str) parses kind:pubkey:d-tag via split on :
• parse(str) tries kpi format, then bech32, then NIP-21 URI
• Display outputs kind:pubkey:identifier
• FromStr delegates to parse()
• verify() validates: replaceable must have empty identifier, addressable must have non-empty
• TLV encode: SPECIAL(0)=identifier, AUTHOR(2)=32-byte pubkey, KIND(3)=u32 BE, RELAY(1)=URL strings
• TLV decode: while loop consuming bytes, first occurrence wins for each field type
• Coordinate converts Into<Tag> and Into<Filter>
• CoordinateBorrow<'a> for zero-copy operations

welshman

• Address class with kind, pubkey, identifier, relays
• Address.from(str, relays?) parses kind:pubkey:identifier via regex
• Address.fromNaddr(naddr) decodes via nostr-tools
• Address.fromEvent(event, relays?) extracts d-tag: event.tags.find(t => t[0] === "d")?.[1] || ""
• toString() returns kind:pubkey:identifier
• toNaddr() delegates to nostr-tools
• getAddress(event) shorthand
• Address.isAddress(str) regex test

Common Patterns

1. Three fields: kind (u16), pubkey (32 bytes), identifier/d-tag (string). All implementations agree.
2. String format: kind:pubkey:identifier — universal, colon-separated, kind is decimal.
3. NIP-19 TLV: identifier=type 0, relay=type 1, author=type 2 (32 bytes), kind=type 3 (u32 big-endian).
4. d-tag defaults to empty string, not None/null — important for replaceable events that have no d-tag.
5. from_event pattern: extract d-tag from tags.find("d")?.value() ?? "", combine with event.kind and event.pubkey.
6. Relay hints are separate: the core address is just the triple; relays are transport metadata. Most implementations keep them optional/separate.
7. Parsing colon-split: most implementations just split on : and take 3 parts. Some handle identifiers containing colons by joining remaining parts.

Considerations for Our Implementation

• Keep the core Address struct to the three fields (kind, pubkey, identifier). Relay hints can be added later as a wrapper or in the naddr encoding methods.
• from_event should work on our existing Event type, using tags.value("d") which already exists.
• NIP-19 TLV encoding is new infrastructure — the keys chapter only used simple bech32 (no TLV). This chapter introduces the TLV pattern that will be reused for nprofile and nevent later.
• Display/FromStr should use the kind:pubkey:identifier format (the a tag value), since that's the most common string representation.
• Unlike rust-nostr, we don't need to validate that addressable kinds have non-empty identifiers — an address is just a reference triple, and empty identifiers are valid for replaceable events.
• The identifier field should handle colons in d-tags correctly during parsing.