@paydlux/agent 0.1.17 → 0.1.19

package/README.md

@@ -234,11 +234,19 @@ combination blocks every payment and looks like a bug in the desk.
 Verified on the published package: 6 x 4.50 against `--daily 20` -> four
 settled, two refused, vault balance moved exactly 18.00 and stopped.
 
+**The budget survives a restart.** `paydlux sell` asks the ledger what the vault
+already paid that payee today and starts from that number, so `ctrl-c` and
+`npm run app` again does not hand the day back. If the day is already spent it
+refuses to start and says so; if the ledger cannot be read it refuses to start
+too, because a budget that silently reads as unspent is worse than no budget.
+The banner shows what is left: `policy: max 10 per payment, 50 per day (27.50
+left today)`.
+
 ### What is enforced where (said honestly)
 
 | enforced by Stellar | enforced by the desk (`policy.ts`) |
 |---|---|
-| payee, token, time window, one-shot execution, per-payment ceiling as a signer rule | per-payment ceiling and daily total at the approve button and again at submission, running daily total, seller allow/deny list |
+| payee, token, time window, one-shot execution, per-payment ceiling as a signer rule | per-payment ceiling and daily total at the approve button and again at submission, running daily total **seeded from the ledger's own payment history**, seller allow/deny list |
 
 The vault is one payment at a time; counting payments is our job. A rule break
 means we never build the transaction, so nothing reaches the ledger.

package/dist/cli.js

