@paydlux/agent 0.1.20 → 0.1.22

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")
@@ -302,16 +322,17 @@ async function sell() {
         // --split is the honest mode: this process cannot approve anything.
         approver: split ? undefined : keys.approver,
         split,
+        agentSeed: keys.agent,
         portalKey,
         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 +774,129 @@ 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) {
+        // The recommended setup: the desk is running with the phone approver, so
+        // hand the release to the DESK instead of writing a file nothing reads.
+        // The desk queues it, the phone signs the claim, the desk submits it.
+        const deskPort = Number(arg("desk") ?? 4022);
+        const portalKey = data.desk?.portalKey;
+        if (portalKey) {
+            try {
+                const res = await fetch(`http://127.0.0.1:${deskPort}/escrow?k=${encodeURIComponent(portalKey)}`, {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify({
+                        escrowId: hit.balanceId, order: hit.memo || undefined,
+                        amount: hit.amount,
+                        asset: hit.asset === "native" ? "XLM" : hit.asset.split(":")[0],
+                        buyer: hit.buyer,
+                    }),
+                });
+                if (res.ok) {
+                    const queued = await res.json();
+                    console.log(`\nrelease queued on the approval desk as ${queued.id}.`);
+                    console.log(`  open:  ${flag("tls") ? `https://${PUBLIC_HOST}` : `http://127.0.0.1:${deskPort}`}/phone/?k=${portalKey}`);
+                    console.log(`  the order is ${hit.memo || hit.balanceId} — approve on the phone only if you delivered it.`);
+                    console.log(`  the phone signs the claim; the desk submits it. vault balance updates after.\n`);
+                    return;
+                }
+                console.log(`the desk answered ${res.status}; falling back to the manual challenge.\n`);
+            }
+            catch {
+                // No desk listening on that port. Fall through to the file path.
+            }
+        }
+        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  the order id is ${hit.memo || hit.balanceId} — sign only if you delivered it.\n`);
+        console.log(`no approval desk is answering on port ${deskPort}. start one with \`paydlux sell\` (or the`);
+        console.log(`app:mainnet:sell script) and re-run this command, and the release goes to your phone.`);
+        console.log(`or finish it on a machine that holds the approver key.\n`);
+        // Written out so the second signature can still be added by hand from a
+        // machine that holds the approver key. Said exactly: nothing 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 also written to ${file} (0600) for the manual path.\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 +1018,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 +1201,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/desk.d.ts

@@ -32,6 +32,20 @@ export type DeskRecord = {
     challenge?: ApprovalChallenge;
     qr?: string;
     signedXdr?: string;
+    /**
+     * What the human is being asked to authorise. `payment` is the vault paying
+     * money OUT. `escrow` is the vault claiming a claimable balance the buyer
+     * already locked — money coming IN. The distinction is load-bearing: the
+     * spending mandate caps payments out, so it must not touch an escrow
+     * release, and the signed transaction is verified against a different
+     * operation type.
+     */
+    kind?: "payment" | "escrow";
+    /** escrow records: the claimable balance to claim, and the order it belongs to */
+    escrowId?: string;
+    order?: string;
+    /** escrow records: the asset the balance pays out ("XLM", "USDC", ...) */
+    asset?: string;
 };
 export type DeskStore = DeskRecord;
 export type DeskConfig = {
@@ -46,6 +60,15 @@ export type DeskConfig = {
      * the desk submits it. The approver seed never touches this machine.
      */
     split?: boolean;
+    /**
+     * The agent seed (the machine-side key). Payments are built with the
+     * principal key; an ESCROW CLAIM is built with the agent key — that is the
+     * key pair the escrow was designed around (agent + phone approver). The desk
+     * needs it to build the release challenge, exactly as it needs the principal
+     * seed to build a payment challenge. It is not the approving half: the claim
+     * still needs the phone's signature to reach the vault's threshold of 2.
+     */
+    agentSeed?: string;
     /** how long a human has to decide before the payment is dead */
     decideWithinSeconds?: number;
     port: number;
@@ -99,6 +122,27 @@ export declare class ApprovalDesk {
     /** Every record carrying this key, newest first. */
     allByKey(key: string): DeskRecord[];
     findByKey(key: string): DeskRecord | null;
+    /**
+     * Queue an escrow release for the human. This is the missing half of
+     * `paydlux escrow --release` on a --split vault: the money already sits in a
+     * claimable balance the buyer locked, so releasing it is the vault CLAIMING
+     * that balance — money coming IN, not going out. The claim still needs the
+     * vault's threshold of 2 (agent + approver), and the approver half lives on
+     * the phone, so it goes through the same challenge/sign/submit loop as a
+     * payment, tagged `kind: "escrow"` so the spending mandate — which caps
+     * money OUT — never touches it.
+     *
+     * The generic fields (uri/price/body) are filled so the portal page renders
+     * the row without knowing about escrow; the structured fields carry the
+     * truth the verification uses.
+     */
+    addEscrow(input: {
+        escrowId: string;
+        order?: string;
+        amount: string;
+        asset: string;
+        buyer?: string;
+    }): DeskRecord;
     get(id: string): DeskRecord | null;
     list(): DeskRecord[];
     /**
@@ -127,6 +171,21 @@ export declare class ApprovalDesk {
     approve(id: string): Promise<DeskRecord>;
     /** Split mode step 1: ask the phone to sign. Nothing is submitted yet. */
     private requestPhoneSignature;
+    /**
+     * Split mode step 1 for an ESCROW release: build the claim, sign it with the
+     * agent key, hand it to the phone. `prepareEscrowRelease` reads the ledger
+     * and refuses a balance that does not exist or whose timer has not passed,
+     * so a queued-but-fake escrow dies here with a real reason instead of
+     * reaching the human as a signable challenge.
+     */
+    private requestEscrowSignature;
+    /**
+     * Split mode step 2 for an ESCROW release: the phone signed the claim.
+     * No mandate check — this is money coming IN — and no recordSpend: the
+     * daily budget counts payments OUT, and counting a release against it would
+     * make the seller's own earned money unclaimable.
+     */
+    private completeEscrow;
     /**
      * Split mode step 2: the phone answered. `signedXdr` is the transaction with
      * the approver signature added, returned by signChallenge() on the phone.