Define cashu_escrow as a canonical PIP-01 subtype

[KvngMikey]

Issue Type

Enhancement

Description

The current PIP-01 draft defines two canonical escrow subtypes: lightning_hold_invoice and custodial_escrow. Cashu-based escrow flows do not fit cleanly under either.

The custody model in Cashu is bearer-instrument rather than relational: the escrow lock is a NUT-11 spending condition on the token itself (locked to the operator's pubkey with a refund pubkey and locktime), not a balance maintained by the operator on behalf of the buyer. The funding proof is a locked token reference rather than an invoice payment or an accepted hold invoice.

A canonical cashu_escrow subtype would let escrow operators declare Cashu ecash semantics while reusing the existing top-level networks model from PIP-01 and the implementations array pattern introduced for custodial_escrow in #4.

This is the exact hook the current PIP-01 Open Question calls out: additional escrow mechanisms beyond lightning_hold_invoice and custodial_escrow may still need their own canonical subtype-specific schemas.

Expected Behaviour

PIP-01 defines cashu_escrow as a third canonical subtype with common custodial authority fields (matching custodial_escrow semantics), plus Cashu-specific implementation fields represented under the implementations array. The top-level networks field remains the canonical supported-network declaration.

Priority

Medium

Scope/Component

Protocol specification, PIP-01 escrow descriptor

Source

Community proposal. Draft idea gist: https://gist.github.com/KvngMikey/5f5621caa5ae432a32aa37d7227518ef

Reporter

KvngMikey

Acceptance Criteria

• PIP-01 includes a canonical cashu_escrow subtype.
• The subtype uses the existing top-level networks array as the canonical supported-network declaration.
• The subtype defines common custodial fields: custody_authority, release_authority, and refund_authority, matching custodial_escrow semantics.
• Release and refund conditions align with the current PIP-01 nested rule style: release_rules.release_trigger and release_rules.refund_trigger.
• Cashu-specific implementation fields are represented under the implementations array, not at the top level: mint_url, lock_mechanism (MUST be p2pk_timelock), invoice_expiry_rule, reference_format, payout_network.
• The subtype references NUT-11 for the P2PK plus locktime primitive without expanding scope into a full Cashu spec.
• Examples show at least one Cashu-to-Lightning implementation with networks: ["cashu", "lightning"].
• Matching event tags emit repeated network tags only for networks present in content.networks.
• The Open Question section is updated: cashu_escrow moves from an open gap to a defined subtype; a new open question is added noting that cashu_escrow introduces a dependency on a specific Cashu mint, and that mint trust, mint selection, and mint failure modes are implementation assumptions rather than Pontmore protocol state.
• The new open question points at [Nimdolf](NUT-XX: Non-Interactive Mint Delegation on Liveness Failure (Nimdolf) cashubtc/nuts#390) as a possible future direction for mint liveness failover without binding to it.

Suggested Implementation

Add a cashu_escrow canonical subtype section to PIP-01 immediately after custodial_escrow and before Selection Rules. Keep escrow_type: "cashu_escrow" stable, use the existing top-level networks array for supported networks, and put Cashu-specific fields inside implementations entries.

Example shape:

{
  "version": 1,
  "escrow_type": "cashu_escrow",
  "networks": ["cashu", "lightning"],
  "funding_rules": {
    "required_confirmation": "cashu_token_locked_to_escrow"
  },
  "release_rules": {
    "release_trigger": "counterparty_fiat_payment_confirmed",
    "refund_trigger": "timeout_or_dispute_refund_decision"
  },
  "dispute_rules": {
    "policy": "operator_resolved"
  },
  "reference_format": "cashu_v4_token",
  "custody_authority": "escrow_operator",
  "release_authority": "escrow_operator",
  "refund_authority": "escrow_operator",
  "implementations": [
    {
      "network": "cashu",
      "invoice_asset": "BTC",
      "invoice_currency": "sats",
      "invoice_amount_rule": "derived_from_swap_request",
      "invoice_expiry_rule": "p2pk_timelock_expiry",
      "payout_network": "lightning",
      "mint_url": "https://mint.example.com",
      "lock_mechanism": "p2pk_timelock",
      "reference_format": "cashu_v4_token"
    }
  ],
  "updated_at": 1775559028
}

The matching event tags SHOULD include:

["d", "default"]
["network", "cashu"]
["network", "lightning"]