Propose NIP for bounties backed by zap-native, trusted escrow agents

[vcavallo]

This PR is to propose a new set of Kinds for supporting bounties backed by trusted escrow agents over nostr and Lightning. I've referred to it as NIP-3400 because I'm not sure how to propose new NIPs.

See 3400.md for a full write-up.
Also see https://github.com/vcavallo/khatru/blob/escrow/nip3400.md for an initial implementation in Khatru with a bare-bones client simulated in nak.

Below is an overview of the NIP for anyone too lazy to open the 3400.md file.

Note on Cashu/ecash: As I neared the end of this proposal I became more and more convinced that handling escrow via Cashu mints is far superior, but I'll leave that for the discussion rather than re-think everything now.

Please let me know if I'm constructing this proposal in the wrong fashion! I'm happy to revise it.
Thanks for reading.

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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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>"]
  ]
}

[vcavallo]

Due to my ignorance, I may be mixing up replaceable events with non-replaceable, either in the implications of my proposal and/or in suggested Kind numbers.

[vcavallo]

For those of you on the edge of your seat: I'm nearly done with a basic web application that implements this entire NIP. I'll host it and the simple relay implementation and post a link here.

Update: https://github.com/vcavallo/catallax-ui

Pending getting a relay live and providing an online demo...

[alltheseas]

Due to my ignorance, I may be mixing up replaceable events with non-replaceable, either in the implications of my proposal and/or in suggested Kind numbers.

Replaceable events, and escrow sound like a risk. Signed non-replaceable events are required to establish a trail of signed events.

Looking forward to seeing bounties move to nostr, and looking forward to galaxy brain dev technical review.

[alltheseas]

Would be nice to test this flow with a non-technical graphical UI (don't require using one of fiatjaf's assembly CLI tools).

[vcavallo]

Would be nice to test this flow with a non-technical graphical UI (don't require using one of fiatjaf's assembly CLI tools).

The web demo is very close to being shareable

[vcavallo]

Due to my ignorance, I may be mixing up replaceable events with non-replaceable, either in the implications of my proposal and/or in suggested Kind numbers.

Replaceable events, and escrow sound like a risk. Signed non-replaceable events are required to establish a trail of signed events.

Looking forward to seeing bounties move to nostr, and looking forward to galaxy brain dev technical review.

Definitely. Some of these events should be replaceable (or re-designed) - ie Arbiter/Agent registration - you should be able to change your fee level, or perhaps the fee should be determined per Task acceptance (though this makes the negotiation process between Agent/Patron more frictionful). But most of them should not!

To be honest, I didn't consider replaceable/non-replaceable when I first prototyped the implementation but it definitely needs another around taking that into account.

Thanks for the thoughts