@nickthelegend69/fund402 0.1.0 → 0.1.2

package/README.md

@@ -128,6 +128,12 @@ const data = await res.json();   // paid + served — the agent's own balance ca
 Prefer Axios? `withPaymentInterceptor(config)` returns an `AxiosInstance` with the
 same behaviour (Axios is an optional peer dependency).
 
+**Tiers & collateral.** Trusted (Tier-3) agents borrow with **zero collateral**.
+New/established (Tier-1/2) agents must post 150% collateral — `fund402Fetch`
+**auto-approves** the vault to escrow it before borrowing (`collateralRatio`, default
+`1.5`; set `autoApprove: false` to manage the allowance yourself, or `collateralRatio: 0`
+for Tier-3).
+
 ---
 
 ## How settlement works (and why you can trust it)
@@ -145,17 +151,30 @@ same behaviour (Axios is an optional peer dependency).
 `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.
 
+## Yield-bearing pool
+
+The vault charges a **5% JIT credit fee** on every borrow. On repayment the agent pays
+back principal **+ fee**, and the fee accrues to the pool's value — so **LPs earn yield**:
+deposits are minted as shares, and a share redeems for more than it cost as fees pile up.
+Agents can settle their newest loan with **`repayLatestOnChain`** (no loan id needed),
+which makes auto-repay-from-earnings trivial.
+
+**Proven live (casper-test):** an LP deposited `2_000_000`, an agent borrowed `1_000_000`
+and repaid via `repay_latest`, the pool grew to `2_050_000`, and the LP **withdrew
+`2_050_000` for its `2_000_000` deposit — `+50_000` realized yield.**
+[repay `80e90a43…`](https://testnet.cspr.live/deploy/80e90a43120b40524038a405088f3f83c4ce45674a9ff3e28c577a20552cba9e) ·
+[LP withdraw `44318b5b…`](https://testnet.cspr.live/deploy/44318b5b303dab8dbbb3c3b26ac0f148bf7b44701996fbd446f17f9f7622023c)
+
 ## Live deployment (casper-test)
 
 | | |
 |---|---|
-| Vault (lending pool) package | `664d99de146b9b573161a387d89fefc649677351d8a6d2acbe22109bf88f6b12` |
+| Vault (yield-bearing lending pool) package | `ca4086d3a7b1abf000d0a79e23a237bb484a14807e9438f2c56f3461073e1b2f` |
 | 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.
+Point `vaultContract` / `asset` at your own deployment for production.
 
 ## Verified live ✅
 
@@ -165,10 +184,17 @@ hits the endpoint → gets a 402 → borrows from the pool (the vault fronts the
 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`).
