@paydlux/agent 0.1.21 → 0.1.22

package/dist/cli.js

@@ -322,6 +322,7 @@ 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)],
@@ -846,21 +847,50 @@ async function escrow() {
     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  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.
+        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 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`);
+        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) });

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.

package/dist/desk.js

@@ -19,6 +19,7 @@ import { TransactionBuilder } from "@stellar/stellar-sdk";
 import { passphrase } from "./vault.js";
 import { portalPage } from "./portal.js";
 import { createApprovalChallenge, submitApproved, challengeQrPayload, } from "./phone.js";
+import { claimEscrow, prepareEscrowRelease } from "./escrow.js";
 /**
  * The approver app is plain static files under phone-app/. Read on each request
  * rather than bundled, so the desk and the app can never drift apart.
@@ -121,6 +122,37 @@ function verifyAgainstChallenge(signedXdr, rec) {
 function recNetwork(rec) {
     return rec.challenge.network;
 }
+/**
+ * Same binding check as verifyAgainstChallenge, for an escrow release. The
+ * signed transaction must be the claim the desk issued (same hash), carry both
+ * signatures, and — the escrow-specific part — claim EXACTLY the balance this
+ * record names. Without that last check a signature collected for one escrow
+ * could be replayed against another order's queue entry.
+ */
+function verifyEscrowAgainstChallenge(signedXdr, rec) {
+    const ch = rec.challenge;
+    let signed;
+    try {
+        signed = TransactionBuilder.fromXDR(signedXdr, passphrase(recNetwork(rec)));
+    }
+    catch {
+        return "the phone returned something that is not a valid transaction for this network";
+    }
+    const hash = Buffer.from(signed.hash()).toString("hex");
+    if (hash !== ch.hash) {
+        return `signed a different transaction (${hash.slice(0, 12)}… was not issued for ${rec.id}, which is ${ch.hash.slice(0, 12)}…)`;
+    }
+    if (signed.signatures.length < 2) {
+        return `only ${signed.signatures.length} signature(s); the vault needs 2`;
+    }
+    const op = signed.operations?.[0];
+    if (!op || op.type !== "claimClaimableBalance")
+        return "the transaction is not an escrow claim";
+    if (op.balanceId !== rec.escrowId) {
+        return `the claim targets ${String(op.balanceId).slice(0, 12)}…, not the escrow ${String(rec.escrowId).slice(0, 12)}… this approval is for`;
+    }
+    return null;
+}
 function readBody(req) {
     return new Promise((resolve, reject) => {
         let data = "";
@@ -222,6 +254,46 @@ export class ApprovalDesk {
     findByKey(key) {
         return this.allByKey(key)[0] ?? 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) {
+        this.sweepExpired();
+        // One live record per balance id. A seller who runs --release twice must
+        // not get two Approve buttons for the same money: the second signature
+        // would fail on the ledger (balance already claimed) and confuse the human.
+        for (const r of this.records.values()) {
+            if (r.kind === "escrow" && r.escrowId === input.escrowId &&
+                r.status !== "denied" && r.status !== "failed" && r.status !== "expired")
+                return r;
+        }
+        const id = `esc_${input.escrowId.slice(-8)}${randomBytes(3).toString("hex")}`;
+        const label = input.order || `${input.escrowId.slice(0, 16)}…`;
+        const rec = {
+            id, at: Date.now(),
+            uri: `/escrow/${label}`,
+            // amount only, like a payment price; the asset rides in `asset` and
+            // reaches the phone as `token`, so the row never prints "3.5 XLM XLM".
+            price: input.amount,
+            body: `escrow release — buyer ${input.buyer ?? "?"} — balance ${input.escrowId}`,
+            status: "pending",
+            kind: "escrow", escrowId: input.escrowId, order: input.order, asset: input.asset,
+        };
+        this.records.set(id, rec);
+        console.log(`[desk] ${id} escrow release awaiting a human: ${rec.price} (${label})`);
+        return rec;
+    }
     get(id) { this.sweepExpired(); return this.records.get(id) ?? null; }
     list() { this.sweepExpired(); return [...this.records.values()]; }
     /**
@@ -285,6 +357,27 @@ export class ApprovalDesk {
             throw new Error("unknown handle " + id);
         if (rec.status !== "pending")
             throw new Error(`already ${rec.status}`);
+        // An escrow release is money coming IN. The spending mandate caps money
+        // going OUT, so applying it here would refuse a release for a budget that
+        // the release does not touch — and would make the seller's own money
+        // unclaimable on a day they already spent.
+        if (rec.kind === "escrow") {
+            // dev mode (both keys on this machine): claim straight away.
+            if (this.cfg.approver && this.cfg.agentSeed) {
+                try {
+                    const out = await claimEscrow(this.cfg.vault.network, rec.escrowId, this.cfg.vault.address, { agent: Keypair.fromSecret(this.cfg.agentSeed), approver: Keypair.fromSecret(this.cfg.approver) });
+                    rec.status = "settled";
+                    rec.tx = out.txHash;
+                    console.log(`[desk] ${rec.id} ESCROW RELEASED ${rec.price} — ledger ${rec.tx}`);
+                }
+                catch (e) {
+                    rec.status = "failed";
+                    rec.reason = e.message;
+                }
+                return rec;
+            }
+            return this.requestEscrowSignature(rec);
+        }
         // Check before asking the phone. A human who approves a payment the mandate
         // will refuse has spent a Face ID scan and a signature for nothing.
         if (this.mandateBlock(rec, "refused before asking"))
@@ -344,6 +437,64 @@ export class ApprovalDesk {
         }
         return rec;
     }
+    /**
+     * 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.
+     */
+    async requestEscrowSignature(rec) {
+        if (!this.cfg.agentSeed) {
+            rec.status = "failed";
+            rec.reason = "an escrow release needs the agent seed on this machine to build the claim";
+            return rec;
+        }
+        try {
+            const challenge = await prepareEscrowRelease(this.cfg.vault.network, rec.escrowId, this.cfg.vault.address, Keypair.fromSecret(this.cfg.agentSeed));
+            // The challenge carries its own id; keep the desk's handle so
+            // /challenge/:id and /signed/:id line up with what the queue shows.
+            challenge.id = rec.id;
+            rec.challenge = challenge;
+            rec.qr = challengeQrPayload(challenge);
+            rec.status = "awaiting_phone";
+            console.log(`[desk] ${rec.id} escrow claim sent to the phone: ${rec.price}`);
+        }
+        catch (e) {
+            rec.status = "failed";
+            rec.reason = e.message;
+            console.log(`[desk] ${rec.id} escrow claim refused before asking: ${rec.reason}`);
+        }
+        return rec;
+    }
+    /**
+     * 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.
+     */
+    async completeEscrow(rec, signedXdr) {
+        const problem = verifyEscrowAgainstChallenge(signedXdr, rec);
+        if (problem) {
+            rec.status = "failed";
+            rec.reason = problem;
+            console.log(`[desk] ${rec.id} rejected: ${problem}`);
+            return rec;
+        }
+        rec.signedXdr = signedXdr;
+        try {
+            const res = await submitApproved(signedXdr, this.cfg.vault.network, this.cfg.vault.horizon);
+            rec.status = "settled";
+            rec.tx = res.hash;
+            console.log(`[desk] ${rec.id} ESCROW RELEASED ${rec.price} — ledger ${rec.tx}`);
+        }
+        catch (e) {
+            rec.status = "failed";
+            rec.reason = e.message;
+            console.log(`[desk] ${rec.id} failed on the ledger: ${rec.reason}`);
+        }
+        return rec;
+    }
     /**
      * Split mode step 2: the phone answered. `signedXdr` is the transaction with
      * the approver signature added, returned by signChallenge() on the phone.
@@ -359,6 +510,11 @@ export class ApprovalDesk {
             throw new Error(`not awaiting a phone signature (it is ${rec.status})`);
         if (!rec.challenge)
             throw new Error("no challenge was issued for " + id);
+        // An escrow release verifies against its own shape (a claim of THIS
+        // balance id) and bypasses the spending mandate, which only caps payments
+        // going out.
+        if (rec.kind === "escrow")
+            return this.completeEscrow(rec, signedXdr);
         // Bind the answer to the question. Without this check the desk would submit
         // any signed transaction posted to this route — including one the phone
         // signed for a DIFFERENT payment, at a different price. That is how a
@@ -432,9 +588,14 @@ export class ApprovalDesk {
             tx: r.tx,
             /** what the buyer says it wants. Agent-controlled text: render as text. */
             wants: (r.body ?? "").slice(0, 200),
-            token: this.cfg.vault.token.getCode(),
+            token: r.kind === "escrow" ? r.asset ?? this.cfg.vault.token.getCode() : this.cfg.vault.token.getCode(),
             expiresAt: r.challenge?.summary.expiresAt,
             hash: r.challenge?.hash,
+            // The phone renders an escrow row differently: it is money IN, and the
+            // human verifies the balance id, not a payee.
+            kind: r.kind ?? "payment",
+            escrowId: r.escrowId,
+            order: r.order,
         }));
     }
     /** Serve the pending list as JSON (the portal polls this). */
@@ -635,7 +796,37 @@ export class ApprovalDesk {
                         wants: (rec.body ?? "").slice(0, 200),
                         memo: rec.challenge.summary.memo ?? "",
                         expiresAt: rec.challenge.summary.expiresAt,
+                        // An escrow challenge renders differently on the phone: the op
+                        // carries no amount and no payee, so the app shows the amount from
+                        // here and asks the human to check the balance id.
+                        kind: rec.kind ?? "payment",
+                        escrowId: rec.escrowId,
+                        // The claim op carries no amount, so the phone shows the amount
+                        // the desk read from the ledger alongside the balance id it puts
+                        // in front of the human.
+                        amount: rec.kind === "escrow" ? rec.price : undefined,
+                        asset: rec.kind === "escrow" ? rec.asset : undefined,
+                    });
+                }
+                // The CLI's hand-off for `paydlux escrow --release` on a --split vault:
+                // queue this balance on the running desk so the phone can sign it.
+                // Key-gated like every other route, and it only queues — approving
+                // still needs the human's hold-and-sign on the phone.
+                if (url.pathname === "/escrow" && req.method === "POST") {
+                    const body = await readBody(req);
+                    const input = JSON.parse(body || "{}");
+                    if (!input.escrowId)
+                        return send(400, { error: "escrowId is required" });
+                    if (!input.amount || !input.asset)
+                        return send(400, { error: "amount and asset are required" });
+                    const rec = this.addEscrow({
+                        escrowId: String(input.escrowId),
+                        order: input.order ? String(input.order) : undefined,
+                        amount: String(input.amount),
+                        asset: String(input.asset),
+                        buyer: input.buyer ? String(input.buyer) : undefined,
                     });
+                    return send(200, { id: rec.id, status: rec.status, escrowId: rec.escrowId });
                 }
                 const m = url.pathname.match(/^\/(approve|deny|signed)\/([\w-]+)$/);
                 if (m && req.method === "POST") {

package/dist/gateway.d.ts

@@ -40,6 +40,12 @@ export type GatewayConfig = {
      * phone sends back.
      */
     split?: boolean;
+    /**
+     * The agent seed, passed to the desk so it can build an ESCROW RELEASE
+     * challenge (the claim is signed agent + phone approver). Same trust level
+     * as `principal`: it is the machine-side half, never the approving half.
+     */
+    agentSeed?: string;
     deskPort?: number;
     /** gate the approval portal behind a single unguessable link */
     portalKey?: string;

package/dist/gateway.js

@@ -45,6 +45,7 @@ export class Gateway {
             port: cfg.deskPort ?? 4022,
             portalKey: cfg.portalKey,
             split: cfg.split,
+            agentSeed: cfg.agentSeed,
             publicHost: cfg.publicHost,
             decideWithinSeconds: cfg.decideWithinSeconds,
             policy: cfg.policy,
@@ -89,6 +90,18 @@ export class Gateway {
                 : outcome.settled ? "released" : o.escrowId ? "gone" : "awaiting_escrow";
             if (state === "released" && !opts.includeSettled)
                 continue;
+            // A releasable escrow goes to the desk automatically, so the phone sees
+            // the release without anyone re-running the CLI. addEscrow is idempotent
+            // per balance id, so this is safe to call from a read path.
+            if (state === "releasable" && e) {
+                this.desk.addEscrow({
+                    escrowId: o.escrowId,
+                    order: o.id,
+                    amount: e.amount,
+                    asset: e.asset === "native" ? "XLM" : e.asset.split(":")[0],
+                    buyer: e.buyer,
+                });
+            }
             out.push({ ...o, state, escrow: e, outcome });
         }
         return out.sort((a, b) => (a.releaseAt ?? 0) - (b.releaseAt ?? 0));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paydlux/agent",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "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",
@@ -65,7 +65,7 @@
     "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",
-    "test:escrow": "tsx stellar/escrow-check.ts && tsx stellar/escrow-gateway-check.ts"
+    "test:escrow": "tsx stellar/escrow-check.ts && tsx stellar/escrow-gateway-check.ts && tsx stellar/escrow-phone-check.ts"
   },
   "keywords": [
     "x402",

package/phone-app/app.js

@@ -371,8 +371,16 @@ async function openReview(id) {
     const rec = await api("/challenge/" + encodeURIComponent(id));
     const env = X.parseEnvelope(rec.xdr);
     const op = env.tx.ops[0];
-    if (env.tx.ops.length !== 1 || op.type !== X.OP_PAYMENT) {
-      throw new Error("this transaction is not a single payment \u2014 refusing to sign it");
+    // Two shapes are signable: a single payment, and a single escrow claim
+    // (the vault taking money a buyer locked in a claimable balance). Anything
+    // else is refused, and the escrow branch verifies the claim targets the
+    // balance id the desk says this approval is for.
+    const isClaim = op.type === X.OP_CLAIM_CLAIMABLE_BALANCE;
+    if (env.tx.ops.length !== 1 || (op.type !== X.OP_PAYMENT && !isClaim)) {
+      throw new Error("this transaction is not a single payment or escrow claim \u2014 refusing to sign it");
+    }
+    if (isClaim && rec.escrowId && op.balanceId !== rec.escrowId) {
+      throw new Error("the claim targets a different balance than this approval is for \u2014 refusing");
     }
     const { hash } = await X.transactionHash(rec.xdr, X.NETWORK_ID[rec.network] || rec.network);
     if (rec.hash && hash !== rec.hash) {
@@ -391,10 +399,14 @@ async function openReview(id) {
     }
     current = {
       id, xdr: rec.xdr, hash,
-      amount: X.formatAmount(op.amount),
-      token: op.asset.code || "XLM",
-      issuer: op.asset.issuer || "",
-      payee: X.encodeAccountEd25519(op.destination.pub),
+      // A claim op carries no amount: the money is whatever the ledger says the
+      // balance holds. The desk read that number when it queued the release,
+      // so the human sees it from the desk, and the balance id next to it is
+      // what ties the number to the order.
+      amount: isClaim ? String(rec.amount ?? "") : X.formatAmount(op.amount),
+      token: isClaim ? String(rec.asset ?? "") : (op.asset.code || "XLM"),
+      issuer: isClaim ? "" : (op.asset.issuer || ""),
+      payee: isClaim ? op.balanceId : X.encodeAccountEd25519(op.destination.pub),
       vault: X.encodeAccountEd25519(env.tx.source.pub),
       // Read the memo out of the envelope, not out of the server's summary:
       // the envelope is what is being signed, so it is the only source that
@@ -417,6 +429,10 @@ async function openReview(id) {
     $("amount").append(num, tk);
     set("wantsBig", current.wants);
     set("token", current.issuer ? `${current.token} (${current.issuer.slice(0, 12)}\u2026)` : current.token);
+    // An escrow claim has no payee: the money goes to the vault itself. What
+    // the human verifies instead is the balance id — the ledger address of the
+    // locked money — so the row is labelled for that.
+    $("payeeLabel").textContent = isClaim ? "Escrow balance" : "Payee";
     set("payee", current.payee);
     set("vault", current.vault);
     set("wants", current.wants);
@@ -432,6 +448,10 @@ async function openReview(id) {
     $("netChip").style.color = current.network === "public" ? "var(--ok)" : "var(--warn)";
     err("signErr", "");
     resetHold();
+    // The hold button says what it does. Releasing an escrow is not paying
+    // anyone: it is the vault taking money a buyer already locked. After
+    // resetHold, which resets the label to the payment wording.
+    if (isClaim) set("holdLbl", "Hold to release \u0026 sign");
     show("review", true);
     show("queue", false);
     $("review").scrollIntoView({ behavior: "smooth", block: "start" });

package/phone-app/index.html

@@ -235,7 +235,7 @@
   <div class="hint" id="wantsBig"></div>
   <dl class="kv" style="margin-top:16px">
     <dt>Token</dt><dd id="token"></dd>
-    <dt>Payee</dt><dd id="payee"></dd>
+    <dt id="payeeLabel">Payee</dt><dd id="payee"></dd>
     <dt>From</dt><dd id="vault"></dd>
     <dt>Wants</dt><dd id="wants"></dd>
     <dt>Reference</dt><dd id="memo"></dd>

package/phone-app/xdr.js

@@ -76,6 +76,10 @@
   const SC_ADDRESS = 4;                // soroban account: we refuse it
   const ASSET_NATIVE = 0, ASSET_ALPHANUM4 = 1, ASSET_ALPHANUM12 = 2;
   const OP_PAYMENT = 1;
+  // ClaimClaimableBalance is the escrow release: the vault taking the money the
+  // buyer locked. The phone must read it as well as payments, or a seller on a
+  // --split vault can never release an escrow from the phone.
+  const OP_CLAIM_CLAIMABLE_BALANCE = 15;
   const PRECOND_NONE = 0, PRECOND_TIME = 1, PRECOND_V2 = 2;
   const MEMO_NONE = 0, MEMO_TEXT = 1, MEMO_ID = 2, MEMO_HASH = 3, MEMO_RETURN = 4;
   const STROOPS = 10000000;
@@ -318,14 +322,29 @@
     const hasSource = r.u32();
     const source = hasSource ? readMuxedAccount(r) : null;
     const type = r.u32();                          // OperationBody union switch
+    if (type === OP_CLAIM_CLAIMABLE_BALANCE) {
+      // ClaimableBalanceID is an union: switch word, then 32 raw bytes. Only
+      // the balance-id form (switch 0) exists today; anything else is refused
+      // rather than skipped, because skipping bytes misreads the rest.
+      const which = r.u32();
+      if (which !== 0) throw new Error("claimable balance id form " + which + " is not supported; refusing to sign");
+      // The balance id AS THE LEDGER AND THE SDK NAME IT: the 4-byte union
+      // switch ("00000000") followed by the 32-byte hash. Returning only the
+      // hash would disagree with every id the desk and Horizon use, and the
+      // desk's "this claim targets THIS escrow" check would never match.
+      const balanceId = "00000000" + hex(r.fixed(32));
+      // The claim op carries NO amount: the money is whatever the ledger says
+      // that balance holds. The human verifies the balance id instead.
+      return { type, source, balanceId, destination: null, asset: null, amount: null };
+    }
     if (type !== OP_PAYMENT) {
-      throw new Error("operation type " + type + " is not a payment; this app only signs payments");
+      throw new Error("operation type " + type + " is not a payment or an escrow claim; this app only signs those");
     }
     const destination = readMuxedAccount(r);
     const asset = readAsset(r);
     const amount = r.i64();
     if (amount < 0n) throw new Error("payment amount is negative; refusing to sign");
-    return { type, source, destination, asset, amount: amount.toString() };
+    return { type, source, destination, asset, amount: amount.toString(), balanceId: null };
   }
 
   function readTransaction(r) {
@@ -336,7 +355,7 @@
     const memo = readMemo(r);
     const numOps = r.u32();
     if (numOps !== 1) {
-      throw new Error("this app signs single-payment transactions, and this one has "
+      throw new Error("this app signs one operation at a time, and this one has "
         + numOps + " operations");
     }
     const ops = [];
@@ -471,6 +490,6 @@
     encodeAccountEd25519, decodeAccountEd25519,
     decodeSecretSeed, encodeSecretSeed, importSecretSeed, importSecretSeedPair,
     NETWORK_ID, crc16Xmodem,
-    ENVELOPE_TYPE_TX, OP_PAYMENT, STROOPS,
+    ENVELOPE_TYPE_TX, OP_PAYMENT, OP_CLAIM_CLAIMABLE_BALANCE, STROOPS,
   };
 })(typeof globalThis !== "undefined" ? globalThis : this);