@paydlux/agent 0.0.0-stage → 0.1.1

package/dist/vault.js

@@ -0,0 +1,296 @@
+// Paydlux on Stellar — the vault.
+//
+// No smart contract. The whole product is three native Stellar primitives:
+//
+//   1. an issued asset            -> the payment token
+//   2. a multisig account         -> the vault (release needs 2 of the signers)
+//   3. a pre-authenticated tx     -> the spending mandate, as a hash-signer
+//
+// The mandate is the interesting one. We pre-build a transaction whose
+// operations are EXACTLY "pay N tokens to this payee, inside this time window,
+// once", take its hash, and register that hash as a weight-1 signer on the
+// vault. The agent is also weight-1, threshold is 2. So the agent can reach
+// threshold only by presenting that exact transaction. It cannot change the
+// amount, the payee, the window, or run it twice — the ledger says no.
+//
+// Verified on testnet by stellar/probe-envelope.ts before this file existed.
+import { Account, Asset, Horizon, Keypair, Memo, Networks, Operation, StrKey, Transaction, TransactionBuilder, } from "stellar-sdk";
+/**
+ * Circle's own USDC issuer on Stellar. Not a wrapped token, not a bridge:
+ * native, and Circle is the issuer. Anyone can put "USDC" on a token name —
+ * only these two accounts are real money. Never accept any other issuer.
+ */
+export const USDC_ISSUER = {
+    public: "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
+    testnet: "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
+};
+/** A rejected Stellar transaction, with the ledger's own reason code. */
+export class StellarTxError extends Error {
+    code;
+    constructor(code, cause) {
+        super(`stellar tx rejected: ${code}`);
+        this.code = code;
+        this.name = "StellarTxError";
+        this.cause = cause;
+    }
+}
+const HORIZON_URL = {
+    testnet: "https://horizon-testnet.stellar.org",
+    public: "https://horizon.stellar.org",
+};
+const PASSPHRASE = {
+    testnet: Networks.TESTNET,
+    public: Networks.PUBLIC,
+};
+const FRIENDBOT = "https://friendbot.stellar.org";
+/** The network passphrase for a network name (needed to hash transactions). */
+export function passphrase(network) { return PASSPHRASE[network]; }
+export class StellarVault {
+    horizon;
+    network;
+    address;
+    token;
+    signers;
+    constructor(address, token, signers, network) {
+        this.address = address;
+        this.token = token;
+        this.signers = signers;
+        this.network = network;
+        this.horizon = new Horizon.Server(HORIZON_URL[network]);
+    }
+    // ---------------------------------------------------------------- lifecycle
+    /** Fund a key on testnet. No captcha, no phone, no faucet hunt. */
+    static async fundTestnet(kp) {
+        const r = await fetch(`${FRIENDBOT}?addr=${encodeURIComponent(kp.publicKey())}`);
+        if (!r.ok)
+            throw new Error(`friendbot failed: ${r.status} ${await r.text()}`);
+        return kp.publicKey();
+    }
+    /**
+     * Create a vault. `issuer` signs the token; the vault account itself is a
+     * multisig whose release threshold needs principal + approver, or agent +
+     * a pre-authorised mandate hash. Nothing else reaches threshold.
+     */
+    static async create(opts) {
+        const { network, issuer, principal, approver, agent } = opts;
+        const vault = opts.vaultSeed ? Keypair.fromSecret(opts.vaultSeed) : Keypair.random();
+        const h = new Horizon.Server(HORIZON_URL[network]);
+        const pass = PASSPHRASE[network];
+        // 1. the vault account itself
+        await sub(h, pass, (await tb(h, issuer.publicKey(), undefined, pass))
+            .addOperation(Operation.createAccount({
+            destination: vault.publicKey(),
+            startingBalance: opts.startingBalance ?? "10",
+        })).setTimeout(300).build(), issuer);
+        // 2. signers + thresholds, in one atomic tx.
+        //    master weight 0: the vault's own seed can never act alone again.
+        // 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, issuer.publicKey());
+        await sub(h, pass, (await tb(h, vault.publicKey(), undefined, pass))
+            .addOperation(Operation.changeTrust({ asset: token, limit: "100000000" }))
+            .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);
+        return new StellarVault(vault.publicKey(), token, {
+            principal: principal.publicKey(), approver: approver.publicKey(), agent: agent.publicKey(),
+        }, network);
+    }
+    /**
+     * A vault that settles in real Circle USDC instead of a test token.
+     * Circle mints USDC, so there is no issuer key for us to hold: the vault
+     * just needs a trustline, and money arrives from an exchange or Circle's
+     * faucet on testnet. Everything else (mandates, thresholds, replay) is the
+     * same code.
+     */
+    static usdcToken(network) { return new Asset("USDC", USDC_ISSUER[network]); }
+    /** Add a USDC trustline to an existing vault (needs both human keys). */
+    async trustUsdc(principal, approver, limit = "1000000") {
+        return sub(this.horizon, PASSPHRASE[this.network], (await this.tb(this.address))
+            .addOperation(Operation.changeTrust({ asset: StellarVault.usdcToken(this.network), limit }))
+            .setTimeout(300).build(), principal, approver);
+    }
+    /** 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. */
+    static async load(address, tokenCode, issuer, signers, network) {
+        const h = new Horizon.Server(HORIZON_URL[network]);
+        const acc = await h.loadAccount(address);
+        const found = acc.signers ?? [];
+        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);
+    }
+    // ------------------------------------------------------------------ money
+    /** The seller must opt in to holding our token before we can pay them. */
+    async trustToken(seller, limit = "100000000", sellerKeypair) {
+        await sub(this.horizon, PASSPHRASE[this.network], (await this.tb(seller))
+            .addOperation(Operation.changeTrust({ asset: this.token, limit }))
+            .setTimeout(300).build(), sellerKeypair);
+    }
+    /** Move tokens into the vault. Only the vault's signers can move them out. */
+    async deposit(amount, from) {
+        await sub(this.horizon, PASSPHRASE[this.network], (await this.tb(from.publicKey()))
+            .addOperation(Operation.payment({ destination: this.address, asset: this.token, amount }))
+            .setTimeout(300).build(), from);
+        return this.balance();
+    }
+    /**
+     * Has this transaction already been applied? Horizon de-duplicates an
+     * identical resubmission and returns the original result, so "submit
+     * succeeded" does NOT mean "money moved just now". Sellers must check.
+     */
+    async txExists(hash) {
+        const r = await fetch(`${HORIZON_URL[this.network]}/transactions/${hash}`).catch(() => null);
+        return !!r && r.ok;
+    }
+    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());
+        return b?.balance ?? "0";
+    }
+    // --------------------------------------------------------------- mandates
+    /**
+     * Build a mandate and register it on the vault.
+     *
+     * Returns the envelope (base64 XDR) to hand to the agent plus its hash. The
+     * agent submits it with its own signature; the pre-auth signer supplies the
+     * second. The agent cannot alter it: any edit changes the hash, and the hash
+     * is the signer.
+     */
+    async createMandate(spec, principal, approver) {
+        if (spec.payee === this.address)
+            throw new Error("payee cannot be the vault");
+        if (!(Number(spec.amount) > 0))
+            throw new Error("amount must be positive");
+        const acc = await this.horizon.loadAccount(this.address);
+        const now = Math.floor(Date.now() / 1000);
+        const notBefore = now + (spec.notBefore ?? -60);
+        const expiresAt = now + (spec.ttl ?? 3600);
+        // The setOptions below takes sequence S+1, so the envelope must claim S+2.
+        const eb = (await this.tbAt(this.address, BigInt(acc.sequence) + 1n))
+            .addOperation(Operation.payment({
+            destination: spec.payee, asset: this.token, amount: spec.amount,
+        }))
+            .setTimebounds(notBefore, expiresAt);
+        if (spec.memo)
+            eb.addMemo(Memo.text(spec.memo));
+        const envelope = eb.build();
+        const hash = envelope.hash().toString("hex");
+        // register the hash as a weight-1 signer. Two signatures now exist that
+        // reach threshold 2: (agent + this hash) and (principal + approver).
+        // setOptions needs med threshold 2, so registering a mandate always takes
+        // both human keys. The agent can never write its own spending rules.
+        //
+        // A pre-auth transaction is bound to a sequence number, so exactly ONE
+        // mandate can be live: the newest. Any older one is already in the past and
+        // can never run again. We revoke the old ones in the same transaction so
+        // the state is never ambiguous — one open order at a time, on purpose.
+        const b = await this.tb(this.address);
+        for (const s of (acc.signers ?? []).filter((s) => s.key.startsWith("T") && s.weight > 0)) {
+            b.addOperation(Operation.setOptions({ signer: { preAuthTx: StrKey.decodePreAuthTx(s.key), weight: 0 } }));
+        }
+        b.addOperation(Operation.setOptions({ signer: { preAuthTx: hash, weight: 1 } }));
+        await sub(this.horizon, PASSPHRASE[this.network], b.setTimeout(expiresAt - now + 60).build(), principal, approver);
+        return { hash, envelope: envelope.toXDR(), spec, sequence: (BigInt(acc.sequence) + 2n).toString(), expiresAt };
+    }
+    /** The agent's side: sign the envelope and submit. That is all it can do. */
+    async executeMandate(mandate, agentKeypair) {
+        const tx = new Transaction(mandate.envelope, PASSPHRASE[this.network]);
+        tx.sign(agentKeypair);
+        return sub(this.horizon, PASSPHRASE[this.network], tx);
+    }
+    /**
+     * The human path: approve a payment directly. Needs principal + approver,
+     * so a stolen agent key cannot use it and a stolen phone cannot use it alone.
+     */
+    async release(payee, amount, principal, approver, memo) {
+        const b = (await this.tb(this.address))
+            .addOperation(Operation.payment({ destination: payee, asset: this.token, amount }))
+            .setTimeout(300);
+        if (memo)
+            b.addMemo(Memo.text(memo));
+        return sub(this.horizon, PASSPHRASE[this.network], b.build(), principal, approver);
+    }
+    /**
+     * Kill every outstanding mandate at once. Any accepted transaction bumps the
+     * vault's sequence, which invalidates all pre-authorized hashes pointing at a
+     * later sequence. This is the panic button: it needs principal + approver,
+     * so a stolen agent key cannot pull it and a stolen phone cannot pull it alone.
+     */
+    async revokeAll(principal, approver) {
+        const acc = await this.horizon.loadAccount(this.address);
+        const outstanding = (acc.signers ?? []).filter((s) => s.key.startsWith("T") && s.weight > 0);
+        if (!outstanding.length)
+            return null;
+        const b = await this.tb(this.address);
+        for (const s of outstanding) {
+            // Horizon returns the preauth signer as a strkey "T…" — decode it back to
+            // the raw 32-byte hash the SDK expects.
+            b.addOperation(Operation.setOptions({ signer: { preAuthTx: StrKey.decodePreAuthTx(s.key), weight: 0 } }));
+        }
+        const res = await sub(this.horizon, PASSPHRASE[this.network], b.setTimeout(300).build(), principal, approver);
+        return { revoked: outstanding.length, tx: res?.hash };
+    }
+    /** Rotate the agent key: a compromised agent is replaced, mandates die with it. */
+    async rotateAgent(oldAgent, newAgentPub, human) {
+        return sub(this.horizon, PASSPHRASE[this.network], (await this.tb(this.address))
+            .addOperation(Operation.setOptions({ signer: { ed25519PublicKey: oldAgent.publicKey(), weight: 0 } }))
+            .addOperation(Operation.setOptions({ signer: { ed25519PublicKey: newAgentPub, weight: 1 } }))
+            .setTimeout(300).build(), human, oldAgent);
+    }
+    /** Who can sign for this vault right now. */
+    async signerSummary() {
+        const acc = await this.horizon.loadAccount(this.address);
+        const t = acc.thresholds ?? {};
+        return {
+            thresholds: {
+                low: t.low_threshold ?? t.lowThreshold,
+                med: t.med_threshold ?? t.medThreshold,
+                high: t.high_threshold ?? t.highThreshold,
+            },
+            signers: (acc.signers ?? []).map((s) => ({
+                key: s.key, weight: s.weight,
+                type: s.key.startsWith("T") ? "preauth-mandate" : s.weight === 0 ? "disabled-master" : "key",
+            })),
+        };
+    }
+    // ---------------------------------------------------------------- plumbing
+    async tb(pub) {
+        return tb(this.horizon, pub, undefined, PASSPHRASE[this.network]);
+    }
+    async tbAt(pub, at) {
+        return tb(this.horizon, pub, at, PASSPHRASE[this.network]);
+    }
+}
+async function tb(h, pub, afterSeq, pass) {
+    const acc = afterSeq === undefined
+        ? await h.loadAccount(pub)
+        : new Account(pub, afterSeq.toString());
+    return new TransactionBuilder(acc, { fee: (await h.fetchBaseFee()).toString(), networkPassphrase: pass });
+}
+async function sub(h, _pass, tx, ...signers) {
+    if (signers.length)
+        tx.sign(...signers);
+    try {
+        return await h.submitTransaction(tx);
+    }
+    catch (e) {
+        // stellar-sdk throws BadResponse with the result codes attached; older
+        // shapes put them under response.data.extras. Try both, then the xdr.
+        let codes;
+        try {
+            codes = e?.resultResultCodes?.()?.results;
+        }
+        catch { /* shape differs */ }
+        codes ??= e?.response?.data?.extras?.result_codes?.results;
+        const detail = codes?.join(",") || e?.response?.data?.extras?.result_xdr || e?.message || String(e);
+        throw new StellarTxError(detail, e);
+    }
+}
+export { Keypair, Asset, Networks };

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "@paydlux/agent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "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",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "demo": "node sdk/demo.ts",
+    "demo:stellar": "tsx stellar/demo.ts",
+    "setup:stellar": "tsx stellar/onboard.ts",
+    "story:stellar": "tsx stellar/story.ts",
+    "test": "cd contracts && forge test",
+    "test:stellar": "tsx stellar/demo.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "x402",
+    "http-402",
+    "stellar",
+    "usdc",
+    "ai-agents",
+    "agent-payments",
+    "escrow",
+    "payments"
+  ],
+  "author": "Paydlux",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mesher589/paydlux.git"
+  },
+  "homepage": "https://paydlux.com",
+  "bugs": {
+    "url": "https://github.com/Mesher589/paydlux/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "stellar-sdk": "^13.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "tsx": "^4.23.15",
+    "typescript": "^7.0.2",
+    "viem": "^2.57.13",
+    "xrpl": "^5.3.0"
+  }
+}