@paydlux/agent 0.1.19 → 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

@@ -24,9 +24,11 @@ import { StellarVault, USDC_ISSUER, passphrase } from "./vault.js";
 import { Gateway } from "./gateway.js";
 import { newPortalKey } from "./desk.js";
 import { PolicyEngine } from "./policy.js";
-import { PUBLIC_HOST, TUNNEL_NAME, runTunnel, tunnelLive, tunnelProblem, tunnelRunning, tunnelServes } from "./tunnel";
-import { DEMO_HOST, DEMO_ROUTE, startDemo } from "./showcase";
-import { DONATE_HOST, DONATE_PORT, startDonate } from "./donate";
+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,26 @@ 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
+      vault already holds a USDC trustline: without one every payment bounces
+      with OP_NO_TRUST and the page looks broken forever.
+  paydlux usdc [--file ./paydlux-vault.json]
+      add that USDC trustline — one claimable, so the human half signs it.
   paydlux status
       balances, signers, live mandates, ledger rent.
   paydlux approver [--forget]
@@ -908,6 +1037,22 @@ one file holds it all: ./paydlux-vault.json (0600, never commit it)
  *    seller's money. Fewer moving parts means less that can leak.
  */
 async function donate() {
+    if (flag("help") || process.argv.includes("-h")) {
+        console.log(`paydlux donate [--file ./paydlux-vault.json] [--usdc] [--price 1]
+                [--tls] [--port ${DONATE_PORT}]
+      a public door where other agents pay YOU from THEIR vault.
+
+      --usdc     price the door in Circle USDC instead of the vault file's
+                 token. Refuses to start unless the vault already holds a
+                 USDC trustline (run: paydlux usdc) — without one every
+                 payment bounces with OP_NO_TRUST and the page looks broken.
+      --price N  what a donation costs, in the asset's own units.
+      --tls      required in practice: an order and its memo over plain HTTP
+                 can be taken by anyone on the path.
+      --port N   local port (default ${DONATE_PORT}); the public name is
+                 ${DONATE_HOST}, routed by the tunnel.`);
+        return;
+    }
     const path = arg("file") ?? VAULT_FILE_DEFAULT;
     if (!existsSync(path))
         bad(`no vault file at ${path}. Run: paydlux setup`);
@@ -1026,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/donate.d.ts

@@ -1,4 +1,4 @@
-import type { Network } from "./receive";
+import type { Network } from "./receive.ts";
 export declare const DONATE_HOST = "donate.paydlux.com";
 export declare const DONATE_PORT = 4024;
 export type DonatePageConfig = {
@@ -43,6 +43,6 @@ export declare function startDonate(cfg: {
     } | null>;
 }): {
     server: import("node:http").Server<typeof import("node:http").IncomingMessage, typeof import("node:http").ServerResponse>;
-    book: import("./receive").OrderBook;
+    book: import("./receive.ts").OrderBook;
     listen: (port: number) => Promise<void>;
 };

package/dist/donate.js

@@ -13,8 +13,8 @@
 //
 // Nothing here holds a buyer key. We publish terms; they sign at home; the
 // ledger is the only witness we accept.
-import { startReceive } from "./receive";
-import { qrSvg } from "./qr";
+import { startReceive } from "./receive.js";
+import { qrSvg } from "./qr.js";
 export const DONATE_HOST = "donate.paydlux.com";
 export const DONATE_PORT = 4024;
 /**

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;
+}>;