@@ -24,7 +24,9 @@ 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, runTunnel, tunnelLive, tunnelProblem } from "./tunnel.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";
 export const VAULT_FILE_DEFAULT = "paydlux-vault.json";
 const arg = (name) => {
     const i = process.argv.indexOf(`--${name}`);
@@ -100,6 +102,9 @@ async function trusts(vault, address) {
     const acc = await vault.horizon.loadAccount(address).catch(() => null);
     if (!acc)
         return false;
+    // Every account can already hold XLM; there is no trustline to be missing.
+    if (vault.isNative)
+        return true;
     const code = vault.token.getCode(), issuer = vault.token.getIssuer();
     return acc.balances.some((b) => b.asset_type !== "native"
         && b.asset_code === code && b.asset_issuer === issuer);
@@ -227,6 +232,29 @@ async function sell() {
     // payment with no valid payee is a payment that fails an hour later, after
     // the human already said yes.
     const payee = await ensurePayee(path, data, vault);
+    // The daily budget has to survive a restart. Counting only what this process
+    // has seen means `ctrl-c`, `npm run app` again, and the day's total is back to
+    // zero — so the mandate in the banner is a promise the code does not keep.
+    // Ask the ledger what the vault already paid this payee today and start from
+    // there. If the query fails, refuse to start rather than run with a budget
+    // that silently reads as unspent.
+    let alreadyPaid = 0;
+    try {
+        alreadyPaid = Number(await vault.paidToday(payee));
+    }
+    catch (e) {
+        bad(`cannot read today's spending from the ledger (${e?.message ?? e}).\n  `
+            + `the daily budget of ${daily} cannot be enforced without it, so nothing was started. `
+            + `Check the network and try again.`);
+    }
+    policy.seedFromLedger(alreadyPaid);
+    if (alreadyPaid > 0) {
+        log(`ledger says ${alreadyPaid.toFixed(2)} of the ${daily} daily budget is already spent today`);
+        if (alreadyPaid >= daily) {
+            bad(`today's budget is already gone: ${alreadyPaid.toFixed(2)} paid, ${daily} allowed.\n  `
+                + `the mandate would refuse every payment. Raise --daily or wait for the UTC day to roll over.`);
+        }
+    }
     if (network === "public") {
         console.log(`
   MAINNET — real money.
@@ -277,7 +305,15 @@ async function sell() {
         portalKey,
         publicHost,
         agentKeys: [pub(keys.agent)],
-        routes: [{ uri, price, mode, holdSeconds: Number(arg("hold") ?? 3600) }],
+        routes: [
+            { uri, price, mode, holdSeconds: Number(arg("hold") ?? 3600) },
+            // --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) }]
+                : []),
+        ],
         // The banner prints these numbers. This line is what makes them true.
         policy,
     });
@@ -286,13 +322,77 @@ async function sell() {
         const problem = tunnelProblem();
         if (problem)
             bad("--tls cannot run here: " + problem);
-        tunnel = runTunnel();
+        // A second `sell` on this machine (the free testnet showcase and the real
+        // mainnet donation door run apart on purpose) must not spawn a second
+        // cloudflared for the same tunnel. Reuse the one already running.
+        if (tunnelRunning())
+            log("the named tunnel is already running on this machine — reusing it");
+        else
+            tunnel = runTunnel();
     }
     await gw.listen(gwPort, (u) => JSON.stringify({
         served: u, at: new Date().toISOString(),
         note: "paid through Paydlux; the payment is on the Stellar ledger",
     }));
     await gw.desk.listen(deskPort);
+    // The public showcase: a page where a stranger drives the real 402 loop.
+    // It is a second listener in front of the SAME gateway, so the mandate, the
+    // desk and the daily budget are the ones already under test. It is refused
+    // without --tls because a payment request over plain HTTP is a request
+    // somebody else can replay.
+    if (flag("showcase")) {
+        if (!tls) {
+            bad("--showcase needs --tls. The page hands out agent identities to strangers; "
+                + "doing that over plain HTTP means anyone on the path can collect them.");
+        }
+        const demoPort = Number(arg("demo-port") ?? 4023);
+        const who = await portHolder(demoPort);
+        if (who)
+            bad(`port ${demoPort} (showcase) is already in use by ${who}.`);
+        await startDemo({
+            port: demoPort, price, network, vault: vault.address, token: data.token.code,
+            explorer: data.explorer ?? "", gateway: gw,
+            onKeys: (pubs) => { gw.agentKeys = [pub(keys.agent), ...pubs]; },
+        });
+        log(`showcase is listening on 127.0.0.1:${demoPort} for https://${DEMO_HOST}`);
+        if (!tunnelServes(DEMO_HOST)) {
+            log(`  the tunnel does not route ${DEMO_HOST} yet. Add to ~/.cloudflared/config.yml:`);
+            log(`    - hostname: ${DEMO_HOST}`);
+            log(`      service: http://127.0.0.1:${demoPort}`);
+            log(`  then: cloudflared tunnel route dns ${TUNNEL_NAME} ${DEMO_HOST}`);
+        }
+    }
+    // The donation door: a stranger's agent pays US from THEIR vault. This is
+    // the seller door (stellar/receive.ts) with a page a human can read. It is a
+    // separate listener on a separate hostname because it has a different trust
+    // profile: it holds no key, signs nothing, and can only ever hand out content
+    // the ledger confirms we were paid for.
+    if (flag("donate")) {
+        if (!tls)
+            bad("--donate needs --tls. The order and its memo travel to a stranger's agent; over plain HTTP someone on the path can take them and pay for your order instead of theirs.");
+        const dPort = Number(arg("donate-port") ?? DONATE_PORT);
+        const who = await portHolder(dPort);
+        if (who)
+            bad(`port ${dPort} (donations) is already in use by ${who}.`);
+        const door = startDonate({
+            port: dPort, hostname: DONATE_HOST, payee, network,
+            price: arg("donate-price") ?? price,
+            asset: vault.isNative
+                ? { code: vault.token.getCode() }
+                : { code: vault.token.getCode(), issuer: vault.token.getIssuer() },
+            vault: vault.address,
+        });
+        // startReceive builds the routes and hands back listen(); without this call
+        // the door answers nothing and the tunnel returns 502 with no local error.
+        await door.listen(dPort);
+        log(`donations are listening on 127.0.0.1:${dPort} for https://${DONATE_HOST}`);
+        if (!tunnelServes(DONATE_HOST)) {
+            log(`  the tunnel does not route ${DONATE_HOST} yet. Add to ~/.cloudflared/config.yml:`);
+            log(`    - hostname: ${DONATE_HOST}`);
+            log(`      service: http://127.0.0.1:${dPort}`);
+            log(`  then: cloudflared tunnel route dns ${TUNNEL_NAME} ${DONATE_HOST}`);
+        }
+    }
     const deskUrl = tls ? `https://${PUBLIC_HOST}` : `http://127.0.0.1:${deskPort}`;
     if (tls) {
         const live = await tunnelLive();
@@ -308,6 +408,8 @@ async function sell() {
   approvals  ${deskUrl}/?k=${portalKey}
   phone      ${deskUrl}/phone/?k=${portalKey}
 
+${flag("donate") ? `  donations  https://${DONATE_HOST}   (they pay YOU from THEIR vault)
+` : ""}
   paste into your bot:
       import { PaydluxAgent } from "@paydlux/agent";
       const agent = new PaydluxAgent({ agentKey: "${keys.agent}", network: "${network}" });
@@ -316,7 +418,7 @@ async function sell() {
   ${split
         ? "approvals need your phone. this machine holds one of the two keys."
         : "WARNING: this process holds BOTH human keys. Anyone with this machine can approve. Use --split for anything real."}
-  policy: max ${maxPer} per payment, ${daily} per day
+  policy: max ${maxPer} per payment, ${daily} per day${alreadyPaid > 0 ? ` (${(daily - alreadyPaid).toFixed(2)} left today)` : ""}
   ctrl-c to stop
 `);
     // The desk is a queue, not a database. If it dies with a payment parked, the
@@ -349,10 +451,18 @@ async function status() {
     const rent = await vaultRent(vault);
     const signers = await vault.signerSummary();
     const live = signers.signers.filter((s) => s.type === "preauth-mandate");
+    // An XLM vault has no issuer at all — the ledger's own currency is not
+    // issued by anyone. This line used to call .slice() on undefined and the
+    // whole status command died with "Cannot read properties of undefined",
+    // which made the one command that shows real balances useless precisely on
+    // the real-money (XLM) setup.
+    const tokenLabel = data.token.issuer
+        ? `${data.token.code} (${String(data.token.issuer).slice(0, 8)}…)`
+        : `${data.token.code} (the ledger's own currency — no issuer)`;
     console.log(`
   network   ${network}
   vault     ${vault.address}
-  token     ${data.token.code} (${data.token.issuer.slice(0, 8)}…)
+  token     ${tokenLabel}
   balance   ${await vault.balance()} ${data.token.code}
   xlm rent  ${rent.xlm} / ${rent.min} XLM  ${rent.short ? "SHORT — payments will fail" : "ok"}
   payee     ${data.payee?.address ?? "(not set)"}
@@ -385,36 +495,53 @@ async function setup() {
     const code = ((arg("token") ?? await ask("token for your payments", mainnet ? "USDC" : "AGPAY")) || "AGPAY").toUpperCase();
     const budget = Number(arg("max") ?? await ask("max per payment", mainnet ? "2" : "10"));
     const daily = Number(arg("daily") ?? await ask("daily budget", mainnet ? "10" : "50"));
-    if (mainnet && code !== "USDC") {
-        bad("on mainnet this first release only supports USDC. Custom tokens need an issuer key you would have to hold and protect — not a first-money decision.");
+    // XLM is a first-class settlement asset now, not a fallback. It is the
+    // cheapest way to take real money: no trustline for the buyer, no issuer to
+    // trust, and a visitor can fund a wallet from any exchange in one step.
+    const native = code === "XLM" || code === "NATIVE";
+    if (mainnet && !native && code !== "USDC") {
+        bad("on mainnet this first release only supports XLM and USDC. Custom tokens need an issuer key you would have to hold and protect — not a first-money decision.");
+    }
+    if (native && (budget < 1 || daily < 1)) {
+        bad("an XLM budget under 1 is not usable: Stellar amounts are 7 decimals but rent is paid in XLM, so a sub-1 daily budget would be eaten by the vault's own ledger rent.");
     }
     rl.close();
     console.log(`\nPaydlux setup — Stellar ${network}${mainnet ? " (REAL MONEY)" : ""}\n`);
     const principal = Keypair.random(), approver = Keypair.random(), agent = Keypair.random();
     const payee = Keypair.random();
-    const issuer = code === "USDC" ? null : Keypair.random();
+    // XLM and USDC both have no issuer key for us to hold: XLM is the ledger's
+    // own currency and Circle mints USDC. Only a custom token needs one.
+    const issuer = native || code === "USDC" ? null : Keypair.random();
     // The account that pays the XLM for creating everything. On testnet that is
     // friendbot. On mainnet it has to be a wallet the human already controls.
     let funder;
     if (!mainnet) {
-        if (!issuer)
-            throw new Error("internal: a custom token needs an issuer key");
         console.log("funding on testnet (friendbot, no captcha)…");
-        for (const k of [issuer, principal, approver, payee])
+        const toFund = [principal, approver, payee, ...(issuer ? [issuer] : [])];
+        for (const k of toFund)
             await StellarVault.fundTestnet(k);
-        funder = issuer;
+        // With no issuer key, one of the throwaway funded accounts pays for the
+        // vault's creation. It is not a key the vault ever trusts.
+        funder = issuer ?? toFund[0];
     }
     else {
         const seed = arg("fund-seed") ?? process.env.PAYDLUX_FUND_SEED;
         if (!seed) {
+            const need = native ? 15 : 8;
             bad(`mainnet needs a wallet to pay the account-creation costs.
 
-  paydlux setup --mainnet --fund-seed S…
+  paydlux setup --mainnet --token ${code} --fund-seed S…
 
-  The wallet only needs a few XLM (about 8 XLM covers everything here, at
-  ~0.17 USDT per XLM). It is used to CREATE two accounts; it cannot touch the
-  vault afterwards, because the vault's own keys are made fresh right now and
-  its master key is switched off in the same transaction that creates it.`);
+  The wallet needs ${need} XLM (at ~0.17 USDT per XLM that is a few dollars). It
+  is used to CREATE two accounts and nothing else: it cannot touch the vault
+  afterwards, because the vault's own keys are made fresh right now and its
+  master key is switched off in the same transaction that creates it.
+
+  If this wallet is brand new it does not exist on the ledger yet, and a plain
+  payment to it fails with op_no_account. It has to receive its first XLM from
+  something that creates the account for you: an exchange withdrawal does this
+  automatically, or any wallet with an "activate"/"fund new address" flow.
+  1 XLM activates it; you need ${need} here.`);
         }
         funder = Keypair.fromSecret(seed);
         const h = new (await import("@stellar/stellar-sdk")).Horizon.Server("https://horizon.stellar.org");
@@ -422,8 +549,16 @@ async function setup() {
         if (!acc)
             bad(`the funding wallet ${funder.publicKey()} does not exist on mainnet. Send it some XLM first.`);
         const xlm = acc.balances.find((b) => b.asset_type === "native")?.balance ?? "0";
-        if (Number(xlm) < 8)
-            bad(`the funding wallet has ${xlm} XLM. Creating a vault + a payee account needs about 8 XLM.`);
+        // The vault's starting balance is locked partly as ledger reserve, and the
+        // payee account costs 2 more. An XLM vault needs a working balance on top
+        // of its reserve because it SPENDS XLM, so it costs more to open than a
+        // token vault. Say the real number instead of a guess.
+        const need = native ? 15 : 8;
+        if (Number(xlm) < need)
+            bad(`the funding wallet ${funder.publicKey()} has ${xlm} XLM and needs at least ${need}.
+  an XLM vault locks 2.5 XLM of reserve but also has to hold spendable XLM, so it
+  opens with 12; the payee account costs 2 more; fees are under 0.01.
+  Send more XLM to ${funder.publicKey()} and re-run. Nothing was created.`);
         console.log(`funding wallet ${funder.publicKey()} — ${xlm} XLM`);
     }
     console.log("creating the 2-of-2 vault…");
@@ -432,10 +567,14 @@ async function setup() {
         issuer: funder,
         principal, approver, agent,
         tokenCode: code,
-        tokenIssuer: code === "USDC" ? USDC_ISSUER[network] : undefined,
+        // XLM has no issuer at all; USDC's issuer is Circle's account, which we
+        // hold no key for. Only a custom token gets the funder as issuer.
+        tokenIssuer: native ? undefined : (code === "USDC" ? USDC_ISSUER[network] : undefined),
         // mainnet: 2 base reserves + 3 signers + 1 trustline = 3 XLM locked, plus
         // room for one live mandate (0.5 XLM) and fees. 5 leaves a margin.
-        startingBalance: mainnet ? "5" : undefined,
+        // An XLM vault skips the trustline, so it needs 0.5 XLM less — but the
+        // vault also *spends* XLM, so it needs a working balance, not just rent.
+        startingBalance: mainnet ? (native ? "12" : "5") : undefined,
     });
     console.log("vault created. master key is off: it can never act alone again.");
     // A Stellar account must exist before it can be paid, and a payment cannot
@@ -444,7 +583,7 @@ async function setup() {
     // with OP_NO_TRUST. This is the single most common reason a first real
     // payment is rejected, so it happens here, once, at setup.
     if (mainnet) {
-        console.log("creating the payee account (2 XLM) and its USDC trustline…");
+        console.log(`creating the payee account (2 XLM)${native ? "" : " and its " + code + " trustline"}…`);
         const { Horizon, TransactionBuilder, Operation, Account, Networks } = await import("@stellar/stellar-sdk");
         const h = new Horizon.Server("https://horizon.stellar.org");
         const fa = await h.loadAccount(funder.publicKey());
@@ -455,14 +594,21 @@ async function setup() {
         await h.submitTransaction(t1);
     }
     await vault.trustToken(payee.publicKey(), "100000", payee);
-    console.log("payee account ready and trusted for " + code + ".");
+    console.log(native
+        ? "payee account ready. XLM needs no trustline — it can already be paid."
+        : "payee account ready and trusted for " + code + ".");
+    // A custom token has to be minted into the vault before it can pay anything.
+    // XLM and USDC arrive from outside, so there is nothing to mint here.
     if (issuer)
         await vault.deposit(String(daily), issuer);
     const data = {
         createdAt: new Date().toISOString(),
         network,
         vault: vault.address,
-        token: { code, issuer: code === "USDC" ? USDC_ISSUER[network] : issuer.publicKey() },
+        // XLM is stored with no issuer on purpose. A recorded issuer next to the
+        // name "XLM" would describe a fake token that anyone could issue, and
+        // parseToken() refuses that combination outright.
+        token: { code, ...(native ? {} : { issuer: code === "USDC" ? USDC_ISSUER[network] : issuer.publicKey() }) },
         policy: { maxPerPayment: budget, dailyBudget: daily, defaultPrice: mainnet ? "1" : "2" },
         payee: { address: payee.publicKey(), seed: payee.secret() },
         keys: {
@@ -607,6 +753,121 @@ async function withdraw() {
     console.log(`done. tx ${res?.hash}`);
     console.log(`vault now holds ${await vault.balance()} ${data.token.code}`);
 }
+// ----------------------------------------------------------------------- usdc
+/**
+ * Let the vault and its payee hold real Circle USDC.
+ *
+ * Circle mints USDC, so there is no issuer key for us to hold — an account
+ * only has to say it accepts USDC (a trustline) before the ledger will let it
+ * receive any. Without this, a payment of real USDC to the vault fails with
+ * OP_NO_TRUST and the money bounces back to the sender.
+ *
+ * Two trustlines are needed, not one: the vault, and the payee the 402 terms
+ * actually name as the destination. Adding only the vault's is the half-fix
+ * that looks set up and still bounces.
+ *
+ * Each trustline also raises the account's XLM rent by 0.5 XLM. The payee we
+ * create is funded with exactly one account entry (2 XLM), so a trustline on
+ * it fails OP_INSUFFICIENT_BALANCE unless it is topped up first. That is why
+ * this command pays the rent before it asks for the trustline.
+ *
+ * This does NOT change what the door charges. The live doors settle in XLM and
+ * the printed price stays XLM until someone deliberately switches the token;
+ * a trustline only makes USDC *possible*, it never silently reprices a live
+ * payment page.
+ */
+async function usdc() {
+    const { data, path } = loadVault();
+    const network = (data.network ?? "testnet");
+    const keys = data.keys ?? {};
+    if (!keys.principal || !keys.approver) {
+        bad(`adding a trustline needs both human keys and this machine holds `
+            + `${keys.principal ? "only the principal" : "neither"}.\n`
+            + "  run this on the machine with both, or approve from the phone.");
+    }
+    if (!data.payee?.seed) {
+        bad(`the payee ${data.payee?.address ?? "(none)"} is not ours to sign for, so we cannot add its\n`
+            + "  trustline. Ask whoever owns that account to add a USDC trustline for:\n\n"
+            + `  ${USDC_ISSUER[network]}\n\n`
+            + "  or drop --payee and let Paydlux manage a payee account it can sign for.");
+    }
+    const principal = Keypair.fromSecret(keys.principal);
+    const approver = Keypair.fromSecret(keys.approver);
+    const payeeKp = Keypair.fromSecret(data.payee.seed);
+    const vault = await StellarVault.load(data.vault, data.token.code, data.token.issuer, { principal: principal.publicKey(), approver: approver.publicKey(), agent: pub(keys.agent) }, network);
+    const has = async (address) => {
+        const acc = await vault.horizon.loadAccount(address).catch(() => null);
+        if (!acc)
+            return null;
+        const line = acc.balances.find((b) => b.asset_type !== "native"
+            && b.asset_code === "USDC" && b.asset_issuer === USDC_ISSUER[network]);
+        // Keep the two balances separate. Reading the native balance and labelling
+        // it "USDC" is how a setup check convinces you there is money in the wrong
+        // asset: XLM and USDC are not interchangeable and the ledger keeps them apart.
+        return {
+            xlm: acc.balances.find((b) => b.asset_type === "native")?.balance ?? "0",
+            usdc: line?.balance ?? "0.0000000",
+            line: !!line,
+        };
+    };
+    log(`USDC on ${network === "public" ? "mainnet" : network}: issuer ${USDC_ISSUER[network]}`);
+    // 1. the payee needs XLM rent for its new subentry before it can accept USDC.
+    const payeeNow = await has(data.payee.address);
+    if (!payeeNow)
+        bad(`${data.payee.address} does not exist on ${network}.`);
+    if (!payeeNow.line) {
+        const rent = await vaultRent(vault);
+        const topup = "0.6";
+        if (Number(rent.xlm) - Number(topup) < Number(rent.min) + 0.5) {
+            bad(`the vault cannot spare the payee's 0.5 XLM rent without going short itself\n`
+                + `  (vault has ${rent.xlm} XLM, needs ${rent.min} to stay open). Fund it first.`);
+        }
+        log(`paying the payee ${topup} XLM so it can afford the trustline rent…`);
+        await vault.release(data.payee.address, topup, principal, approver, "paydlux usdc rent");
+    }
+    // 2. both trustlines. useUsdc() first so trustToken() signs for the right asset.
+    vault.useUsdc();
+    const vaultNow = await has(vault.address);
+    if (vaultNow?.line)
+        log("the vault already holds a USDC trustline");
+    else {
+        log(`adding the vault's USDC trustline…`);
+        await vault.trustUsdc(principal, approver);
+    }
+    if (payeeNow.line)
+        log("the payee already holds a USDC trustline");
+    else {
+        log(`adding the payee's USDC trustline…`);
+        await vault.trustToken(data.payee.address, "1000000", payeeKp);
+    }
+    // 3. verify by re-reading the ledger. A trustline the ledger does not show is
+    // not a trustline.
+    const v2 = await has(vault.address);
+    const p2 = await has(data.payee.address);
+    console.log(`
+  vault  ${vault.address}
+         USDC ${v2?.line ? "accepted" : "NOT ACCEPTED"}   holds ${v2?.usdc} USDC, ${v2?.xlm} XLM
+  payee  ${data.payee.address}
+         USDC ${p2?.line ? "accepted" : "NOT ACCEPTED"}   holds ${p2?.usdc} USDC, ${p2?.xlm} XLM
+`);
+    if (!v2?.line || !p2?.line)
+        bad("the ledger does not show both trustlines. nothing was set up.");
+    console.log(`both accounts can now hold real Circle USDC.
+
+what that does NOT change: the doors still charge what their config says
+(${data.token.code}), and the printed price on the page stays in that asset.
+Switching the price itself is a deliberate step, because a live page that
+promises 1 XLM and asks for 1 USDC is a page that takes the wrong money.
+
+to put real USDC in, send it from an exchange to:
+
+  ${vault.address}
+
+${network === "public"
+        ? `on MAINNET, and pick the STELLAR network at the exchange — not Tron, not\nEthereum, not Solana. A withdrawal on the wrong network is not recoverable\nby us. No memo or destination tag is needed: this is your own account, not an\nexchange deposit address.`
+        : "on testnet."}
+`);
+}
 // ------------------------------------------------------------------------- main
 const HELP = `paydlux — get paid by AI agents, with a human in the loop.
 
@@ -629,6 +890,122 @@ const HELP = `paydlux — get paid by AI agents, with a human in the loop.
 
 one file holds it all: ./paydlux-vault.json (0600, never commit it)
 `;
+/**
+ * `paydlux donate` — the public donation door, on its own.
+ *
+ * This is deliberately NOT `sell --donate`. Three reasons:
+ *
+ * 1. It reads no private key. The door's whole security property is that it
+ *    cannot sign anything: it verifies an incoming payment against the public
+ *    ledger and serves content only if the ledger says we were paid. Loading the
+ *    vault file's seeds into this process would throw that property away, so
+ *    only the public address, network and token code are read here.
+ * 2. It can run on the real network while the free showcase runs on testnet.
+ *    The demo spends the seller's money and must stay play-money; the donation
+ *    door has to take real XLM. They are separate processes on separate ports
+ *    behind the same tunnel.
+ * 3. It has no gateway, no desk and no mandate, because nothing here spends the
+ *    seller's money. Fewer moving parts means less that can leak.
+ */
+async function donate() {
+    const path = arg("file") ?? VAULT_FILE_DEFAULT;
+    if (!existsSync(path))
+        bad(`no vault file at ${path}. Run: paydlux setup`);
+    const data = JSON.parse(readFileSync(path, "utf8"));
+    const network = data.network === "public" ? "public" : "testnet";
+    // Public fields only. If this file ever gains a field this code needs a seed
+    // for, that is a bug to fix here, not a reason to load the seeds.
+    const payee = typeof data.payee === "string"
+        ? data.payee
+        : data.payee?.address;
+    if (!payee)
+        bad(`the vault file has no payee address. Re-run: paydlux setup`);
+    // `vault` in the file is the account's public address (a string). Accept an
+    // object form too, but never read a seed from either.
+    const vaultAddress = typeof data.vault === "string"
+        ? data.vault
+        : data.vault?.address ?? data.vault?.publicKey;
+    if (!/^G[A-Z2-7]{55}$/.test(vaultAddress ?? "")) {
+        bad(`the vault file's address is not a valid Stellar account: ${vaultAddress}`);
+    }
+    let assetCode = data.token?.code ?? "XLM";
+    let assetIssuer = data.token?.issuer;
+    // --usdc prices this door in real Circle USDC instead of whatever the vault
+    // file says. Two things have to be true before that is safe to serve, and
+    // both are checked against the ledger rather than assumed:
+    //
+    // 1. the vault must already hold a USDC trustline. Without it every payment
+    //    bounces with OP_NO_TRUST, the donor's money comes back, and the page
+    //    still says "not paid yet" forever — a door that looks broken and is.
+    // 2. the payee the 402 terms name must hold one too. Here the payee IS the
+    //    vault, so one check covers both, but the check is written for the
+    //    account the terms actually name so it stays true if that ever changes.
+    if (flag("usdc")) {
+        if (assetCode !== "USDC")
+            log(`pricing in USDC instead of the file's ${assetCode}`);
+        assetCode = "USDC";
+        assetIssuer = USDC_ISSUER[network];
+        const h = network === "public" ? "https://horizon.stellar.org" : "https://horizon-testnet.stellar.org";
+        const acc = await fetch(`${h}/accounts/${vaultAddress}`).then((r) => r.ok ? r.json() : null).catch(() => null);
+        const line = acc?.balances?.find((b) => b.asset_type !== "native"
+            && b.asset_code === "USDC" && b.asset_issuer === assetIssuer);
+        if (!line) {
+            bad(`${vaultAddress} has no USDC trustline on ${network}, so a USDC payment would be\n`
+                + "  rejected by the ledger (OP_NO_TRUST) and the donor's money would come back.\n\n"
+                + "  add it first:\n\n"
+                + `  paydlux usdc --file ${path}\n`);
+        }
+        log(`USDC trustline confirmed on the ledger. Circle is the issuer: ${assetIssuer}`);
+    }
+    const price = arg("price") ?? data.policy?.defaultPrice ?? "1";
+    if (!(Number(price) > 0))
+        bad("--price must be a positive number");
+    const tls = flag("tls") || !process.env.PAYDLUX_NO_TLS;
+    if (tls) {
+        const problem = tunnelProblem();
+        if (problem)
+            bad("--tls cannot run here: " + problem);
+        if (!tunnelRunning())
+            runTunnel();
+    }
+    else {
+        log("running without TLS. The public door needs --tls: an order and its memo over plain HTTP can be taken by anyone on the path, who then pays for YOUR order with their vault and collects the goods.");
+    }
+    const dPort = Number(arg("port") ?? DONATE_PORT);
+    const who = await portHolder(dPort);
+    if (who) {
+        bad(`port ${dPort} (donations) is already in use by ${who}.\n`
+            + `  a donation door is already running. Stop it first, or this one answers nothing\n`
+            + `  and https://${DONATE_HOST} returns 502 with no error in this window.`);
+    }
+    // The vault address IS the payee here. Two reasons, and both matter:
+    //
+    // 1. Money lands straight in the 2-of-2. The gateway's payee account is a
+    //    plain single-key account whose seed sits in a file on this machine, and
+    //    it exists so the gateway can pay OUT without the vault signing every
+    //    time. A donation has no reason to pass through it, so it does not.
+    // 2. One address on the page. The QR, the printed address and the 402 terms
+    //    all name the same account, so a human scanning the code and an agent
+    //    following the 402 loop cannot end up paying into different places.
+    const door = startDonate({
+        port: dPort, hostname: DONATE_HOST, payee: vaultAddress, network, price,
+        asset: assetIssuer ? { code: assetCode, issuer: assetIssuer } : { code: assetCode },
+        vault: vaultAddress,
+    });
+    await door.listen(dPort);
+    const live = tls ? await tunnelLive(DONATE_HOST, 12) : false;
+    console.log(`
+  donation door is ${live ? `LIVE at https://${DONATE_HOST}` : `listening on 127.0.0.1:${dPort}`}
+  network    ${network === "public" ? "MAINNET — real money" : "testnet — play money"}
+  price      ${price} ${assetCode}
+  paid into  ${vaultAddress}   (the 2-of-2 vault itself — watch every payment land here)
+
+  this process holds no signing key. It can only serve what the ledger confirms
+  was paid for, and it cannot spend anything of yours.
+`);
+    if (tls && !live)
+        log(`https://${DONATE_HOST} is not answering yet. ${tunnelServes(DONATE_HOST) ? "Give the tunnel a few seconds." : `The tunnel does not route ${DONATE_HOST} — add it to ~/.cloudflared/config.yml pointing at 127.0.0.1:${dPort}.`}`);
+}
 export async function main() {
     const cmd = process.argv[2];
     if (!cmd || cmd === "-h" || cmd === "--help" || cmd === "help") {
@@ -639,12 +1016,16 @@ export async function main() {
         return setup();
     if (cmd === "sell")
         return sell();
+    if (cmd === "donate")
+        return donate();
     if (cmd === "status")
         return status();
     if (cmd === "approver")
         return approver();
     if (cmd === "withdraw")
         return withdraw();
+    if (cmd === "usdc")
+        return usdc();
     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.js

@@ -323,6 +323,10 @@ export class ApprovalDesk {
                 amount: rec.price,
                 tokenCode: this.cfg.vault.token.getCode(),
                 tokenIssuer: this.cfg.vault.token.getIssuer() ?? "",
+                // Stated, not inferred from the name: a token someone issued and
+                // called XLM must not be turned into native XLM on the way to the
+                // phone, because that would change what the human is approving.
+                native: this.cfg.vault.isNative,
                 network: this.cfg.vault.network,
                 horizon: this.cfg.vault.horizon,
                 id: rec.id,

package/dist/donate.d.ts

@@ -0,0 +1,48 @@
+import type { Network } from "./receive";
+export declare const DONATE_HOST = "donate.paydlux.com";
+export declare const DONATE_PORT = 4024;
+export type DonatePageConfig = {
+    price: string;
+    asset: string;
+    network: Network;
+    payee: string;
+    vault: string;
+    explorer: string;
+};
+/**
+ * The page. No inline script and nothing visitor-controlled is interpolated, so
+ * the strict CSP is real rather than decorative — the same rule the showcase
+ * follows, because this port is public.
+ */
+export declare function donatePage(cfg: DonatePageConfig): string;
+/**
+ * The browser half. It does NOT sign anything — it cannot, and that is the
+ * design. It fetches an order, prints the exact command your agent runs, and
+ * then polls until the ledger says the money landed.
+ */
+export declare function donateScript(): string;
+/**
+ * Start the donation endpoint: the seller door plus a page a human can read.
+ */
+export declare function startDonate(cfg: {
+    port: number;
+    hostname: string;
+    payee: string;
+    network: Network;
+    price: string;
+    asset: {
+        code: string;
+        issuer?: string;
+    };
+    vault: string;
+    explorer?: string;
+    /** Test seam: a stub ledger, so the routes can be driven without a network. */
+    fetchJson?: (url: string) => Promise<{
+        status: number;
+        body: any;
+    } | null>;
+}): {
+    server: import("node:http").Server<typeof import("node:http").IncomingMessage, typeof import("node:http").ServerResponse>;
+    book: import("./receive").OrderBook;
+    listen: (port: number) => Promise<void>;
+};