@nickthelegend69/fund402 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nickthelegend
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,192 @@
+# @nickthelegend69/fund402
+
+**Create x402-gated HTTP endpoints that are settled by a lending pool — on Casper.**
+
+A normal [x402](https://x402.org) paywall makes the *caller* pay from their own
+balance. Fund402 adds one twist that changes everything for AI agents:
+
+> the caller borrows **just-in-time** from the Fund402 vault, the **lending 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. One SDK, both sides:
+
+| | |
+|---|---|
+| 🟢 **Server (merchant)** | `paywall()` + drop-in middleware for **Express / Hono / Next.js** — issue the 402 challenge, verify the pool settled on-chain, serve the resource. |
+| 🔵 **Client (agent)** | `fund402Fetch()` — a drop-in `fetch` that pays any Fund402 endpoint with JIT pool credit and replays the request. |
+
+Casper-native: CEP-18 token + EIP-712 `exact` scheme over the `casper:*` network
+family, verified against the live **CSPR.cloud x402 facilitator** and the deployed
+**Fund402 vault** on testnet.
+
+```
+   ┌────────────┐  1. GET (no payment)         ┌─────────────────────┐
+   │            │ ───────────────────────────▶ │   your API           │
+   │   agent    │  2. 402 + x402 challenge      │   paywall(...)       │
+   │ fund402-   │ ◀─────────────────────────── │   (Express/Hono/Next)│
+   │   Fetch    │                               └─────────┬───────────┘
+   │            │  3. borrow_and_pay  ┌─────────────────┐ │ 5. verify settlement
+   │            │ ──────────────────▶ │  Fund402 vault  │ │    on-chain (CSPR.cloud)
+   │            │     (pool fronts $) │  (lending pool) │◀┘
+   │            │  4. retry + payment-signature           ▲
+   │            │ ───────────────────────────▶ pays merchant from pool
+   └────────────┘  6. 200 + resource
+```
+
+## Install
+
+```bash
+npm i @nickthelegend69/fund402
+# the agent/client side also needs a Casper key; axios is optional (fetch is built in)
+```
+
+---
+
+## Server — create an endpoint settled by the pool
+
+### Express
+
+```ts
+import express from "express";
+import { expressPaywall } from "@nickthelegend69/fund402/express";
+
+const app = express();
+
+app.use("/v", expressPaywall({
+  payTo: "00" + MERCHANT_ACCOUNT_HASH,   // who gets paid (tagged account hash)
+  asset: CEP18_PACKAGE_HASH,             // the CEP-18 settlement token
+  price: "1000000",                      // base units per call (0.001 @ 9 decimals)
+  vaultContract: VAULT_PACKAGE_HASH,     // the lending pool that settles
+  csprCloudApiKey: process.env.CSPR_CLOUD_API_KEY,
+}));
+
+app.get("/v/price/:pair", (req, res) => {
+  // only runs once the pool settled on-chain; proof is on req.fund402
+  res.json({ pair: req.params.pair, price: 64250.12, settledBy: req.fund402.deployHash });
+});
+
+app.listen(3000);
+```
+
+### Next.js (App Router)
+
+```ts
+// app/api/v/[...path]/route.ts
+import { withPaywall } from "@nickthelegend69/fund402/next";
+
+export const GET = withPaywall(
+  { payTo, asset, price: "1000000", vaultContract, csprCloudApiKey: process.env.CSPR_CLOUD_API_KEY },
+  async () => Response.json({ data: "the protected resource" })
+);
+```
+
+### Hono (Node, Bun, Workers, Deno)
+
+```ts
+import { Hono } from "hono";
+import { honoPaywall } from "@nickthelegend69/fund402/hono";
+
+const app = new Hono();
+app.use("/v/*", honoPaywall({ payTo, asset, price: "1000000", vaultContract, csprCloudApiKey }));
+app.get("/v/price", (c) => c.json({ price: 64250.12 }));
+```
+
+### Any framework
+
+```ts
+import { paywall } from "@nickthelegend69/fund402";
+
+const pay = paywall({ payTo, asset, price: "1000000", vaultContract, csprCloudApiKey });
+
+const g = await pay.guard({ method: req.method, url: fullUrl, headers: req.headers });
+if (!g.paid) return send(g.response);                 // 402 challenge / 400 / error
+res.setHeader("payment-response", g.paymentResponseHeader);
+return serveTheResource();                            // g.settlement has the on-chain proof
+```
+
+---
+
+## Client — pay an endpoint with JIT pool credit
+
+```ts
+import { fund402Fetch } from "@nickthelegend69/fund402";
+
+const f = fund402Fetch({
+  agentSecretKey,        // PEM or hex
+  agentPublicKey,        // 01.. / 02.. account-key hex
+  vaultContract: VAULT_PACKAGE_HASH,
+  network: "casper:casper-test",
+  onEvent: (e) => console.log(e.type, e.data),   // intercepted_402 → borrowing → … → payment_confirmed
+});
+
+// transparent: on 402, it borrows from the pool, settles on-chain, retries.
+const res = await f("https://merchant.example/v/price/BTC-USD");
+const data = await res.json();   // paid + served — the agent's own balance can be zero
+```
+
+Prefer Axios? `withPaymentInterceptor(config)` returns an `AxiosInstance` with the
+same behaviour (Axios is an optional peer dependency).
+
+---
+
+## How settlement works (and why you can trust it)
+
+1. The agent calls the vault's `borrow_and_pay(merchant, amount, collateral, vault_id)`.
+   The **pool transfers `amount` CEP-18 to the merchant** and books a loan.
+2. The agent attaches the resulting **deploy hash** to a signed x402 `exact` payload
+   and replays the request.
+3. The server calls `verifyPoolSettlement()` — it reads the deploy from **CSPR.cloud**
+   and confirms it `processed`, paid the right **merchant + amount**, and targeted
+   the configured **vault package**. The gateway trusts the chain, not the caller.
+4. Optionally also POSTs the signed authorization to an x402 **facilitator** `/verify`
+   (set `facilitatorUrl`) for defense-in-depth.
+
+`verifyPoolSettlement` is resilient to indexer lag — it polls a bounded window while
+the deploy is still propagating, and fails fast on an executed on-chain failure.
+
+## Live deployment (casper-test)
+
+| | |
+|---|---|
+| Vault (lending pool) package | `664d99de146b9b573161a387d89fefc649677351d8a6d2acbe22109bf88f6b12` |
+| CEP-18 asset (Fund402 USDC / F402) | `389cedc529cc553e2639884c9dcc5e6dcbeb3920f7f5ca5a39bf7f7b866bccd0` |
+| Network | `casper:casper-test` |
+| Facilitator | `https://x402-facilitator.cspr.cloud` |
+
+These are the defaults the SDK ships with — point `vaultContract` / `asset` at your
+own deployment for production.
+
+## Verified live ✅
+
+`npm run test:e2e` stands up a real HTTP server with `paywall()`, points a
+`fund402Fetch()` agent at it, and runs the **whole loop on casper-test**: the agent
+hits the endpoint → gets a 402 → borrows from the pool (the vault fronts the F402 to
+the merchant) → retries → the server verifies the settlement on-chain via CSPR.cloud
+→ serves the resource.
+
+Last live run — agent `01baa8d8…` (Tier-3, **zero collateral**) borrowed `1000000`
+F402; the pool fronted it to the merchant and the server served the resource after
+verifying it on-chain:
+**[settlement deploy `96f30ddf…` ↗](https://testnet.cspr.live/deploy/96f30ddfac9b3b8bc04a9fe274b1c006aff398ac624e7360669a2c1f3dc28264)** (`status: processed`).
+
+## API
+
+**Server:** `paywall(cfg)` → `{ challenge, verify, guard }` · `buildPaymentRequirements`
+· `challengeBody` · `decodePaymentSignature` · `verifyPoolSettlement` ·
+`verifyWithFacilitator` · `explorerTx` · adapters `expressPaywall` / `honoPaywall` /
+`withPaywall` (Next).
+
+**Client:** `fund402Fetch(cfg)` · `withPaymentInterceptor(cfg)` (Axios) · `payViaPool`
+· `decodeChallenge` · `selectCasperOption` · `testnetClient` / `mainnetClient`.
+
+**On-chain primitives:** `borrowAndPayOnChain` · `repayLoanOnChain` ·
+`ensureCollateralAllowance` · `buildExactPayload` · `waitForDeploy` ·
+`agentTaggedAddress` · `transferAuthorizationDigest`.
+
+## ⚠️ Security
+
+The client side signs real deploys with a local key — **testnet only**, never reuse
+keys on mainnet. Keep keys out of source control. MIT licensed.
+
+Part of [Fund402](https://github.com/nickthelegend/fund402-casper) — JIT credit for AI agents on Casper.

package/dist/adapters/express.d.ts

@@ -0,0 +1,2 @@
+import { type PaywallConfig, type Fund402Paywall } from "../server";
+export declare function expressPaywall(config: PaywallConfig | Fund402Paywall): (req: any, res: any, next: any) => Promise<any>;

package/dist/adapters/express.js

@@ -0,0 +1,32 @@
+"use strict";
+// Express adapter. `app.use("/v", expressPaywall({...}))` gates everything under
+// it: unpaid requests get the 402 x402 challenge; settled ones fall through to
+// your handler with `req.fund402` set to the on-chain settlement proof.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expressPaywall = expressPaywall;
+const server_1 = require("../server");
+function fullUrl(req) {
+    const proto = req.headers["x-forwarded-proto"] || req.protocol || "http";
+    const host = req.headers["x-forwarded-host"] || req.headers["host"] || "localhost";
+    return `${proto}://${host}${req.originalUrl ?? req.url ?? ""}`;
+}
+function expressPaywall(config) {
+    const pay = "guard" in config ? config : (0, server_1.paywall)(config);
+    return async function fund402Middleware(req, res, next) {
+        try {
+            const g = await pay.guard({ method: req.method, url: fullUrl(req), headers: req.headers });
+            if (g.paid) {
+                res.setHeader("payment-response", g.paymentResponseHeader);
+                req.fund402 = g.settlement;
+                return next();
+            }
+            const r = g.response;
+            for (const [k, v] of Object.entries(r.headers))
+                res.setHeader(k, v);
+            return res.status(r.status).json(r.body);
+        }
+        catch (e) {
+            return res.status(500).json({ error: `fund402 paywall error: ${e?.message ?? e}` });
+        }
+    };
+}

package/dist/adapters/hono.d.ts

@@ -0,0 +1,2 @@
+import { type PaywallConfig, type Fund402Paywall } from "../server";
+export declare function honoPaywall(config: PaywallConfig | Fund402Paywall): (c: any, next: any) => Promise<any>;

package/dist/adapters/hono.js

@@ -0,0 +1,21 @@
+"use strict";
+// Hono adapter. `app.use("/v/*", honoPaywall({...}))`. Works on any Hono runtime
+// (Node, Bun, Workers, Deno). Settled requests expose the proof via `c.get("fund402")`.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.honoPaywall = honoPaywall;
+const server_1 = require("../server");
+function honoPaywall(config) {
+    const pay = "guard" in config ? config : (0, server_1.paywall)(config);
+    return async function fund402Middleware(c, next) {
+        const headers = {};
+        c.req.raw.headers.forEach((v, k) => (headers[k] = v));
+        const g = await pay.guard({ method: c.req.method, url: c.req.url, headers });
+        if (g.paid) {
+            c.header("payment-response", g.paymentResponseHeader);
+            c.set("fund402", g.settlement);
+            return next();
+        }
+        const r = g.response;
+        return c.json(r.body, r.status, r.headers);
+    };
+}

package/dist/adapters/next.d.ts

@@ -0,0 +1,4 @@
+import { type PaywallConfig, type Fund402Paywall } from "../server";
+type NextHandler = (req: any, ctx?: any) => Response | Promise<Response>;
+export declare function withPaywall(config: PaywallConfig | Fund402Paywall, handler: NextHandler): NextHandler;
+export {};

package/dist/adapters/next.js

@@ -0,0 +1,37 @@
+"use strict";
+// Next.js App Router adapter. Wrap a route handler so it only runs once payment
+// has settled on-chain; otherwise the wrapper returns the 402 x402 challenge.
+//
+//   // app/api/v/[...path]/route.ts
+//   import { withPaywall } from "@nickthelegend69/fund402/next";
+//   export const GET = withPaywall(
+//     { payTo, asset, price: "1000000", vaultContract, csprCloudApiKey: process.env.CSPR_CLOUD_API_KEY },
+//     async (req) => Response.json({ data: "the protected resource" })
+//   );
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withPaywall = withPaywall;
+const server_1 = require("../server");
+function withPaywall(config, handler) {
+    const pay = "guard" in config ? config : (0, server_1.paywall)(config);
+    return async function fund402Route(req, ctx) {
+        const url = req?.nextUrl?.href ?? req?.url ?? "";
+        const headers = {};
+        if (req?.headers?.forEach)
+            req.headers.forEach((v, k) => (headers[k] = v));
+        const g = await pay.guard({ method: req?.method, url, headers });
+        if (!g.paid) {
+            return new Response(JSON.stringify(g.response.body), {
+                status: g.response.status,
+                headers: g.response.headers,
+            });
+        }
+        const out = await handler(req, ctx);
+        try {
+            out.headers.set("payment-response", g.paymentResponseHeader);
+        }
+        catch {
+            /* immutable response headers — best effort */
+        }
+        return out;
+    };
+}

package/dist/casper.d.ts

@@ -0,0 +1,116 @@
+import { RpcClient, PrivateKey, KeyAlgorithm } from "casper-js-sdk";
+import type { PaymentRequirements } from "./types";
+export interface CasperWiringConfig {
+    nodeUrl: string;
+    network: string;
+    chainName: string;
+    vaultContractHash: string;
+    agentSecretKey: string;
+    agentPublicKey: string;
+    keyAlgorithm?: KeyAlgorithm;
+    /** payment (gas) in motes for a borrow_and_pay call. Default 5 CSPR. */
+    borrowGasMotes?: string;
+}
+export declare function rpc(nodeUrl: string): RpcClient;
+export declare function loadPrivateKey(secret: string, algo?: KeyAlgorithm): Promise<PrivateKey>;
+/**
+ * Call the vault's `borrow_and_pay(merchant, amount, collateral, vault_id)`.
+ * The vault pulls the agent's CEP-18 collateral into escrow (transfer_from) and
+ * fronts the CEP-18 `amount` to the merchant from the liquidity pool. Returns the
+ * settlement deploy hash. (Tier-3 agents borrow with zero collateral; lower tiers
+ * must `approve` the vault for >= collateral first — see ensureCollateralAllowance.)
+ */
+export declare function borrowAndPayOnChain(cfg: CasperWiringConfig, args: {
+    merchant: string;
+    amount: bigint;
+    collateral: bigint;
+    vaultId: string;
+}): Promise<{
+    deployHash: string;
+}>;
+/** Repay a loan: vault pulls principal back from the agent (CEP-18 allowance required). */
+export declare function repayLoanOnChain(cfg: CasperWiringConfig, loanId: number): Promise<{
+    deployHash: string;
+}>;
+/**
+ * Approve the vault to pull `amount` of the CEP-18 asset from the agent (needed
+ * before a collateralized borrow_and_pay can escrow, and before repay_loan can
+ * pull the principal). One-time per allowance top-up.
+ */
+export declare function ensureCollateralAllowance(cfg: CasperWiringConfig & {
+    assetPackageHash: string;
+}, spender: {
+    vaultContractHash: string;
+}, amount: bigint): Promise<{
+    deployHash: string;
+}>;
+/**
+ * Poll the node until a deploy executes; resolves true on success. Mirrors the
+ * pattern proven live in production: stringify the whole getDeploy response (the
+ * v5 SDK shape varies across Casper 1.x / 2.0 Condor), treat a non-null
+ * errorMessage / "Failure" tag as failure, and "cost"/"Success" as success.
+ */
+export declare function waitForDeploy(cfg: Pick<CasperWiringConfig, "nodeUrl">, deployHash: string, { tries, intervalMs }?: {
+    tries?: number;
+    intervalMs?: number;
+}): Promise<boolean>;
+/** Casper account-hash ("00" + 32-byte hash) for the agent's public key. */
+export declare function agentTaggedAddress(agentPublicKey: string): string;
+/**
+ * Build the real x402 v2 `exact` PaymentPayload for the casper:* family. The
+ * `authorization` + 65-byte EIP-712 `signature` verify against the CSPR.cloud
+ * facilitator's POST /verify. We attach the Fund402 `settlement.deployHash`
+ * extension — the on-chain vault borrow_and_pay deploy the gateway checks.
+ */
+export declare function buildExactPayload(cfg: CasperWiringConfig, req: Partial<PaymentRequirements> & {
+    payTo: string;
+}, proof: {
+    deployHash: string;
+}): Promise<{
+    x402Version: 2;
+    resource: {
+        url: string;
+    } | undefined;
+    accepted: {
+        scheme: "exact";
+        network: string;
+        asset: string;
+        payTo: string;
+        amount: string;
+        maxTimeoutSeconds: number;
+        extra: {
+            name: string;
+            version: string;
+        };
+    };
+    scheme: "exact";
+    network: string;
+    payload: {
+        signature: string;
+        publicKey: string;
+        authorization: {
+            from: string;
+            to: string;
+            value: string;
+            validAfter: string;
+            validBefore: string;
+            nonce: string;
+        };
+        settlement: {
+            deployHash: string;
+            asset: string;
+        };
+    };
+    paymentRequirements: {
+        scheme: "exact";
+        network: string;
+        asset: string;
+        payTo: string;
+        amount: string;
+        maxTimeoutSeconds: number;
+        extra: {
+            name: string;
+            version: string;
+        };
+    };
+}>;

package/dist/casper.js

@@ -0,0 +1,212 @@
+"use strict";
+// Real Casper wiring (casper-js-sdk@5.x / Casper 2.0 Condor). Turns the abstract
+// "borrow + settle" steps into actual on-chain calls against the Fund402 Vault,
+// and builds the x402 `exact` PaymentPayload the facilitator's POST /verify checks.
+//
+// The payload is signed off the proven `eip712.ts` digest + `signAndAddAlgorithmBytes`
+// (65-byte [algorithm|sig]) — byte-identical to the official @make-software/casper-x402
+// client, but WITHOUT depending on its broken CJS build at runtime.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rpc = rpc;
+exports.loadPrivateKey = loadPrivateKey;
+exports.borrowAndPayOnChain = borrowAndPayOnChain;
+exports.repayLoanOnChain = repayLoanOnChain;
+exports.ensureCollateralAllowance = ensureCollateralAllowance;
+exports.waitForDeploy = waitForDeploy;
+exports.agentTaggedAddress = agentTaggedAddress;
+exports.buildExactPayload = buildExactPayload;
+const casper_js_sdk_1 = require("casper-js-sdk");
+const eip712_1 = require("./eip712");
+function rpc(nodeUrl) {
+    return new casper_js_sdk_1.RpcClient(new casper_js_sdk_1.HttpHandler(nodeUrl));
+}
+async function loadPrivateKey(secret, algo = casper_js_sdk_1.KeyAlgorithm.ED25519) {
+    const trimmed = secret.trim();
+    if (trimmed.includes("BEGIN") && trimmed.includes("PRIVATE KEY")) {
+        return casper_js_sdk_1.PrivateKey.fromPem(trimmed, algo);
+    }
+    return casper_js_sdk_1.PrivateKey.fromHex(trimmed, algo);
+}
+const stripPkg = (s) => s.replace(/^(hash-|contract-package-|package-)/, "");
+/**
+ * Build a CLKey arg from an account address. Accepts a raw 64-hex account hash,
+ * an "account-hash-…" formatted string, OR an x402 *tagged* address ("00" + 64-hex,
+ * the Account tag) as carried in a payment challenge's `payTo` — the 1-byte tag is
+ * stripped so the on-chain Key uses the bare 32-byte account hash.
+ */
+function addressKey(addr) {
+    let h = addr.replace(/^account-hash-/, "");
+    if (/^00[0-9a-fA-F]{64}$/.test(h))
+        h = h.slice(2); // drop the "00" account tag
+    return casper_js_sdk_1.CLValue.newCLKey(casper_js_sdk_1.Key.newKey(`account-hash-${h}`));
+}
+/** Build a CLKey arg for a contract/package ("hash-<package>"). */
+function pkgKey(pkgHash) {
+    return casper_js_sdk_1.CLValue.newCLKey(casper_js_sdk_1.Key.newKey("hash-" + stripPkg(pkgHash)));
+}
+/**
+ * Session item calling a stored contract BY PACKAGE HASH (StoredVersionedContractByHash,
+ * latest version). This is the path proven live on testnet — the deployed Fund402
+ * vault + CEP-18 are addressed by their package hash (what cspr.live shows).
+ */
+function callPkg(pkgHash, entryPoint, args) {
+    const s = new casper_js_sdk_1.ExecutableDeployItem();
+    s.storedVersionedContractByHash = new casper_js_sdk_1.StoredVersionedContractByHash(casper_js_sdk_1.ContractHash.newContract(stripPkg(pkgHash)), entryPoint, args, undefined);
+    return s;
+}
+/**
+ * Call the vault's `borrow_and_pay(merchant, amount, collateral, vault_id)`.
+ * The vault pulls the agent's CEP-18 collateral into escrow (transfer_from) and
+ * fronts the CEP-18 `amount` to the merchant from the liquidity pool. Returns the
+ * settlement deploy hash. (Tier-3 agents borrow with zero collateral; lower tiers
+ * must `approve` the vault for >= collateral first — see ensureCollateralAllowance.)
+ */
+async function borrowAndPayOnChain(cfg, args) {
+    const client = rpc(cfg.nodeUrl);
+    const algo = cfg.keyAlgorithm ?? casper_js_sdk_1.KeyAlgorithm.ED25519;
+    const signer = await loadPrivateKey(cfg.agentSecretKey, algo);
+    const sender = casper_js_sdk_1.PublicKey.fromHex(cfg.agentPublicKey);
+    const runtimeArgs = casper_js_sdk_1.Args.fromMap({
+        merchant: addressKey(args.merchant),
+        amount: casper_js_sdk_1.CLValue.newCLUInt256(args.amount.toString()),
+        collateral: casper_js_sdk_1.CLValue.newCLUInt256(args.collateral.toString()),
+        vault_id: casper_js_sdk_1.CLValue.newCLString(args.vaultId),
+    });
+    const header = casper_js_sdk_1.DeployHeader.default();
+    header.account = sender;
+    header.chainName = cfg.chainName;
+    header.ttl = new casper_js_sdk_1.Duration(casper_js_sdk_1.DEFAULT_DEPLOY_TTL);
+    const session = callPkg(cfg.vaultContractHash, "borrow_and_pay", runtimeArgs);
+    const payment = casper_js_sdk_1.ExecutableDeployItem.standardPayment(cfg.borrowGasMotes ?? "5000000000");
+    const deploy = casper_js_sdk_1.Deploy.makeDeploy(header, payment, session);
+    deploy.sign(signer);
+    const result = await client.putDeploy(deploy);
+    return { deployHash: result.deployHash.toHex() };
+}
+/** Repay a loan: vault pulls principal back from the agent (CEP-18 allowance required). */
+async function repayLoanOnChain(cfg, loanId) {
+    const client = rpc(cfg.nodeUrl);
+    const algo = cfg.keyAlgorithm ?? casper_js_sdk_1.KeyAlgorithm.ED25519;
+    const signer = await loadPrivateKey(cfg.agentSecretKey, algo);
+    const sender = casper_js_sdk_1.PublicKey.fromHex(cfg.agentPublicKey);
+    const header = casper_js_sdk_1.DeployHeader.default();
+    header.account = sender;
+    header.chainName = cfg.chainName;
+    header.ttl = new casper_js_sdk_1.Duration(casper_js_sdk_1.DEFAULT_DEPLOY_TTL);
+    const session = callPkg(cfg.vaultContractHash, "repay_loan", casper_js_sdk_1.Args.fromMap({ loan_id: casper_js_sdk_1.CLValue.newCLUint64(BigInt(loanId)) }));
+    const payment = casper_js_sdk_1.ExecutableDeployItem.standardPayment("3000000000");
+    const deploy = casper_js_sdk_1.Deploy.makeDeploy(header, payment, session);
+    deploy.sign(signer);
+    const result = await client.putDeploy(deploy);
+    return { deployHash: result.deployHash.toHex() };
+}
+/**
+ * Approve the vault to pull `amount` of the CEP-18 asset from the agent (needed
+ * before a collateralized borrow_and_pay can escrow, and before repay_loan can
+ * pull the principal). One-time per allowance top-up.
+ */
+async function ensureCollateralAllowance(cfg, spender, amount) {
+    const client = rpc(cfg.nodeUrl);
+    const algo = cfg.keyAlgorithm ?? casper_js_sdk_1.KeyAlgorithm.ED25519;
+    const signer = await loadPrivateKey(cfg.agentSecretKey, algo);
+    const sender = casper_js_sdk_1.PublicKey.fromHex(cfg.agentPublicKey);
+    const header = casper_js_sdk_1.DeployHeader.default();
+    header.account = sender;
+    header.chainName = cfg.chainName;
+    header.ttl = new casper_js_sdk_1.Duration(casper_js_sdk_1.DEFAULT_DEPLOY_TTL);
+    const session = callPkg(cfg.assetPackageHash, "approve", casper_js_sdk_1.Args.fromMap({
+        spender: pkgKey(spender.vaultContractHash),
+        amount: casper_js_sdk_1.CLValue.newCLUInt256(amount.toString()),
+    }));
+    const payment = casper_js_sdk_1.ExecutableDeployItem.standardPayment("2000000000");
+    const deploy = casper_js_sdk_1.Deploy.makeDeploy(header, payment, session);
+    deploy.sign(signer);
+    const result = await client.putDeploy(deploy);
+    return { deployHash: result.deployHash.toHex() };
+}
+/**
+ * Poll the node until a deploy executes; resolves true on success. Mirrors the
+ * pattern proven live in production: stringify the whole getDeploy response (the
+ * v5 SDK shape varies across Casper 1.x / 2.0 Condor), treat a non-null
+ * errorMessage / "Failure" tag as failure, and "cost"/"Success" as success.
+ */
+async function waitForDeploy(cfg, deployHash, { tries = 60, intervalMs = 3000 } = {}) {
+    const client = rpc(cfg.nodeUrl);
+    for (let i = 0; i < tries; i++) {
+        try {
+            const res = await client.getDeploy(deployHash);
+            const txt = JSON.stringify(res?.executionResults ?? res?.executionInfo ?? res ?? {});
+            if (txt.includes('"Failure"') || /"error_?[Mm]essage":\s*"[^"]/.test(txt))
+                return false;
+            if (txt.includes('"Success"') || txt.includes('"cost"'))
+                return true;
+        }
+        catch {
+            /* not propagated yet */
+        }
+        await new Promise((r) => setTimeout(r, intervalMs));
+    }
+    return false;
+}
+/** Casper account-hash ("00" + 32-byte hash) for the agent's public key. */
+function agentTaggedAddress(agentPublicKey) {
+    const pk = casper_js_sdk_1.PublicKey.fromHex(agentPublicKey);
+    const ah = pk.accountHash();
+    let hex = (ah?.toHex?.() ?? ah?.toString?.() ?? String(ah)).replace(/^account-hash-/, "");
+    hex = hex.replace(/^0x/, "");
+    return "00" + hex; // 00 = AccountHash tag
+}
+/**
+ * Build the real x402 v2 `exact` PaymentPayload for the casper:* family. The
+ * `authorization` + 65-byte EIP-712 `signature` verify against the CSPR.cloud
+ * facilitator's POST /verify. We attach the Fund402 `settlement.deployHash`
+ * extension — the on-chain vault borrow_and_pay deploy the gateway checks.
+ */
+async function buildExactPayload(cfg, req, proof) {
+    const algo = cfg.keyAlgorithm ?? casper_js_sdk_1.KeyAlgorithm.ED25519;
+    const priv = await loadPrivateKey(cfg.agentSecretKey, algo);
+    const assetPkg = (req.asset ?? req.extra?.name ?? "").replace(/^0x/, "");
+    const amount = String(req.amount ?? "0");
+    const maxTimeoutSeconds = req.maxTimeoutSeconds ?? 300;
+    const name = req.extra?.name ?? "Cep18x402";
+    const version = req.extra?.version ?? "1";
+    const now = Math.floor(Date.now() / 1000);
+    const validAfter = now - 600;
+    const validBefore = now + maxTimeoutSeconds;
+    const nonce = (0, eip712_1.randomNonce)();
+    const from = "00" + priv.publicKey.accountHash().toHex(); // tagged account hash
+    const to = req.payTo;
+    const digest = (0, eip712_1.transferAuthorizationDigest)({ name, version, chainName: cfg.network, contractPackageHash: assetPkg }, { from, to, value: amount, validAfter: String(validAfter), validBefore: String(validBefore), nonce });
+    const signature = (0, eip712_1.bytesToHex)(priv.signAndAddAlgorithmBytes(digest));
+    const publicKey = priv.publicKey.toHex();
+    const requirements = {
+        scheme: "exact",
+        network: cfg.network,
+        asset: assetPkg,
+        payTo: to,
+        amount,
+        maxTimeoutSeconds,
+        extra: { name, version },
+    };
+    return {
+        x402Version: 2,
+        resource: req.resource ? { url: req.resource } : undefined,
+        accepted: requirements,
+        scheme: "exact",
+        network: cfg.network,
+        payload: {
+            signature,
+            publicKey,
+            authorization: {
+                from,
+                to,
+                value: amount,
+                validAfter: String(validAfter),
+                validBefore: String(validBefore),
+                nonce,
+            },
+            settlement: { deployHash: proof.deployHash, asset: assetPkg },
+        },
+        paymentRequirements: requirements,
+    };
+}