diff --git a/AGENTS.md b/AGENTS.md index 224f88e..1d5478e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,12 +14,13 @@ When referring to automation working on this repository, use explicit terms such ## Spec Structure -The active PIP series contains only required PIPs for the minimum interoperable core: +The active PIP series contains the required PIPs for the minimum interoperable core plus one recommended discovery layer: - `PIP-00-agent-definition.md`: public agent capability and discovery record - `PIP-01-escrow-descriptor.md`: public escrow declaration referenced by agents and swaps - `PIP-02-swap-state-machine.md`: request, transition, evidence, dispute, note, and snapshot event lifecycle - `PIP-03-dispute-policy.md`: dispute classes, timeout classes, evidence boundary, and resolution modes +- `PIP-04-agent-short-code.md`: user-friendly agent identification, verification, and discovery using NIP-05 and NIP-19 (recommended) Read `README.md` first, then read only the PIPs directly relevant to the requested change. diff --git a/PIP-04-agent-short-code.md b/PIP-04-agent-short-code.md new file mode 100644 index 0000000..8b6721c --- /dev/null +++ b/PIP-04-agent-short-code.md @@ -0,0 +1,156 @@ +# PIP-04: Agent Short Code + +## Status + +- Status: Draft +- Implementation: Recommended +- Scope: user-friendly agent identification, verification, and discovery using NIP-05 and NIP-19 +- Related: + - [PIP-00-agent-definition.md](./PIP-00-agent-definition.md) + - [PIP-02-swap-state-machine.md](./PIP-02-swap-state-machine.md) + + ## Purpose + +This document defines the agent short code: a compact, human-friendly identifier that lets users discover, verify, and share Pontmore agents without handling raw pubkeys. + +The short code reuses two existing Nostr standards: + +- NIP-05 for DNS-backed mapping from a memorable handle to a canonical hex pubkey +- NIP-19 for bech32-encoded shareable artifacts that bundle the pubkey with relay hints + +The short code is a discovery and display surface. It does not replace the pubkey as canonical agent identity. + + ## Core Rule + +- **the Nostr pubkey is the canonical agent identity** +- **the short code is a verified alias for discovery, display, and sharing** + +Clients MUST always follow the pubkey, not the short code. If a short code ever resolves to a different pubkey, clients MUST NOT silently replace a previously established agent reference. The short code is an entry point, not a persistent identity. + + ## Short Code Format + +A short code is a NIP-05 internet identifier: + +```text +@ +``` + +- `` is the NIP-05 local part +- `` is the NIP-05 domain that serves `.well-known/nostr.json` + +The full NIP-05 character set is permitted. For agent short codes, handles SHOULD be: + +- lowercase +- 3 to 16 characters +- limited to `a-z`, `0-9`, and `-` +- free of leading or trailing hyphens + +These constraints are recommendations for memorability and consistent display, not a hard restriction on the NIP-05 charset. Clients MUST accept any valid NIP-05 identifier. + + ### Domain Root + +A short code MAY use the NIP-05 root form `_@`, in which case clients SHOULD display it as just ``. + + ## Declaration + +The short code is declared through two cooperating events. No new event kind is introduced. + +### Kind 0 Profile Event + +The agent's kind 0 profile event SHOULD include a `nip05` field set to the short code: + +```json +{ + "name": "K45 Sud", + "about": "Pontmore swap agent serving East Africa", + "nip05": "k45sud@pontmore.example" +} +``` + +This is standard NIP-05. The kind 0 event is the primary verification anchor for the short code. + + ### Agent Definition Event + +The agent definition event defined in [PIP-00](./PIP-00-agent-definition.md) SHOULD reference the short code in two places: + +1. A `nip05` tag on the event, for relay filtering and indexing: + + ```text + ["nip05", "k45sud@pontmore.example"] + ``` + +2. A `short_code` field inside the versioned `content` JSON: + + ```json + "short_code": "k45sud@pontmore.example" + ``` + +The `short_code` content field is the canonical declaration on the agent definition. The `nip05` tag is an index and discovery aid. Clients MUST NOT treat a `nip05` tag as authoritative unless the same value is present in `content.short_code`. + + ## Resolution + +To resolve a short code to a canonical agent, a client SHOULD: + +1. Split the short code into `` and ``. +2. Fetch `https:///.well-known/nostr.json?name=`. +3. Read the hex pubkey from `names[]`. +4. Fetch the kind 0 profile event for that pubkey. +5. Verify that the kind 0 `nip05` field matches the original short code. +6. Fetch the agent definition event (kind `30360`) for that pubkey. +7. Verify that `content.short_code` matches the original short code. + +If any verification step fails, the client MUST treat the short code as unverified and SHOULD warn the user before proceeding. + +The `.well-known/nostr.json` response MAY include a `relays` map as described in NIP-05. Clients SHOULD use the listed relays as hints for fetching the agent's profile, agent definition, and relay list. + + ### Multiple Agent Profiles + +An identity may publish multiple agent definitions with different `d` tags, as described in [PIP-00](./PIP-00-agent-definition.md). A short code resolves to one pubkey. The short code does not select a specific `d` tag. + +When a resolved pubkey has multiple agent definitions, clients SHOULD default to the `agent` profile unless the user or a deeper reference selects a more specific profile. + +## Sharing + +For sharing an agent outside of a typed short code, clients SHOULD use NIP-19 `nprofile` encoding. An `nprofile` bundles the agent pubkey with relay hints, letting recipients locate the agent without re-resolving the short code: + +```text +nprofile1qqsrhuxx8l9ex335q7he0f09aej04zpazpl0ne2cgukyawd24mayt8gpp4mhxue69uhhytnc9e3k7mgpz4mhxue69uhkg6nzv9ejuumpv34kytnrdaksjlyr9p +``` + +Clients MAY also share the short code directly. The two forms serve different contexts: + +- **short code**: human-typed, human-read, DNS-verified entry point +- **nprofile**: copy-paste and QR-code shareable artifact with relay hints + +Neither form replaces the hex pubkey as the canonical identifier used in protocol events. + + ## Display + +Clients that support short codes SHOULD: + +- display the short code alongside or instead of the raw `npub` when one is verified +- continue to display the `npub` or `nprofile` when no verified short code exists +- show the short code in a visually distinct way from free-text names so users can tell it is a verified identifier + +Clients MUST NOT present an unverified short code as if it were confirmed by DNS lookup. + + ## Use in Swap Events + +Swap request events defined in [PIP-02](./PIP-02-swap-state-machine.md) identify participants by pubkey. The short code is not used inside swap content as a participant identifier. + +A short code MAY appear in a human-readable note event (kind `7304`) or in client UI as a display label for an agent referenced by pubkey. The swap state machine itself MUST use pubkeys for all normative participant references. + + ## Verification Boundary + +Short code verification is a discovery-time check, not a protocol-state fact. Specifically: + +- verification confirms that a handle and domain currently map to a pubkey +- verification does not certify trustworthiness, operator status, or escrow solvency +- a verified short code does not override the agent definition, escrow descriptor, or dispute policy + +Trust and capability assertions remain the responsibility of [PIP-00](./PIP-00-agent-definition.md), [PIP-01-escrow-descriptor.md](./PIP-01-escrow-descriptor.md), and [PIP-03-dispute-policy.md](./PIP-03-dispute-policy.md). + + ## Open Questions + +- Whether a Pontmore-specific well-known path or response shape is needed beyond standard NIP-05, or whether plain NIP-05 is sufficient for all agent discovery cases. +- Whether short codes should support a Pontmore-native suffix or tag to distinguish agent handles from general Nostr handles in mixed directories. diff --git a/README.md b/README.md index 89db8d6..2d1a749 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ References to automation working on this repository are written explicitly as `A ## PIP Series -The PIPs are ordered by dependency and implementation priority. At this stage, the repository contains only the required PIPs for the minimum interoperable protocol core. +The PIPs are ordered by dependency and implementation priority. `PIP-00` through `PIP-03` are required for the minimum interoperable protocol core. `PIP-04` is a recommended discovery and display layer. Read `PIP-00` through `PIP-03` first. @@ -32,6 +32,10 @@ Read `PIP-00` through `PIP-03` first. - Implementation: `Required` - dispute classes, timeout classes, evidence boundary, and resolution modes +- [PIP-04-agent-short-code.md](./PIP-04-agent-short-code.md) + - Implementation: `Recommended` + - user-friendly agent identification, verification, and discovery using NIP-05 and NIP-19 + ## Design Direction Pontmore is designed around a small set of protocol positions: