@subly_fi/pay 0.2.0 → 0.4.0

package/dist/mcp-server.js

@@ -1,16 +1,12 @@
-// demo/mcp-server.ts
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import {
-  CallToolRequestSchema,
-  ListToolsRequestSchema
-} from "@modelcontextprotocol/sdk/types.js";
+// src/mcp-server.ts
+import { homedir } from "node:os";
+import { join as join2 } from "node:path";
 
-// 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,
@@ -25,8 +21,9 @@ import {
   setTransactionMessageLifetimeUsingBlockhash
 } from "@solana/kit";
 
-// src/lib/hash.ts
+// ../../src/lib/hash.ts
 import { createHash } from "node:crypto";
+var EMPTY_BODY_HASH = "sha256-e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
 function sha256TaggedHex(data) {
   return `sha256-${createHash("sha256").update(data).digest("hex")}`;
 }
@@ -50,7 +47,7 @@ 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"));
 }
@@ -70,11 +67,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";
@@ -90,7 +87,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,
@@ -105,7 +102,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");
@@ -123,12 +120,12 @@ function deriveAssociatedTokenAddress(params) {
     "associatedTokenProgramId"
   );
   for (let bump = 255; bump >= 0; bump -= 1) {
-    const address3 = createProgramAddress(
+    const address2 = createProgramAddress(
       [owner, tokenProgramId, mint, Uint8Array.of(bump)],
       associatedTokenProgramId
     );
-    if (address3 !== null) {
-      return bs582.encode(address3);
+    if (address2 !== null) {
+      return bs582.encode(address2);
     }
   }
   throw new Error("Unable to derive associated token account address");
@@ -197,7 +194,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";
@@ -883,7 +880,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;
@@ -953,7 +950,15 @@ var LocalKeypairAgentWalletSigner = class {
   }
 };
 
-// src/api/wallet-auth.ts
+// ../../src/client/mcp-payment-server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+
+// ../../src/api/wallet-auth.ts
 import { createHash as createHash3 } from "node:crypto";
 import bs585 from "bs58";
 import nacl from "tweetnacl";
@@ -971,7 +976,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({
@@ -987,7 +992,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) {
@@ -1044,187 +1049,7 @@ async function ensureWalletOnboarded(params) {
   await post("sync", `/v1/wallets/${wallet}/sync`, { source: "chain" });
 }
 
-// src/client/standard-x402-factory.ts
-import { createX402Client } from "x402-solana/client";
-
-// src/client/relayer-yield-realizer.ts
-import { address as address2 } from "@solana/kit";
-
-// src/client/lookup-tables.ts
-import { fetchAllMaybeAddressLookupTable } from "@solana-program/address-lookup-table";
-import { address, getCompiledTransactionMessageDecoder as getCompiledTransactionMessageDecoder2 } from "@solana/kit";
-function lookupTableAddressesForTransaction(serializedTransaction) {
-  const wire = Buffer.from(serializedTransaction, "base64");
-  let offset = 0;
-  let signatureCount = 0;
-  let shift = 0;
-  while (offset < wire.length) {
-    const byte = wire[offset];
-    signatureCount |= (byte & 127) << shift;
-    offset += 1;
-    if ((byte & 128) === 0) {
-      break;
-    }
-    shift += 7;
-  }
-  const messageBytes = wire.subarray(offset + signatureCount * 64);
-  const compiled = getCompiledTransactionMessageDecoder2().decode(messageBytes);
-  const lookups = compiled.addressTableLookups ?? [];
-  return lookups.map((lookup) => String(lookup.lookupTableAddress));
-}
-async function fetchLookupTablesForTransaction(rpc2, serializedTransaction) {
-  const addresses = lookupTableAddressesForTransaction(serializedTransaction);
-  if (addresses.length === 0) {
-    return {};
-  }
-  const tables = await fetchAllMaybeAddressLookupTable(
-    rpc2,
-    addresses.map((value) => address(value))
-  );
-  const result = {};
-  for (const table of tables) {
-    if (table.exists) {
-      result[table.address] = table.data.addresses.map(String);
-    }
-  }
-  return result;
-}
-
-// src/client/relayer-yield-realizer.ts
-var RelayerRealizeError = class extends Error {
-  constructor(code, message, detail = null) {
-    super(message);
-    this.code = code;
-    this.detail = detail;
-    this.name = "RelayerRealizeError";
-  }
-  code;
-  detail;
-};
-var RelayerYieldRealizer = class {
-  config;
-  signer;
-  rpc;
-  fetchImpl;
-  lookupTablesFor;
-  constructor(config) {
-    this.config = {
-      facilitatorBaseUrl: config.facilitatorBaseUrl.replace(/\/$/, ""),
-      usdcMint: config.usdcMint ?? SUBLY_VAULT.usdcMint
-    };
-    this.signer = config.signer;
-    this.rpc = config.rpc;
-    this.fetchImpl = config.fetchImpl ?? fetch;
-    this.lookupTablesFor = config.lookupTablesFor ?? ((serializedTransaction) => fetchLookupTablesForTransaction(this.rpc, serializedTransaction));
-  }
-  async ensureUsdcAvailable(input) {
-    const agentAta = deriveAssociatedTokenAddress({
-      owner: this.signer.walletAddress,
-      mint: this.config.usdcMint
-    });
-    const currentBalance = await this.readTokenBalance(agentAta);
-    if (currentBalance >= input.amountRawUsdc) {
-      return { realizedRawUsdc: 0n, txSignature: null };
-    }
-    const shortfallRawUsdc = input.amountRawUsdc - currentBalance;
-    await this.assertSpendableYield(shortfallRawUsdc);
-    const prepared = await this.postJson("/v1/withdrawals/prepare", {
-      wallet: this.signer.walletAddress,
-      amountRawUsdc: shortfallRawUsdc.toString()
-    });
-    const signed = await this.signer.signWithdrawal({
-      intent: prepared.signingIntent,
-      serializedTransaction: prepared.serializedTransaction,
-      lookupTables: await this.lookupTablesFor(prepared.serializedTransaction)
-    });
-    const submitted = await this.postJson("/v1/withdrawals/submit", {
-      withdrawalId: prepared.withdrawalId,
-      serializedTransaction: signed.serializedTransaction,
-      agentSignature: signed.agentSignature
-    });
-    if (submitted.status !== "confirmed" || submitted.txSignature === null) {
-      throw new RelayerRealizeError(
-        "realize_not_confirmed",
-        `yield realize withdrawal did not confirm (status=${submitted.status})`,
-        submitted
-      );
-    }
-    return {
-      realizedRawUsdc: BigInt(submitted.actualWithdrawRawUsdc ?? "0"),
-      txSignature: submitted.txSignature
-    };
-  }
-  /** Refuses to realize more than the ledger's spendable yield (principal). */
-  async assertSpendableYield(shortfallRawUsdc) {
-    const url = `${this.config.facilitatorBaseUrl}/v1/wallets/${this.signer.walletAddress}/budget`;
-    let response;
-    try {
-      response = await this.fetchImpl(url, {
-        headers: await walletAuthHeaders({
-          signer: this.signer,
-          method: "GET",
-          url
-        })
-      });
-    } catch (error) {
-      throw new RelayerRealizeError(
-        "budget_unavailable",
-        "could not read the spendable-yield budget",
-        error
-      );
-    }
-    if (response.status !== 200) {
-      throw new RelayerRealizeError(
-        "budget_unavailable",
-        `budget endpoint returned ${response.status}`
-      );
-    }
-    const body = await response.json();
-    const spendable = BigInt(body.budget?.spendableYieldRawUsdc ?? "0");
-    if (spendable < shortfallRawUsdc) {
-      throw new RelayerRealizeError(
-        "insufficient_yield",
-        `spendable yield ${spendable} cannot cover ${shortfallRawUsdc} raw USDC; the principal is never spent \u2014 wait for more yield`,
-        { spendableYieldRawUsdc: spendable.toString() }
-      );
-    }
-  }
-  async postJson(path, body) {
-    const url = `${this.config.facilitatorBaseUrl}${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 RelayerRealizeError(
-        path.endsWith("/submit") ? "submit_failed" : "prepare_failed",
-        `${path} failed with ${response.status}: ${text}`
-      );
-    }
-    return JSON.parse(text);
-  }
-  async readTokenBalance(ata) {
-    try {
-      const response = await this.rpc.getTokenAccountBalance(address2(ata), { commitment: "confirmed" }).send();
-      return BigInt(response.value.amount);
-    } catch {
-      return 0n;
-    }
-  }
-};
-
-// src/x402/headers.ts
+// ../../src/x402/headers.ts
 import { z } from "zod";
 var PAYMENT_REQUIRED_HEADER = "payment-required";
 var MAX_HEADER_JSON_BYTES = 16384;
@@ -1290,8 +1115,26 @@ function decodeX402Header(headerValue) {
     );
   }
 }
+function requestBodyHashFor(body) {
+  if (body === null || body === void 0 || body.length === 0) {
+    return EMPTY_BODY_HASH;
+  }
+  return sha256TaggedHex(
+    typeof body === "string" ? Buffer.from(body, "utf8") : Buffer.from(body)
+  );
+}
+
+// ../../src/client/paid-fetch.ts
+function formatRawUsdcAmount(raw) {
+  const value = BigInt(raw);
+  const negative = value < 0n;
+  const abs = negative ? -value : value;
+  const whole = abs / 1000000n;
+  const frac = (abs % 1000000n).toString().padStart(6, "0");
+  return `${negative ? "-" : ""}${whole}.${frac}`;
+}
 
-// src/x402/standard-requirements.ts
+// ../../src/x402/standard-requirements.ts
 import { z as z2 } from "zod";
 var STANDARD_EXACT_SCHEME = "exact";
 var standardExactRequirementSchema = z2.object({
@@ -1372,8 +1215,26 @@ function selectPayableSolanaRequirement(requirements, options) {
     feePayer: requirement.extra?.feePayer ?? null
   };
 }
+function standardRequirementMatchesSelected(candidate, selected) {
+  const parsed = standardExactRequirementSchema.safeParse(candidate);
+  return parsed.success && stableJson(parsed.data) === stableJson(selected.requirement);
+}
+function stableJson(value) {
+  return JSON.stringify(sortJson(value));
+}
+function sortJson(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortJson);
+  }
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).filter(([, entry]) => entry !== void 0).sort(([a], [b]) => a.localeCompare(b)).map(([key, entry]) => [key, sortJson(entry)])
+    );
+  }
+  return value;
+}
 
-// src/client/standard-x402-payer.ts
+// ../../src/client/standard-x402-payer.ts
 var StandardX402PayError = class extends Error {
   constructor(reason, message, detail = null) {
     super(message);
@@ -1391,6 +1252,10 @@ var StandardX402Payer = class {
   defaultMaxAmountRawUsdc;
   network;
   usdcMint;
+  stateStore;
+  pending = /* @__PURE__ */ new Map();
+  inFlight = /* @__PURE__ */ new Map();
+  nowMs;
   constructor(config) {
     this.realizer = config.realizer;
     this.x402Fetch = config.x402Fetch;
@@ -1398,10 +1263,59 @@ var StandardX402Payer = class {
     this.defaultMaxAmountRawUsdc = config.defaultMaxAmountRawUsdc;
     this.network = config.network ?? SOLANA_MAINNET_NETWORK;
     this.usdcMint = config.usdcMint ?? SUBLY_VAULT.usdcMint;
+    this.stateStore = config.stateStore ?? null;
+    this.nowMs = config.nowMs ?? (() => Date.now());
+    if (this.stateStore !== null) {
+      for (const record of this.stateStore.load()) {
+        this.pending.set(record.key, record);
+      }
+    }
+  }
+  pay(input) {
+    const method = (input.method ?? "GET").toUpperCase();
+    const requestBodyHash = requestBodyHashFor(input.body ?? null);
+    const pendingKey = pendingPaymentKey({
+      url: input.url,
+      method,
+      requestBodyHash
+    });
+    const existingFlow = this.inFlight.get(pendingKey);
+    if (existingFlow !== void 0) {
+      return existingFlow;
+    }
+    const flow = this.run(input, {
+      method,
+      requestBodyHash,
+      pendingKey
+    }).finally(() => {
+      this.inFlight.delete(pendingKey);
+    });
+    this.inFlight.set(pendingKey, flow);
+    return flow;
   }
-  async pay(input) {
+  async run(input, computed) {
+    const { method, requestBodyHash, pendingKey } = computed;
+    const existingPending = this.pending.get(pendingKey);
+    if (existingPending !== void 0 && input.forceNewPayment !== true) {
+      throw new StandardX402PayError(
+        "payment_outcome_unknown",
+        "a previous external x402 payment for this request has an unknown outcome. Verify whether it settled before purchasing again; to pay again anyway, call with forceNewPayment=true.",
+        existingPending
+      );
+    }
+    if (existingPending !== void 0 && input.forceNewPayment === true) {
+      try {
+        this.untrack(pendingKey);
+      } catch (error) {
+        throw new StandardX402PayError(
+          "state_persist_failed",
+          "could not clear the previous pending x402 marker before forcing a new payment",
+          error
+        );
+      }
+    }
     const init = {
-      method: input.method ?? "GET",
+      method,
       ...input.body === void 0 ? {} : { body: input.body },
       ...input.headers === void 0 ? {} : { headers: input.headers }
     };
@@ -1430,15 +1344,55 @@ var StandardX402Payer = class {
         error
       );
     }
-    const response = await this.x402Fetch(input.url, init);
+    const pendingRecord = {
+      key: pendingKey,
+      url: input.url,
+      method,
+      requestBodyHash,
+      amountRawUsdc: selected.amountRawUsdc.toString(),
+      payTo: selected.payTo,
+      feePayer: selected.feePayer,
+      realizedRawUsdc: realized.realizedRawUsdc.toString(),
+      realizeTxSignature: realized.txSignature,
+      status: "realized",
+      createdAtMs: this.nowMs(),
+      updatedAtMs: this.nowMs()
+    };
+    try {
+      this.track(pendingRecord);
+    } catch (error) {
+      throw new StandardX402PayError(
+        "state_persist_failed",
+        "could not persist the pending x402 marker; refusing to attempt the external payment because a restart would not be double-payment safe",
+        { error, pendingPayment: pendingRecord }
+      );
+    }
+    let response;
+    try {
+      response = await this.x402Fetch(input.url, init, selected);
+    } catch (error) {
+      const persistError = this.tryMarkUnknown(pendingKey, {
+        message: error instanceof Error ? error.message : String(error)
+      });
+      throw new StandardX402PayError(
+        "payment_outcome_unknown",
+        `the x402 payment attempt failed after yield was realized; verify whether it settled before paying again: ${error instanceof Error ? error.message : String(error)}`,
+        { error, persistError }
+      );
+    }
     const bodyText = await response.text();
     if (response.status !== 200) {
+      const persistError = this.tryMarkUnknown(pendingKey, {
+        status: response.status,
+        body: bodyText
+      });
       throw new StandardX402PayError(
-        "delivery_failed",
-        `the x402 payment did not deliver (status ${response.status})`,
-        { status: response.status, body: bodyText }
+        "payment_outcome_unknown",
+        `the x402 payment attempt returned ${response.status} after yield was realized; verify whether it settled before paying again`,
+        { status: response.status, body: bodyText, persistError }
       );
     }
+    this.clearDelivered(pendingKey);
     return {
       paid: true,
       status: response.status,
@@ -1484,260 +1438,971 @@ var StandardX402Payer = class {
       );
     }
   }
-};
-
-// src/client/web3-wallet-adapter.ts
-import { Keypair } from "@solana/web3.js";
-function createX402WalletAdapter(secretKey) {
-  if (secretKey.length !== 64) {
-    throw new Error("agent secret key must be 64 bytes");
+  track(record) {
+    const previous = this.pending.get(record.key);
+    this.pending.set(record.key, record);
+    try {
+      this.persist();
+    } catch (error) {
+      if (previous === void 0) {
+        this.pending.delete(record.key);
+      } else {
+        this.pending.set(record.key, previous);
+      }
+      throw error;
+    }
   }
-  const keypair = Keypair.fromSecretKey(secretKey);
-  return {
-    address: keypair.publicKey.toBase58(),
-    signTransaction: async (tx) => {
-      tx.sign([keypair]);
-      return tx;
+  markUnknown(key, detail) {
+    const current = this.pending.get(key);
+    if (current === void 0) {
+      return;
     }
-  };
-}
-
-// src/client/standard-x402-factory.ts
-function createStandardX402Payer(config) {
-  const realizer = new RelayerYieldRealizer({
-    facilitatorBaseUrl: config.facilitatorBaseUrl,
-    signer: config.signer,
-    rpc: config.rpc
-  });
-  const client = createX402Client({
-    wallet: createX402WalletAdapter(config.agentSecretKey),
-    network: config.network ?? "solana",
-    rpcUrl: config.rpcUrl
-  });
-  const x402Fetch = (url, init) => client.fetch(url, init);
-  return new StandardX402Payer({
-    realizer,
-    x402Fetch,
-    defaultMaxAmountRawUsdc: config.defaultMaxAmountRawUsdc
-  });
-}
-
-// src/client/paid-fetch.ts
-function formatRawUsdcAmount(raw) {
-  const value = BigInt(raw);
-  const negative = value < 0n;
-  const abs = negative ? -value : value;
-  const whole = abs / 1000000n;
-  const frac = (abs % 1000000n).toString().padStart(6, "0");
-  return `${negative ? "-" : ""}${whole}.${frac}`;
-}
-
-// src/solana/keys.ts
-import { readFileSync } from "node:fs";
-import bs586 from "bs58";
-import {
-  createKeyPairSignerFromBytes
-} from "@solana/kit";
-async function loadKeyPairSigner(params) {
-  const { base58Secret, jsonFilePath, label } = params;
-  if (base58Secret !== void 0 && base58Secret.length > 0) {
-    const bytes = bs586.decode(base58Secret);
-    if (bytes.length !== 64) {
-      throw new Error(`${label} base58 secret must decode to 64 bytes`);
+    const next = {
+      ...current,
+      status: "external_outcome_unknown",
+      updatedAtMs: this.nowMs(),
+      detail
+    };
+    this.pending.set(key, next);
+    try {
+      this.persist();
+    } catch (error) {
+      this.pending.set(key, current);
+      throw error;
     }
-    return createKeyPairSignerFromBytes(bytes);
   }
-  if (jsonFilePath !== void 0 && jsonFilePath.length > 0) {
-    const raw = JSON.parse(readFileSync(jsonFilePath, "utf8"));
-    if (!Array.isArray(raw) || raw.length !== 64) {
-      throw new Error(`${label} keypair file must be a 64-byte JSON array`);
+  tryMarkUnknown(key, detail) {
+    try {
+      this.markUnknown(key, detail);
+      return null;
+    } catch (error) {
+      return error;
     }
-    return createKeyPairSignerFromBytes(Uint8Array.from(raw));
   }
-  throw new Error(`${label} keypair is not configured`);
-}
-function loadSecretKeyBytes(params) {
-  const { base58Secret, jsonFilePath, label } = params;
-  if (base58Secret !== void 0 && base58Secret.length > 0) {
-    const bytes = bs586.decode(base58Secret);
-    if (bytes.length !== 64) {
-      throw new Error(`${label} base58 secret must decode to 64 bytes`);
-    }
-    return bytes;
+  untrack(key) {
+    const previous = this.pending.get(key);
+    const existed = previous !== void 0;
+    this.pending.delete(key);
+    try {
+      this.persist();
+    } catch (error) {
+      if (existed) {
+        this.pending.set(key, previous);
+      }
+      throw error;
+    }
   }
-  if (jsonFilePath !== void 0 && jsonFilePath.length > 0) {
-    const raw = JSON.parse(readFileSync(jsonFilePath, "utf8"));
-    if (!Array.isArray(raw) || raw.length !== 64) {
-      throw new Error(`${label} keypair file must be a 64-byte JSON array`);
+  clearDelivered(key) {
+    const previous = this.pending.get(key);
+    this.pending.delete(key);
+    try {
+      this.persist();
+    } catch (error) {
+      if (previous !== void 0) {
+        this.pending.set(key, previous);
+      }
+      console.error(
+        `[subly-x402] payment delivered but pending marker could not be cleared: ${error instanceof Error ? error.message : String(error)}`
+      );
     }
-    return Uint8Array.from(raw);
   }
-  throw new Error(`${label} keypair is not configured`);
+  persist() {
+    if (this.stateStore === null) {
+      return;
+    }
+    this.stateStore.save([...this.pending.values()]);
+  }
+};
+function pendingPaymentKey(input) {
+  return `${input.method}:${input.url}:${input.requestBodyHash}`;
 }
 
-// src/solana/rpc.ts
-import { createSolanaRpc } from "@solana/kit";
-function createRpc(url) {
-  return createSolanaRpc(url);
+// ../../src/client/lookup-tables.ts
+import { fetchAllMaybeAddressLookupTable } from "@solana-program/address-lookup-table";
+import { address, getCompiledTransactionMessageDecoder as getCompiledTransactionMessageDecoder2 } from "@solana/kit";
+function lookupTableAddressesForTransaction(serializedTransaction) {
+  const wire = Buffer.from(serializedTransaction, "base64");
+  let offset = 0;
+  let signatureCount = 0;
+  let shift = 0;
+  while (offset < wire.length) {
+    const byte = wire[offset];
+    signatureCount |= (byte & 127) << shift;
+    offset += 1;
+    if ((byte & 128) === 0) {
+      break;
+    }
+    shift += 7;
+  }
+  const messageBytes = wire.subarray(offset + signatureCount * 64);
+  const compiled = getCompiledTransactionMessageDecoder2().decode(messageBytes);
+  const lookups = compiled.addressTableLookups ?? [];
+  return lookups.map((lookup) => String(lookup.lookupTableAddress));
+}
+async function fetchLookupTablesForTransaction(rpc2, serializedTransaction) {
+  const addresses = lookupTableAddressesForTransaction(serializedTransaction);
+  if (addresses.length === 0) {
+    return {};
+  }
+  const tables = await fetchAllMaybeAddressLookupTable(
+    rpc2,
+    addresses.map((value) => address(value))
+  );
+  const result = {};
+  for (const table of tables) {
+    if (table.exists) {
+      result[table.address] = table.data.addresses.map(String);
+    }
+  }
+  return result;
 }
 
-// demo/mcp-server.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/client/mcp-payment-server.ts
 var TOOL_NAME = "fetch_with_subly_payment";
-var DEFAULT_MAX_AMOUNT_RAW_USDC = 10000n;
-var facilitatorBaseUrl = process.env.SUBLY_FACILITATOR_URL ?? "https://api.demo.sublyfi.com";
-var rpcUrl = process.env.SOLANA_RPC_URL ?? "https://api.mainnet-beta.solana.com";
-var defaultMaxAmountRawUsdc = process.env.SUBLY_MCP_MAX_AMOUNT_RAW_USDC === void 0 ? DEFAULT_MAX_AMOUNT_RAW_USDC : BigInt(process.env.SUBLY_MCP_MAX_AMOUNT_RAW_USDC);
-var keyPairSigner = await loadKeyPairSigner({
-  base58Secret: process.env.SUBLY_DEMO_AGENT_KEYPAIR,
-  jsonFilePath: process.env.SUBLY_DEMO_AGENT_KEYPAIR_PATH,
-  label: "SUBLY_DEMO_AGENT_KEYPAIR"
-});
-var agentSecretKey = loadSecretKeyBytes({
-  base58Secret: process.env.SUBLY_DEMO_AGENT_KEYPAIR,
-  jsonFilePath: process.env.SUBLY_DEMO_AGENT_KEYPAIR_PATH,
-  label: "SUBLY_DEMO_AGENT_KEYPAIR"
-});
-var signer = new LocalKeypairAgentWalletSigner(keyPairSigner);
-var rpc = createRpc(rpcUrl);
-var payer = createStandardX402Payer({
-  facilitatorBaseUrl,
-  signer,
-  agentSecretKey,
-  rpc,
-  rpcUrl,
-  defaultMaxAmountRawUsdc
-});
+var DEPOSIT_TOOL_NAME = "deposit_to_subly_vault";
+var WITHDRAW_TOOL_NAME = "withdraw_from_subly_vault";
+var BUDGET_TOOL_NAME = "get_subly_yield_budget";
 var SERVER_INSTRUCTIONS = `Subly lets an agent pay for ANY standard x402 (HTTP 402) paid API from its wallet's Kamino vault YIELD \u2014 the deposited principal is never spent, and the seller needs no Subly integration.
 
-Before payments can succeed the operator of this server must have, once:
-1. A Solana keypair for the agent wallet. Subly does NOT create wallets; make one with \`solana-keygen new -o agent.json\` (or export a keypair from an existing wallet) and point SUBLY_DEMO_AGENT_KEYPAIR_PATH at it. The private key never leaves that file; this server only signs locally with it.
-2. Funded that wallet with USDC on Solana mainnet (no SOL needed \u2014 realize fees are sponsored) and deposited into the vault (see the project's deposit command). The vault minimum deposit is 1 USDC.
-3. Waited for yield to accrue; a payment needs the seller's price of spendable yield.
+One-time setup: the operator needs a Solana keypair for the agent wallet. Subly does NOT create wallets; make one with \`solana-keygen new -o agent.json\` (or export a keypair from an existing wallet) and point SUBLY_DEMO_AGENT_KEYPAIR_PATH at it. The private key never leaves that file; this server only signs locally with it. Then fund the wallet with USDC on Solana mainnet \u2014 no SOL is ever needed, all vault transaction fees are sponsored.
 
-Then use fetch_with_subly_payment(url) to GET a paid resource from any x402 seller (e.g. Nansen): it realizes just enough yield to the agent's USDC ATA and pays the seller's standard x402 challenge, returning the body plus the payment details. If it returns insufficient_yield, that is expected \u2014 wait for yield, do not loop.`;
-var server = new Server(
-  { name: "subly-payments", version: "0.2.0" },
-  { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS }
-);
-server.setRequestHandler(ListToolsRequestSchema, () => ({
-  tools: [
+From there the agent can do everything with these tools:
+1. deposit_to_subly_vault(amountRawUsdc) puts wallet USDC into the vault (minimum 1 USDC = 1000000 raw) so it starts earning yield.
+2. get_subly_yield_budget() shows the principal, position value, and the spendable yield a payment can use right now.
+3. fetch_with_subly_payment(url) GETs or POSTs a paid resource from any x402 seller (e.g. Nansen): it realizes just enough yield to the agent's USDC ATA and pays the seller's standard x402 challenge, returning the body plus the payment details. If it returns insufficient_yield, that is expected \u2014 yield accrues over time; wait, do not loop.
+4. withdraw_from_subly_vault(amountRawUsdc) exits: moves vault funds (principal included) back to the agent wallet's USDC account.`;
+async function runMcpPaymentServer(config) {
+  const { payer: payer2, signer: signer2, facilitatorBaseUrl, defaultMaxAmountRawUsdc: defaultMaxAmountRawUsdc2 } = config;
+  const vaultFlows = config.vaultFlows ?? null;
+  const server = new Server(
+    { name: "subly-payments", version: config.serverVersion ?? "0.3.0" },
+    { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS }
+  );
+  const vaultTools = vaultFlows === null ? [] : [
     {
-      name: TOOL_NAME,
-      description: `GET a URL, automatically paying a standard x402 (HTTP 402) challenge from any x402-compatible seller (Nansen, etc.) out of the agent wallet's Kamino vault yield. Subly realizes just enough yield to the agent's USDC ATA (sponsored) and pays the seller's Solana USDC \`exact\` challenge; the seller needs no Subly integration. Returns the response body and, when a payment was made, the payment details (amount, payee, realize tx). Challenges above maxAmountRawUsdc (default ${defaultMaxAmountRawUsdc} raw = ${formatRawUsdcAmount(
-        defaultMaxAmountRawUsdc
-      )} USDC) are refused without paying. Payments are refused when the spendable yield budget cannot cover them \u2014 the principal is never spent. Use only for URLs you intend to purchase access to.`,
+      name: DEPOSIT_TOOL_NAME,
+      description: "Deposit USDC from the agent wallet into the Subly/Kamino vault so it starts earning the yield that funds x402 payments. The transaction fee is sponsored \u2014 the agent wallet needs USDC only, never SOL. The vault minimum deposit is 1 USDC (1000000 raw). The deposited amount becomes protected principal: payments can only ever spend the yield on top of it.",
       inputSchema: {
         type: "object",
         properties: {
-          url: {
+          amountRawUsdc: {
             type: "string",
-            description: "URL to fetch (GET). Must match the seller's resource URL exactly."
-          },
-          maxAmountRawUsdc: {
+            description: 'Amount to deposit in raw USDC units (6 decimals, e.g. "1000000" = 1 USDC). Must be at least 1000000.'
+          }
+        },
+        required: ["amountRawUsdc"]
+      },
+      annotations: {
+        title: "Deposit into the Subly vault",
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+      }
+    },
+    {
+      name: WITHDRAW_TOOL_NAME,
+      description: "Withdraw USDC from the Subly/Kamino vault back to the agent wallet's USDC account (fee sponsored, no SOL needed). This is the exit path and may spend PRINCIPAL \u2014 it reduces the deposit that earns yield. Limited to the vault's instant liquidity.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          amountRawUsdc: {
             type: "string",
-            description: 'Refuse (without paying) any challenge above this amount in raw USDC units (6 decimals, e.g. "10000" = 0.01 USDC). Defaults to the server-side cap.'
+            description: 'Amount to withdraw in raw USDC units (6 decimals, e.g. "1000000" = 1 USDC).'
           }
         },
-        required: ["url"]
+        required: ["amountRawUsdc"]
       },
       annotations: {
-        title: "Fetch with Subly payment",
+        title: "Withdraw from the Subly vault",
         readOnlyHint: false,
         destructiveHint: true,
         idempotentHint: false,
-        openWorldHint: true
+        openWorldHint: false
       }
+    },
+    {
+      name: BUDGET_TOOL_NAME,
+      description: "Show the agent wallet's Subly vault budget: protected principal, current position value, and the spendable yield available for x402 payments right now. Syncs the position from chain first, so newly accrued yield is included.",
+      inputSchema: { type: "object", properties: {} },
+      annotations: {
+        title: "Get Subly yield budget",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    }
+  ];
+  server.setRequestHandler(ListToolsRequestSchema, () => ({
+    tools: [
+      ...vaultTools,
+      {
+        name: TOOL_NAME,
+        description: `Fetch a URL (GET or POST), automatically paying a standard x402 (HTTP 402) challenge from any x402-compatible seller (Nansen, etc.) out of the agent wallet's Kamino vault yield. Subly realizes just enough yield to the agent's USDC ATA (sponsored) and pays the seller's Solana USDC \`exact\` challenge; the seller needs no Subly integration. Returns the response body and, when a payment was made, the payment details (amount, payee, realize tx). Challenges above maxAmountRawUsdc (default ${defaultMaxAmountRawUsdc2} raw = ${formatRawUsdcAmount(
+          defaultMaxAmountRawUsdc2
+        )} USDC) are refused without paying. Payments are refused when the spendable yield budget cannot cover them \u2014 the principal is never spent. Use only for URLs you intend to purchase access to.`,
+        inputSchema: {
+          type: "object",
+          properties: {
+            url: {
+              type: "string",
+              description: "URL to fetch. Must match the seller's resource URL exactly."
+            },
+            method: {
+              type: "string",
+              description: "HTTP method (default GET). Some x402 sellers deliver the paid resource over POST (e.g. an API that takes a JSON body)."
+            },
+            body: {
+              type: "string",
+              description: "Request body sent on both the probe and the paid retry. Provide a JSON string for POST sellers; sent as content-type application/json unless headers override it."
+            },
+            headers: {
+              type: "object",
+              description: "Extra request headers (object of string values), merged into both the probe and the paid retry.",
+              additionalProperties: { type: "string" }
+            },
+            maxAmountRawUsdc: {
+              type: "string",
+              description: 'Refuse (without paying) any challenge above this amount in raw USDC units (6 decimals, e.g. "10000" = 0.01 USDC). Defaults to the server-side cap.'
+            },
+            forceNewPayment: {
+              type: "boolean",
+              description: "Pay again even if a previous external x402 attempt for the same URL/method/body has an unknown outcome. This may pay twice for the same resource."
+            }
+          },
+          required: ["url"]
+        },
+        annotations: {
+          title: "Fetch with Subly payment",
+          readOnlyHint: false,
+          destructiveHint: true,
+          idempotentHint: false,
+          openWorldHint: true
+        }
+      }
+    ]
+  }));
+  const textResult = (value, isError = false) => ({
+    content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+    ...isError ? { isError: true } : {}
+  });
+  const vaultFlowFailure = (error) => {
+    if (error instanceof VaultFlowClientError) {
+      return textResult(
+        { ok: false, step: error.step, message: error.message },
+        true
+      );
     }
-  ]
-}));
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  if (request.params.name !== TOOL_NAME) {
     return {
       content: [
-        { type: "text", text: `unknown tool: ${request.params.name}` }
+        {
+          type: "text",
+          text: error instanceof Error ? error.message : String(error)
+        }
       ],
       isError: true
     };
-  }
-  const args = request.params.arguments ?? {};
-  const url = args.url;
-  if (typeof url !== "string" || url.length === 0) {
-    return {
-      content: [{ type: "text", text: "missing required argument: url" }],
-      isError: true
-    };
-  }
-  let maxAmountRawUsdc;
-  if (args.maxAmountRawUsdc !== void 0) {
-    const raw = args.maxAmountRawUsdc;
+  };
+  const parseRawAmount = (value) => {
+    if (typeof value !== "string" && typeof value !== "number") {
+      return null;
+    }
     try {
-      if (typeof raw !== "string" && typeof raw !== "number") {
-        throw new TypeError("not a string or number");
-      }
-      maxAmountRawUsdc = BigInt(raw);
+      const amount = BigInt(value);
+      return amount > 0n ? amount : null;
     } catch {
-      return {
-        content: [
+      return null;
+    }
+  };
+  const vaultFlowOutcome = (outcome, amountField) => {
+    const solscanUrl = outcome.txSignature === null ? null : `https://solscan.io/tx/${outcome.txSignature}`;
+    if (outcome.status === "submitted") {
+      return textResult(
+        {
+          ...outcome,
+          ...amountField,
+          solscanUrl,
+          stillConfirming: true,
+          warning: "the transaction was broadcast but had not confirmed before the poll timeout. Do NOT submit this deposit/withdrawal again \u2014 it may still confirm and moving the funds twice is not what the user asked for. Check get_subly_yield_budget in a minute, or the solscanUrl."
+        },
+        true
+      );
+    }
+    return textResult(
+      { ...outcome, ...amountField, solscanUrl },
+      outcome.status !== "confirmed"
+    );
+  };
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const vaultToolNames = [
+      BUDGET_TOOL_NAME,
+      DEPOSIT_TOOL_NAME,
+      WITHDRAW_TOOL_NAME
+    ];
+    if (vaultFlows !== null && vaultToolNames.includes(request.params.name)) {
+      try {
+        await ensureWalletOnboarded({ facilitatorBaseUrl, signer: signer2 });
+      } catch {
+      }
+      if (request.params.name === BUDGET_TOOL_NAME) {
+        try {
+          const budget = await vaultFlows.getBudget();
+          return textResult({
+            ...budget,
+            principalUsdc: formatRawUsdcAmount(
+              BigInt(budget.principalBasisRawUsdc)
+            ),
+            positionValueUsdc: formatRawUsdcAmount(
+              BigInt(budget.positionValueRawUsdc)
+            ),
+            spendableYieldUsdc: formatRawUsdcAmount(
+              BigInt(budget.spendableYieldRawUsdc)
+            )
+          });
+        } catch (error) {
+          return vaultFlowFailure(error);
+        }
+      }
+      const amountRawUsdc = parseRawAmount(
+        (request.params.arguments ?? {}).amountRawUsdc
+      );
+      if (amountRawUsdc === null) {
+        return textResult(
           {
-            type: "text",
-            text: "maxAmountRawUsdc must be an integer raw USDC amount"
-          }
-        ],
+            ok: false,
+            message: 'amountRawUsdc must be a positive integer raw USDC amount (6 decimals, e.g. "1000000" = 1 USDC)'
+          },
+          true
+        );
+      }
+      try {
+        if (request.params.name === DEPOSIT_TOOL_NAME) {
+          const outcome2 = await vaultFlows.deposit({ amountRawUsdc });
+          return vaultFlowOutcome(outcome2, {
+            depositedUsdc: formatRawUsdcAmount(
+              BigInt(outcome2.actualDepositRawUsdc ?? "0")
+            )
+          });
+        }
+        const outcome = await vaultFlows.withdraw({ amountRawUsdc });
+        return vaultFlowOutcome(outcome, {
+          withdrawnUsdc: formatRawUsdcAmount(
+            BigInt(outcome.actualWithdrawRawUsdc ?? "0")
+          )
+        });
+      } catch (error) {
+        return vaultFlowFailure(error);
+      }
+    }
+    if (request.params.name !== TOOL_NAME) {
+      return {
+        content: [{ type: "text", text: `unknown tool: ${request.params.name}` }],
         isError: true
       };
     }
-  }
-  try {
-    const result = await payer.pay({
-      url,
-      ...maxAmountRawUsdc === void 0 ? {} : { maxAmountRawUsdc }
-    });
-    return {
-      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
-    };
-  } catch (error) {
-    if (error instanceof StandardX402PayError) {
+    const args = request.params.arguments ?? {};
+    const url = args.url;
+    if (typeof url !== "string" || url.length === 0) {
+      return {
+        content: [{ type: "text", text: "missing required argument: url" }],
+        isError: true
+      };
+    }
+    let maxAmountRawUsdc;
+    if (args.maxAmountRawUsdc !== void 0) {
+      const raw = args.maxAmountRawUsdc;
+      try {
+        if (typeof raw !== "string" && typeof raw !== "number") {
+          throw new TypeError("not a string or number");
+        }
+        maxAmountRawUsdc = BigInt(raw);
+      } catch {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "maxAmountRawUsdc must be an integer raw USDC amount"
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+    const method = typeof args.method === "string" ? args.method : void 0;
+    const body = typeof args.body === "string" ? args.body : void 0;
+    const forceNewPayment = args.forceNewPayment === true;
+    const headers = args.headers !== null && typeof args.headers === "object" && !Array.isArray(args.headers) ? Object.fromEntries(
+      Object.entries(args.headers).filter(([, v]) => typeof v === "string").map(([k, v]) => [k, v])
+    ) : void 0;
+    const mergedHeaders = body === void 0 ? headers : { "content-type": "application/json", ...headers ?? {} };
+    try {
+      const result = await payer2.pay({
+        url,
+        ...method === void 0 ? {} : { method },
+        ...body === void 0 ? {} : { body },
+        ...mergedHeaders === void 0 ? {} : { headers: mergedHeaders },
+        ...maxAmountRawUsdc === void 0 ? {} : { maxAmountRawUsdc },
+        ...forceNewPayment ? { forceNewPayment } : {}
+      });
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+      };
+    } catch (error) {
+      if (error instanceof StandardX402PayError) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  paid: false,
+                  refused: true,
+                  reason: error.reason,
+                  message: error.message,
+                  detail: error.detail
+                },
+                null,
+                2
+              )
+            }
+          ],
+          isError: true
+        };
+      }
       return {
         content: [
           {
             type: "text",
-            text: JSON.stringify(
-              {
-                paid: false,
-                refused: true,
-                reason: error.reason,
-                message: error.message,
-                detail: error.detail
-              },
-              null,
-              2
-            )
+            text: error instanceof Error ? error.message : String(error)
           }
         ],
         isError: true
       };
     }
+  });
+  try {
+    await ensureWalletOnboarded({ facilitatorBaseUrl, signer: signer2 });
+    console.error("[subly-mcp] wallet registered and synced at the relayer");
+  } catch (error) {
+    console.error(
+      `[subly-mcp] wallet onboarding failed (will still serve tools): ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(
+    `[subly-mcp] ready: agent wallet ${signer2.walletAddress}, relayer ${facilitatorBaseUrl}, default cap ${formatRawUsdcAmount(defaultMaxAmountRawUsdc2)} USDC`
+  );
+}
+
+// ../../src/client/relayer-yield-realizer.ts
+var REALIZE_OVERHEAD_RAW_USDC = 2500n;
+var RelayerRealizeError = class extends Error {
+  constructor(code, message, detail = null) {
+    super(message);
+    this.code = code;
+    this.detail = detail;
+    this.name = "RelayerRealizeError";
+  }
+  code;
+  detail;
+};
+var RelayerYieldRealizer = class {
+  vaultFlows;
+  constructor(config) {
+    this.vaultFlows = new VaultFlowClient({
+      facilitatorBaseUrl: config.facilitatorBaseUrl,
+      signer: config.signer,
+      rpc: config.rpc,
+      ...config.fetchImpl === void 0 ? {} : { fetchImpl: config.fetchImpl },
+      ...config.lookupTablesFor === void 0 ? {} : { lookupTablesFor: config.lookupTablesFor }
+    });
+  }
+  async ensureUsdcAvailable(input) {
+    const shortfallRawUsdc = input.amountRawUsdc;
+    await this.assertSpendableYield(shortfallRawUsdc);
+    let outcome;
+    try {
+      outcome = await this.vaultFlows.withdraw({
+        amountRawUsdc: shortfallRawUsdc,
+        // The relayer refuses to prepare this withdrawal beyond the spendable
+        // yield — the principal-protection guard the client cannot bypass.
+        purpose: "yield_realize"
+      });
+    } catch (error) {
+      throw this.mapWithdrawError(error);
+    }
+    if (outcome.status !== "confirmed" || outcome.txSignature === null) {
+      throw new RelayerRealizeError(
+        "realize_not_confirmed",
+        `yield realize withdrawal did not confirm (status=${outcome.status})`,
+        outcome
+      );
+    }
     return {
-      content: [
+      realizedRawUsdc: BigInt(outcome.actualWithdrawRawUsdc ?? "0"),
+      txSignature: outcome.txSignature
+    };
+  }
+  /**
+   * Refuses to realize more than the ledger's spendable yield (principal).
+   * getBudget syncs the relayer's ledger from chain first (best-effort), so a
+   * long-running client sees yield as it accrues instead of a frozen view.
+   */
+  async assertSpendableYield(shortfallRawUsdc) {
+    let spendable;
+    try {
+      const budget = await this.vaultFlows.getBudget();
+      spendable = BigInt(budget.spendableYieldRawUsdc);
+    } catch (error) {
+      throw new RelayerRealizeError(
+        "budget_unavailable",
+        "could not read the spendable-yield budget",
+        error
+      );
+    }
+    const requiredRawUsdc = shortfallRawUsdc + REALIZE_OVERHEAD_RAW_USDC;
+    if (spendable < requiredRawUsdc) {
+      throw new RelayerRealizeError(
+        "insufficient_yield",
+        `spendable yield ${spendable} cannot cover ${shortfallRawUsdc} raw USDC plus the ${REALIZE_OVERHEAD_RAW_USDC} raw fee headroom; the principal is never spent \u2014 wait for more yield`,
+        { spendableYieldRawUsdc: spendable.toString() }
+      );
+    }
+  }
+  mapWithdrawError(error) {
+    if (!(error instanceof VaultFlowClientError)) {
+      return new RelayerRealizeError(
+        "prepare_failed",
+        `yield realize failed: ${error instanceof Error ? error.message : String(error)}`,
+        error
+      );
+    }
+    const serverCode = errorCodeFrom(error.detail);
+    if (serverCode === "insufficient_yield" || serverCode === "post_state_principal_invariant_failed") {
+      return new RelayerRealizeError(
+        "insufficient_yield",
+        "the relayer refused to realize beyond the spendable yield; the principal is never spent \u2014 wait for more yield",
+        error.detail
+      );
+    }
+    return new RelayerRealizeError(
+      error.step === "submit" ? "submit_failed" : "prepare_failed",
+      error.message,
+      error.detail
+    );
+  }
+};
+function errorCodeFrom(detail) {
+  if (typeof detail !== "string") {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(detail);
+    return typeof parsed.error?.code === "string" ? parsed.error.code : null;
+  } catch {
+    return null;
+  }
+}
+
+// ../../src/client/relayer-payer.ts
+function createRelayerX402Payer(config) {
+  const realizer = new RelayerYieldRealizer({
+    facilitatorBaseUrl: config.facilitatorBaseUrl,
+    signer: config.signer,
+    rpc: config.rpc
+  });
+  return new StandardX402Payer({
+    realizer,
+    x402Fetch: config.x402Fetch,
+    defaultMaxAmountRawUsdc: config.defaultMaxAmountRawUsdc,
+    ...config.stateStore === void 0 ? {} : { stateStore: config.stateStore }
+  });
+}
+
+// ../../src/client/standard-x402-state-store.ts
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+function fileStandardX402StateStore(path) {
+  return {
+    load() {
+      let text;
+      try {
+        text = readFileSync(path, "utf8");
+      } catch (error) {
+        if (isMissingFileError(error)) {
+          return [];
+        }
+        throw error;
+      }
+      const parsed = JSON.parse(text);
+      if (!Array.isArray(parsed)) {
+        throw new Error(`pending payment state is not an array: ${path}`);
+      }
+      for (const [index, record] of parsed.entries()) {
+        if (!isPendingPaymentRecord(record)) {
+          throw new Error(
+            `pending payment state has an invalid record at index ${index}: ${path}`
+          );
+        }
+      }
+      return parsed;
+    },
+    save(records) {
+      const directory = dirname(path);
+      mkdirSync(directory, { recursive: true });
+      const tempPath = join(
+        directory,
+        `.${basename(path)}.${process.pid}.${Date.now()}.tmp`
+      );
+      writeFileSync(tempPath, JSON.stringify(records, null, 2));
+      renameSync(tempPath, path);
+    }
+  };
+}
+function isMissingFileError(error) {
+  return error !== null && typeof error === "object" && "code" in error && error.code === "ENOENT";
+}
+function isPendingPaymentRecord(value) {
+  if (value === null || typeof value !== "object") {
+    return false;
+  }
+  const record = value;
+  return typeof record.key === "string" && typeof record.url === "string" && typeof record.method === "string" && typeof record.requestBodyHash === "string" && typeof record.amountRawUsdc === "string" && typeof record.payTo === "string" && (record.feePayer === null || typeof record.feePayer === "string") && typeof record.realizedRawUsdc === "string" && (record.realizeTxSignature === null || typeof record.realizeTxSignature === "string") && (record.status === "realized" || record.status === "external_outcome_unknown") && typeof record.createdAtMs === "number" && typeof record.updatedAtMs === "number";
+}
+
+// ../../src/solana/keys.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+import bs586 from "bs58";
+import {
+  createKeyPairSignerFromBytes
+} from "@solana/kit";
+async function loadKeyPairSigner(params) {
+  const { base58Secret, jsonFilePath, label } = params;
+  if (base58Secret !== void 0 && base58Secret.length > 0) {
+    const bytes = bs586.decode(base58Secret);
+    if (bytes.length !== 64) {
+      throw new Error(`${label} base58 secret must decode to 64 bytes`);
+    }
+    return createKeyPairSignerFromBytes(bytes);
+  }
+  if (jsonFilePath !== void 0 && jsonFilePath.length > 0) {
+    const raw = JSON.parse(readFileSync2(jsonFilePath, "utf8"));
+    if (!Array.isArray(raw) || raw.length !== 64) {
+      throw new Error(`${label} keypair file must be a 64-byte JSON array`);
+    }
+    return createKeyPairSignerFromBytes(Uint8Array.from(raw));
+  }
+  throw new Error(`${label} keypair is not configured`);
+}
+function loadSecretKeyBytes(params) {
+  const { base58Secret, jsonFilePath, label } = params;
+  if (base58Secret !== void 0 && base58Secret.length > 0) {
+    const bytes = bs586.decode(base58Secret);
+    if (bytes.length !== 64) {
+      throw new Error(`${label} base58 secret must decode to 64 bytes`);
+    }
+    return bytes;
+  }
+  if (jsonFilePath !== void 0 && jsonFilePath.length > 0) {
+    const raw = JSON.parse(readFileSync2(jsonFilePath, "utf8"));
+    if (!Array.isArray(raw) || raw.length !== 64) {
+      throw new Error(`${label} keypair file must be a 64-byte JSON array`);
+    }
+    return Uint8Array.from(raw);
+  }
+  throw new Error(`${label} keypair is not configured`);
+}
+
+// ../../src/solana/rpc.ts
+import { createSolanaRpc } from "@solana/kit";
+function createRpc(url) {
+  return createSolanaRpc(url);
+}
+
+// src/svm-x402-fetch.ts
+import { createKeyPairSignerFromBytes as createKeyPairSignerFromBytes2 } from "@solana/kit";
+import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
+import { ExactSvmScheme, toClientSvmSigner } from "@x402/svm";
+async function createSvmX402Fetch(params) {
+  const signer2 = toClientSvmSigner(
+    await createKeyPairSignerFromBytes2(params.agentSecretKey)
+  );
+  return (url, init, expected) => {
+    const wrapped = wrapFetchWithPaymentFromConfig(fetch, {
+      schemes: [
         {
-          type: "text",
-          text: error instanceof Error ? error.message : String(error)
+          network: expected.requirement.network,
+          client: new ExactSvmScheme(signer2, { rpcUrl: params.rpcUrl })
         }
       ],
-      isError: true
-    };
-  }
-});
-try {
-  await ensureWalletOnboarded({ facilitatorBaseUrl, signer });
-  console.error("[subly-mcp] wallet registered and synced at the relayer");
-} catch (error) {
-  console.error(
-    `[subly-mcp] wallet onboarding failed (will still serve tools): ${error instanceof Error ? error.message : String(error)}`
+      paymentRequirementsSelector: (_x402Version, requirements) => selectExpectedRequirement(requirements, expected)
+    });
+    return wrapped(url, init);
+  };
+}
+function selectExpectedRequirement(requirements, expected) {
+  const match = requirements.find(
+    (candidate) => standardRequirementMatchesSelected(candidate, expected)
   );
+  if (match === void 0) {
+    throw new Error(
+      "x402 challenge changed after preflight; refusing to pay an unchecked requirement"
+    );
+  }
+  return match;
 }
-var transport = new StdioServerTransport();
-await server.connect(transport);
-console.error(
-  `[subly-mcp] ready: agent wallet ${signer.walletAddress}, relayer ${facilitatorBaseUrl}, default cap ${formatRawUsdcAmount(defaultMaxAmountRawUsdc)} USDC`
-);
+
+// src/mcp-server.ts
+var relayerBaseUrl = process.env.SUBLY_RELAYER_URL ?? process.env.SUBLY_FACILITATOR_URL ?? "https://api.demo.sublyfi.com";
+var rpcUrl = process.env.SOLANA_RPC_URL ?? "https://api.mainnet-beta.solana.com";
+var defaultMaxAmountRawUsdc = process.env.SUBLY_MCP_MAX_AMOUNT_RAW_USDC === void 0 ? 10000n : BigInt(process.env.SUBLY_MCP_MAX_AMOUNT_RAW_USDC);
+var pendingStatePath = process.env.SUBLY_MCP_STATE_PATH ?? join2(homedir(), ".subly", "standard-x402-pending.json");
+var keyPairSigner = await loadKeyPairSigner({
+  base58Secret: process.env.SUBLY_DEMO_AGENT_KEYPAIR,
+  jsonFilePath: process.env.SUBLY_DEMO_AGENT_KEYPAIR_PATH,
+  label: "SUBLY_DEMO_AGENT_KEYPAIR"
+});
+var agentSecretKey = loadSecretKeyBytes({
+  base58Secret: process.env.SUBLY_DEMO_AGENT_KEYPAIR,
+  jsonFilePath: process.env.SUBLY_DEMO_AGENT_KEYPAIR_PATH,
+  label: "SUBLY_DEMO_AGENT_KEYPAIR"
+});
+var signer = new LocalKeypairAgentWalletSigner(keyPairSigner);
+var rpc = createRpc(rpcUrl);
+var payer = createRelayerX402Payer({
+  facilitatorBaseUrl: relayerBaseUrl,
+  signer,
+  rpc,
+  x402Fetch: await createSvmX402Fetch({ agentSecretKey, rpcUrl }),
+  defaultMaxAmountRawUsdc,
+  stateStore: fileStandardX402StateStore(pendingStatePath)
+});
+await runMcpPaymentServer({
+  payer,
+  signer,
+  facilitatorBaseUrl: relayerBaseUrl,
+  defaultMaxAmountRawUsdc,
+  vaultFlows: new VaultFlowClient({
+    facilitatorBaseUrl: relayerBaseUrl,
+    signer,
+    rpc
+  })
+});