@paydlux/agent 0.1.18 → 0.1.19

package/dist/vault.js

@@ -74,6 +74,57 @@ const PASSPHRASE = {
 const FRIENDBOT = "https://friendbot.stellar.org";
 /** The network passphrase for a network name (needed to hash transactions). */
 export function passphrase(network) { return PASSPHRASE[network]; }
+/**
+ * Does a Horizon balance/payment record name this exact asset?
+ *
+ * The old code hard-coded "not native" in two places, which quietly made a
+ * native-XLM vault blind to its own money: balance() reported 0 and paidToday()
+ * reported 0 spent, so the daily budget never moved no matter how much XLM left
+ * the vault. Asset identity has to be ONE comparison that handles both cases,
+ * because a budget that reads as unspent is worse than no budget at all.
+ *
+ * Exported as a pure function so the rule is testable without funding an
+ * account: this decides whether money counts against a spending mandate.
+ */
+export function assetMatches(token, rec) {
+    // stellar-base has no Native subclass: a native asset is an Asset whose
+    // getAssetType() is "native" and whose getIssuer() is undefined. Comparing
+    // constructors would silently treat XLM as a token with no issuer.
+    if (token.getAssetType() === "native") {
+        // Native XLM records carry asset_type "native" and no code/issuer at all.
+        return rec?.asset_type === "native";
+    }
+    return rec?.asset_type !== "native"
+        && rec?.asset_type !== "liquidity_pool_shares"
+        && rec?.asset_code === token.getCode()
+        && rec?.asset_issuer === token.getIssuer();
+}
+/**
+ * Turn a token name from a config file into an Asset.
+ *
+ * "XLM" is not a token. It is the ledger's own currency, and it behaves
+ * differently in one way that breaks code written for tokens: an account does
+ * not need a trustline to receive it. Passing Asset("XLM", someIssuer) would
+ * build a *fake* asset that merely happens to be called XLM — and the ledger
+ * would then demand a trustline for an asset that cannot have one, while
+ * assetMatches() would refuse to count the real XLM that actually arrived.
+ *
+ * So the name is resolved here, in one place, and every caller gets either a
+ * real native asset or a real code+issuer pair.
+ */
+export function parseToken(code, issuer) {
+    const c = (code ?? "").toUpperCase();
+    if (c === "XLM" || c === "NATIVE") {
+        if (issuer)
+            throw new Error(`XLM has no issuer. Do not pass one (got ${issuer}).`);
+        return Asset.native();
+    }
+    if (!c)
+        throw new Error("token code is empty");
+    if (!issuer)
+        throw new Error(`token ${c} needs an issuer account`);
+    return new Asset(c, issuer);
+}
 export class StellarVault {
     horizon;
     network;
@@ -123,14 +174,21 @@ export class StellarVault {
         // The trustline has to ride in this same transaction: once masterWeight is
         // 0 the vault seed cannot sign anything on its own, so a later changeTrust
         // would need two human signatures before the vault can even hold tokens.
-        const token = new Asset(opts.tokenCode, opts.tokenIssuer ?? issuer.publicKey());
-        await sub(h, pass, (await tb(h, vault.publicKey(), undefined, pass))
-            .addOperation(Operation.changeTrust({ asset: token, limit: "100000000" }))
+        //
+        // XLM gets no trustline at all. It is the ledger's own currency, so
+        // changeTrust on it is not merely unnecessary — the ledger rejects the
+        // operation, which would abort this whole transaction and leave a vault
+        // that exists but has no signers and no thresholds.
+        const token = parseToken(opts.tokenCode, opts.tokenIssuer ?? (opts.tokenCode.toUpperCase() === "XLM" ? undefined : issuer.publicKey()));
+        const setup = (await tb(h, vault.publicKey(), undefined, pass))
             .addOperation(Operation.setOptions({ signer: { ed25519PublicKey: principal.publicKey(), weight: 1 } }))
             .addOperation(Operation.setOptions({ signer: { ed25519PublicKey: approver.publicKey(), weight: 1 } }))
             .addOperation(Operation.setOptions({ signer: { ed25519PublicKey: agent.publicKey(), weight: 1 } }))
-            .addOperation(Operation.setOptions({ masterWeight: 0, lowThreshold: 2, medThreshold: 2, highThreshold: 2 }))
-            .setTimeout(300).build(), vault);
+            .addOperation(Operation.setOptions({ masterWeight: 0, lowThreshold: 2, medThreshold: 2, highThreshold: 2 }));
+        if (token.getAssetType() !== "native") {
+            setup.addOperation(Operation.changeTrust({ asset: token, limit: "100000000" }));
+        }
+        await sub(h, pass, setup.setTimeout(300).build(), vault);
         return new StellarVault(vault.publicKey(), token, {
             principal: principal.publicKey(), approver: approver.publicKey(), agent: agent.publicKey(),
         }, network);
@@ -151,7 +209,7 @@ export class StellarVault {
     }
     /** Point this vault at USDC instead of a custom token. */
     useUsdc() { this.token = StellarVault.usdcToken(this.network); return this; }
-    /** Re-attach to an existing vault by account id. */
+    /** Re-attach to an existing vault by account id. `issuer` is omitted for XLM. */
     static async load(address, tokenCode, issuer, signers, network) {
         const h = new Horizon.Server(HORIZON_URL[network]);
         const acc = await h.loadAccount(address);
@@ -159,11 +217,16 @@ export class StellarVault {
         if (!found.some((s) => s.key === signers.principal)) {
             throw new Error(`${address} is not a Paydlux vault (principal ${signers.principal} is not a signer)`);
         }
-        return new StellarVault(address, new Asset(tokenCode, issuer), signers, network);
+        return new StellarVault(address, parseToken(tokenCode, issuer), signers, network);
     }
     // ------------------------------------------------------------------ money
     /** The seller must opt in to holding our token before we can pay them. */
     async trustToken(seller, limit = "100000000", sellerKeypair) {
+        // XLM needs no trustline — every account on the ledger can already hold it.
+        // Sending changeTrust for a native asset is an outright ledger error, so
+        // this is a no-op rather than a call that would abort the transaction.
+        if (this.isNative)
+            return;
         await sub(this.horizon, PASSPHRASE[this.network], (await this.tb(seller))
             .addOperation(Operation.changeTrust({ asset: this.token, limit }))
             .setTimeout(300).build(), sellerKeypair);
@@ -184,10 +247,34 @@ export class StellarVault {
         const r = await fetch(`${HORIZON_URL[this.network]}/transactions/${hash}`).catch(() => null);
         return !!r && r.ok;
     }
+    /**
+     * Does a Horizon balance/payment record name *this* vault's token?
+     *
+     * The old code hard-coded "not native" in two places, which quietly made a
+     * native-XLM vault blind to its own money: balance() reported 0 and
+     * paidToday() reported 0 spent, so the daily budget never moved no matter how
+     * much XLM left the vault. Asset identity has to be one comparison that
+     * handles both cases, because a budget that reads as unspent is worse than no
+     * budget at all.
+     */
+    isOurAsset(rec) {
+        if (this.isNative) {
+            // Native XLM records carry asset_type "native" and no code/issuer at all.
+            return rec.asset_type === "native";
+        }
+        return rec.asset_type !== "native"
+            && rec.asset_type !== "liquidity_pool_shares"
+            && rec.asset_code === this.token.getCode()
+            && rec.asset_issuer === this.token.getIssuer();
+    }
+    /** True when this vault settles in XLM itself rather than a token. */
+    // stellar-base has no Native subclass: a native asset is an Asset whose
+    // getAssetType() is "native" and whose getIssuer() is undefined. Comparing
+    // constructors would silently treat XLM as a token with no issuer.
+    get isNative() { return this.token.getAssetType() === "native"; }
     async balance(account = this.address) {
         const acc = await this.horizon.loadAccount(account);
-        const b = acc.balances.find((x) => x.asset_type !== "native" && x.asset_type !== "liquidity_pool_shares"
-            && x.asset_code === this.token.getCode() && x.asset_issuer === this.token.getIssuer());
+        const b = acc.balances.find((x) => this.isOurAsset(x));
         return b?.balance ?? "0";
     }
     // --------------------------------------------------------------- mandates
@@ -203,6 +290,16 @@ export class StellarVault {
      * query away, and it survives restarts, crashes and redeploys.
      */
     async paidToday(payee) {
+        // A payee that is not an address string compares unequal to every `to`
+        // field on the ledger, so the walk finds nothing and reports 0 spent — a
+        // budget that reads as unspent, which is the exact failure this query
+        // exists to prevent. Fail loudly instead.
+        if (typeof payee !== "string" || !/^G[A-Z2-7]{55}$/.test(payee)) {
+            throw new Error(`paidToday needs a payee account id (G…56 chars), got `
+                + (payee && typeof payee === "object"
+                    ? `an object — pass payee.address, not the payee record`
+                    : JSON.stringify(payee)));
+        }
         const start = new Date();
         start.setUTCHours(0, 0, 0, 0);
         let total = 0;
@@ -226,9 +323,9 @@ export class StellarVault {
                     continue;
                 if (e.to !== payee)
                     continue;
-                if (e.asset_type === "native")
-                    continue;
-                if (e.asset_code !== this.token.getCode() || e.asset_issuer !== this.token.getIssuer())
+                // Native XLM counts too. Skipping it here is how an XLM vault would pay
+                // its whole daily budget and still be told it had the full budget left.
+                if (!this.isOurAsset(e))
                     continue;
                 total += Number(e.amount);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paydlux/agent",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "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",
@@ -49,7 +49,21 @@
     "test:seed": "DEVELOPER_DIR=/Library/Developer/CommandLineTools /usr/bin/swiftc -target arm64-apple-macosx14.0 ios/PaydluxApprover/Seed.swift ios/PaydluxApprover/Hex.swift ios/Checks/main.swift -o \"$TMPDIR/seedcheck\" && \"$TMPDIR/seedcheck\"",
     "typecheck": "tsc --noEmit",
     "app": "tsx stellar/cli.ts",
-    "app:mainnet": "tsx stellar/cli.ts setup --mainnet"
+    "app:mainnet": "tsx stellar/cli.ts setup --mainnet --file paydlux-mainnet.json --token XLM --max 2 --daily 20",
+    "fund:check": "tsx stellar/check-address.ts GARPB3CO3JMMED3ETFRSSZXCH2X7UTXW4FNUP3Z7HDMBKAC2H355W4SA",
+    "test:showcase": "tsx stellar/showcase-check.ts",
+    "test:native": "tsx stellar/native-check.ts",
+    "test:receive": "tsx stellar/receive-check.ts",
+    "test:xlm": "tsx stellar/xlm-check.ts",
+    "test:donate": "tsx stellar/donate-check.ts",
+    "donate:live": "tsx stellar/donate-live.ts",
+    "app:mainnet:sell": "tsx stellar/cli.ts sell --file paydlux-mainnet.json --split --tls --price 1 --route /market/data --max 2 --daily 20",
+    "app:testnet:sell": "tsx stellar/cli.ts sell --split --tls --showcase --price 1 --route /market/data --max 10 --daily 50",
+    "app:donate": "tsx stellar/cli.ts donate --file paydlux-mainnet.json --tls --price 1",
+    "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"
   },
   "keywords": [
     "x402",
@@ -75,10 +89,12 @@
     "access": "public"
   },
   "dependencies": {
-    "@stellar/stellar-sdk": "^17.4.0"
+    "@stellar/stellar-sdk": "^17.4.0",
+    "qrcode-generator": "^2.0.4"
   },
   "devDependencies": {
     "@types/node": "^26.6.6",
+    "jsqr": "^1.4.0",
     "tsx": "^4.23.15",
     "typescript": "^7.0.2",
     "viem": "^2.57.13",

package/phone-app/app.js

@@ -289,7 +289,7 @@ function row(rec) {
     const btns = document.createElement("div");
     btns.className = "btns";
     const yes = document.createElement("button");
-    yes.textContent = "Review";
+    yes.textContent = "Review & approve";
     yes.addEventListener("click", () => openReview(rec.id));
     const no = document.createElement("button");
     no.className = "danger";
@@ -297,6 +297,13 @@ function row(rec) {
     no.addEventListener("click", () => reject(rec.id));
     btns.append(yes, no);
     foot.append(btns);
+    // Say what the next screen asks for. Approving is a deliberate hold, not a
+    // tap, and a person who expects a button on this row concludes the page is
+    // broken and gives up before ever seeing the hold control.
+    const how = document.createElement("div");
+    how.className = "howto";
+    how.textContent = `Approving takes a ${holdSeconds()}-second hold on the next screen. Reject is one tap.`;
+    wrap.append(how);
   }
 
   wrap.append(top, uri, wants, foot);
@@ -446,6 +453,10 @@ function backToQueue() {
 // is one tap and Approve needs a deliberate hold. This is what stops a pocket
 // tap, a mis-tap, and the person who taps Approve and only then starts reading.
 const HOLD_MS = 1200;
+// The queue row quotes this number, so it is stated once and read from the
+// constant. Copy that says "one second" over a 1.2s gesture teaches the wrong
+// gesture and reads as broken the first time it does not fire.
+const holdSeconds = () => (HOLD_MS / 1000).toFixed(1).replace(/\.0$/, "");
 let holdStart = 0, holdTimer = null;
 
 function resetHold() {

package/phone-app/index.html

@@ -129,6 +129,7 @@
   .item .foot { display:flex; justify-content:space-between; align-items:center; gap:10px; margin-top:12px }
   .item .ago { font-size:11.5px; color:var(--dim) }
   .item .btns { display:flex; gap:8px }
+  .item .howto { flex-basis:100%; font-size:12.5px; color:var(--dim); margin-top:2px }
   .item .btns button { width:auto; margin:0; min-height:44px; padding:11px 18px; font-size:15px }
   .empty { color:var(--dim); font-size:15px; padding:18px 2px; text-align:center }
   .hist { opacity:.6 }