@subly_fi/pay 0.2.0 → 0.4.0

package/README.md

@@ -7,7 +7,10 @@ locally with your own Solana key; Subly never holds it.
 
 Ships one `pay` dispatcher bin with subcommands, all runnable with `npx` (no clone):
 
-- `pay mcp` — an MCP server (Claude Code, Cursor, any MCP client)
+- `pay mcp` — an MCP server (Claude Code, Cursor, any MCP client) exposing
+  the full lifecycle as tools: `deposit_to_subly_vault`,
+  `get_subly_yield_budget`, `fetch_with_subly_payment`,
+  `withdraw_from_subly_vault`
 - `pay fetch <url>` — one-shot: pay for a URL, print the receipt (used by the
   OpenClaw skill)
 - `pay deposit <amountRawUsdc>` / `pay withdraw <amountRawUsdc>` — vault
@@ -45,10 +48,14 @@ npx -y @subly_fi/pay fetch https://seller.example.com/api/premium
 | Var | Required | Default |
 |---|---|---|
 | `SUBLY_DEMO_AGENT_KEYPAIR_PATH` | yes (or `SUBLY_DEMO_AGENT_KEYPAIR` base58) | — |
-| `SUBLY_FACILITATOR_URL` | no | `https://api.demo.sublyfi.com` |
+| `SUBLY_RELAYER_URL` | no | `https://api.demo.sublyfi.com` |
 | `SOLANA_RPC_URL` | no | public mainnet RPC |
 | `SUBLY_MCP_MAX_AMOUNT_RAW_USDC` | no | `10000` (0.01 USDC) per-payment cap |
 
 Requests authenticate with a signature from your wallet key — there is no API
-token. The cap and the facilitator's yield-budget check both bound spending;
-the principal is never touched.
+token. `SUBLY_FACILITATOR_URL` is still accepted as a legacy fallback for
+`SUBLY_RELAYER_URL`. Spending is bounded twice: the client cap, and the
+relayer's server-side guard that refuses to realize anything beyond the
+spendable yield — the deposited principal is never touched by a payment.
+(A plain `pay withdraw` is the exit path and may of course move principal
+back to your wallet.)

package/dist/deposit.js

@@ -1,8 +1,8 @@
-// src/client/agent-wallet-signer.ts
+// ../../src/client/agent-wallet-signer.ts
 import { signBytes } from "@solana/kit";
 import bs584 from "bs58";
 
