nostr-protocol · vcavallo · Jan 23, 2025 · Jan 23, 2025
diff --git a/3400.md b/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": "<string>",
+    "about": "<string>",
+    "fee_rate": "<decimal between 0 and 1>",
+    "min_amount": "<integer in sats>",
+    "max_amount": "<integer in sats>",
+    "dispute_resolution_policy": "<string>",
+    "supported_currencies": ["BTC"]
+  },
+  "tags": [
+    ["p", "<agent-pubkey>"],
+    ["r", "<agent-terms-url>", "<optional recommended relay URL>"]
+  ]
+}
+```
+
+### Task Proposal (3401)
+
+Used to propose an escrow task with specified terms and requirements.
+
+```json
+{
+  "kind": 3401,
+  "content": {
+    "description": "<string>",
+    "requirements": "<string>",
+    "deadline": "<unix timestamp in seconds>"
+  },
+  "tags": [
+    ["p", "<agent-pubkey>", "<optional recommended relay URL>"],
+    ["amount", "<integer in sats>"]
+  ]
+}
+```
+
+### 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", "<task-proposal-event-id>", "<optional recommended relay URL>"],
+    ["p", "<creator-pubkey>", "<optional recommended relay URL>"]
+  ]
+}
+```
+
+### 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", "<agent-acceptance-event-id>", "<optional recommended relay URL>"],
+    ["e", "<zap-receipt-event-id>", "<optional recommended relay URL>"],
+    ["p", "<agent-pubkey>", "<optional recommended relay URL>"],
+    ["amount", "<integer in sats>"]
+  ]
+}
+```
+
+### Worker Application (3404)
+
+Used by workers to apply for a finalized task.
+
+```json
+{
+  "kind": 3404,
+  "content": "<application details>",
+  "tags": [
+    ["e", "<task-finalization-event-id>", "<optional recommended relay URL>"],
+    ["p", "<creator-pubkey>", "<optional recommended relay URL>"],
+    ["p", "<agent-pubkey>", "<optional recommended relay URL>"]
+  ]
+}
+```
+
+### Worker Assignment (3405)
+
+Used by task creator to assign the task to a specific worker.
+
+```json
+{
+  "kind": 3405,
+  "tags": [
+    ["e", "<task-finalization-event-id>", "<optional recommended relay URL>"],
+    ["e", "<worker-application-event-id>", "<optional recommended relay URL>"],
+    ["p", "<worker-pubkey>", "<optional recommended relay URL>"],
+    ["p", "<agent-pubkey>", "<optional recommended relay URL>"]
+  ]
+}
+```
+
+### Work Submission (3406)
+
+Used by assigned worker to submit completed work.
+
+```json
+{
+  "kind": 3406,
+  "content": "<work details/proof>",
+  "tags": [
+    ["e", "<worker-assignment-event-id>", "<optional recommended relay URL>"],
+    ["p", "<creator-pubkey>", "<optional recommended relay URL>"],
+    ["p", "<agent-pubkey>", "<optional recommended relay URL>"]
+  ]
+}
+```
+
+### 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": "<string>"
+  },
+  "tags": [
+    ["e", "<work-submission-event-id>", "<optional recommended relay URL>"],
+    ["e", "<zap-receipt-event-id>", "<optional recommended relay URL>"],
+    ["p", "<creator-pubkey>", "<optional recommended relay URL>"],
+    ["p", "<worker-pubkey>", "<optional recommended relay URL>"],
+    ["amount", "<integer in sats>"]
+  ]
+}
+```
+
+## 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`. 
+