feat: add Cashu P2PK escrow for oracle-mediated payments

Implements NUT-11 2-of-2(Oracle, Worker) multisig with timelock refund
to Requester. Includes atomic swap for bounty split and oracle fee.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: motxx

src/cashu/escrow.test.ts

@@ -0,0 +1,44 @@
+import { expect, test } from "bun:test";
+import { buildEscrowP2PKOptions, calculateOracleFee, inspectEscrowToken } from "./escrow";
+
+// Valid 32-byte x-only pubkeys (64 hex chars)
+const ORACLE_PUB = "0000000000000000000000000000000000000000000000000000000000000001";
+const WORKER_PUB = "0000000000000000000000000000000000000000000000000000000000000002";
+const REQUESTER_PUB = "0000000000000000000000000000000000000000000000000000000000000003";
+
+test("buildEscrowP2PKOptions creates 2-of-2 with timelock refund", () => {
+  const opts = buildEscrowP2PKOptions({
+    oraclePubkey: ORACLE_PUB,
+    workerPubkey: WORKER_PUB,
+    requesterRefundPubkey: REQUESTER_PUB,
+    locktimeSeconds: 1700000000,
+  });
+
+  expect(opts.requiredSignatures).toBe(2);
+  // P2PKBuilder prepends 02 prefix (compressed pubkey format)
+  expect(opts.pubkey).toEqual([`02${ORACLE_PUB}`, `02${WORKER_PUB}`]);
+  expect(opts.refundKeys).toEqual([`02${REQUESTER_PUB}`]);
+  expect(opts.locktime).toBe(1700000000);
+  expect(opts.sigFlag).toBe("SIG_ALL");
+});
+
+test("calculateOracleFee computes correct fee", () => {
+  // 5% fee (50,000 ppm)
+  expect(calculateOracleFee(100, 50_000)).toBe(5);
+  expect(calculateOracleFee(1000, 50_000)).toBe(50);
+
+  // 1% fee (10,000 ppm)
+  expect(calculateOracleFee(100, 10_000)).toBe(1);
+  expect(calculateOracleFee(1000, 10_000)).toBe(10);
+
+  // Sub-sat rounds up
+  expect(calculateOracleFee(1, 50_000)).toBe(1);
+
+  // 0% fee
+  expect(calculateOracleFee(100, 0)).toBe(0);
+});
+
+test("inspectEscrowToken returns null for invalid token", () => {
+  expect(inspectEscrowToken("invalid")).toBe(null);
+  expect(inspectEscrowToken("")).toBe(null);
+});

src/cashu/escrow.ts

