@nickthelegend69/fund402 0.1.0

package/dist/server.js

@@ -0,0 +1,251 @@
+"use strict";
+// Fund402 SERVER side — create x402-gated HTTP endpoints that are SETTLED BY THE
+// LENDING POOL.
+//
+// A normal x402 paywall makes the *caller* pay from their own balance. Fund402's
+// twist: the agent borrows just-in-time from the Fund402 vault, the vault (the
+// liquidity pool) fronts the CEP-18 payment to YOU (the merchant), and the agent
+// repays later. To you it looks like any x402 endpoint — except your callers can
+// pay even with an empty wallet, because the pool settles on their behalf.
+//
+// This module is framework-agnostic. `paywall()` returns a tiny object you drive
+// from any HTTP handler; thin adapters for Express / Hono / Next.js live in
+// ./adapters and call straight into it.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPaymentRequirements = buildPaymentRequirements;
+exports.challengeBody = challengeBody;
+exports.decodePaymentSignature = decodePaymentSignature;
+exports.explorerTx = explorerTx;
+exports.verifyPoolSettlement = verifyPoolSettlement;
+exports.verifyWithFacilitator = verifyWithFacilitator;
+exports.paywall = paywall;
+const DEFAULT_NETWORK = "casper:casper-test";
+function isTestnet(network) {
+    return network.includes("test");
+}
+function defaultRest(network) {
+    return isTestnet(network) ? "https://api.testnet.cspr.cloud" : "https://api.cspr.cloud";
+}
+function headerGet(headers, name) {
+    const want = name.toLowerCase();
+    for (const k of Object.keys(headers)) {
+        if (k.toLowerCase() === want) {
+            const v = headers[k];
+            return Array.isArray(v) ? v[0] : v ?? undefined;
+        }
+    }
+    return undefined;
+}
+/** Build the x402 v2 `exact` PaymentRequirements for this paywall + resource. */
+function buildPaymentRequirements(cfg, resource, description) {
+    const network = cfg.network ?? DEFAULT_NETWORK;
+    return {
+        scheme: "exact",
+        network,
+        payTo: cfg.payTo,
+        amount: String(BigInt(cfg.price)),
+        asset: cfg.asset.replace(/^0x/, ""),
+        resource,
+        description: description ?? cfg.description ?? "Fund402 x402-gated resource",
+        mimeType: "application/json",
+        maxTimeoutSeconds: cfg.maxTimeoutSeconds ?? 900,
+        extra: {
+            name: cfg.asset_meta?.name ?? "Cep18x402",
+            version: cfg.asset_meta?.version ?? "1",
+            decimals: cfg.asset_meta?.decimals ?? "9",
+            symbol: cfg.asset_meta?.symbol ?? "USDC",
+        },
+    };
+}
+/** Wrap requirements in the x402 v2 `402 Payment Required` envelope. */
+function challengeBody(req) {
+    return { x402Version: 2, accepts: [req], error: "payment required" };
+}
+/** Decode a base64(JSON) x402 payment header. Returns null if malformed. */
+function decodePaymentSignature(header) {
+    try {
+        return JSON.parse(Buffer.from(header, "base64").toString("utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** cspr.live explorer URL for a deploy. */
+function explorerTx(network, deployHash) {
+    return `https://cspr.live/deploy/${deployHash}?network=${isTestnet(network) ? "casper-test" : "casper"}`;
+}
+/**
+ * Verify, on-chain via CSPR.cloud, that the Fund402 vault `borrow_and_pay` deploy
+ * actually executed and paid the required merchant + amount. THIS is the real
+ * settlement proof — the pool already moved the funds to the merchant; the gateway
+ * trusts the chain, not the caller.
+ */
+async function verifyPoolSettlement(cfg, deployHash, opts = {}) {
+    const network = cfg.network ?? DEFAULT_NETWORK;
+    const rest = cfg.csprCloudRest ?? defaultRest(network);
+    if (!cfg.csprCloudApiKey) {
+        return { valid: false, reason: "csprCloudApiKey not set — cannot verify settlement on-chain" };
+    }
+    if (!/^[0-9a-fA-F]{64}$/.test(deployHash)) {
+        return { valid: false, reason: "malformed deploy hash" };
+    }
+    // The deploy is RPC-confirmed before CSPR.cloud finishes indexing it, so a
+    // 404 / "pending" right after settlement is transient — poll a bounded window.
+    // An executed *failure* is terminal and breaks out immediately.
+    const tries = opts.tries ?? 12;
+    const intervalMs = opts.intervalMs ?? 3000;
+    let d;
+    let lastReason = "deploy not found on cspr.cloud yet";
+    for (let i = 0; i < tries; i++) {
+        try {
+            const res = await fetch(`${rest}/deploys/${deployHash}`, {
+                headers: { Authorization: cfg.csprCloudApiKey },
+            });
+            if (res.ok) {
+                const body = await res.json();
+                const cand = body?.data ?? body;
+                const st = cand?.status ?? "unknown";
+                if (cand?.error_message || /fail|error/i.test(st)) {
+                    return { valid: false, reason: `deploy failed on-chain (status=${st})`, status: st };
+                }
+                if (st === "processed") {
+                    d = cand;
+                    break;
+                }
+                lastReason = `deploy not processed yet (status=${st})`;
+            }
+            else {
+                lastReason = `cspr.cloud /deploys ${res.status}`;
+            }
+        }
+        catch (e) {
+            lastReason = `cspr.cloud fetch failed: ${e?.message}`;
+        }
+        if (i < tries - 1)
+            await new Promise((r) => setTimeout(r, intervalMs));
+    }
+    if (!d)
+        return { valid: false, reason: lastReason };
+    const status = d?.status ?? "processed";
+    const expectAmount = String(BigInt(cfg.price));
+    const expectMerchant = cfg.payTo;
+    const args = d?.args ?? {};
+    const argAmount = String(args?.amount?.parsed ?? "");
+    const argMerchant = String(args?.merchant?.parsed ?? args?.merchant?.parsed?.Account ?? "");
+    const paidAmount = !argAmount || argAmount === expectAmount;
+    const paidMerchant = !argMerchant ||
+        argMerchant.toLowerCase().includes(expectMerchant.replace(/^00/, "").toLowerCase());
+    // The vault is addressed by its PACKAGE hash; CSPR.cloud exposes that as
+    // `contract_package_hash` (NOT `contract_hash`, which is the versioned contract).
+    const vault = (cfg.vaultContract ?? "").replace(/^(hash-|contract-package-|package-)/, "");
+    const onChainPkg = String(d?.contract_package_hash ?? d?.contract_hash ?? "").toLowerCase();
+    if (vault && onChainPkg && !onChainPkg.includes(vault.toLowerCase())) {
+        return { valid: false, reason: "deploy did not target the configured vault pool", status };
+    }
+    const valid = paidAmount && paidMerchant;
+    const paymentResponseHeader = Buffer.from(JSON.stringify({ success: valid, network, deployHash, explorer: explorerTx(network, deployHash) })).toString("base64");
+    return {
+        valid,
+        status,
+        deployHash,
+        settlement: { deployHash },
+        paymentResponseHeader,
+        paidMerchant,
+        paidAmount,
+    };
+}
+/**
+ * Optional defense-in-depth: ask an x402 facilitator to verify the agent's signed
+ * `exact` authorization. Returns `{ isValid }`. Never throws — network/decode
+ * problems resolve to `{ isValid:false, reason }`.
+ */
+async function verifyWithFacilitator(facilitatorUrl, payload) {
+    try {
+        const res = await fetch(`${facilitatorUrl.replace(/\/$/, "")}/verify`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(payload),
+        });
+        const j = await res.json().catch(() => ({}));
+        return { isValid: !!(j?.isValid ?? j?.valid), reason: j?.invalidReason ?? j?.reason };
+    }
+    catch (e) {
+        return { isValid: false, reason: e?.message };
+    }
+}
+/**
+ * Create a paywall. Drive it from any framework (or use ./adapters).
+ *
+ * ```ts
+ * const pay = paywall({ payTo, asset, price: "1000000", vaultContract,
+ *                       csprCloudApiKey: process.env.CSPR_CLOUD_API_KEY });
+ * const g = await pay.guard({ url: fullUrl, headers: req.headers });
+ * if (!g.paid) return send(g.response);          // 402 challenge / error
+ * res.setHeader("payment-response", g.paymentResponseHeader); // settled — serve it
+ * ```
+ */
+function paywall(config) {
+    if (!config.payTo)
+        throw new Error("paywall: `payTo` (merchant account) is required");
+    if (!config.asset)
+        throw new Error("paywall: `asset` (CEP-18 package hash) is required");
+    const network = config.network ?? DEFAULT_NETWORK;
+    function challenge(resource, description) {
+        const req = buildPaymentRequirements(config, resource, description);
+        const body = challengeBody(req);
+        return {
+            status: 402,
+            headers: {
+                "content-type": "application/json",
+                "payment-required": Buffer.from(JSON.stringify(body)).toString("base64"),
+            },
+            body,
+        };
+    }
+    async function verify(paymentHeader) {
+        const payload = decodePaymentSignature(paymentHeader);
+        if (!payload)
+            return { valid: false, reason: "malformed payment header" };
+        const deployHash = payload?.payload?.settlement?.deployHash ?? payload?.settlement?.deployHash;
+        if (!deployHash)
+            return { valid: false, reason: "payment payload missing settlement.deployHash" };
+        const settled = await verifyPoolSettlement(config, deployHash);
+        if (!settled.valid)
+            return settled;
+        // Optional: also verify the signed authorization at the facilitator.
+        if (config.facilitatorUrl) {
+            const fac = await verifyWithFacilitator(config.facilitatorUrl, payload);
+            if (!fac.isValid) {
+                return { ...settled, valid: false, reason: `facilitator rejected signature: ${fac.reason}` };
+            }
+        }
+        return settled;
+    }
+    async function guard(req) {
+        const resource = req.url;
+        const header = headerGet(req.headers, "payment-signature") ?? headerGet(req.headers, "x-payment");
+        if (!header)
+            return { paid: false, response: challenge(resource) };
+        const result = await verify(header);
+        if (!result.valid) {
+            const malformed = result.reason?.startsWith("malformed");
+            return {
+                paid: false,
+                response: {
+                    status: malformed ? 400 : 402,
+                    headers: { "content-type": "application/json" },
+                    body: malformed
+                        ? { error: result.reason }
+                        : { ...challengeBody(buildPaymentRequirements(config, resource)), reason: result.reason },
+                },
+            };
+        }
+        return {
+            paid: true,
+            deployHash: result.deployHash,
+            settlement: result,
+            paymentResponseHeader: result.paymentResponseHeader,
+        };
+    }
+    return { config: { ...config, network }, challenge, verify, guard };
+}

package/dist/types.d.ts

@@ -0,0 +1,60 @@
+/** CAIP-2 network id, e.g. "casper:casper-test" or "casper:casper". */
+export type CasperNetwork = `casper:${string}`;
+/** x402 v2 `exact` PaymentRequirements (one entry of a 402 challenge's `accepts`). */
+export interface PaymentRequirements {
+    scheme: "exact";
+    network: string;
+    /** Merchant account, tagged: "00" + 32-byte account hash. */
+    payTo: string;
+    /** Token base units required for this call. */
+    amount: string;
+    /** CEP-18 contract **package** hash (64 hex) — the settlement asset. */
+    asset: string;
+    resource?: string;
+    description?: string;
+    mimeType?: string;
+    maxTimeoutSeconds?: number;
+    extra?: {
+        name?: string;
+        version?: string;
+        decimals?: string;
+        symbol?: string;
+    };
+}
+/** x402 v2 `402 Payment Required` body. */
+export interface PaymentRequiredBody {
+    x402Version: 2;
+    accepts: PaymentRequirements[];
+    error?: string;
+}
+/** The Fund402 settlement extension carried inside the x402 payload. */
+export interface Fund402Settlement {
+    /** The vault `borrow_and_pay` deploy hash that actually moved the funds. */
+    deployHash: string;
+    /** CEP-18 package hash that was transferred. */
+    asset?: string;
+}
+/** The decoded x402 `exact` payment payload an agent sends back (header value). */
+export interface ExactPaymentPayload {
+    x402Version: 2;
+    scheme: "exact";
+    network: string;
+    resource?: {
+        url: string;
+    };
+    accepted?: Partial<PaymentRequirements>;
+    paymentRequirements?: Partial<PaymentRequirements>;
+    payload: {
+        signature: string;
+        publicKey: string;
+        authorization: {
+            from: string;
+            to: string;
+            value: string;
+            validAfter: string;
+            validBefore: string;
+            nonce: string;
+        };
+        settlement?: Fund402Settlement;
+    };
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+"use strict";
+// Shared x402 types for the Fund402 SDK. The `exact` scheme over the casper:*
+// network family, as the CSPR.cloud x402 facilitator expects.
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@nickthelegend69/fund402",
+  "version": "0.1.0",
+  "description": "Create x402-gated HTTP endpoints settled by the Fund402 lending pool on Casper — and the agent client that pays them with just-in-time credit. Drop-in middleware for Express, Hono and Next.js.",
+  "keywords": [
+    "x402",
+    "casper",
+    "payments",
+    "402",
+    "ai-agents",
+    "micropayments",
+    "lending",
+    "cep18",
+    "stablecoin",
+    "paywall"
+  ],
+  "license": "MIT",
+  "author": "nickthelegend",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nickthelegend/fund402-sdk.git"
+  },
+  "homepage": "https://github.com/nickthelegend/fund402-casper",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
+    "./server": { "types": "./dist/server.d.ts", "default": "./dist/server.js" },
+    "./client": { "types": "./dist/client.d.ts", "default": "./dist/client.js" },
+    "./express": { "types": "./dist/adapters/express.d.ts", "default": "./dist/adapters/express.js" },
+    "./hono": { "types": "./dist/adapters/hono.d.ts", "default": "./dist/adapters/hono.js" },
+    "./next": { "types": "./dist/adapters/next.d.ts", "default": "./dist/adapters/next.js" }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "test": "npm run build && node test/server.test.mjs && node test/eip712.test.mjs",
+    "test:e2e": "npm run build && node test/e2e-live.mjs"
+  },
+  "dependencies": {
+    "@noble/hashes": "^1.4.0",
+    "casper-js-sdk": "^5.0.12"
+  },
+  "peerDependencies": {
+    "axios": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "axios": { "optional": true }
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}