@paydlux/agent 0.1.19 → 0.1.21

package/dist/escrow.js

@@ -0,0 +1,325 @@
+// Paydlux escrow — a payment the buyer locks, not a payment the seller holds.
+//
+// The claim on the website is: "the escrow that holds a payment until delivery
+// is proven". This file is what makes that claim true, and it deliberately does
+// NOT use a smart contract. Stellar has a native primitive for exactly this
+// shape of deal — a claimable balance with two claimants and a time predicate —
+// and it is strictly better than a contract for a payment rail:
+//
+//   * no contract to audit, and no contract address that can be wrong
+//   * the money never sits in an account the seller controls
+//   * the reserve is paid by whoever creates the balance (the buyer), and the
+//     ledger gives it back when the balance is claimed
+//   * the rules are enforced by the network, not by our server being up
+//
+// The shape, verified against testnet (see stellar/escrow-check.ts):
+//
+//   claimant 1 — the seller vault, predicate NOT(abs_before = releaseAt)
+//                so the vault can only claim AFTER the release time
+//   claimant 2 — the buyer,          predicate abs_before = releaseAt
+//                so the buyer can claw the money back ONLY before it
+//
+// Three properties follow, and all three were observed on the ledger:
+//   1. before releaseAt the vault cannot take the money, even with both of its
+//      keys (tx_failed on the claim)
+//   2. after releaseAt the vault can take it, but only with BOTH keys — one
+//      signature is tx_bad_auth, so a stolen agent key cannot empty an escrow
+//   3. before releaseAt the buyer can always take it back, no seller consent
+//
+// So the seller's incentive is to prove delivery before the timer: releasing
+// early needs the human approval key anyway, and until then the money is the
+// buyer's to reclaim. That is the whole product in two claimants.
+import { Asset, Claimant, Horizon, Memo, Operation, TransactionBuilder, getClaimableBalanceIdFromResult, xdr, } from "@stellar/stellar-sdk";
+import { passphrase } from "./vault.js";
+const HORIZON_URL = {
+    testnet: "https://horizon-testnet.stellar.org",
+    public: "https://horizon.stellar.org",
+};
+export const horizonUrl = (network) => HORIZON_URL[network];
+/** Horizon writes an asset as "native" or "USDC:Gissuer…". */
+export function assetToHorizonString(asset) {
+    return asset.getAssetType() === "native"
+        ? "native"
+        : `${asset.getCode()}:${asset.getIssuer()}`;
+}
+export function assetFromHorizonString(s) {
+    if (s === "native")
+        return Asset.native();
+    const [code, issuer] = String(s).split(":");
+    if (!code || !issuer)
+        throw new Error(`unrecognised asset string "${s}"`);
+    return new Asset(code, issuer);
+}
+async function getJson(url) {
+    const r = await fetch(url);
+    if (!r.ok) {
+        const e = new Error(`horizon ${r.status} on ${url.split("?")[0]}`);
+        e.status = r.status;
+        throw e;
+    }
+    return r.json();
+}
+/**
+ * Read a claimable balance back from the ledger and turn it into an Escrow.
+ *
+ * Horizon does NOT put the memo on the balance record — the memo lives on the
+ * transaction that created it. So the join between "this pile of money" and
+ * "that order" is one extra request. It is not optional: without it, two orders
+ * of the same price to the same vault are indistinguishable, and a seller could
+ * deliver order A and claim the escrow that was locked for order B.
+ */
+export async function readEscrow(network, balanceId) {
+    const h = horizonUrl(network);
+    let cb;
+    try {
+        cb = await getJson(`${h}/claimable_balances/${balanceId}`);
+    }
+    catch (e) {
+        if (e.status === 404 || e.status === 400)
+            return null;
+        throw e;
+    }
+    if (!cb?.claimants)
+        return null;
+    // The two claimants are distinguished by their predicate, not by position:
+    // the seller's is wrapped in `not`, the buyer's is the bare abs_before.
+    const seller = cb.claimants.find((c) => c.predicate?.not);
+    const buyer = cb.claimants.find((c) => !c.predicate?.not && c.predicate?.abs_before_epoch);
+    if (!seller || !buyer)
+        return null;
+    const txs = await getJson(`${h}/claimable_balances/${balanceId}/transactions?order=asc&limit=1`);
+    const tx = txs?._embedded?.records?.[0];
+    return {
+        balanceId,
+        amount: cb.amount,
+        asset: cb.asset,
+        vault: seller.destination,
+        buyer: buyer.destination,
+        releaseAt: Number(seller.predicate.not.abs_before_epoch),
+        txHash: tx?.hash ?? "",
+        memo: tx?.memo ?? "",
+        memoType: tx?.memo_type ?? "none",
+        claimed: false,
+    };
+}
+/**
+ * Does this on-chain escrow actually pay THIS deal?
+ *
+ * Every field is checked against the terms the gateway issued, because the
+ * buyer is untrusted: a buyer could lock 0.0000001 XLM, or lock money to a
+ * different vault, or set the timer to next year, or reuse the escrow from a
+ * previous order. Anything short of an exact match is a refusal.
+ */
+export async function verifyEscrow(network, balanceId, want, opts = {}) {
+    const e = await readEscrow(network, balanceId);
+    if (!e)
+        return { ok: false, reason: "no such claimable balance (already claimed, or never created)" };
+    if (e.asset !== assetToHorizonString(want.asset))
+        return { ok: false, reason: `escrow holds ${e.asset}, this route is priced in ${assetToHorizonString(want.asset)}` };
+    if (Number(e.amount) !== Number(want.amount))
+        return { ok: false, reason: `escrow holds ${e.amount}, this route costs ${want.amount}` };
+    if (e.vault !== want.vault)
+        return { ok: false, reason: "escrow names a different seller vault" };
+    if (want.buyer && e.buyer !== want.buyer)
+        return { ok: false, reason: "escrow was locked by a different account" };
+    // The memo is the only link between money and order. Exact match, or no deal.
+    if (e.memoType !== "text" || e.memo !== want.orderId)
+        return { ok: false, reason: `escrow memo "${e.memo}" does not match order ${want.orderId}` };
+    const now = Math.floor(Date.now() / 1000);
+    if (e.releaseAt <= now && !opts.allowClosedWindow) {
+        return { ok: false, reason: "the refund window has already closed — the seller could already have claimed it" };
+    }
+    if (opts.minReleaseSeconds != null && e.releaseAt - now < opts.minReleaseSeconds)
+        return { ok: false, reason: "release timer is too soon to prove delivery" };
+    if (opts.maxReleaseSeconds != null && e.releaseAt - now > opts.maxReleaseSeconds)
+        return { ok: false, reason: "release timer is further out than this route allows" };
+    return { ok: true, escrow: e };
+}
+/**
+ * The balance id of the escrow a submitted transaction created.
+ *
+ * Horizon does not return this to the submitter, and the id is not derivable
+ * from the account alone — it comes out of the transaction RESULT. A buyer who
+ * locks money with their own code needs this to know what to put in the
+ * `x-payment` header, so it is exported rather than kept private.
+ */
+export function escrowBalanceId(resultXdr, index = 0) {
+    return getClaimableBalanceIdFromResult(xdr.TransactionResult.fromXdr(resultXdr, "base64"), index);
+}
+/**
+ * Lock an escrow. Needs the BUYER's key: the money leaves the buyer's account,
+ * so only the buyer can put it in escrow. The seller never gets a signature on
+ * this transaction — that is the point.
+ */
+export async function createEscrow(network, terms, buyerKey) {
+    if (!terms.buyer)
+        throw new Error("creating an escrow needs terms.buyer — the money leaves that account");
+    if (buyerKey.publicKey() !== terms.buyer)
+        throw new Error("the signing key is not the escrow buyer");
+    const h = new Horizon.Server(horizonUrl(network));
+    const acc = await h.loadAccount(terms.buyer);
+    const releaseAt = Math.floor(terms.releaseAt);
+    const tx = new TransactionBuilder(acc, { fee: "100", networkPassphrase: passphrase(network) })
+        .addOperation(Operation.createClaimableBalance({
+        asset: terms.asset,
+        amount: terms.amount,
+        // Order matters for readability only; the predicates are what enforce the deal.
+        claimants: [
+            new Claimant(terms.vault, Claimant.predicateNot(Claimant.predicateBeforeAbsoluteTime(String(releaseAt)))),
+            new Claimant(terms.buyer, Claimant.predicateBeforeAbsoluteTime(String(releaseAt))),
+        ],
+    }))
+        // The memo is the order id. Without it the escrow cannot be matched to an
+        // order, and verifyEscrow() will refuse it.
+        .addMemo(Memo.text(terms.orderId))
+        .setTimeout(300)
+        .build();
+    tx.sign(buyerKey);
+    const res = await h.submitTransaction(tx);
+    const balanceId = getClaimableBalanceIdFromResult(xdr.TransactionResult.fromXdr(res.result_xdr, "base64"), 0);
+    const escrow = await readEscrow(network, balanceId);
+    if (!escrow)
+        throw new Error("escrow was created but Horizon will not show it yet");
+    return { escrow, txHash: res.hash };
+}
+/**
+ * The seller takes the escrow. Two keys, always: the vault's threshold is 2 and
+ * the claim is a medium-threshold operation, so the agent key alone gets
+ * tx_bad_auth. `approverKey` lives on the phone in a real deployment.
+ *
+ * Refuses before the release time rather than letting Horizon reject it, so the
+ * caller gets a sentence instead of an error code — and so a buggy scheduler
+ * cannot accidentally try to release early in a loop.
+ */
+export async function claimEscrow(network, balanceId, vaultAddress, keys) {
+    const e = await readEscrow(network, balanceId);
+    if (!e)
+        throw new Error("no such escrow — it has already been claimed or refunded");
+    if (e.vault !== vaultAddress)
+        throw new Error(`escrow ${balanceId.slice(0, 12)}… pays a different vault`);
+    const now = Math.floor(Date.now() / 1000);
+    if (now < e.releaseAt)
+        throw new Error(`release timer has not passed (${e.releaseAt - now}s to go)`);
+    const h = new Horizon.Server(horizonUrl(network));
+    const acc = await h.loadAccount(vaultAddress);
+    const tx = new TransactionBuilder(acc, { fee: "100", networkPassphrase: passphrase(network) })
+        .addOperation(Operation.claimClaimableBalance({ balanceId }))
+        .setTimeout(120)
+        .build();
+    tx.sign(keys.agent);
+    tx.sign(keys.approver);
+    const res = await h.submitTransaction(tx);
+    return { txHash: res.hash, claimedAt: now };
+}
+/**
+ * Release an escrow with the approver's key on a PHONE.
+ *
+ * `claimEscrow` needs both keys in one process. In a real deployment the human
+ * half never lives on the seller's machine — it lives on their phone. So build
+ * the claim here, sign it with the agent key, and hand it out as the same
+ * challenge the payment desk already uses: the phone reads a sentence
+ * ("claim 3.5 XLM from escrow ord_…"), signs, and sends back XDR.
+ *
+ * The phone is the only place the second signature can be added. This process
+ * cannot sign for it, cannot submit a completed claim, and cannot do anything
+ * with the half-signed transaction except wait.
+ */
+export async function prepareEscrowRelease(network, balanceId, vaultAddress, agent) {
+    const e = await readEscrow(network, balanceId);
+    if (!e)
+        throw new Error("no such escrow — it has already been claimed or refunded");
+    if (e.vault !== vaultAddress)
+        throw new Error(`escrow ${balanceId.slice(0, 12)}… pays a different vault`);
+    const now = Math.floor(Date.now() / 1000);
+    if (now < e.releaseAt)
+        throw new Error(`release timer has not passed (${e.releaseAt - now}s to go)`);
+    const h = new Horizon.Server(horizonUrl(network));
+    const acc = await h.loadAccount(vaultAddress);
+    const tx = new TransactionBuilder(acc, { fee: "100", networkPassphrase: passphrase(network) })
+        .addOperation(Operation.claimClaimableBalance({ balanceId }))
+        .addMemo(Memo.text(`release ${e.memo}`))
+        .setTimeout(1800)
+        .build();
+    tx.sign(agent);
+    return {
+        id: `escrow:${balanceId}`,
+        network,
+        xdr: tx.toXDR(),
+        summary: {
+            payee: vaultAddress,
+            amount: e.amount,
+            token: e.asset === "native" ? "XLM" : e.asset.split(":")[0],
+            tokenIssuer: e.asset === "native" ? "" : e.asset.split(":")[1] ?? "",
+            from: `escrow ${balanceId.slice(0, 16)}…`,
+            memo: `order ${e.memo} — release timer passed`,
+            expiresAt: Number(tx.timeBounds?.maxTime) || undefined,
+        },
+        hash: Buffer.from(tx.hash()).toString("hex"),
+    };
+}
+/**
+ * The buyer takes their money back. No seller signature, no permission, and it
+ * works right up to the release second — which is why the seller has to earn
+ * the release by proving delivery instead of waiting for the timer.
+ */
+export async function refundEscrow(network, balanceId, buyerKey) {
+    const e = await readEscrow(network, balanceId);
+    if (!e)
+        throw new Error("no such escrow — it has already been claimed or refunded");
+    if (e.buyer !== buyerKey.publicKey())
+        throw new Error("only the account that locked this escrow can refund it");
+    const now = Math.floor(Date.now() / 1000);
+    if (now >= e.releaseAt)
+        throw new Error("the refund window has closed");
+    const h = new Horizon.Server(horizonUrl(network));
+    const acc = await h.loadAccount(buyerKey.publicKey());
+    const tx = new TransactionBuilder(acc, { fee: "100", networkPassphrase: passphrase(network) })
+        .addOperation(Operation.claimClaimableBalance({ balanceId }))
+        .setTimeout(120)
+        .build();
+    tx.sign(buyerKey);
+    const res = await h.submitTransaction(tx);
+    return { txHash: res.hash };
+}
+/**
+ * Every escrow currently waiting on this vault, newest first.
+ *
+ * Horizon filters claimable balances by claimant, which is exactly the seller's
+ * question: "what money is sitting in escrow for me, and when does each one
+ * become mine?" A balance that has already been claimed disappears from this
+ * list, so it doubles as the pending-release queue.
+ */
+export async function pendingEscrows(network, vaultAddress, limit = 200) {
+    const h = horizonUrl(network);
+    const list = await getJson(`${h}/claimable_balances?claimant=${vaultAddress}&order=desc&limit=${Math.min(limit, 200)}`);
+    const out = [];
+    for (const rec of list?._embedded?.records ?? []) {
+        const e = await readEscrow(network, rec.id);
+        if (e)
+            out.push(e);
+    }
+    return out.sort((a, b) => a.releaseAt - b.releaseAt);
+}
+/**
+ * Has this escrow been settled, and by whom?
+ *
+ * A claimed balance vanishes from Horizon, so the answer is in the operations
+ * of the transaction that claimed it. This is the proof-of-delivery receipt:
+ * the buyer can look up the same number on any explorer.
+ */
+export async function escrowOutcome(network, balanceId) {
+    const h = horizonUrl(network);
+    let ops;
+    try {
+        ops = await getJson(`${h}/claimable_balances/${balanceId}/operations?order=desc&limit=5`);
+    }
+    catch (e) {
+        if (e.status === 404 || e.status === 400)
+            return { settled: false };
+        throw e;
+    }
+    const claim = (ops?._embedded?.records ?? []).find((o) => o.type === "claim_claimable_balance");
+    if (!claim)
+        return { settled: false };
+    return { settled: true, by: claim.account ?? claim.source_account, txHash: claim.transaction_hash, at: claim.created_at };
+}