@@ -0,0 +1,204 @@
+/**
+ * Cashu P2PK escrow for Anchr protocol.
+ *
+ * Implements the 1-token escrow pattern:
+ *   Lock:    2-of-2(Oracle, Worker) with timeout refund to Requester
+ *   Pass:    Oracle + Worker co-sign swap → bounty split (worker reward + oracle fee)
+ *   Fail:    Nobody signs → timeout → Requester reclaims
+ *
+ * Uses NUT-11 P2PK spending conditions via @cashu/cashu-ts P2PKBuilder.
+ */
+
+import {
+  P2PKBuilder,
+  type Proof,
+  type P2PKOptions,
+  getEncodedToken,
+  getDecodedToken,
+} from "@cashu/cashu-ts";
+import { getCashuWallet, getCashuConfig } from "./wallet";
+
+export interface EscrowParams {
+  /** Oracle's public key (hex). */
+  oraclePubkey: string;
+  /** Worker's public key (hex). */
+  workerPubkey: string;
+  /** Requester's public key for timeout refund (hex). */
+  requesterRefundPubkey: string;
+  /** Locktime as unix timestamp (seconds). After this, requester can reclaim. */
+  locktimeSeconds: number;
+}
+
+export interface EscrowToken {
+  /** Encoded Cashu token string. */
+  token: string;
+  /** Raw proofs. */
+  proofs: Proof[];
+  /** The P2PK options used. */
+  p2pkOptions: P2PKOptions;
+  /** Total amount in sats. */
+  amountSats: number;
+}
+
+export interface SwapResult {
+  /** Token for the worker (bounty minus fee). */
+  workerToken: string;
+  /** Token for the oracle (fee). */
+  oracleToken: string;
+  /** Worker amount in sats. */
+  workerAmountSats: number;
+  /** Oracle fee in sats. */
+  oracleFeeSats: number;
+}
+
+/**
+ * Build P2PK options for escrow: 2-of-2(Oracle, Worker) + timeout refund to Requester.
+ */
+export function buildEscrowP2PKOptions(params: EscrowParams): P2PKOptions {
+  return new P2PKBuilder()
+    .addLockPubkey([params.oraclePubkey, params.workerPubkey])
+    .requireLockSignatures(2)
+    .lockUntil(params.locktimeSeconds)
+    .addRefundPubkey(params.requesterRefundPubkey)
+    .requireRefundSignatures(1)
+    .sigAll()
+    .toOptions();
+}
+
+/**
+ * Create a P2PK-locked escrow token.
+ *
+ * The token can only be spent by both Oracle and Worker signing together.
+ * After locktime, the Requester can reclaim with their refund key.
+ *
+ * Requires an existing funded wallet (proofs available).
+ */
+export async function createEscrowToken(
+  amountSats: number,
+  params: EscrowParams,
+  sourceProofs: Proof[],
+): Promise<EscrowToken | null> {
+  const wallet = getCashuWallet();
+  const config = getCashuConfig();
+  if (!wallet || !config) return null;
+
+  const p2pkOptions = buildEscrowP2PKOptions(params);
+
+  try {
+    await wallet.loadMint();
+    const { send } = await wallet.ops
+      .send(amountSats, sourceProofs)
+      .asP2PK(p2pkOptions)
+      .run();
+
+    const token = getEncodedToken({ mint: config.mintUrl, proofs: send });
+    return {
+      token,
+      proofs: send,
+      p2pkOptions,
+      amountSats,
+    };
+  } catch (error) {
+    console.error("[cashu-escrow] Failed to create escrow token:", error instanceof Error ? error.message : error);
+    return null;
+  }
+}
+
+/**
+ * Execute the atomic swap: Oracle + Worker co-sign to split the escrowed token.
+ *
+ * Both parties must sign the proofs before calling this.
+ * The swap produces two outputs:
+ *   1. Worker reward (amountSats - feeSats) locked to workerPubkey
+ *   2. Oracle fee (feeSats) locked to oraclePubkey
+ */
+export async function executeEscrowSwap(
+  signedProofs: Proof[],
+  workerPubkey: string,
+  oraclePubkey: string,
+  feeSats: number,
+): Promise<SwapResult | null> {
+  const wallet = getCashuWallet();
+  const config = getCashuConfig();
+  if (!wallet || !config) return null;
+
+  const totalSats = signedProofs.reduce((sum, p) => sum + p.amount, 0);
+  const workerSats = totalSats - feeSats;
+
+  if (workerSats <= 0) {
+    console.error("[cashu-escrow] Fee exceeds total amount");
+    return null;
+  }
+
+  try {
+    await wallet.loadMint();
+
+    // Swap into two P2PK outputs: worker reward + oracle fee
+    const workerP2PK = new P2PKBuilder().addLockPubkey(workerPubkey).toOptions();
+    const oracleP2PK = new P2PKBuilder().addLockPubkey(oraclePubkey).toOptions();
+
+    // Use the wallet's swap to split into two outputs
+    const { send: workerProofs } = await wallet.ops
+      .send(workerSats, signedProofs)
+      .asP2PK(workerP2PK)
+      .run();
+
+    // The remaining proofs (change) should be fee amount for oracle
+    const remainingProofs = signedProofs.filter(
+      (p) => !workerProofs.some((wp) => wp.C === p.C),
+    );
+
+    // If there are remaining proofs, swap them to oracle
+    let oracleProofs: Proof[];
+    if (remainingProofs.length > 0) {
+      const { send } = await wallet.ops
+        .send(feeSats, remainingProofs)
+        .asP2PK(oracleP2PK)
+        .run();
+      oracleProofs = send;
+    } else {
+      // Edge case: no remaining proofs, oracle gets nothing
+      oracleProofs = [];
+    }
+
+    return {
+      workerToken: getEncodedToken({ mint: config.mintUrl, proofs: workerProofs }),
+      oracleToken: oracleProofs.length > 0
+        ? getEncodedToken({ mint: config.mintUrl, proofs: oracleProofs })
+        : "",
+      workerAmountSats: workerSats,
+      oracleFeeSats: feeSats,
+    };
+  } catch (error) {
+    console.error("[cashu-escrow] Swap failed:", error instanceof Error ? error.message : error);
+    return null;
+  }
+}
+
+/**
+ * Calculate oracle fee from bounty amount and fee rate.
+ */
+export function calculateOracleFee(amountSats: number, feePpm: number): number {
+  return Math.ceil((amountSats * feePpm) / 1_000_000);
+}
+
+/**
+ * Decode an escrow token and inspect its P2PK conditions.
+ */
+export function inspectEscrowToken(token: string): {
+  amountSats: number;
+  proofCount: number;
+  mintUrl: string;
+} | null {
+  try {
+    const decoded = getDecodedToken(token);
+    const amountSats = decoded.proofs.reduce((sum: number, p: Proof) => sum + p.amount, 0);
+    return {
+      amountSats,
+      proofCount: decoded.proofs.length,
+      mintUrl: decoded.mint,
+    };
+  } catch {
+    return null;
+  }
+}

src/index.ts

@@ -38,6 +38,8 @@ export type { Oracle, OracleInfo, OracleAttestation } from "./oracle";
 export { stripExif } from "./exif-strip";
 export { purgeExpiredQueries } from "./data-purge";
 export { isCashuEnabled, getCashuConfig, verifyToken, encodeToken } from "./cashu/wallet";
+export { buildEscrowP2PKOptions, calculateOracleFee, createEscrowToken, executeEscrowSwap, inspectEscrowToken } from "./cashu/escrow";
+export type { EscrowParams, EscrowToken, SwapResult } from "./cashu/escrow";
 export * as nostr from "./nostr/index";
 export * as blossom from "./blossom/client";
 export * as verification from "./verification/index";