From 9b1dbd116d882d4b6ef03f138d1bde4c900d7ecb Mon Sep 17 00:00:00 2001 From: "shakespeare.diy" Date: Mon, 22 Jun 2026 22:46:03 +0300 Subject: [PATCH 1/2] Add PIP-04: Agent Short Code Define a user-friendly agent identifier built on NIP-05 (DNS-backed handle-to-pubkey mapping) and NIP-19 (nprofile sharing artifacts). - short code is a NIP-05 internet identifier, verified via .well-known/nostr.json - declared through kind 0 profile (nip05 field) and the PIP-00 agent definition event (short_code content field + nip05 tag) - nprofile used for copy-paste/QR sharing with relay hints - pubkey remains canonical identity; short code is discovery/display only - marked Recommended, sitting outside the required core baseline - update README and AGENTS.md to include PIP-04 in the series Co-authored-by: shakespeare.diy --- AGENTS.md | 3 +- PIP-04-agent-short-code.md | 156 +++++++++++++++++++++++++++++++++++++ README.md | 6 +- 3 files changed, 163 insertions(+), 2 deletions(-) create mode 100644 PIP-04-agent-short-code.md 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..5ceda40 --- /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: From d814a13714945eec82a2702f304f5ded9dec189e Mon Sep 17 00:00:00 2001 From: Denver <135147764+Denver-1st@users.noreply.github.com> Date: Mon, 22 Jun 2026 22:52:20 +0300 Subject: [PATCH 2/2] adding PIP-04 :Agent Short-code --- PIP-04-agent-short-code.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/PIP-04-agent-short-code.md b/PIP-04-agent-short-code.md index 5ceda40..8b6721c 100644 --- a/PIP-04-agent-short-code.md +++ b/PIP-04-agent-short-code.md @@ -9,7 +9,7 @@ - [PIP-00-agent-definition.md](./PIP-00-agent-definition.md) - [PIP-02-swap-state-machine.md](./PIP-02-swap-state-machine.md) -## Purpose + ## 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. @@ -20,14 +20,14 @@ The short code reuses two existing Nostr standards: The short code is a discovery and display surface. It does not replace the pubkey as canonical agent identity. -## Core Rule + ## 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 + ## Short Code Format A short code is a NIP-05 internet identifier: @@ -47,11 +47,11 @@ The full NIP-05 character set is permitted. For agent short codes, handles SHOUL 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 + ### Domain Root A short code MAY use the NIP-05 root form `_@`, in which case clients SHOULD display it as just ``. -## Declaration + ## Declaration The short code is declared through two cooperating events. No new event kind is introduced. @@ -69,7 +69,7 @@ The agent's kind 0 profile event SHOULD include a `nip05` field set to the short This is standard NIP-05. The kind 0 event is the primary verification anchor for the short code. -### Agent Definition Event + ### Agent Definition Event The agent definition event defined in [PIP-00](./PIP-00-agent-definition.md) SHOULD reference the short code in two places: @@ -87,7 +87,7 @@ The agent definition event defined in [PIP-00](./PIP-00-agent-definition.md) SHO 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 + ## Resolution To resolve a short code to a canonical agent, a client SHOULD: @@ -103,7 +103,7 @@ If any verification step fails, the client MUST treat the short code as unverifi 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 + ### 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. @@ -124,7 +124,7 @@ Clients MAY also share the short code directly. The two forms serve different co Neither form replaces the hex pubkey as the canonical identifier used in protocol events. -## Display + ## Display Clients that support short codes SHOULD: @@ -134,13 +134,13 @@ Clients that support short codes SHOULD: Clients MUST NOT present an unverified short code as if it were confirmed by DNS lookup. -## Use in Swap Events + ## 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 + ## Verification Boundary Short code verification is a discovery-time check, not a protocol-state fact. Specifically: @@ -150,7 +150,7 @@ Short code verification is a discovery-time check, not a protocol-state fact. Sp 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 + ## 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.