-// src/solana/tx.ts
+// ../../src/solana/tx.ts
 import bs58 from "bs58";
 import {
   appendTransactionMessageInstructions,
@@ -17,7 +17,7 @@ import {
   setTransactionMessageLifetimeUsingBlockhash
 } from "@solana/kit";
 
-// src/lib/hash.ts
+// ../../src/lib/hash.ts
 import { createHash } from "node:crypto";
 function sha256TaggedHex(data) {
   return `sha256-${createHash("sha256").update(data).digest("hex")}`;
@@ -42,16 +42,16 @@ function hashStableJson(value) {
   return sha256TaggedHex(stableStringify(value));
 }
 
-// src/solana/tx.ts
+// ../../src/solana/tx.ts
 function decodeSerializedTransaction(serializedBase64) {
   return getTransactionDecoder().decode(Buffer.from(serializedBase64, "base64"));
 }
 async function addSignaturesToSerializedTransaction(params) {
   const decoded = decodeSerializedTransaction(params.serializedBase64);
-  const signed2 = await partiallySignTransaction(params.signers, decoded);
+  const signed = await partiallySignTransaction(params.signers, decoded);
   return {
-    serializedBase64: getBase64EncodedWireTransaction(signed2),
-    transaction: signed2
+    serializedBase64: getBase64EncodedWireTransaction(signed),
+    transaction: signed
   };
 }
 function signatureBase58ForSigner(transaction, signer2) {
@@ -62,11 +62,11 @@ function signatureBase58ForSigner(transaction, signer2) {
   return bs58.encode(signature);
 }
 
-// src/client/transaction-intent-validator.ts
+// ../../src/client/transaction-intent-validator.ts
 import bs583 from "bs58";
 import { getCompiledTransactionMessageDecoder } from "@solana/kit";
 
-// src/config/constants.ts
+// ../../src/config/constants.ts
 var PAYMENT_SCHEME = "subly-yield-exact";
 var SOLANA_MAINNET_NETWORK = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
 var SPL_TOKEN_PROGRAM_ID = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
@@ -82,7 +82,7 @@ var SUBLY_VAULT = {
 };
 var USDC_DECIMALS = 6;
 
-// src/domain/request-binding.ts
+// ../../src/domain/request-binding.ts
 function computeRequestBindingHash(fields) {
   return hashStableJson({
     sellerRequestId: fields.sellerRequestId,
@@ -97,7 +97,7 @@ function computeRequestBindingHash(fields) {
   });
 }
 
-// src/lib/associated-token-account.ts
+// ../../src/lib/associated-token-account.ts
 import { createHash as createHash2 } from "node:crypto";
 import bs582 from "bs58";
 var PDA_MARKER = Buffer.from("ProgramDerivedAddress", "utf8");
@@ -189,7 +189,7 @@ function modPow(base, exponent, modulus) {
   return result;
 }
 
-// src/client/transaction-intent-validator.ts
+// ../../src/client/transaction-intent-validator.ts
 var COMPUTE_BUDGET_PROGRAM_ID = "ComputeBudget111111111111111111111111111111";
 var SYSTEM_PROGRAM_ID = "11111111111111111111111111111111";
 var ASSOCIATED_TOKEN_PROGRAM_ID2 = "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL";
@@ -875,7 +875,7 @@ function readShortVec(bytes, startOffset) {
   return null;
 }
 
-// src/client/agent-wallet-signer.ts
+// ../../src/client/agent-wallet-signer.ts
 var LocalKeypairAgentWalletSigner = class {
   validationMode = "structured_intent_transaction";
   keyPairSigner;
@@ -945,7 +945,7 @@ var LocalKeypairAgentWalletSigner = class {
   }
 };
 
-// src/api/wallet-auth.ts
+// ../../src/api/wallet-auth.ts
 import { createHash as createHash3 } from "node:crypto";
 import bs585 from "bs58";
 import nacl from "tweetnacl";
@@ -963,7 +963,7 @@ function walletAuthMessage(params) {
   );
 }
 
-// src/client/wallet-auth-headers.ts
+// ../../src/client/wallet-auth-headers.ts
 async function walletAuthHeaders(params) {
   const signedAtMs = String(Date.now());
   const message = walletAuthMessage({
@@ -979,7 +979,7 @@ async function walletAuthHeaders(params) {
   };
 }
 
-// src/client/onboarding.ts
+// ../../src/client/onboarding.ts
 var SELF_SERVE_POLICY_ID = "self-serve";
 var OnboardingError = class extends Error {
   constructor(step, message, detail = null) {
@@ -1036,7 +1036,7 @@ async function ensureWalletOnboarded(params) {
   await post("sync", `/v1/wallets/${wallet}/sync`, { source: "chain" });
 }
 
-// src/client/lookup-tables.ts
+// ../../src/client/lookup-tables.ts
 import { fetchAllMaybeAddressLookupTable } from "@solana-program/address-lookup-table";
 import { address, getCompiledTransactionMessageDecoder as getCompiledTransactionMessageDecoder2 } from "@solana/kit";
 function lookupTableAddressesForTransaction(serializedTransaction) {
@@ -1076,7 +1076,223 @@ async function fetchLookupTablesForTransaction(rpc2, serializedTransaction) {
   return result;
 }
 
-// src/solana/keys.ts
+// ../../src/client/vault-flows.ts
+var VaultFlowClientError = class extends Error {
+  constructor(step, message, detail = null) {
+    super(message);
+    this.step = step;
+    this.detail = detail;
+    this.name = "VaultFlowClientError";
+  }
+  step;
+  detail;
+};
+var VaultFlowClient = class {
+  baseUrl;
+  signer;
+  fetchImpl;
+  lookupTablesFor;
+  pollTimeoutMs;
+  pollIntervalMs;
+  constructor(config) {
+    this.baseUrl = config.facilitatorBaseUrl.replace(/\/$/, "");
+    this.signer = config.signer;
+    this.fetchImpl = config.fetchImpl ?? fetch;
+    this.lookupTablesFor = config.lookupTablesFor ?? ((serializedTransaction) => fetchLookupTablesForTransaction(config.rpc, serializedTransaction));
+    this.pollTimeoutMs = config.pollTimeoutMs ?? 9e4;
+    this.pollIntervalMs = config.pollIntervalMs ?? 2500;
+  }
+  /** Moves USDC from the agent wallet into the vault (fee sponsored). */
+  async deposit(input) {
+    const prepared = await this.postJson("prepare", "/v1/deposits/prepare", {
+      wallet: this.signer.walletAddress,
+      amountRawUsdc: input.amountRawUsdc.toString()
+    });
+    const signed = await this.signer.signDeposit({
+      intent: prepared.signingIntent,
+      serializedTransaction: prepared.serializedTransaction,
+      lookupTables: await this.lookupTablesFor(prepared.serializedTransaction)
+    });
+    let outcome = await this.postJson("submit", "/v1/deposits/submit", {
+      depositId: prepared.depositId,
+      serializedTransaction: signed.serializedTransaction,
+      agentSignature: signed.agentSignature
+    });
+    if (outcome.status === "submitted") {
+      outcome = await this.pollUntilTerminal(
+        `/v1/deposits/${prepared.depositId}`,
+        outcome
+      );
+    }
+    return {
+      depositId: prepared.depositId,
+      status: outcome.status,
+      txSignature: outcome.txSignature ?? null,
+      actualDepositRawUsdc: outcome.actualDepositRawUsdc ?? null,
+      sharesMintedRaw: outcome.sharesMintedRaw ?? null,
+      errorCode: outcome.errorCode ?? null
+    };
+  }
+  /**
+   * Moves USDC from the vault back to the agent wallet's USDC ATA (fee
+   * sponsored). A plain withdrawal is the exit path and MAY spend principal;
+   * with purpose "yield_realize" the relayer refuses anything beyond the
+   * spendable yield (the payment path, via RelayerYieldRealizer).
+   */
+  async withdraw(input) {
+    const prepared = await this.postJson(
+      "prepare",
+      "/v1/withdrawals/prepare",
+      {
+        wallet: this.signer.walletAddress,
+        amountRawUsdc: input.amountRawUsdc.toString(),
+        ...input.purpose === void 0 ? {} : { purpose: input.purpose }
+      }
+    );
+    const signed = await this.signer.signWithdrawal({
+      intent: prepared.signingIntent,
+      serializedTransaction: prepared.serializedTransaction,
+      lookupTables: await this.lookupTablesFor(prepared.serializedTransaction)
+    });
+    let outcome = await this.postJson("submit", "/v1/withdrawals/submit", {
+      withdrawalId: prepared.withdrawalId,
+      serializedTransaction: signed.serializedTransaction,
+      agentSignature: signed.agentSignature
+    });
+    if (outcome.status === "submitted") {
+      outcome = await this.pollUntilTerminal(
+        `/v1/withdrawals/${prepared.withdrawalId}`,
+        outcome
+      );
+    }
+    return {
+      withdrawalId: prepared.withdrawalId,
+      status: outcome.status,
+      txSignature: outcome.txSignature ?? null,
+      destinationUsdcAta: prepared.destinationUsdcAta,
+      actualWithdrawRawUsdc: outcome.actualWithdrawRawUsdc ?? null,
+      actualSharesBurnedRaw: outcome.actualSharesBurnedRaw ?? null,
+      errorCode: outcome.errorCode ?? null
+    };
+  }
+  /**
+   * Reads the yield budget. Syncs the relayer's ledger from chain first (so
+   * yield accrued since the last sync shows up); the sync is best-effort and
+   * on failure the last-synced view is returned.
+   */
+  async getBudget(options = {}) {
+    if (options.refreshFromChain !== false) {
+      try {
+        await this.postJson(
+          "sync",
+          `/v1/wallets/${this.signer.walletAddress}/sync`,
+          { source: "chain" }
+        );
+      } catch {
+      }
+    }
+    const url = `${this.baseUrl}/v1/wallets/${this.signer.walletAddress}/budget`;
+    const response = await this.fetchImpl(url, {
+      headers: await walletAuthHeaders({
+        signer: this.signer,
+        method: "GET",
+        url
+      })
+    });
+    const text = await response.text();
+    if (response.status !== 200) {
+      throw new VaultFlowClientError(
+        "budget",
+        `budget endpoint returned ${response.status}: ${text}`
+      );
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      throw new VaultFlowClientError(
+        "budget",
+        "budget endpoint returned 200 with a non-JSON body",
+        text
+      );
+    }
+    const body = parsed;
+    return {
+      wallet: this.signer.walletAddress,
+      principalBasisRawUsdc: body.position?.principalBasisRawUsdc ?? "0",
+      positionValueRawUsdc: body.budget?.positionValueRawUsdc ?? "0",
+      grossYieldRawUsdc: body.budget?.grossYieldRawUsdc ?? "0",
+      spendableYieldRawUsdc: body.budget?.spendableYieldRawUsdc ?? "0"
+    };
+  }
+  /**
+   * Polls the reconciling GET endpoint until the intent leaves "submitted"
+   * (each read looks the tx up on-chain) or the timeout elapses.
+   */
+  async pollUntilTerminal(path, last) {
+    const deadline = Date.now() + this.pollTimeoutMs;
+    let latest = last;
+    while (Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, this.pollIntervalMs));
+      const url = `${this.baseUrl}${path}`;
+      const response = await this.fetchImpl(url, {
+        headers: await walletAuthHeaders({
+          signer: this.signer,
+          method: "GET",
+          url
+        })
+      });
+      if (response.status !== 200) {
+        continue;
+      }
+      try {
+        latest = await response.json();
+      } catch {
+        continue;
+      }
+      if (latest.status !== "submitted") {
+        return latest;
+      }
+    }
+    return latest;
+  }
+  async postJson(step, path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const serialized = JSON.stringify(body);
+    const response = await this.fetchImpl(url, {
+      method: "POST",
+      headers: {
+        ...await walletAuthHeaders({
+          signer: this.signer,
+          method: "POST",
+          url,
+          body: serialized
+        }),
+        "content-type": "application/json"
+      },
+      body: serialized
+    });
+    const text = await response.text();
+    if (response.status !== 200) {
+      throw new VaultFlowClientError(
+        step,
+        `${path} failed with ${response.status}: ${text}`,
+        text
+      );
+    }
+    try {
+      return JSON.parse(text);
+    } catch {
+      throw new VaultFlowClientError(
+        step,
+        `${path} returned 200 with a non-JSON body`,
+        text
+      );
+    }
+  }
+};
+
+// ../../src/solana/keys.ts
 import { readFileSync } from "node:fs";
 import bs586 from "bs58";
 import {
@@ -1101,13 +1317,13 @@ async function loadKeyPairSigner(params) {
   throw new Error(`${label} keypair is not configured`);
 }
 
-// src/solana/rpc.ts
+// ../../src/solana/rpc.ts
 import { createSolanaRpc } from "@solana/kit";
 function createRpc(url) {
   return createSolanaRpc(url);
 }
 
-// demo/shared.ts
+// ../../demo/shared.ts
 function fail(message) {
   console.error(message);
   process.exit(1);
@@ -1119,8 +1335,8 @@ function formatRawUsdc(raw) {
   return `${whole}.${fraction}`;
 }
 
-// demo/deposit.ts
-var facilitatorBaseUrl = process.env.SUBLY_FACILITATOR_URL ?? "https://api.demo.sublyfi.com";
+// ../../demo/deposit.ts
+var relayerBaseUrl = process.env.SUBLY_RELAYER_URL ?? process.env.SUBLY_FACILITATOR_URL ?? "https://api.demo.sublyfi.com";
 var amountRawUsdc = process.argv[2];
 if (amountRawUsdc === void 0 || !/^[1-9]\d*$/.test(amountRawUsdc)) {
   fail(
@@ -1136,69 +1352,44 @@ var signer = new LocalKeypairAgentWalletSigner(keyPairSigner);
 var rpc = createRpc(
   process.env.SOLANA_RPC_URL ?? "https://api.mainnet-beta.solana.com"
 );
-async function postJson(path, body) {
-  const url = `${facilitatorBaseUrl}${path}`;
-  const serialized = JSON.stringify(body);
-  const response = await fetch(url, {
-    method: "POST",
-    headers: {
-      ...await walletAuthHeaders({
-        signer,
-        method: "POST",
-        url,
-        body: serialized
-      }),
-      "content-type": "application/json"
-    },
-    body: serialized
-  });
-  const text = await response.text();
-  if (response.status !== 200) {
-    fail(`[deposit] ${path} failed with ${response.status}: ${text}`);
-  }
-  return JSON.parse(text);
-}
+var vaultFlows = new VaultFlowClient({
+  facilitatorBaseUrl: relayerBaseUrl,
+  signer,
+  rpc
+});
 console.log(`[deposit] agent wallet: ${signer.walletAddress}`);
-console.log(`[deposit] facilitator:  ${facilitatorBaseUrl}`);
+console.log(`[deposit] relayer:  ${relayerBaseUrl}`);
 console.log("\n[deposit] step 0: ensure the wallet is registered (self-serve)");
-await ensureWalletOnboarded({ facilitatorBaseUrl, signer });
+await ensureWalletOnboarded({ facilitatorBaseUrl: relayerBaseUrl, signer });
 console.log("[deposit] wallet registered and synced");
 console.log(
   `
-[deposit] step 1: prepare deposit of ${formatRawUsdc(amountRawUsdc)} USDC`
+[deposit] step 1: deposit ${formatRawUsdc(amountRawUsdc)} USDC (prepare -> validate intent + sign locally -> sponsor submits)`
 );
-var prepared = await postJson("/v1/deposits/prepare", {
-  wallet: signer.walletAddress,
-  amountRawUsdc
-});
-console.log(`[deposit] prepared (depositId=${prepared.depositId})`);
-console.log(
-  "\n[deposit] step 2: validate the signing intent against the transaction, sign locally"
-);
-var signed = await signer.signDeposit({
-  intent: prepared.signingIntent,
-  serializedTransaction: prepared.serializedTransaction,
-  lookupTables: await fetchLookupTablesForTransaction(
-    rpc,
-    prepared.serializedTransaction
-  )
-});
-console.log("[deposit] agent signature attached");
-console.log("\n[deposit] step 3: submit (sponsor co-signs and broadcasts)");
-var submitted = await postJson("/v1/deposits/submit", {
-  depositId: prepared.depositId,
-  serializedTransaction: signed.serializedTransaction,
-  agentSignature: signed.agentSignature
-});
+var submitted;
+try {
+  submitted = await vaultFlows.deposit({ amountRawUsdc: BigInt(amountRawUsdc) });
+} catch (error) {
+  if (error instanceof VaultFlowClientError) {
+    fail(`[deposit] ${error.step} failed: ${error.message}`);
+  }
+  throw error;
+}
+console.log(`[deposit] depositId: ${submitted.depositId}`);
 console.log(`[deposit] status: ${submitted.status}`);
 if (submitted.txSignature !== null) {
   console.log(
     `[deposit] transaction: https://solscan.io/tx/${submitted.txSignature}`
   );
 }
+if (submitted.status === "submitted") {
+  fail(
+    `[deposit] broadcast but not yet confirmed \u2014 it may still land. Do NOT resubmit; check GET /v1/deposits/${submitted.depositId} (or the tx link above) first`
+  );
+}
 if (submitted.status !== "confirmed") {
   fail(
-    `[deposit] not confirmed (errorCode=${submitted.errorCode}); check GET /v1/deposits/${prepared.depositId} and the facilitator logs`
+    `[deposit] not confirmed (errorCode=${submitted.errorCode}); check GET /v1/deposits/${submitted.depositId} and the relayer logs`
   );
 }
 console.log(