@subly_fi/pay 0.7.0 → 0.7.2

package/README.md

@@ -9,12 +9,12 @@ Version 0.7 is beta software and has not had an external security audit. Vault o
 You need **Node.js 24+**, a Solana agent wallet with mainnet USDC, a trusted relayer URL, and a mainnet RPC endpoint that supports transaction simulation with inner instructions. Your wallet can be a local keypair or a supported custody signer. The owner who approves spending controls can use a passkey or a separate Solana wallet.
 
 ```bash
-npx -y @subly_fi/pay@0.7.0 --help
+npx -y @subly_fi/pay@0.7.2 --help
 export SUBLY_RELAYER_URL=https://your-relayer.example.com
 export SOLANA_RPC_URL=https://your-mainnet-rpc.example.com
 export SUBLY_DEMO_AGENT_KEYPAIR_PATH=/absolute/path/to/agent.json
-npx -y @subly_fi/pay@0.7.0 doctor
-npx -y @subly_fi/pay@0.7.0 vaults
+npx -y @subly_fi/pay@0.7.2 doctor
+npx -y @subly_fi/pay@0.7.2 vaults
 ```
 
 Use an existing dedicated agent wallet, or create one with `solana-keygen new -o agent.json`. Keep its recovery material private and restrict the file to its owner (`chmod 600 agent.json`). Fund its public address with **USDC on Solana mainnet**. Subly does not create or fund wallets. Vault fees require a funded relayer sponsor; the final API payment requires the seller's facilitator fee payer.
@@ -23,28 +23,28 @@ Use an existing dedicated agent wallet, or create one with `solana-keygen new -o
 2. Create an owner setup link. This example pre-approves a **1.01 USDC** deposit; the selected vault's minimum can differ:
 
    ```bash
-   npx -y @subly_fi/pay@0.7.0 setup-link --initial-deposit 1010000
+   npx -y @subly_fi/pay@0.7.2 setup-link --initial-deposit 1010000
    ```
 
    Open the returned `setupUrl`, review the wallet, vault and limits, then approve with your passkey or wallet. Links expire in 10 minutes. Treat setup and approval links as private capabilities. The first person completing an initial setup becomes the owner for that wallet/vault.
 3. Check completion and deposit promptly; initial deposit approval lasts about 15 minutes:
 
    ```bash
-   npx -y @subly_fi/pay@0.7.0 setup-status <sessionId>
-   npx -y @subly_fi/pay@0.7.0 deposit 1010000
-   npx -y @subly_fi/pay@0.7.0 budget
+   npx -y @subly_fi/pay@0.7.2 setup-status <sessionId>
+   npx -y @subly_fi/pay@0.7.2 deposit 1010000
+   npx -y @subly_fi/pay@0.7.2 budget
    ```
 
 4. Wait until **spendable yield** covers the price and vault fees. A new deposit does not immediately provide a payment budget. Then request a compatible API:
 
    ```bash
-   npx -y @subly_fi/pay@0.7.0 fetch https://seller.example.com/paid-resource
+   npx -y @subly_fi/pay@0.7.2 fetch https://seller.example.com/paid-resource
    ```
 
 5. Withdraw funds back to the same agent wallet when needed:
 
    ```bash
