Defining an Open (Human) Agent Network for Bitcoin On/Off-Ramps
## Summary This 45-minute hands-on technical workshop introduces contributors to the Pontmore protocol, showcases the minimum interoperable protocol core, and helps participants produce concrete contribution candidates for the protocol repository. Pontmore is a Nostr-native protocol family for Agent identity, capability discovery, escrow declaration, and swap lifecycle coordination. The workshop focuses on protocol specification work: reading the active PIPs, mapping behavior to the correct protocol surface, identifying ambiguities, and drafting small issues or pull-request-ready text. ## Audience This workshop is intended for: - Nostr builders - Bitcoin and Lightning developers - protocol reviewers - escrow or swap operators - technical contributors interested in Pontmore interoperability Participants should be comfortable reading technical specifications and structured event examples. No Pontmore implementation experience is required. ## Workshop Goals By the end of the workshop, participants should be able to: - explain Pontmore's core protocol model - identify the role of each required PIP - distinguish public protocol state from private or operator-layer data - map swap behavior to the correct PIP - identify valid protocol contribution opportunities - draft a small issue or pull-request-ready clarification ## Required Materials Participants should have access to the Pontmore protocol repository: - `README.md` - `PIP-00-agent-definition.md` - `PIP-01-escrow-descriptor.md` - `PIP-02-swap-state-machine.md` - `PIP-03-dispute-policy.md` Optional: - a GitHub account - a local clone of `https://github.com/pontmore/protocol` - a text editor for drafting issue or PR text ## Core Message Pontmore does not make an application account the identity root. The Nostr identity is the Agent. Applications, dashboards, indexes, operator tools, and databases are implementation overlays that wrap around the protocol rather than redefine it. The public protocol surface is defined by: - Agent definitions - escrow descriptors - swap request and transition events - public evidence references - dispute events - replaceable snapshots Private settlement details, internal operator notes, payment instructions, raw screenshots, KYC data, and application databases are outside the canonical public protocol state unless the PIPs explicitly define a public reference or disclosure boundary. ## Agenda ### 0:00-0:05 - Framing Introduce Pontmore as a Nostr-native protocol family for: - Agent identity and capability discovery - escrow declaration - swap lifecycle coordination - dispute and evidence boundaries Explain that the repository contains the required PIPs for the minimum interoperable core: - `PIP-00`: public Agent capability and discovery record - `PIP-01`: public escrow declaration referenced by Agents and swaps - `PIP-02`: swap request, transition, evidence, dispute, note, and snapshot event lifecycle - `PIP-03`: dispute classes, timeout classes, evidence boundary, and resolution modes ### 0:05-0:12 - Protocol Map Walk through the four required PIPs in dependency order. `PIP-00` answers: - Who is the Agent? - How is the Agent discovered? - What capabilities does the Agent publicly declare? - Which escrow descriptor is the default? `PIP-01` answers: - What escrow mechanism is being used? - Which settlement or invoice networks are supported? - What funding, release, refund, and dispute assumptions apply? - How is the escrow instance referenced? `PIP-02` answers: - What is the immutable swap request? - Which append-only transition events advance the swap? - What evidence is public? - What remains in the companion private message lane? - What role do replaceable snapshots play? `PIP-03` answers: - Which dispute and timeout classes exist? - Which evidence categories can support a dispute? - Which resolution modes can an operator apply? - What belongs in public protocol state versus private operator handling? ### 0:12-0:22 - Showcase: One Swap Through the PIPs Use a simple scenario: A customer wants to swap fiat payment for Bitcoin payout through an Agent using Lightning-based escrow. Ask participants to map each fact to the correct protocol area: ```text Agent supports MZN and Lightning Escrow uses custodial_escrow Raw bank receipt screenshot Public hash of payment proof Swap moved from requested to funded Refund allowed after timeout Operator dashboard queue Agent has profile d tag agent:ke ``` Expected mapping: ```text Agent supports MZN and Lightning -> PIP-00 Escrow uses custodial_escrow -> PIP-01 Raw bank receipt screenshot -> private/operator layer Public hash of payment proof -> PIP-02/PIP-03 evidence reference Swap moved from requested to funded -> PIP-02 transition Refund allowed after timeout -> PIP-01 release/refund rule and PIP-03 timeout class Operator dashboard queue -> implementation overlay Agent has profile d tag agent:ke -> PIP-00 ``` The point of this exercise is to make participants practice the most important contribution skill: deciding where a rule belongs before trying to write it. ### 0:22-0:35 - Hands-On Contribution Exercise Split participants into pairs or small groups. Assign each group one contribution track. #### Track A: Agent Discovery Read `PIP-00-agent-definition.md`. Look for one place where a client implementer might need more precision around: - multiple Agent definitions - `d` tag conventions - default profile behavior - recommended tags Output: - one issue title - the current ambiguity - proposed clarification text Example issue title: ```text PIP-00: Clarify default Agent profile selection when multiple d tags exist ``` #### Track B: Escrow Descriptor Compatibility Read `PIP-01-escrow-descriptor.md`. Review the `networks`, repeated `network` tags, and `custodial_escrow` implementation rules. Prompt: ```text What should a client do if an implementation entry references a network not listed in content.networks? ``` Output: - a testable rule summary - an example invalid descriptor case - optional proposed wording Example issue title: ```text PIP-01: Add invalid custodial implementation example for unsupported networks ``` #### Track C: Swap State and Private Payloads Read `PIP-02-swap-state-machine.md`. Identify which data belongs in public events versus Gift Wrap private messages. Prompt: ```text Draft one example of a public evidence event that references private evidence without exposing it. ``` Output: - a short JSON-style evidence example - a note explaining which private data is intentionally withheld Example issue title: ```text PIP-02: Add evidence reference example for private payment proof ``` #### Track D: Dispute Policy Boundary Read `PIP-03-dispute-policy.md`. Pick one dispute class and define what should be public versus private. Prompt: ```text For payment amount mismatch, what public facts are enough to justify resolution without publishing raw screenshots? ``` Output: - public facts - private evidence - proposed disclosure boundary Example issue title: ```text PIP-03: Clarify public resolution fields for payment amount mismatch ``` ### 0:35-0:42 - Contribution Review Each group presents: - the PIP they touched - the ambiguity or missing example they found - whether the contribution should be an issue, PR, or open question - why it belongs in protocol text rather than an implementation The facilitator should check: - Is this protocol-level? - Is there one primary PIP that should own the rule? - Does it avoid product UX, database, deployment, or SDK assumptions? - Does it preserve the distinction between canonical public protocol state and operator-layer overlays? - Would an independent implementer benefit from the clarification? ### 0:42-0:45 - Close and Contribution Path Close with concrete next steps: 1. Open a GitHub issue with the PIP number in the title. 2. Keep proposals atomic. 3. Include the current ambiguity, proposed wording, and interoperability impact. 4. Avoid implementation-specific details unless they reveal a protocol gap. 5. Prefer documenting draft conventions or open questions over implying false finality. Good contribution titles: ```text PIP-00: Clarify default Agent profile selection when multiple d tags exist PIP-01: Add invalid custodial implementation example for unsupported networks PIP-02: Add evidence reference example for private payment proof PIP-03: Clarify public resolution fields for payment amount mismatch ``` ## Facilitator Notes Keep the workshop focused on specification work. If participants drift into application design, redirect them with this question: ```text Is this canonical public protocol state, or is it an implementation overlay? ``` Valid protocol contributions usually clarify: - event kinds - required fields - public tags - content schema - lifecycle rules - evidence boundaries - dispute and timeout semantics - cross-PIP consistency Contributions should generally avoid: - application UX plans - database schemas - deployment notes - SDK instructions - operator dashboard workflows - product-specific assumptions - private business process details ## Success Criteria The workshop is successful if each participant or group leaves with at least one of: - a concrete GitHub issue draft - a small PR-ready paragraph - a missing example to propose - a documented open question tied to a specific PIP The best contribution candidates are small, specific, and useful to independent implementers.