package/dist/gateway.d.ts

@@ -1,13 +1,14 @@
 import { type IncomingMessage, type Server, type ServerResponse } from "node:http";
-import { Transaction } from "@stellar/stellar-sdk";
+import { Keypair, Transaction } from "@stellar/stellar-sdk";
 import { StellarVault, StellarTxError, type Amount, type Mandate, type Network } from "./vault.ts";
 import { ApprovalDesk, type DeskStore } from "./desk.ts";
 import type { PolicyEngine } from "./policy.ts";
+import { claimEscrow } from "./escrow.ts";
 export declare const PAY_HEADER = "x-payment";
 export type Route = {
     uri: string;
     price: Amount;
-    mode: "preauth" | "approval";
+    mode: "preauth" | "approval" | "escrow";
     /** seconds the seller's content stays reserved while a human decides */
     holdSeconds?: number;
     /**
@@ -15,6 +16,12 @@ export type Route = {
      * holdSeconds. Set it to 0 to make every single call cost its own approval.
      */
     collectSeconds?: number;
+    /**
+     * escrow mode: how long the buyer keeps the right to take their money back.
+     * The seller cannot touch the money before this passes, so it is also the
+     * deadline for proving delivery. Default 3600.
+     */
+    releaseSeconds?: number;
 };
 export type GatewayConfig = {
     vault: StellarVault;
@@ -69,6 +76,12 @@ export type PaymentProof = {
         payload: string;
         signature: string;
     };
+    /**
+     * escrow mode: the id of the claimable balance the BUYER locked for this
+     * order. The money is not the seller's yet — it becomes claimable after the
+     * release timer, and only with both human keys.
+     */
+    escrow?: string;
 };
 export declare class Gateway {
     private routes;
@@ -80,6 +93,66 @@ export declare class Gateway {
     constructor(cfg: GatewayConfig);
     /** Mandates the vault currently holds, so the gateway can hand them out. */
     syncMandates(): Promise<any>;
+    /**
+     * Escrow orders this gateway has issued, keyed by order id.
+     *
+     * The order id is the ONLY link between a pile of money on the ledger and a
+     * piece of content behind a route: Horizon does not put a memo on the balance
+     * record, so matching money to a deal means reading the memo off the creating
+     * transaction and comparing it to an order we recognise. An escrow whose memo
+     * matches nothing here is money locked for a deal this seller never quoted, so
+     * it buys nothing.
+     */
+    private orders;
+    /**
+     * A stable order id for one request. Deterministic on purpose: a buyer who
+     * retries while the escrow settles must land on the same order, and a seller
+     * who restarts must be able to recognise the memo on money already locked.
+     * It is not a secret and it is not a capability — holding an id buys nothing
+     * without the matching escrow on the ledger.
+     */
+    orderId(uri: string, price: Amount, body: string): string;
+    /** Escrow orders, oldest first, with whatever the ledger says about each. */
+    escrowOrders(opts?: {
+        includeSettled?: boolean;
+    }): Promise<{
+        id: string;
+        uri: string;
+        price: Amount;
+        at: number;
+        escrowId?: string;
+        releaseAt?: number;
+        served: number;
+        state: string;
+        escrow: import("./escrow.ts").Escrow | null;
+        outcome: {
+            settled: boolean;
+            by?: string;
+            txHash?: string;
+            at?: string;
+        };
+    }[]>;
+    /**
+     * Take the money the buyer locked. Two keys, always — the vault's threshold
+     * is 2, so a stolen agent key cannot empty an escrow on its own.
+     */
+    releaseEscrow(orderId: string, keys: {
+        agent: Parameters<typeof claimEscrow>[3]["agent"];
+        approver: Parameters<typeof claimEscrow>[3]["approver"];
+    }): Promise<{
+        txHash: string;
+        claimedAt: number;
+    }>;
+    /**
+     * The split-key release: build the claim, sign it with the agent key, and
+     * hand it to the phone. This process cannot finish it — that is the point.
+     */
+    escrowReleaseChallenge(orderId: string, agent: Keypair): Promise<import("./phone.ts").ApprovalChallenge>;
+    /** Take the phone's signature back and settle the escrow on the ledger. */
+    submitEscrowRelease(signedXdr: string, orderId: string): Promise<{
+        hash: string;
+        ok: true;
+    }>;
     /** Register a pre-authorised mandate for a route (needs both human keys). */
     authorise(uri: string, spec: Parameters<StellarVault["createMandate"]>[0], principal: Parameters<StellarVault["createMandate"]>[1], approver: Parameters<StellarVault["createMandate"]>[2]): Promise<Mandate>;
     /**
@@ -104,9 +177,28 @@ export declare class Gateway {
             issuer: string | undefined;
         };
         vault: string;
-        mode: "approval" | "preauth";
+        mode: "approval" | "escrow" | "preauth";
+        maxTimeoutSeconds: number;
+        version: string;
+    } | {
+        scheme: string;
+        network: string;
+        maxAmountRequired: string;
+        resource: string;
+        payTo: string;
+        token: {
+            code: string;
+            issuer: string | undefined;
+        };
+        vault: string;
+        mode: "approval" | "escrow" | "preauth";
         maxTimeoutSeconds: number;
         version: string;
+        escrow: {
+            vault: string;
+            releaseSeconds: number;
+            memoMustBe: string;
+        };
     };
     /**
      * Check a proof against the live request before spending anything.

package/dist/gateway.js

@@ -1,7 +1,7 @@
 // Paydlux gateway on Stellar — an HTTP resource server that answers 402 and
 // only serves the body once payment has actually landed on the ledger.
 //
-// Two modes per route:
+// Three modes per route:
 //
 //   preauth   the human already registered a mandate envelope for this seller
 //             and amount. The gateway hands it over, the agent signs, submits,
@@ -11,12 +11,19 @@
 //             holds it at the approval desk, and a person approves or denies.
 //             On approval the vault releases with principal + approver.
 //
+//   escrow    the buyer locks the money in a claimable balance the seller
+//             cannot touch until the release timer passes. Delivery has to be
+//             proven before that timer, and releasing still needs both human
+//             keys. Until then the buyer can always take it back.
+//
 // Either way the agent's key alone can never move money: threshold is 2.
 import { createServer } from "node:http";
 import { createHash } from "node:crypto";
 import { Keypair, StrKey, Transaction } from "@stellar/stellar-sdk";
 import { StellarTxError, hex, passphrase } from "./vault.js";
 import { ApprovalDesk } from "./desk.js";
+import { claimEscrow, escrowOutcome, prepareEscrowRelease, readEscrow, verifyEscrow } from "./escrow.js";
+import { submitApproved } from "./phone.js";
 export const PAY_HEADER = "x-payment";
 export class Gateway {
     routes = new Map();
@@ -48,6 +55,75 @@ export class Gateway {
         const s = await this.cfg.vault.signerSummary();
         return s.signers.filter((x) => x.type === "preauth-mandate");
     }
+    /**
+     * Escrow orders this gateway has issued, keyed by order id.
+     *
+     * The order id is the ONLY link between a pile of money on the ledger and a
+     * piece of content behind a route: Horizon does not put a memo on the balance
+     * record, so matching money to a deal means reading the memo off the creating
+     * transaction and comparing it to an order we recognise. An escrow whose memo
+     * matches nothing here is money locked for a deal this seller never quoted, so
+     * it buys nothing.
+     */
+    orders = new Map();
+    /**
+     * A stable order id for one request. Deterministic on purpose: a buyer who
+     * retries while the escrow settles must land on the same order, and a seller
+     * who restarts must be able to recognise the memo on money already locked.
+     * It is not a secret and it is not a capability — holding an id buys nothing
+     * without the matching escrow on the ledger.
+     */
+    orderId(uri, price, body) {
+        return "ord_" + createHash("sha256")
+            .update(`${this.cfg.vault.address}|${uri}|${price}|${body}`).digest("hex").slice(0, 16);
+    }
+    /** Escrow orders, oldest first, with whatever the ledger says about each. */
+    async escrowOrders(opts = {}) {
+        const out = [];
+        for (const o of this.orders.values()) {
+            const e = o.escrowId ? await readEscrow(this.cfg.vault.network, o.escrowId) : null;
+            const outcome = o.escrowId ? await escrowOutcome(this.cfg.vault.network, o.escrowId) : { settled: false };
+            const now = Math.floor(Date.now() / 1000);
+            const state = e
+                ? (now >= e.releaseAt ? "releasable" : "locked")
+                : outcome.settled ? "released" : o.escrowId ? "gone" : "awaiting_escrow";
+            if (state === "released" && !opts.includeSettled)
+                continue;
+            out.push({ ...o, state, escrow: e, outcome });
+        }
+        return out.sort((a, b) => (a.releaseAt ?? 0) - (b.releaseAt ?? 0));
+    }
+    /**
+     * Take the money the buyer locked. Two keys, always — the vault's threshold
+     * is 2, so a stolen agent key cannot empty an escrow on its own.
+     */
+    async releaseEscrow(orderId, keys) {
+        const o = this.orders.get(orderId);
+        if (!o?.escrowId)
+            throw new Error(`no escrow locked for order ${orderId}`);
+        const out = await claimEscrow(this.cfg.vault.network, o.escrowId, this.cfg.vault.address, keys);
+        this.settled.add("escrow:" + o.escrowId);
+        return out;
+    }
+    /**
+     * The split-key release: build the claim, sign it with the agent key, and
+     * hand it to the phone. This process cannot finish it — that is the point.
+     */
+    async escrowReleaseChallenge(orderId, agent) {
+        const o = this.orders.get(orderId);
+        if (!o?.escrowId)
+            throw new Error(`no escrow locked for order ${orderId}`);
+        return prepareEscrowRelease(this.cfg.vault.network, o.escrowId, this.cfg.vault.address, agent);
+    }
+    /** Take the phone's signature back and settle the escrow on the ledger. */
+    async submitEscrowRelease(signedXdr, orderId) {
+        const o = this.orders.get(orderId);
+        if (!o?.escrowId)
+            throw new Error(`no escrow locked for order ${orderId}`);
+        const out = await submitApproved(signedXdr, this.cfg.vault.network, this.cfg.vault.horizon);
+        this.settled.add("escrow:" + o.escrowId);
+        return out;
+    }
     /** Register a pre-authorised mandate for a route (needs both human keys). */
     async authorise(uri, spec, principal, approver) {
         const r = this.routes.get(uri);
@@ -101,8 +177,8 @@ export class Gateway {
     agentKeys;
     requirements(uri) {
         const r = this.routes.get(uri);
-        return {
-            scheme: "stellar-exact",
+        const base = {
+            scheme: r.mode === "escrow" ? "stellar-escrow" : "stellar-exact",
             network: `stellar:${this.cfg.network}`,
             maxAmountRequired: r.price,
             resource: uri,
@@ -113,6 +189,21 @@ export class Gateway {
             maxTimeoutSeconds: r.holdSeconds ?? 3600,
             version: "1",
         };
+        if (r.mode !== "escrow")
+            return base;
+        // An escrow route tells the buyer how to lock the money, not just what to
+        // pay. Without the release window in the 402 the buyer cannot compute a
+        // valid timer, and the seller has no deadline to prove delivery against.
+        return {
+            ...base,
+            escrow: {
+                vault: this.cfg.vault.address,
+                releaseSeconds: r.releaseSeconds ?? 3600,
+                // The memo on the creating transaction must be this order id, or the
+                // money cannot be matched to a deal and buys nothing.
+                memoMustBe: "the order id returned in this response",
+            },
+        };
     }
     /**
      * Check a proof against the live request before spending anything.
@@ -193,8 +284,12 @@ export class Gateway {
             const raw = req.headers[PAY_HEADER];
             if (!raw) {
                 const reqs = this.requirements(uri);
-                res.writeHead(402, { [PAY_HEADER]: JSON.stringify(reqs) });
-                res.end(JSON.stringify({ error: "payment_required", accepts: reqs }));
+                // An escrow buyer has to know the order id BEFORE locking the money,
+                // because the memo on the creating transaction is the only thing that
+                // ties that pile of money to this deal. Hand it out in the 402.
+                const order = r.mode === "escrow" ? { order: this.orderId(uri, r.price, body) } : {};
+                res.writeHead(402, { [PAY_HEADER]: JSON.stringify({ ...reqs, ...order }) });
+                res.end(JSON.stringify({ error: "payment_required", accepts: reqs, ...order }));
                 return;
             }
             let proof;
@@ -205,8 +300,63 @@ export class Gateway {
                 res.writeHead(400).end("bad payment header");
                 return;
             }
-            if (!proof.intent && !proof.envelope) {
-                res.writeHead(400).end("payment header needs an envelope or an intent");
+            if (!proof.intent && !proof.envelope && !proof.escrow) {
+                res.writeHead(400).end("payment header needs an envelope, an intent, or an escrow id");
+                return;
+            }
+            // escrow mode: the buyer locked the money in a claimable balance. The
+            // seller cannot claim it yet — that is the whole deal. Serving the body
+            // now means the buyer still holds the refund right, so the seller's
+            // incentive is to deliver first and release later.
+            if (r.mode === "escrow") {
+                if (!proof.escrow) {
+                    res.writeHead(402, { [PAY_HEADER]: JSON.stringify(this.requirements(uri)) });
+                    res.end(JSON.stringify({ error: "escrow_required", reason: "this route is sold against escrow: lock the payment in a claimable balance first", escrow: this.requirements(uri).escrow }));
+                    return;
+                }
+                const id = this.orderId(uri, r.price, body);
+                const releaseSeconds = r.releaseSeconds ?? 3600;
+                const check = await verifyEscrow(this.cfg.vault.network, proof.escrow, {
+                    orderId: id,
+                    asset: this.cfg.vault.token,
+                    amount: r.price,
+                    vault: this.cfg.vault.address,
+                    releaseAt: 0, // not compared; the window checks below do the work
+                }, { minReleaseSeconds: 1, maxReleaseSeconds: releaseSeconds + 300 });
+                if (!check.ok || !check.escrow) {
+                    res.writeHead(402, { [PAY_HEADER]: JSON.stringify(this.requirements(uri)) });
+                    res.end(JSON.stringify({ error: "escrow_invalid", order: id, reason: check.reason }));
+                    return;
+                }
+                const prior = this.orders.get(id);
+                this.orders.set(id, {
+                    id, uri, price: r.price, at: prior?.at ?? Date.now(),
+                    escrowId: proof.escrow, releaseAt: check.escrow.releaseAt,
+                    served: (prior?.served ?? 0) + 1,
+                });
+                const content = getContent(uri);
+                res.writeHead(200, {
+                    "content-type": "application/json",
+                    "x-payment-response": JSON.stringify({
+                        escrow: proof.escrow, order: id,
+                        releaseAt: check.escrow.releaseAt,
+                        lockTx: check.escrow.txHash,
+                    }),
+                });
+                res.end(JSON.stringify({
+                    data: content,
+                    order: id,
+                    escrow: {
+                        id: proof.escrow,
+                        amount: check.escrow.amount,
+                        releaseAt: check.escrow.releaseAt,
+                        // The buyer's own refund right, spelled out so a client can act on
+                        // it without reading a spec: claim the balance back before this
+                        // second, no seller consent needed.
+                        refundUntil: check.escrow.releaseAt,
+                        lockTx: check.escrow.txHash,
+                    },
+                }));
                 return;
             }
             // approval mode: the agent sends a signed intent, a human decides