From 0adb51fdbbef8a569b4c661a56b1643b76a41a2d Mon Sep 17 00:00:00 2001 From: vinney cavallo Date: Thu, 23 Jan 2025 16:42:37 -0500 Subject: [PATCH] Add nip-3400 proposal --- nip-3400.md | 203 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 203 insertions(+) create mode 100644 nip-3400.md diff --git a/nip-3400.md b/nip-3400.md new file mode 100644 index 00000000..ec3b357d --- /dev/null +++ b/nip-3400.md @@ -0,0 +1,203 @@ +NIP-3400(?) +======= + +Note: This proposal has a minimal prototype implementation in khatru/nak here: [https://github.com/vcavallo/khatru/blob/escrow/nip100.md](https://github.com/vcavallo/khatru/blob/escrow/nip100.md). In that project it is referred to as "nip-100" because I have a loose grasp on reality. + +Lightning Network Bounties/Escrow +--------------------------------- + +`draft` `optional` + +This NIP defines event kinds and structure for facilitating Lightning Network escrow services and bounties on nostr. It enables escrow agents to register their services and users to create, accept, and resolve bounty tasks using Lightning Network payments through nostr zaps. + +## Events + +### Event Kinds + +- `3400`: Escrow Agent Registration +- `3401`: Task Proposal +- `3402`: Agent Task Acceptance +- `3403`: Task Finalization +- `3404`: Worker Application +- `3405`: Worker Assignment +- `3406`: Work Submission +- `3407`: Task Resolution + +### Escrow Agent Registration (3400) + +Used by escrow agents to advertise their services and terms. + +```json +{ + "kind": 3400, + "content": { + "name": "", + "about": "", + "fee_rate": "", + "min_amount": "", + "max_amount": "", + "dispute_resolution_policy": "", + "supported_currencies": ["BTC"] + }, + "tags": [ + ["p", ""], + ["r", "", ""] + ] +} +``` + +### Task Proposal (3401) + +Used to propose an escrow task with specified terms and requirements. + +```json +{ + "kind": 3401, + "content": { + "description": "", + "requirements": "", + "deadline": "" + }, + "tags": [ + ["p", "", ""], + ["amount", ""] + ] +} +``` + +### Agent Task Acceptance (3402) + +Used by escrow agents to accept task proposals. Only the agent specified in the task proposal can accept it. + +```json +{ + "kind": 3402, + "tags": [ + ["e", "", ""], + ["p", "", ""] + ] +} +``` + +### Task Finalization (3403) + +Created after the task creator zaps the agent's acceptance event. This event makes the task live and available for worker applications. + +```json +{ + "kind": 3403, + "content": "", + "tags": [ + ["e", "", ""], + ["e", "", ""], + ["p", "", ""], + ["amount", ""] + ] +} +``` + +### Worker Application (3404) + +Used by workers to apply for a finalized task. + +```json +{ + "kind": 3404, + "content": "", + "tags": [ + ["e", "", ""], + ["p", "", ""], + ["p", "", ""] + ] +} +``` + +### Worker Assignment (3405) + +Used by task creator to assign the task to a specific worker. + +```json +{ + "kind": 3405, + "tags": [ + ["e", "", ""], + ["e", "", ""], + ["p", "", ""], + ["p", "", ""] + ] +} +``` + +### Work Submission (3406) + +Used by assigned worker to submit completed work. + +```json +{ + "kind": 3406, + "content": "", + "tags": [ + ["e", "", ""], + ["p", "", ""], + ["p", "", ""] + ] +} +``` + +### Task Resolution (3407) + +Used by agent to resolve the task and provide proof of payment. + +```json +{ + "kind": 3407, + "content": { + "resolution": "completed|rejected|canceled", + "resolution_details": "" + }, + "tags": [ + ["e", "", ""], + ["e", "", ""], + ["p", "", ""], + ["p", "", ""], + ["amount", ""] + ] +} +``` + +## Client Behavior + +1. Clients MUST verify all signatures and event relationships before displaying or acting on escrow events +2. Clients MUST verify zap receipts for task finalization and resolution events +3. Clients MUST maintain accurate state of task progression through the event chain +4. Clients SHOULD respect the deadline specified in task creation events +5. Clients MUST NOT consider a task active until finalized with valid zap receipt +6. Clients MUST verify that task acceptance events are signed by the specified agent + +## Relay Behavior + +1. Relays MAY choose to not store escrow events +2. If a relay stores escrow events, it SHOULD store all related events including referenced zap receipts +3. Relays implementing this NIP SHOULD implement [NIP-01](01.md) replaceable events for agent registration updates + +## Security Considerations + +1. All events MUST be properly signed by their respective actors +2. Escrow agents MUST verify task completion before releasing funds to worker +3. Escrow agents MUST return funds to creator if task is rejected or canceled +4. Dispute resolution process MUST be clearly defined in agent registration +5. Clients SHOULD verify agent signatures and reputation before engagement +6. Task creators SHOULD verify agent reputation and terms before sending funds +7. Workers SHOULD verify agent reputation before applying to tasks +8. All payment proofs MUST be verifiable through nostr zap receipts + +## Ideas and other directions that need thought: + +- Why not Cashu?! Escrow agents would be synonymous with mints and funds would be "locked" in mint tokens. We have to trust escrow agents and we have to trust ecash mints. Seems natural to combine these. +- I haven't thought through the game theory of any of this yet. There may be exploits and spam attacks waiting here. + +## Definite problems to address: + +- Should agents be able to adjust their fee after announcing? +- The author barely knows how to write a NIP and has only "implemented" this one in `nak`. +