+Both credit paths are proven live through the SDK:
+
+- **Tier-3 (zero collateral)** — agent `01baa8d8…` borrowed `1000000` F402; the pool
+  fronted it to the merchant.
+  [settlement deploy `96f30ddf…` ↗](https://testnet.cspr.live/deploy/96f30ddfac9b3b8bc04a9fe274b1c006aff398ac624e7360669a2c1f3dc28264) (`status: processed`).
+- **Tier-1 (150% collateral)** — agent `017e90a1…` had `fund402Fetch` auto-approve and
+  **escrow `1500000` collateral** ([approve `f088362a…`](https://testnet.cspr.live/deploy/f088362a89720107dfe475ba8bc0660dbdb278cf25c3d633cf4e846414d8aa47)),
+  then borrow; verified on-chain (`collateral=1500000`).
+  [settlement deploy `a9dd1581…` ↗](https://testnet.cspr.live/deploy/a9dd158199ca65fda900863cd43db577983c1dcf3d6661409bf8d4c56bab649f) (`status: processed`).
+
+Run them yourself: `npm run test:e2e` (Tier-3) and `npm run test:e2e:collateral` (Tier-1).
 
 ## API
 
@@ -181,8 +207,9 @@ verifying it on-chain:
 · `decodeChallenge` · `selectCasperOption` · `testnetClient` / `mainnetClient`.
 
 **On-chain primitives:** `borrowAndPayOnChain` · `repayLoanOnChain` ·
-`ensureCollateralAllowance` · `buildExactPayload` · `waitForDeploy` ·
-`agentTaggedAddress` · `transferAuthorizationDigest`.
+`repayLatestOnChain` (repay your newest loan — no loan id) · `ensureCollateralAllowance`
+· `buildExactPayload` · `waitForDeploy` · `agentTaggedAddress` ·
+`transferAuthorizationDigest`.
 
 ## ⚠️ Security
 

package/dist/casper.d.ts

@@ -32,6 +32,15 @@ export declare function borrowAndPayOnChain(cfg: CasperWiringConfig, args: {
 export declare function repayLoanOnChain(cfg: CasperWiringConfig, loanId: number): Promise<{
     deployHash: string;
 }>;
+/**
+ * Repay the agent's **most recent** open loan without needing its id (vault
+ * `repay_latest`). Pulls back principal + the JIT fee — the fee accrues to the pool
+ * as LP yield. The agent must first `approve` the vault for principal + fee
+ * (see ensureCollateralAllowance) and hold that much of the asset.
+ */
+export declare function repayLatestOnChain(cfg: CasperWiringConfig): 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

package/dist/casper.js

@@ -11,6 +11,7 @@ exports.rpc = rpc;
 exports.loadPrivateKey = loadPrivateKey;
 exports.borrowAndPayOnChain = borrowAndPayOnChain;
 exports.repayLoanOnChain = repayLoanOnChain;
+exports.repayLatestOnChain = repayLatestOnChain;
 exports.ensureCollateralAllowance = ensureCollateralAllowance;
 exports.waitForDeploy = waitForDeploy;
 exports.agentTaggedAddress = agentTaggedAddress;
@@ -100,6 +101,28 @@ async function repayLoanOnChain(cfg, loanId) {
     const result = await client.putDeploy(deploy);
     return { deployHash: result.deployHash.toHex() };
 }
+/**
+ * Repay the agent's **most recent** open loan without needing its id (vault
+ * `repay_latest`). Pulls back principal + the JIT fee — the fee accrues to the pool
+ * as LP yield. The agent must first `approve` the vault for principal + fee
+ * (see ensureCollateralAllowance) and hold that much of the asset.
+ */
+async function repayLatestOnChain(cfg) {
+    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_latest", casper_js_sdk_1.Args.fromMap({}));
+    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
@@ -118,7 +141,9 @@ async function ensureCollateralAllowance(cfg, spender, amount) {
         spender: pkgKey(spender.vaultContractHash),
         amount: casper_js_sdk_1.CLValue.newCLUInt256(amount.toString()),
     }));
-    const payment = casper_js_sdk_1.ExecutableDeployItem.standardPayment("2000000000");
+    // 5 CSPR — the gas the proven live approves use; lower (e.g. 2 CSPR) is rejected
+    // by Condor at submission as Invalid Deploy.
+    const payment = casper_js_sdk_1.ExecutableDeployItem.standardPayment("5000000000");
     const deploy = casper_js_sdk_1.Deploy.makeDeploy(header, payment, session);
     deploy.sign(signer);
     const result = await client.putDeploy(deploy);

package/dist/client.d.ts

@@ -16,6 +16,8 @@ export interface Fund402ClientConfig {
     keyAlgorithm?: KeyAlgorithm;
     /** Over-collateralisation ratio the agent posts (vault re-checks on-chain). Default 1.5. */
     collateralRatio?: number;
+    /** Auto-approve the vault to escrow collateral before a Tier-1/2 borrow. Default true. */
+    autoApprove?: boolean;
     /** Gas (motes) for the borrow_and_pay deploy. Default 5 CSPR. */
     borrowGasMotes?: string;
     /** Underlying fetch implementation. Default global fetch. */
@@ -23,7 +25,7 @@ export interface Fund402ClientConfig {
     onEvent?: (event: Fund402Event) => void;
 }
 export interface Fund402Event {
-    type: "intercepted_402" | "borrowing" | "borrow_submitted" | "payment_settled" | "payment_sent" | "request_retried" | "payment_confirmed";
+    type: "intercepted_402" | "approving" | "approve_submitted" | "borrowing" | "borrow_submitted" | "payment_settled" | "payment_sent" | "request_retried" | "payment_confirmed";
     data: Record<string, unknown>;
     timestamp: number;
 }

package/dist/client.js

@@ -79,6 +79,20 @@ async function payViaPool(config, option, resource) {
     const amount = BigInt(option.amount);
     const ratio = config.collateralRatio ?? 1.5;
     const collateral = (amount * BigInt(Math.round(ratio * 100))) / 100n;
+    // Tier-1/2 collateralized borrow: the vault escrows `collateral` via transfer_from,
+    // so the agent must approve it on the CEP-18 asset first. Tier-3 borrows post zero
+    // collateral and skip this entirely.
+    if (collateral > 0n && config.autoApprove !== false) {
+        const asset = (option.asset ?? "").replace(/^0x/, "");
+        if (!asset)
+            throw new Error("402 challenge has no `asset` — cannot approve collateral");
+        emit(config, "approving", { asset, collateral: collateral.toString() });
+        const { deployHash: approveHash } = await (0, casper_1.ensureCollateralAllowance)({ ...wiring, assetPackageHash: asset }, { vaultContractHash: wiring.vaultContractHash }, collateral);
+        emit(config, "approve_submitted", { deployHash: approveHash });
+        const okApprove = await (0, casper_1.waitForDeploy)(wiring, approveHash);
+        if (!okApprove)
+            throw new Error(`collateral approve deploy failed: ${approveHash}`);
+    }
     emit(config, "borrowing", { amount: amount.toString(), collateral: collateral.toString() });
     const { deployHash } = await (0, casper_1.borrowAndPayOnChain)(wiring, {
         merchant: option.payTo,

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export * from "./types";
 export { paywall, buildPaymentRequirements, challengeBody, decodePaymentSignature, verifyPoolSettlement, verifyWithFacilitator, explorerTx, type PaywallConfig, type Fund402Paywall, type VerifyResult, type GuardResult, type RequestLike, type HttpResponseLike, } from "./server";
 export { fund402Fetch, withPaymentInterceptor, payViaPool, decodeChallenge, selectCasperOption, testnetClient, mainnetClient, type Fund402ClientConfig, type Fund402Event, } from "./client";
-export { borrowAndPayOnChain, repayLoanOnChain, ensureCollateralAllowance, buildExactPayload, waitForDeploy, agentTaggedAddress, loadPrivateKey, rpc, type CasperWiringConfig, } from "./casper";
+export { borrowAndPayOnChain, repayLoanOnChain, repayLatestOnChain, ensureCollateralAllowance, buildExactPayload, waitForDeploy, agentTaggedAddress, loadPrivateKey, rpc, type CasperWiringConfig, } from "./casper";
 export { transferAuthorizationDigest, randomNonce, bytesToHex } from "./eip712";
 export { expressPaywall } from "./adapters/express";
 export { honoPaywall } from "./adapters/hono";

package/dist/index.js

@@ -25,7 +25,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.withPaywall = exports.honoPaywall = exports.expressPaywall = exports.bytesToHex = exports.randomNonce = exports.transferAuthorizationDigest = exports.rpc = exports.loadPrivateKey = exports.agentTaggedAddress = exports.waitForDeploy = exports.buildExactPayload = exports.ensureCollateralAllowance = exports.repayLoanOnChain = exports.borrowAndPayOnChain = exports.mainnetClient = exports.testnetClient = exports.selectCasperOption = exports.decodeChallenge = exports.payViaPool = exports.withPaymentInterceptor = exports.fund402Fetch = exports.explorerTx = exports.verifyWithFacilitator = exports.verifyPoolSettlement = exports.decodePaymentSignature = exports.challengeBody = exports.buildPaymentRequirements = exports.paywall = void 0;
+exports.withPaywall = exports.honoPaywall = exports.expressPaywall = exports.bytesToHex = exports.randomNonce = exports.transferAuthorizationDigest = exports.rpc = exports.loadPrivateKey = exports.agentTaggedAddress = exports.waitForDeploy = exports.buildExactPayload = exports.ensureCollateralAllowance = exports.repayLatestOnChain = exports.repayLoanOnChain = exports.borrowAndPayOnChain = exports.mainnetClient = exports.testnetClient = exports.selectCasperOption = exports.decodeChallenge = exports.payViaPool = exports.withPaymentInterceptor = exports.fund402Fetch = exports.explorerTx = exports.verifyWithFacilitator = exports.verifyPoolSettlement = exports.decodePaymentSignature = exports.challengeBody = exports.buildPaymentRequirements = exports.paywall = void 0;
 __exportStar(require("./types"), exports);
 // Server
 var server_1 = require("./server");
@@ -49,6 +49,7 @@ Object.defineProperty(exports, "mainnetClient", { enumerable: true, get: functio
 var casper_1 = require("./casper");
 Object.defineProperty(exports, "borrowAndPayOnChain", { enumerable: true, get: function () { return casper_1.borrowAndPayOnChain; } });
 Object.defineProperty(exports, "repayLoanOnChain", { enumerable: true, get: function () { return casper_1.repayLoanOnChain; } });
+Object.defineProperty(exports, "repayLatestOnChain", { enumerable: true, get: function () { return casper_1.repayLatestOnChain; } });
 Object.defineProperty(exports, "ensureCollateralAllowance", { enumerable: true, get: function () { return casper_1.ensureCollateralAllowance; } });
 Object.defineProperty(exports, "buildExactPayload", { enumerable: true, get: function () { return casper_1.buildExactPayload; } });
 Object.defineProperty(exports, "waitForDeploy", { enumerable: true, get: function () { return casper_1.waitForDeploy; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nickthelegend69/fund402",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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",
@@ -36,7 +36,8 @@
     "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"
+    "test:e2e": "npm run build && node test/e2e-live.mjs",
+    "test:e2e:collateral": "npm run build && node test/e2e-collateral.mjs"
   },
   "dependencies": {
     "@noble/hashes": "^1.4.0",