@paydlux/agent 0.1.20 → 0.1.21

package/README.md

@@ -264,6 +264,74 @@ Two ledger behaviours we verified rather than assumed, and designed around:
   the content twice — so `gateway.ts` checks the ledger for an already-applied
   transaction before shipping anything.
 
+### Escrow: proof of delivery, not a promise
+
+The claim on the landing page is that a payment can be held until delivery is
+proven. That is only worth anything if the hold is enforced by the network, so
+escrow is built from **native Stellar claimable balances** — not a smart
+contract.
+
+```
+paydlux sell --escrow --price 3.5 --release 3600
+```
+
+A buyer locks the price in a claimable balance with two claimants:
+
+| claimant | predicate | what it means |
+|---|---|---|
+| the seller's vault | `NOT(abs_before = releaseAt)` | can claim **only after** the release timer, and only with both human keys |
+| the buyer | `abs_before = releaseAt` | can take the money back **any time before** the timer, alone, no seller consent |
+
+Why claimable balances instead of a contract:
+
+- **No contract to audit.** The rules are a ledger primitive, not code we wrote.
+- **No contract address to get wrong.** A wrong address in a payment path is an
+  irreversible loss; there is no address here.
+- **The money never sits in an account the seller controls.** The seller cannot
+  spend it, pledge it, or lose it to a bug in their own server.
+- **The reserve is paid by whoever creates the balance and returned when it is
+  claimed.** No standing rent for an idle escrow.
+- **The rules hold when the seller's server is down.** Uptime cannot unlock a
+  predicate.
+
+The seller gets paid by *proving delivery before the timer*, not by waiting it
+out. The buyer's leverage is the refund right, which is real: it works up to the
+release second and needs nobody's permission.
+
+Matching money to a deal is the part that is easy to get wrong. Horizon does not
+put a memo on the balance record, so `readEscrow` fetches the creating
+transaction and reads the memo off it. The memo **must** equal the order id the
+gateway handed out in the `402`; an escrow whose memo matches nothing buys
+nothing. Without that join, two orders at the same price to the same vault are
+indistinguishable, and a seller could deliver order A and claim the escrow locked
+for order B.
+
+```bash
+paydlux escrow                       # what is locked, who locked it, when it releases
+paydlux escrow --release ord_7f3a…   # needs both human keys; on --split, prints the phone challenge
+PAYDLUX_BUYER_SEED=S… paydlux escrow --refund <escrow id>   # the buyer's way out
+```
+
+`--release` refuses before the timer in words ("42 min to go") — the ledger would
+refuse the transaction anyway, but a seller deserves to know why before they
+reach for a key.
+
+Three suites, all against the live test network, none mocked:
+
+```bash
+npm run test:escrow        # ledger primitives + the HTTP 402 escrow deal
+npx tsx stellar/escrow-cli-check.ts   # the whole thing through the published CLI
+```
+
+`escrow-check.ts` locks real balances and asserts the ledger's answer: the vault
+cannot claim early, a wrong second key gets `tx_bad_auth`, the buyer's refund
+lands, and after the timer a 2-of-2 claim settles. `escrow-gateway-check.ts`
+drives the product: `402` with escrow terms, the buyer locking money, the body
+served against the escrow id, a different request body refused because the memo
+names the other order, and the release queue flipping from `locked` to
+`releasable`. `escrow-cli-check.ts` runs `dist/cli.js` the way a user does, so a
+command printed in `--help` that is not actually dispatched fails the build.
+
 ### Real money
 
 Circle issues USDC natively on Stellar — not wrapped, not bridged. `vault.ts`

package/dist/agent.d.ts