-   npx -y @subly_fi/pay@0.7.0 withdraw 1000000
+   npx -y @subly_fi/pay@0.7.2 withdraw 1000000
    ```
 
 All amounts are raw USDC integers: `1000000` = 1 USDC. `fetch` defaults to a **0.01 USDC cap**, configurable with `SUBLY_MCP_MAX_AMOUNT_RAW_USDC` or `fetch <URL> <capRawUSDC>`. The owner mandate may set stricter limits. `setup-link --help` lists policy options. A withdrawal can include principal and is subject to liquidity, fees and the owner's policy. A revoked mandate also blocks relayer withdrawals.
@@ -60,7 +60,7 @@ Add this to the MCP configuration of your editor or agent host. Replace all exam
   "mcpServers": {
     "subly": {
       "command": "npx",
-      "args": ["-y", "@subly_fi/pay@0.7.0", "mcp"],
+      "args": ["-y", "@subly_fi/pay@0.7.2", "mcp"],
       "env": {
         "SUBLY_RELAYER_URL": "https://your-relayer.example.com",
         "SOLANA_RPC_URL": "https://your-mainnet-rpc.example.com",

package/dist/budget.js

@@ -1747,8 +1747,11 @@ async function agentWalletSignerFromEnv(env = process.env) {
   );
 }
 
+// ../../src/domain/withdrawal-rounding.ts
+var WITHDRAWAL_ROUNDING_RAW_USDC = 10n;
+var YIELD_REALIZE_ROUNDING_RAW_USDC = WITHDRAWAL_ROUNDING_RAW_USDC / 2n;
+
 // ../../src/client/withdrawal-preview.ts
-var ROUNDING_RAW_USDC = 10n;
 async function assertWithdrawalPreview(input) {
   const destination = deriveAssociatedTokenAddress({ owner: input.wallet, mint: input.vault.usdcMint });
   const simulation = await input.rpc.simulateTransaction(
@@ -1781,7 +1784,8 @@ async function assertWithdrawalPreview(input) {
       if (info.source === destination) received -= amount;
     }
   }
-  if (received <= 0n || received > input.amountRawUsdc + ROUNDING_RAW_USDC || received < input.amountRawUsdc - ROUNDING_RAW_USDC) {
+  const minimum = input.purpose === "yield_realize" ? input.amountRawUsdc : input.amountRawUsdc - WITHDRAWAL_ROUNDING_RAW_USDC;
+  if (received <= 0n || received > input.amountRawUsdc + WITHDRAWAL_ROUNDING_RAW_USDC || received < minimum) {
     throw new Error("Withdrawal preview differs from the requested USDC amount; no transaction was signed");
   }
 }
@@ -1988,7 +1992,8 @@ var VaultFlowClient = class {
       serializedTransaction: prepared.serializedTransaction,
       wallet: this.signer.walletAddress,
       vault: this.vault,
-      amountRawUsdc: input.amountRawUsdc
+      amountRawUsdc: input.amountRawUsdc,
+      ...input.purpose === void 0 ? {} : { purpose: input.purpose }
     });
     const signed = await this.signer.signWithdrawal({
       intent: prepared.signingIntent,

package/dist/deposit.js

@@ -1843,8 +1843,11 @@ async function agentWalletSignerFromEnv(env = process.env) {
   );
 }
 
+// ../../src/domain/withdrawal-rounding.ts
+var WITHDRAWAL_ROUNDING_RAW_USDC = 10n;
+var YIELD_REALIZE_ROUNDING_RAW_USDC = WITHDRAWAL_ROUNDING_RAW_USDC / 2n;
+
 // ../../src/client/withdrawal-preview.ts
-var ROUNDING_RAW_USDC = 10n;
 async function assertWithdrawalPreview(input) {
   const destination = deriveAssociatedTokenAddress({ owner: input.wallet, mint: input.vault.usdcMint });
   const simulation = await input.rpc.simulateTransaction(
@@ -1877,7 +1880,8 @@ async function assertWithdrawalPreview(input) {
       if (info.source === destination) received -= amount;
     }
   }
-  if (received <= 0n || received > input.amountRawUsdc + ROUNDING_RAW_USDC || received < input.amountRawUsdc - ROUNDING_RAW_USDC) {
+  const minimum = input.purpose === "yield_realize" ? input.amountRawUsdc : input.amountRawUsdc - WITHDRAWAL_ROUNDING_RAW_USDC;
+  if (received <= 0n || received > input.amountRawUsdc + WITHDRAWAL_ROUNDING_RAW_USDC || received < minimum) {
     throw new Error("Withdrawal preview differs from the requested USDC amount; no transaction was signed");
   }
 }
@@ -2047,7 +2051,8 @@ var VaultFlowClient = class {
       serializedTransaction: prepared.serializedTransaction,
       wallet: this.signer.walletAddress,
       vault: this.vault,
-      amountRawUsdc: input.amountRawUsdc
+      amountRawUsdc: input.amountRawUsdc,
+      ...input.purpose === void 0 ? {} : { purpose: input.purpose }
     });
     const signed = await this.signer.signWithdrawal({
       intent: prepared.signingIntent,

package/dist/doctor.js

@@ -169,18 +169,18 @@ await check("relayer and vault", async () => {
   if (url.protocol !== "https:" && !(url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname))) throw new Error("Use HTTPS (HTTP is allowed only for local development)");
   const catalog = vaultCatalogFromEnv();
   const local = defaultCatalogVault(catalog);
-  const health = await fetch(`${url.toString().replace(/\/$/, "")}/healthz`, { signal: AbortSignal.timeout(1e4) });
-  if (!health.ok || (await health.json()).ok !== true) throw new Error("Relayer health check failed");
+  const health = await fetch(`${url.toString().replace(/\/$/, "")}/readyz`, { signal: AbortSignal.timeout(1e4) });
+  if (!health.ok || (await health.json()).ok !== true) throw new Error("Relayer readiness check failed");
   const response = await fetch(`${url.toString().replace(/\/$/, "")}/v1/vaults`, { signal: AbortSignal.timeout(1e4) });
   if (!response.ok) throw new Error("Relayer vault catalogue unavailable");
   const remote = (await response.json()).vaults?.find((v) => v.address === local.address);
   if (!remote || ["programId", "usdcMint", "shareMint", "farm"].some((key) => remote[key] !== local[key])) throw new Error("Selected local vault trust anchors differ from the relayer; review the operator catalogue before changing configuration");
-  return `Healthy; selected vault ${local.address} matches local trust anchors`;
+  return `Ready; selected vault ${local.address} matches local trust anchors`;
 });
 await check("Solana RPC", async () => {
   const response = await fetch(env.SOLANA_RPC_URL ?? "https://api.mainnet-beta.solana.com", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "getGenesisHash" }), signal: AbortSignal.timeout(1e4) });
   const body = await response.json();
-  if (!response.ok || body.result !== "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp") throw new Error("RPC is unavailable or is not Solana mainnet-beta");
+  if (!response.ok || body.result !== "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d") throw new Error("RPC is unavailable or is not Solana mainnet-beta");
   return "Mainnet-beta RPC reachable";
 });
 var ok = checks.every((c) => c.ok);

package/dist/mcp-server.js

@@ -274,8 +274,11 @@ function modPow(base, exponent, modulus) {
   return result;
 }
 
+// ../../src/domain/withdrawal-rounding.ts
+var WITHDRAWAL_ROUNDING_RAW_USDC = 10n;
+var YIELD_REALIZE_ROUNDING_RAW_USDC = WITHDRAWAL_ROUNDING_RAW_USDC / 2n;
+
 // ../../src/client/withdrawal-preview.ts
-var ROUNDING_RAW_USDC = 10n;
 async function assertWithdrawalPreview(input) {
   const destination = deriveAssociatedTokenAddress({ owner: input.wallet, mint: input.vault.usdcMint });
   const simulation = await input.rpc.simulateTransaction(
@@ -308,7 +311,8 @@ async function assertWithdrawalPreview(input) {
       if (info.source === destination) received -= amount;
     }
   }
-  if (received <= 0n || received > input.amountRawUsdc + ROUNDING_RAW_USDC || received < input.amountRawUsdc - ROUNDING_RAW_USDC) {
+  const minimum = input.purpose === "yield_realize" ? input.amountRawUsdc : input.amountRawUsdc - WITHDRAWAL_ROUNDING_RAW_USDC;
+  if (received <= 0n || received > input.amountRawUsdc + WITHDRAWAL_ROUNDING_RAW_USDC || received < minimum) {
     throw new Error("Withdrawal preview differs from the requested USDC amount; no transaction was signed");
   }
 }
@@ -515,7 +519,8 @@ var VaultFlowClient = class {
       serializedTransaction: prepared.serializedTransaction,
       wallet: this.signer.walletAddress,
       vault: this.vault,
-      amountRawUsdc: input.amountRawUsdc
+      amountRawUsdc: input.amountRawUsdc,
+      ...input.purpose === void 0 ? {} : { purpose: input.purpose }
     });
     const signed = await this.signer.signWithdrawal({
       intent: prepared.signingIntent,
@@ -1013,6 +1018,7 @@ function hashStableJson(value) {
 
 // ../../src/x402/headers.ts
 var PAYMENT_REQUIRED_HEADER = "payment-required";
+var PAYMENT_RESPONSE_HEADER = "payment-response";
 var MAX_HEADER_JSON_BYTES = 16384;
 var X402HeaderError = class extends Error {
   reason;
@@ -1367,6 +1373,13 @@ var StandardX402Payer = class {
         { error, pendingPayment: pendingRecord }
       );
     }
+    if (realized.realizedRawUsdc < selected2.amountRawUsdc) {
+      throw new StandardX402PayError(
+        "realize_underfunded",
+        "The confirmed withdrawal did not cover the exact API price. No external payment was attempted; reconcile the recorded withdrawal before retrying.",
+        { pendingPayment: pendingRecord }
+      );
+    }
     let response;
     try {
       response = await this.x402Fetch(input.url, init, selected2);
@@ -1532,7 +1545,7 @@ function pendingPaymentKey(input) {
   return `${input.method}:${input.url}:${input.requestBodyHash}`;
 }
 function extractSettledPaymentTxSignature(response) {
-  const header = response.headers.get("x-payment-response");
+  const header = response.headers.get(PAYMENT_RESPONSE_HEADER) ?? response.headers.get("x-payment-response");
   if (header === null || header.length === 0) {
     return null;
   }

package/dist/pay.js

@@ -328,8 +328,11 @@ function modPow(base, exponent, modulus) {
   return result;
 }
 
+// ../../src/domain/withdrawal-rounding.ts
+var WITHDRAWAL_ROUNDING_RAW_USDC = 10n;
+var YIELD_REALIZE_ROUNDING_RAW_USDC = WITHDRAWAL_ROUNDING_RAW_USDC / 2n;
+
 // ../../src/client/withdrawal-preview.ts
-var ROUNDING_RAW_USDC = 10n;
 async function assertWithdrawalPreview(input) {
   const destination = deriveAssociatedTokenAddress({ owner: input.wallet, mint: input.vault.usdcMint });
   const simulation = await input.rpc.simulateTransaction(
@@ -362,7 +365,8 @@ async function assertWithdrawalPreview(input) {
       if (info.source === destination) received -= amount;
     }
   }
-  if (received <= 0n || received > input.amountRawUsdc + ROUNDING_RAW_USDC || received < input.amountRawUsdc - ROUNDING_RAW_USDC) {
+  const minimum = input.purpose === "yield_realize" ? input.amountRawUsdc : input.amountRawUsdc - WITHDRAWAL_ROUNDING_RAW_USDC;
+  if (received <= 0n || received > input.amountRawUsdc + WITHDRAWAL_ROUNDING_RAW_USDC || received < minimum) {
     throw new Error("Withdrawal preview differs from the requested USDC amount; no transaction was signed");
   }
 }
@@ -532,7 +536,8 @@ var VaultFlowClient = class {
       serializedTransaction: prepared.serializedTransaction,
       wallet: this.signer.walletAddress,
       vault: this.vault,
-      amountRawUsdc: input.amountRawUsdc
+      amountRawUsdc: input.amountRawUsdc,
+      ...input.purpose === void 0 ? {} : { purpose: input.purpose }
     });
     const signed = await this.signer.signWithdrawal({
       intent: prepared.signingIntent,
@@ -965,6 +970,7 @@ function sha256HexOf(data) {
 // ../../src/x402/headers.ts
 import { z as z2 } from "zod";
 var PAYMENT_REQUIRED_HEADER = "payment-required";
+var PAYMENT_RESPONSE_HEADER = "payment-response";
 var MAX_HEADER_JSON_BYTES = 16384;
 var X402HeaderError = class extends Error {
   reason;
@@ -1303,6 +1309,13 @@ var StandardX402Payer = class {
         { error, pendingPayment: pendingRecord }
       );
     }
+    if (realized.realizedRawUsdc < selected.amountRawUsdc) {
+      throw new StandardX402PayError(
+        "realize_underfunded",
+        "The confirmed withdrawal did not cover the exact API price. No external payment was attempted; reconcile the recorded withdrawal before retrying.",
+        { pendingPayment: pendingRecord }
+      );
+    }
     let response;
     try {
       response = await this.x402Fetch(input.url, init, selected);
@@ -1468,7 +1481,7 @@ function pendingPaymentKey(input) {
   return `${input.method}:${input.url}:${input.requestBodyHash}`;
 }
 function extractSettledPaymentTxSignature(response) {
-  const header = response.headers.get("x-payment-response");
+  const header = response.headers.get(PAYMENT_RESPONSE_HEADER) ?? response.headers.get("x-payment-response");
   if (header === null || header.length === 0) {
     return null;
   }

package/dist/setup-link.js

@@ -1747,8 +1747,11 @@ async function agentWalletSignerFromEnv(env = process.env) {
   );
 }
 
+// ../../src/domain/withdrawal-rounding.ts
+var WITHDRAWAL_ROUNDING_RAW_USDC = 10n;
+var YIELD_REALIZE_ROUNDING_RAW_USDC = WITHDRAWAL_ROUNDING_RAW_USDC / 2n;
+
 // ../../src/client/withdrawal-preview.ts
-var ROUNDING_RAW_USDC = 10n;
 async function assertWithdrawalPreview(input) {
   const destination = deriveAssociatedTokenAddress({ owner: input.wallet, mint: input.vault.usdcMint });
   const simulation = await input.rpc.simulateTransaction(
@@ -1781,7 +1784,8 @@ async function assertWithdrawalPreview(input) {
       if (info.source === destination) received -= amount;
     }
   }
-  if (received <= 0n || received > input.amountRawUsdc + ROUNDING_RAW_USDC || received < input.amountRawUsdc - ROUNDING_RAW_USDC) {
+  const minimum = input.purpose === "yield_realize" ? input.amountRawUsdc : input.amountRawUsdc - WITHDRAWAL_ROUNDING_RAW_USDC;
+  if (received <= 0n || received > input.amountRawUsdc + WITHDRAWAL_ROUNDING_RAW_USDC || received < minimum) {
     throw new Error("Withdrawal preview differs from the requested USDC amount; no transaction was signed");
   }
 }
@@ -1988,7 +1992,8 @@ var VaultFlowClient = class {
       serializedTransaction: prepared.serializedTransaction,
       wallet: this.signer.walletAddress,
       vault: this.vault,
-      amountRawUsdc: input.amountRawUsdc
+      amountRawUsdc: input.amountRawUsdc,
+      ...input.purpose === void 0 ? {} : { purpose: input.purpose }
     });
     const signed = await this.signer.signWithdrawal({
       intent: prepared.signingIntent,

package/dist/withdraw.js

@@ -1747,8 +1747,11 @@ async function agentWalletSignerFromEnv(env = process.env) {
   );
 }
 
+// ../../src/domain/withdrawal-rounding.ts
+var WITHDRAWAL_ROUNDING_RAW_USDC = 10n;
+var YIELD_REALIZE_ROUNDING_RAW_USDC = WITHDRAWAL_ROUNDING_RAW_USDC / 2n;
+
 // ../../src/client/withdrawal-preview.ts
-var ROUNDING_RAW_USDC = 10n;
 async function assertWithdrawalPreview(input) {
   const destination = deriveAssociatedTokenAddress({ owner: input.wallet, mint: input.vault.usdcMint });
   const simulation = await input.rpc.simulateTransaction(
@@ -1781,7 +1784,8 @@ async function assertWithdrawalPreview(input) {
       if (info.source === destination) received -= amount;
     }
   }
-  if (received <= 0n || received > input.amountRawUsdc + ROUNDING_RAW_USDC || received < input.amountRawUsdc - ROUNDING_RAW_USDC) {
+  const minimum = input.purpose === "yield_realize" ? input.amountRawUsdc : input.amountRawUsdc - WITHDRAWAL_ROUNDING_RAW_USDC;
+  if (received <= 0n || received > input.amountRawUsdc + WITHDRAWAL_ROUNDING_RAW_USDC || received < minimum) {
     throw new Error("Withdrawal preview differs from the requested USDC amount; no transaction was signed");
   }
 }
@@ -1988,7 +1992,8 @@ var VaultFlowClient = class {
       serializedTransaction: prepared.serializedTransaction,
       wallet: this.signer.walletAddress,
       vault: this.vault,
-      amountRawUsdc: input.amountRawUsdc
+      amountRawUsdc: input.amountRawUsdc,
+      ...input.purpose === void 0 ? {} : { purpose: input.purpose }
     });
     const signed = await this.signer.signWithdrawal({
       intent: prepared.signingIntent,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@subly_fi/pay",
-  "version": "0.7.0",
-  "description": "Subly client: pay compatible standard x402 Solana USDC exact APIs from Kamino vault yield \u2014 the seller needs no Subly integration. Ships an MCP server and a one-shot pay/deposit CLI; non-custodial (signs locally with your own key).",
+  "version": "0.7.2",
+  "description": "Subly client: pay compatible standard x402 Solana USDC exact APIs from Kamino vault yield — the seller needs no Subly integration. Ships an MCP server and a one-shot pay/deposit CLI; non-custodial (signs locally with your own key).",
   "keywords": [
     "x402",
     "solana",