@paydlux/agent 0.1.20 → 0.1.22

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();
@@ -38,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,
@@ -48,6 +56,87 @@ 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;
+            // 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));
+    }
+    /**
+     * 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 +190,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 +202,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 +297,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 +313,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.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",
@@ -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 && 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);