@@ -31,6 +31,19 @@ export type PayResponse<T = string> = {
     desk?: string;
     /** where THIS buyer polls for the answer (the gateway, no key needed) */
     statusUrl?: string;
+    /**
+     * Escrow mode: the seller's order id, and what the ledger now says about the
+     * locked money. `escrow.refundUntil` is the buyer's own protection — until
+     * that second the buyer can claim the money back without the seller.
+     */
+    order?: string;
+    escrow?: {
+        id: string;
+        amount: string;
+        releaseAt: number;
+        refundUntil: number;
+        lockTx: string;
+    };
     reason?: string;
     requirements?: any;
 };
@@ -46,6 +59,7 @@ export declare class PaydluxAgent {
     get<T = string>(url: string, opts?: {
         mandate?: Mandate;
         body?: string;
+        buyerKey?: string;
     }): Promise<PayResponse<T>>;
     /**
      * Sign and submit a mandate envelope directly to Horizon. Used when the

package/dist/agent.js

@@ -6,7 +6,8 @@
 // The agent holds one key of two. It can ask, and it can execute a mandate a
 // human already signed. It cannot move money on its own — the ledger refuses.
 import { Horizon, Keypair, Transaction } from "@stellar/stellar-sdk";
-import { passphrase } from "./vault.js";
+import { passphrase, parseToken } from "./vault.js";
+import { createEscrow } from "./escrow.js";
 const PAY_HEADER = "x-payment";
 export class PaydluxAgent {
     key;
@@ -31,6 +32,10 @@ export class PaydluxAgent {
         const reqs = parseRequirements(first.headers.get(PAY_HEADER));
         if (!reqs)
             return { ok: false, status: 402, reason: "seller sent 402 without payment terms", requirements: null };
+        // The 402 body carries the order id for escrow routes: the memo on the
+        // buyer's lock transaction has to name it, so it must be known before any
+        // money is locked.
+        const j0 = await first.json().catch(() => ({}));
         if (reqs.mode === "approval") {
             // Tell the seller we want it. The seller parks the request at the
             // approval desk and a person decides. We do not get to decide.
@@ -50,6 +55,52 @@ export class PaydluxAgent {
                 statusUrl: j.statusUrl, requirements: reqs,
                 reason: j.reason ?? "a human has to approve this payment" };
         }
+        if (reqs.mode === "escrow") {
+            // Escrow is the opposite of the other two modes: the buyer keeps the
+            // power. The money is locked in a claimable balance the seller cannot
+            // touch until the release timer, and the buyer can reclaim it any time
+            // before then. So the buyer needs its OWN funding key here — not the
+            // agent key, which is a signer on a vault and has no business paying.
+            if (!opts.buyerKey) {
+                return { ok: false, status: 402, requirements: reqs,
+                    reason: "this route is sold against escrow; pass buyerKey (the account that funds the escrow)" };
+            }
+            const orderId = j0.order ?? reqs.order;
+            if (!orderId)
+                return { ok: false, status: 402, requirements: reqs, reason: "seller did not name an order id" };
+            const buyerKp = Keypair.fromSecret(opts.buyerKey);
+            const releaseSeconds = Number(reqs.escrow?.releaseSeconds ?? 3600);
+            let locked;
+            try {
+                locked = await createEscrow(this.cfg.network, {
+                    orderId,
+                    asset: parseToken(String(reqs.token?.code ?? "XLM"), reqs.token?.issuer),
+                    amount: String(reqs.maxAmountRequired),
+                    buyer: buyerKp.publicKey(),
+                    vault: reqs.escrow?.vault ?? reqs.vault,
+                    releaseAt: Math.floor(Date.now() / 1000) + releaseSeconds,
+                }, buyerKp);
+            }
+            catch (e) {
+                return { ok: false, status: 402, requirements: reqs, order: orderId,
+                    reason: `could not lock the escrow: ${e.message}` };
+            }
+            const retry = await f(url, {
+                method: opts.body ? "POST" : "GET", body: opts.body,
+                headers: { [PAY_HEADER]: JSON.stringify({ escrow: locked.escrow.balanceId }) },
+            });
+            const j = await retry.json().catch(() => ({}));
+            if (retry.status === 200) {
+                return {
+                    ok: true, status: 200, data: (j.data ?? j), requirements: reqs,
+                    order: j.order, escrow: j.escrow,
+                    // The buyer's protection, spelled out: until escrow.refundUntil this
+                    // money is still claimable back by the buyer, no seller consent needed.
+                    tx: j.escrow?.lockTx,
+                };
+            }
+            return { ok: false, status: retry.status, reason: j.reason ?? "escrow refused", requirements: reqs, order: orderId };
+        }
         if (!opts.mandate) {
             return { ok: false, status: 402, requirements: reqs,
                 reason: "seller wants a pre-authorised mandate and none was supplied" };

package/dist/cli.js

@@ -27,6 +27,8 @@ import { PolicyEngine } from "./policy.js";
 import { PUBLIC_HOST, TUNNEL_NAME, runTunnel, tunnelLive, tunnelProblem, tunnelRunning, tunnelServes } from "./tunnel.js";
 import { DEMO_HOST, DEMO_ROUTE, startDemo } from "./showcase.js";
 import { DONATE_HOST, DONATE_PORT, startDonate } from "./donate.js";
+import { claimEscrow, pendingEscrows, prepareEscrowRelease, refundEscrow } from "./escrow.js";
+import { describeChallenge } from "./phone.js";
 export const VAULT_FILE_DEFAULT = "paydlux-vault.json";
 const arg = (name) => {
     const i = process.argv.indexOf(`--${name}`);
@@ -202,7 +204,15 @@ async function sell() {
     if (!(Number(price) > 0))
         bad("--price must be a positive number");
     const uri = arg("route") ?? "/api/data";
-    const mode = flag("preauth") ? "preauth" : "approval";
+    if (flag("preauth") && flag("escrow"))
+        bad("--preauth and --escrow are different deals: pre-authorised payment, or payment held until delivery is proven. Pick one.");
+    const mode = flag("preauth") ? "preauth" : flag("escrow") ? "escrow" : "approval";
+    // How long the buyer's money stays locked. The seller needs this window to
+    // prove delivery; the buyer is the one who can walk away inside it. Too short
+    // and the seller never gets paid; too long and the buyer is stuck waiting.
+    const releaseSeconds = Number(arg("release") ?? 3600);
+    if (!(releaseSeconds >= 60))
+        bad("--release must be at least 60 seconds. A window shorter than that cannot be audited by either side.");
     const tls = flag("tls");
     const split = flag("split");
     // Real money gets a hard ceiling, and it is not a suggestion. The ledger
@@ -219,11 +229,21 @@ async function sell() {
     const priceNum = Number(price);
     if (!(priceNum > 0))
         bad(`--price ${price} is not a number greater than zero.`);
-    if (priceNum > maxPer) {
-        bad(`--price ${price} is above --max ${maxPer}, so every payment would be refused by your own mandate.\n  raise --max to at least ${price} (for example --max ${price}) or lower --price.`);
+    // The mandate ceiling is a limit on what YOUR vault pays out. An escrow route
+    // takes money IN from the buyer, so the ceiling does not apply to it — and
+    // applying it would refuse a perfectly good escrow price for no reason.
+    if (mode === "escrow") {
+        if (priceNum > maxPer) {
+            log(`note: --escrow price ${price} is above --max ${maxPer}. That is fine here — escrow money comes FROM the buyer, so your spending mandate never touches it.`);
+        }
     }
-    if (priceNum > daily) {
-        bad(`--price ${price} is above --daily ${daily}: one payment would spend the whole day's budget and the second would be refused.\n  set --daily to at least ${price}.`);
+    else {
+        if (priceNum > maxPer) {
+            bad(`--price ${price} is above --max ${maxPer}, so every payment would be refused by your own mandate.\n  raise --max to at least ${price} (for example --max ${price}) or lower --price.`);
+        }
+        if (priceNum > daily) {
+            bad(`--price ${price} is above --daily ${daily}: one payment would spend the whole day's budget and the second would be refused.\n  set --daily to at least ${price}.`);
+        }
     }
     const vault = await StellarVault.load(data.vault, data.token.code, data.token.issuer, { principal: pub(keys.principal), approver: keys.approver ? pub(keys.approver) : undefined, agent: pub(keys.agent) }, network);
     if (data.token.code === "USDC")
@@ -306,12 +326,12 @@ async function sell() {
         publicHost,
         agentKeys: [pub(keys.agent)],
         routes: [
-            { uri, price, mode, holdSeconds: Number(arg("hold") ?? 3600) },
+            { uri, price, mode, holdSeconds: Number(arg("hold") ?? 3600), releaseSeconds },
             // --showcase adds a second priced route for the public page. Same price,
             // same mandate, same desk: the showcase gets no special treatment at the
             // spending door, it only gets its own hostname.
             ...(flag("showcase")
-                ? [{ uri: DEMO_ROUTE, price, mode: mode, holdSeconds: Number(arg("hold") ?? 3600) }]
+                ? [{ uri: DEMO_ROUTE, price, mode: mode, holdSeconds: Number(arg("hold") ?? 3600), releaseSeconds }]
                 : []),
         ],
         // The banner prints these numbers. This line is what makes them true.
@@ -753,6 +773,100 @@ async function withdraw() {
     console.log(`done. tx ${res?.hash}`);
     console.log(`vault now holds ${await vault.balance()} ${data.token.code}`);
 }
+// ---------------------------------------------------------------------- escrow
+/**
+ * The seller's view of every escrow sold through this gateway.
+ *
+ * `paydlux escrow` lists what is locked, who locked it, and what the ledger
+ * says about each one. `paydlux escrow --release ord_…` takes the money — which
+ * needs both human keys, so on a --split vault it prints the challenge for the
+ * phone and stops, exactly like the approval desk does.
+ *
+ * Nothing here can take money early. The release timer is enforced by the
+ * ledger, not by this command: asking before the timer gets a sentence saying
+ * how long is left, and the network would refuse the transaction anyway.
+ */
+async function escrow() {
+    const { data, path } = loadVault();
+    const network = (data.network ?? "testnet");
+    const vault = await StellarVault.load(data.vault, data.token.code, data.token.issuer, {
+        principal: pub(data.keys.principal),
+        approver: data.keys.approver ? pub(data.keys.approver) : undefined,
+        agent: pub(data.keys.agent),
+    }, network);
+    if (data.token.code === "USDC")
+        vault.useUsdc();
+    const release = arg("release");
+    const refund = arg("refund");
+    if (refund) {
+        // The buyer's side, kept here so the protection is a command and not a
+        // paragraph. Needs the buyer's key, which this file does not hold unless
+        // the buyer is also the seller — so it reads it from the environment.
+        const seed = process.env.PAYDLUX_BUYER_SEED;
+        if (!seed)
+            bad("--refund returns the BUYER's money, so it needs the buyer's key.\n  PAYDLUX_BUYER_SEED=S… paydlux escrow --refund <escrow id>");
+        const out = await refundEscrow(network, refund, Keypair.fromSecret(seed));
+        console.log(`refunded. the money is back in the buyer's account. tx ${out.txHash}`);
+        return;
+    }
+    // Anything the ledger has locked for this vault, whether or not this process
+    // remembers quoting it. A seller who restarted still has to see money that is
+    // already locked, or it looks like nothing was ever ordered.
+    const live = await pendingEscrows(network, vault.address);
+    const now = Math.floor(Date.now() / 1000);
+    if (!release) {
+        if (!live.length) {
+            console.log(`\nno escrow is locked for ${vault.address} right now.\n`);
+            console.log(`sell against escrow with:  paydlux sell --escrow --price 3.5 --release 3600\n`);
+            return;
+        }
+        console.log(`\nescrow locked for ${vault.address} on ${network === "public" ? "MAINNET" : "testnet"}\n`);
+        for (const e of live) {
+            const left = e.releaseAt - now;
+            console.log(`  ${e.memo || "(no order id)"}   ${e.amount} ${e.asset === "native" ? "XLM" : e.asset.split(":")[0]}`);
+            console.log(`    escrow   ${e.balanceId}`);
+            console.log(`    buyer    ${e.buyer}`);
+            console.log(`    ${left > 0 ? `buyer can still take it back for ${Math.ceil(left / 60)} more min` : `release timer passed — claimable now with both keys`}`);
+            if (left <= 0)
+                console.log(`    release: paydlux escrow --release ${e.memo || e.balanceId}`);
+            console.log("");
+        }
+        console.log(`an escrow with no order id you recognise is money locked for a deal you never quoted. Do not release it: refund it.\n`);
+        return;
+    }
+    // Match on order id first (what a human reads), then on balance id (what a
+    // script has). Both are exact; a prefix is not accepted, because two order
+    // ids can share a prefix and money cannot be released "approximately".
+    const hit = live.find((e) => e.memo === release || e.balanceId === release);
+    if (!hit)
+        bad(`nothing locked matches "${release}".\n  run \`paydlux escrow\` to list what is locked, and use the order id or the escrow id exactly as printed.`);
+    if (now < hit.releaseAt) {
+        bad(`the release timer has not passed: ${Math.ceil((hit.releaseAt - now) / 60)} min to go.\n  the buyer can still refund this money until then, so releasing it is not on the table.\n  the ledger would refuse this anyway — this command only says so earlier and in words.`);
+    }
+    const keys = data.keys ?? {};
+    const agent = Keypair.fromSecret(keys.agent);
+    if (!keys.approver) {
+        const challenge = await prepareEscrowRelease(network, hit.balanceId, vault.address, agent);
+        console.log(`\nthis laptop holds one of the two keys, so the release needs your phone.\n`);
+        console.log(describeChallenge(challenge));
+        console.log(`\n  open:  ${flag("tls") ? `https://${PUBLIC_HOST}` : "http://127.0.0.1:4022"}/?k=${data.desk?.portalKey ?? "…"}`);
+        console.log(`  the order id is ${hit.memo || hit.balanceId} — sign only if you delivered it.\n`);
+        // Written out so the second signature can be added by whatever holds the
+        // approver key, without retyping XDR. Said exactly, because a promise here
+        // that nothing implements is a lie in the seller's terminal: no process
+        // reads this file back on its own.
+        const file = path.replace(/\.json$/, ".escrow-release.json");
+        writeFileSync(file, JSON.stringify({ order: hit.memo || hit.balanceId, challenge }, null, 2), { mode: 0o600 });
+        console.log(`challenge written to ${file} (0600).`);
+        console.log(`nothing completes this by itself. finish it from a machine that holds the approver key,`);
+        console.log(`or run this command there. the phone approver releases PAYMENTS today; releasing ESCROW`);
+        console.log(`from the phone is not wired yet, so until it is, use the second key's machine.\n`);
+        return;
+    }
+    const out = await claimEscrow(network, hit.balanceId, vault.address, { agent, approver: Keypair.fromSecret(keys.approver) });
+    console.log(`released ${hit.amount} for order ${hit.memo || "(no id)"}. tx ${out.txHash}`);
+    console.log(`vault now holds ${await vault.balance()} ${data.token.code}`);
+}
 // ----------------------------------------------------------------------- usdc
 /**
  * Let the vault and its payee hold real Circle USDC.
@@ -874,11 +988,19 @@ const HELP = `paydlux — get paid by AI agents, with a human in the loop.
   paydlux setup [--mainnet] [--token USDC] [--fund-seed S…]
       create a vault. testnet by default (free, no wallet needed).
   paydlux sell  [--price 1] [--route /api/data] [--max N] [--daily N]
-                [--split] [--tls] [--preauth]
+                [--split] [--tls] [--preauth] [--escrow] [--release SECONDS]
       start the gateway and the approval desk.
       --max / --daily are your spending mandate: no single payment above --max,
       and nothing past --daily in a day. The desk refuses at the approve button,
       so a runaway agent cannot drain the vault even if you approve in error.
+      --escrow sells the route against escrow instead: the buyer locks the money
+      in a claimable balance you cannot touch until --release seconds have
+      passed, and the buyer can take it back any time before then. You get paid
+      by proving delivery before the timer, not by waiting for it.
+  paydlux escrow [--release ORD | --refund ESCROW_ID]
+      list what is locked for your vault, release one order, or take a buyer's
+      money back. Release needs both human keys; on a --split vault it prints
+      the challenge for your phone and stops there.
   paydlux donate [--file ./paydlux-vault.json] [--usdc] [--price 1] [--tls]
       a public door where other agents pay YOU from THEIR vault.
       --usdc prices the door in Circle USDC. It refuses to start unless the
@@ -1049,6 +1171,8 @@ export async function main() {
         return withdraw();
     if (cmd === "usdc")
         return usdc();
+    if (cmd === "escrow")
+        return escrow();
     bad(`unknown command "${cmd}".\n\n${HELP}`);
 }
 // Run only when this file is the entry point, so importing it in a test is safe.

package/dist/escrow.d.ts

@@ -0,0 +1,154 @@
+import { Asset, Keypair } from "@stellar/stellar-sdk";
+import { type Amount, type Network } from "./vault.ts";
+export declare const horizonUrl: (network: Network) => string;
+/** Horizon writes an asset as "native" or "USDC:Gissuer…". */
+export declare function assetToHorizonString(asset: Asset): string;
+export declare function assetFromHorizonString(s: string): Asset;
+/** The deal the buyer must lock into the ledger. */
+export type EscrowTerms = {
+    /** the order id the buyer must put in the creating transaction's memo */
+    orderId: string;
+    asset: Asset;
+    amount: Amount;
+    /**
+     * The account that funds and locks the escrow. Required to create one.
+     * Optional when VERIFYING: a seller usually does not care who the buyer is,
+     * only that the money is locked to the right order, price and vault. Pin it
+     * when the buyer's account was agreed up front, and any other account is
+     * refused.
+     */
+    buyer?: string;
+    /** the seller vault allowed to claim after release */
+    vault: string;
+    /** unix seconds; the vault cannot claim before this, the buyer can refund until this */
+    releaseAt: number;
+};
+export type Escrow = {
+    balanceId: string;
+    amount: Amount;
+    asset: string;
+    vault: string;
+    buyer: string;
+    releaseAt: number;
+    /** the transaction that created it, and the memo it carried */
+    txHash: string;
+    memo: string;
+    memoType: string;
+    /** true once the ledger says the balance is gone (claimed or swept) */
+    claimed: boolean;
+};
+export type EscrowCheck = {
+    ok: boolean;
+    reason?: string;
+    escrow?: Escrow;
+};
+/**
+ * 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 declare function readEscrow(network: Network, balanceId: string): Promise<Escrow | null>;
+/**
+ * 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 declare function verifyEscrow(network: Network, balanceId: string, want: EscrowTerms, opts?: {
+    minReleaseSeconds?: number;
+    maxReleaseSeconds?: number;
+    /**
+     * The refund window being open is a requirement when ACCEPTING a deal —
+     * a buyer who locks money with a timer that already expired has locked
+     * nothing, because the seller could claim it the instant it lands.
+     *
+     * It is not a requirement when RELEASING one. An escrow that reached its
+     * timer is still a valid escrow; that is the normal, successful case. So
+     * the release path passes allowClosedWindow and gets the money it earned.
+     */
+    allowClosedWindow?: boolean;
+}): Promise<EscrowCheck>;
+/**
+ * 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 declare function escrowBalanceId(resultXdr: string, index?: number): string;
+/**
+ * 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 declare function createEscrow(network: Network, terms: EscrowTerms, buyerKey: Keypair): Promise<{
+    escrow: Escrow;
+    txHash: string;
+}>;
+/**
+ * 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 declare function claimEscrow(network: Network, balanceId: string, vaultAddress: string, keys: {
+    agent: Keypair;
+    approver: Keypair;
+}): Promise<{
+    txHash: string;
+    claimedAt: number;
+}>;
+/**
+ * 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 declare function prepareEscrowRelease(network: Network, balanceId: string, vaultAddress: string, agent: Keypair): Promise<import("./phone.ts").ApprovalChallenge>;
+/**
+ * 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 declare function refundEscrow(network: Network, balanceId: string, buyerKey: Keypair): Promise<{
+    txHash: string;
+}>;
+/**
+ * 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 declare function pendingEscrows(network: Network, vaultAddress: string, limit?: number): Promise<Escrow[]>;
+/**
+ * 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 declare function escrowOutcome(network: Network, balanceId: string): Promise<{
+    settled: boolean;
+    by?: string;
+    txHash?: string;
+    at?: string;
+}>;

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

package/dist/index.d.ts

@@ -12,3 +12,5 @@ export type { Policy, SpendEvent, Verdict } from "./policy.ts";
 export { createApprovalChallenge, signChallenge, describeChallenge, submitApproved, challengeQrPayload, parseChallengeQr, } from "./phone.ts";
 export { txResultName } from "./vault.ts";
 export type { ApprovalChallenge } from "./phone.ts";
+export { createEscrow, verifyEscrow, readEscrow, claimEscrow, refundEscrow, escrowOutcome, pendingEscrows, escrowBalanceId, assetToHorizonString, assetFromHorizonString, } from "./escrow.ts";
+export type { EscrowTerms, Escrow, EscrowCheck } from "./escrow.ts";

package/dist/index.js

@@ -10,3 +10,7 @@ export { PolicyEngine, DEFAULT_POLICY } from "./policy.js";
 // Split signing: the human's key lives on a phone, not in the seller's process.
 export { createApprovalChallenge, signChallenge, describeChallenge, submitApproved, challengeQrPayload, parseChallengeQr, } from "./phone.js";
 export { txResultName } from "./vault.js";
+// Escrow: native claimable balances, not a contract. The buyer locks the money,
+// the seller cannot touch it until the release timer, and the buyer can always
+// take it back before then.
+export { createEscrow, verifyEscrow, readEscrow, claimEscrow, refundEscrow, escrowOutcome, pendingEscrows, escrowBalanceId, assetToHorizonString, assetFromHorizonString, } from "./escrow.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paydlux/agent",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "description": "Payments for AI agents that a human approves. Spending mandates enforced on the Stellar ledger: 2-of-2 vault, pre-authorised transaction envelopes, HTTP 402, USDC.",
   "type": "module",
   "main": "./dist/index.js",
@@ -64,7 +64,8 @@
     "site:qr": "tsx stellar/make-site-qr.ts paydlux-mainnet.json site/qr.svg",
     "address:check": "tsx stellar/check-address.ts",
     "test:address": "tsx stellar/address-check.ts",
-    "site:deploy": "tsx stellar/make-site-qr.ts paydlux-mainnet.json site/qr.svg && wrangler deploy"
+    "site:deploy": "tsx stellar/make-site-qr.ts paydlux-mainnet.json site/qr.svg && wrangler deploy",
+    "test:escrow": "tsx stellar/escrow-check.ts && tsx stellar/escrow-gateway-check.ts"
   },
   "keywords": [
     "x402",