# Plan: Addresses

## Overview

This chapter introduces the `Address` struct — a stable reference to a replaceable or
addressable event. Where an event ID is a hash of a specific version, an address is the
triple `(kind, pubkey, identifier)` that names the *slot* a mutable event occupies.

## Prerequisites

Reader has already covered: keys (PublicKey, bech32), tags (Tags, d-tag access via
`tags.value("d")`), events (Event struct), kinds (kind ranges, is_addressable,
is_replaceable).

## Structure

### 1. Motivation (prose only)
- Event IDs are hashes of content — they change when the content changes
- For replaceable/addressable events, you need a stable reference
- An address is `kind:pubkey:identifier` — it names the slot, not the version

### 2. The module
- Register `pub mod addresses;` in lib.rs
- Import dependencies: keys::PublicKey, tags::Tag, events::Event, kinds, bech32, std::fmt, std::str::FromStr

### 3. Error type
- `AddressError` enum: InvalidFormat, InvalidBech32, WrongPrefix, InvalidKey, FieldMissing(&'static str), TlvError

### 4. The `Address` struct
- Fields: `kind: u16`, `pubkey: PublicKey`, `identifier: String`
- Constructor: `Address::new(kind, pubkey, identifier)`
- `from_event(event) -> Option<Self>` — returns None for non-replaceable/non-addressable events. Uses `tags.value("d").unwrap_or("").to_string()` for identifier.
- `to_tag(relay_hint: Option<&str>) -> Tag` — produces an `a` tag

### 5. Display / FromStr (kind:pubkey:identifier format)
- `Display`: `write!(f, "{}:{}:{}", self.kind, self.pubkey, self.identifier)`
- `FromStr`: split on `:`, take first two segments, join remainder as identifier (handles colons in d-tags)

### 6. NIP-19 naddr encoding
- Introduce TLV format: type(1 byte) + length(1 byte) + value(N bytes)
- Constants: SPECIAL=0, RELAY=1, AUTHOR=2, KIND=3
- `to_naddr() -> String` — encode as bech32 with "naddr" prefix
- `from_naddr(s: &str) -> Result<(Self, Vec<String>), AddressError>` — returns address + relay hints
  - TLV decode: while loop consuming bytes
  - SPECIAL=identifier (UTF-8), RELAY=URL string, AUTHOR=32-byte pubkey, KIND=u32 big-endian

### 7. What's next
- Brief pointer to proof of work or filters chapter

## Code placement
- All code in `coracle-lib/src/addresses.rs`
- Module registered in `coracle-lib/src/lib.rs`

## Tests needed
- `Address::new` basic construction
- `from_event` for addressable event (returns Some)
- `from_event` for regular event (returns None)
- `from_event` for replaceable event (returns Some, empty identifier)
- Display round-trip through FromStr
- to_naddr / from_naddr round-trip
- FromStr with identifier containing colons
- to_tag produces correct `a` tag format