@subly_fi/pay 0.7.3 → 0.8.1

package/dist/pay.js

@@ -236,1266 +236,1493 @@ async function ensureWalletOnboarded(params) {
   await post("sync", `/v1/wallets/${wallet}/sync`, { source: "chain", vault });
 }
 
-// ../../src/lib/associated-token-account.ts
+// ../../src/lib/canonical-json.ts
+import { createHash as createHash3 } from "node:crypto";
+
+// ../../src/lib/hash.ts
 import { createHash as createHash2 } from "node:crypto";
-import bs582 from "bs58";
-var PDA_MARKER = Buffer.from("ProgramDerivedAddress", "utf8");
-var ED25519_P = (1n << 255n) - 19n;
-var ED25519_D = mod(-121665n * modPow(121666n, ED25519_P - 2n, ED25519_P), ED25519_P);
-function deriveAssociatedTokenAddress(params) {
-  const owner = decodePublicKey(params.owner, "owner");
-  const mint = decodePublicKey(params.mint ?? SUBLY_VAULT.usdcMint, "mint");
-  const tokenProgramId = decodePublicKey(
-    params.tokenProgramId ?? SPL_TOKEN_PROGRAM_ID,
-    "tokenProgramId"
-  );
-  const associatedTokenProgramId = decodePublicKey(
-    ASSOCIATED_TOKEN_PROGRAM_ID,
-    "associatedTokenProgramId"
-  );
-  for (let bump = 255; bump >= 0; bump -= 1) {
-    const address3 = createProgramAddress(
-      [owner, tokenProgramId, mint, Uint8Array.of(bump)],
-      associatedTokenProgramId
-    );
-    if (address3 !== null) {
-      return bs582.encode(address3);
-    }
-  }
-  throw new Error("Unable to derive associated token account address");
-}
-function createProgramAddress(seeds, programId) {
-  const hash = createHash2("sha256");
-  for (const seed of seeds) {
-    hash.update(seed);
-  }
-  hash.update(programId);
-  hash.update(PDA_MARKER);
-  const digest = hash.digest();
-  return isEd25519Point(digest) ? null : new Uint8Array(digest);
+var EMPTY_BODY_HASH = "sha256-e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+function sha256TaggedHex(data) {
+  return `sha256-${createHash2("sha256").update(data).digest("hex")}`;
 }
-function decodePublicKey(value, fieldName) {
-  const decoded = bs582.decode(value);
-  if (decoded.length !== 32) {
-    throw new Error(`${fieldName} must be a 32-byte public key`);
+function stableStringify(value) {
+  if (value === null) {
+    return "null";
   }
-  return decoded;
-}
-function isEd25519Point(bytes) {
-  if (bytes.length !== 32) {
-    return false;
+  if (typeof value === "bigint") {
+    return JSON.stringify(value.toString());
   }
-  const yBytes = Uint8Array.from(bytes);
-  yBytes[31] = yBytes[31] & 127;
-  const y = littleEndianToBigInt(yBytes);
-  if (y >= ED25519_P) {
-    return false;
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return JSON.stringify(value);
   }
-  const ySquared = mod(y * y, ED25519_P);
-  const numerator = mod(ySquared - 1n, ED25519_P);
-  const denominator = mod(ED25519_D * ySquared + 1n, ED25519_P);
-  if (denominator === 0n) {
-    return false;
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
   }
-  const xSquared = mod(
-    numerator * modPow(denominator, ED25519_P - 2n, ED25519_P),
-    ED25519_P
-  );
-  return xSquared === 0n || modPow(xSquared, (ED25519_P - 1n) / 2n, ED25519_P) === 1n;
+  const keys = Object.keys(value).filter((key) => value[key] !== void 0).sort();
+  return `{${keys.map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(",")}}`;
 }
-function littleEndianToBigInt(bytes) {
-  let value = 0n;
-  for (let index = bytes.length - 1; index >= 0; index -= 1) {
-    value = (value << 8n) + BigInt(bytes[index]);
-  }
-  return value;
+function hashStableJson(value) {
+  return sha256TaggedHex(stableStringify(value));
 }
-function mod(value, modulus) {
-  const result = value % modulus;
-  return result >= 0n ? result : result + modulus;
+
+// ../../src/lib/canonical-json.ts
+function canonicalJson(value) {
+  return stableStringify(value);
 }
-function modPow(base, exponent, modulus) {
-  let result = 1n;
-  let nextBase = mod(base, modulus);
-  let nextExponent = exponent;
-  while (nextExponent > 0n) {
-    if ((nextExponent & 1n) === 1n) {
-      result = mod(result * nextBase, modulus);
-    }
-    nextBase = mod(nextBase * nextBase, modulus);
-    nextExponent >>= 1n;
-  }
-  return result;
+function sha256HexOf(data) {
+  return createHash3("sha256").update(data, "utf8").digest("hex");
+}
+function canonicalJsonHash(value) {
+  return sha256HexOf(canonicalJson(value));
 }
 
-// ../../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
-async function assertWithdrawalPreview(input) {
-  const destination = deriveAssociatedTokenAddress({ owner: input.wallet, mint: input.vault.usdcMint });
-  const simulation = await input.rpc.simulateTransaction(
-    input.serializedTransaction,
-    {
-      encoding: "base64",
-      commitment: "confirmed",
-      sigVerify: false,
-      replaceRecentBlockhash: false,
-      innerInstructions: true
-    }
-  ).send({ abortSignal: AbortSignal.timeout(15e3) });
-  if (simulation.value.err !== null) {
-    throw new Error("Withdrawal preview failed on the client RPC; no transaction was signed. Check liquidity, RPC and blockhash, then prepare again.");
-  }
-  let received = 0n;
-  for (const group of simulation.value.innerInstructions ?? []) {
-    for (const instruction of group.instructions) {
-      if (!("parsed" in instruction) || instruction.programId !== SPL_TOKEN_PROGRAM_ID) continue;
-      const parsed = instruction.parsed;
-      if (parsed.type !== "transfer" && parsed.type !== "transferChecked") continue;
-      const info = parsed.info;
-      if (!info || info.destination !== destination && info.source !== destination) continue;
-      const raw = parsed.type === "transferChecked" ? info.tokenAmount?.amount : info.amount;
-      if (typeof raw !== "string" || !/^\d+$/.test(raw)) {
-        throw new Error("Withdrawal preview returned an invalid token amount");
-      }
-      const amount = BigInt(raw);
-      if (info.destination === destination) received += amount;
-      if (info.source === destination) received -= amount;
-    }
+// ../../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;
+  constructor(reason, message) {
+    super(message);
+    this.name = "X402HeaderError";
+    this.reason = reason;
   }
-  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");
+};
+var sublyPaymentRequirementsSchema = z2.object({
+  scheme: z2.literal(PAYMENT_SCHEME),
+  network: z2.string().min(1),
+  asset: z2.string().min(32),
+  /** Exact seller amount in raw USDC; the scheme settles exactly this. */
+  amountRawUsdc: z2.string().regex(/^[1-9]\d*$/),
+  resource: z2.string().url(),
+  description: z2.string().optional(),
+  mimeType: z2.string().optional(),
+  payTo: z2.string().min(32),
+  maxTimeoutSeconds: z2.number().int().positive(),
+  extra: z2.object({
+    sellerRequestId: z2.string().min(1),
+    seller: z2.string().min(32),
+    sellerUsdcAta: z2.string().min(32),
+    vault: z2.string().min(32),
+    shareMint: z2.string().min(32)
+  })
+}).loose();
+var paymentRequiredSchema = z2.object({
+  x402Version: z2.number().int(),
+  accepts: z2.array(z2.unknown()),
+  error: z2.string().optional()
+}).loose();
+var sublyPaymentPayloadSchema = z2.object({
+  x402Version: z2.number().int(),
+  scheme: z2.literal(PAYMENT_SCHEME),
+  network: z2.string().min(1),
+  payload: z2.object({
+    paymentId: z2.string().min(1),
+    requestBindingHash: z2.string().min(1),
+    preparedMessageHash: z2.string().min(1),
+    serializedTransaction: z2.string().min(1).max(4096),
+    agentSignature: z2.string().min(1).max(128),
+    temporarySettlementSignature: z2.string().min(1).max(128)
+  })
+}).loose();
+function decodeX402Header(headerValue) {
+  if (headerValue.length > Math.ceil(MAX_HEADER_JSON_BYTES * 4 / 3) + 4) {
+    throw new X402HeaderError(
+      "header_too_large",
+      `x402 header exceeds ${MAX_HEADER_JSON_BYTES} encoded bytes`
+    );
   }
-}
-
-// ../../src/client/lookup-tables.ts
-import { fetchAllMaybeAddressLookupTable } from "@solana-program/address-lookup-table";
-import { address, getCompiledTransactionMessageDecoder } 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 json = Buffer.from(headerValue, "base64").toString("utf8");
+  try {
+    return JSON.parse(json);
+  } catch {
+    throw new X402HeaderError(
+      "invalid_header_encoding",
+      "x402 header is not base64-encoded JSON"
+    );
   }
-  const messageBytes = wire.subarray(offset + signatureCount * 64);
-  const compiled = getCompiledTransactionMessageDecoder().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 {};
+function requestBodyHashFor(body2) {
+  if (body2 === null || body2 === void 0 || body2.length === 0) {
+    return EMPTY_BODY_HASH;
   }
-  const tables = await fetchAllMaybeAddressLookupTable(
-    rpc2,
-    addresses.map((value) => address(value))
+  return sha256TaggedHex(
+    typeof body2 === "string" ? Buffer.from(body2, "utf8") : Buffer.from(body2)
   );
-  const result = {};
-  for (const table of tables) {
-    if (table.exists) {
-      result[table.address] = table.data.addresses.map(String);
-    }
-  }
-  return result;
 }
 
-// ../../src/client/vault-flows.ts
-var VaultFlowClientError = class extends Error {
-  constructor(step, message, detail = null, code = null, errorDetails = null) {
-    super(message);
-    this.step = step;
-    this.detail = detail;
-    this.code = code;
-    this.errorDetails = errorDetails;
-    this.name = "VaultFlowClientError";
+// ../../src/x402/standard-requirements.ts
+import { z as z3 } from "zod";
+var STANDARD_EXACT_SCHEME = "exact";
+var standardExactRequirementSchema = z3.object({
+  scheme: z3.literal(STANDARD_EXACT_SCHEME),
+  /** CAIP-2 chain id, e.g. "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp". */
+  network: z3.string().min(1),
+  /** SPL mint (Solana) or token contract (EVM); Subly only pays USDC/Solana. */
+  asset: z3.string().min(1),
+  /** Exact price in the asset's atomic units, as a decimal string. */
+  amount: z3.string().regex(/^[1-9]\d*$/),
+  /** Recipient wallet; the transfer destination ATA is derived from it. */
+  payTo: z3.string().min(1),
+  maxTimeoutSeconds: z3.number().int().positive().optional(),
+  extra: z3.object({
+    /** Facilitator address that pays the tx fee (gas sponsorship). */
+    feePayer: z3.string().min(1).optional()
+  }).loose().optional()
+}).loose();
+var standardPaymentRequiredSchema = z3.object({
+  x402Version: z3.number().int(),
+  accepts: z3.array(z3.unknown()),
+  error: z3.string().optional(),
+  resource: z3.object({ url: z3.string().optional() }).loose().optional()
+}).loose();
+var StandardX402ChallengeError = class extends Error {
+  reason;
+  constructor(reason, message) {
+    super(message);
+    this.name = "StandardX402ChallengeError";
+    this.reason = reason;
   }
-  step;
-  detail;
-  code;
-  errorDetails;
 };
-var VaultFlowClient = class {
-  vault;
-  rpc;
-  baseUrl;
-  signer;
-  fetchImpl;
-  lookupTablesFor;
-  pollTimeoutMs;
-  pollIntervalMs;
-  constructor(config) {
-    this.rpc = config.rpc;
-    this.vault = config.vault ?? config.signer.vault ?? SUBLY_VAULT;
-    if (config.signer.vault && config.signer.vault.address !== this.vault.address) {
-      throw new Error("Vault flow client and signer must select the same vault");
-    }
-    this.baseUrl = config.relayerBaseUrl.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;
+function parseStandardChallenge(challenge) {
+  const parsed = standardPaymentRequiredSchema.safeParse(challenge);
+  if (!parsed.success) {
+    throw new StandardX402ChallengeError(
+      "invalid_payment_required",
+      "Response is not a valid x402 PaymentRequired object"
+    );
   }
-  /**
-   * Moves USDC from the agent wallet into the vault (fee sponsored). Under
-   * depositPolicy "owner_approval_required" the relayer refuses to prepare
-   * without an owner approval; when the caller passes none, an already
-   * APPROVED deposit approval for this exact amount (e.g. the mandate's
-   * initialDeposit — "one Face ID covers mandate + first deposit") is looked
-   * up and used automatically before surfacing deposit_approval_required.
-   */
-  async deposit(input) {
-    let approvalId2 = input.approvalId;
-    let prepared;
-    try {
-      prepared = await this.postJson("prepare", "/v1/deposits/prepare", {
-        wallet: this.signer.walletAddress,
-        vault: this.vault.address,
-        amountRawUsdc: input.amountRawUsdc.toString(),
-        ...approvalId2 === void 0 ? {} : { approvalId: approvalId2 }
-      });
-    } catch (error) {
-      if (!(error instanceof VaultFlowClientError) || error.code !== "deposit_approval_required" || approvalId2 !== void 0) {
-        throw error;
-      }
-      approvalId2 = await this.findApprovedDepositApproval(input.amountRawUsdc);
-      if (approvalId2 === void 0) {
-        throw error;
-      }
-      prepared = await this.postJson("prepare", "/v1/deposits/prepare", {
-        wallet: this.signer.walletAddress,
-        vault: this.vault.address,
-        amountRawUsdc: input.amountRawUsdc.toString(),
-        approvalId: approvalId2
-      });
-    }
-    if (prepared.signingIntent?.wallet !== this.signer.walletAddress || prepared.signingIntent.vault !== this.vault.address || prepared.signingIntent.amountRawUsdc !== input.amountRawUsdc.toString()) {
-      throw new VaultFlowClientError("prepare", "Prepared deposit differs from the requested wallet, vault or amount");
-    }
-    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
-      );
+  const solanaExactRequirements = parsed.data.accepts.flatMap((candidate) => {
+    const requirement = standardExactRequirementSchema.safeParse(candidate);
+    if (!requirement.success) {
+      return [];
     }
-    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,
-        vault: this.vault.address,
-        amountRawUsdc: input.amountRawUsdc.toString(),
-        ...input.purpose === void 0 ? {} : { purpose: input.purpose },
-        ...input.payment === void 0 ? {} : { payment: input.payment },
-        ...input.approvalId === void 0 ? {} : { approvalId: input.approvalId }
-      }
+    return requirement.data.network.startsWith("solana:") ? [requirement.data] : [];
+  });
+  return { paymentRequired: parsed.data, solanaExactRequirements };
+}
+function decodeStandardPaymentRequiredHeader(headerValue) {
+  let decoded;
+  try {
+    decoded = decodeX402Header(headerValue);
+  } catch (error) {
+    throw new StandardX402ChallengeError(
+      error instanceof X402HeaderError ? error.reason : "invalid_header",
+      "Cannot decode the payment-required header"
     );
-    if (prepared.signingIntent?.wallet !== this.signer.walletAddress || prepared.signingIntent.vault !== this.vault.address || prepared.requestedWithdrawRawUsdc !== input.amountRawUsdc.toString() || prepared.purpose !== (input.purpose ?? "normal") || input.purpose === "yield_realize" && prepared.signingIntent.allowFullExit) {
-      throw new VaultFlowClientError("prepare", "Prepared withdrawal differs from the requested operation");
-    }
-    await assertWithdrawalPreview({
-      rpc: this.rpc,
-      serializedTransaction: prepared.serializedTransaction,
-      wallet: this.signer.walletAddress,
-      vault: this.vault,
-      amountRawUsdc: input.amountRawUsdc,
-      ...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", vault: this.vault.address }
-        );
-      } catch {
-      }
-    }
-    const url2 = `${this.baseUrl}/v1/wallets/${this.signer.walletAddress}/budget?vault=${this.vault.address}`;
-    const response = await this.fetchImpl(url2, {
-      headers: await walletAuthHeaders({
-        signer: this.signer,
-        method: "GET",
-        url: url2
-      })
-    });
-    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 body2 = parsed;
-    if (body2.position?.vault !== void 0 && body2.position.vault !== this.vault.address) {
-      throw new VaultFlowClientError("budget", "Relayer returned the budget for a different vault");
-    }
-    return {
-      wallet: this.signer.walletAddress,
-      vault: this.vault.address,
-      principalBasisRawUsdc: body2.position?.principalBasisRawUsdc ?? "0",
-      positionValueRawUsdc: body2.budget?.positionValueRawUsdc ?? "0",
-      grossYieldRawUsdc: body2.budget?.grossYieldRawUsdc ?? "0",
-      spendableYieldRawUsdc: body2.budget?.spendableYieldRawUsdc ?? "0"
-    };
+  return parseStandardChallenge(decoded);
+}
+function selectPayableSolanaRequirement(requirements, options) {
+  const network = options?.network ?? SOLANA_MAINNET_NETWORK;
+  const usdcMint = options?.usdcMint ?? SUBLY_VAULT.usdcMint;
+  const matchingRequirements = requirements.filter(
+    (candidate) => candidate.network === network && candidate.asset === usdcMint
+  );
+  if (matchingRequirements.length === 0) {
+    throw new StandardX402ChallengeError(
+      "no_payable_requirement",
+      `The challenge has no Solana exact requirement on ${network} paying ${usdcMint}`
+    );
   }
-  /** Best-effort audit link: reports the x402 payment tx a realize funded. */
-  async reportPayment(input) {
-    await this.postJson("submit", "/v1/payments/report", {
-      wallet: this.signer.walletAddress,
-      withdrawalId: input.withdrawalId,
-      paymentTxSignature: input.paymentTxSignature
-    });
+  const requirement = matchingRequirements.find(
+    (candidate) => candidate.extra?.feePayer !== void 0
+  ) ?? null;
+  if (requirement === null) {
+    throw new StandardX402ChallengeError(
+      "missing_svm_fee_payer",
+      "The Solana exact requirement does not include extra.feePayer, which the official @x402/svm client requires for gas sponsorship"
+    );
   }
-  /** Wallet's approvals as the relayer sees them (optionally by status). */
-  async listApprovals(status) {
-    const body2 = await this.getJson(
-      `/v1/wallets/${this.signer.walletAddress}/approvals${`?vault=${this.vault.address}${status === void 0 ? "" : `&status=${encodeURIComponent(status)}`}`}`
+  const feePayer = requirement.extra?.feePayer;
+  if (feePayer === void 0) {
+    throw new StandardX402ChallengeError(
+      "missing_svm_fee_payer",
+      "The Solana exact requirement does not include extra.feePayer, which the official @x402/svm client requires for gas sponsorship"
     );
-    return body2.approvals ?? [];
   }
-  /**
-   * Creates the owner-onboarding setup link (wallet-auth pins the agreed
-   * policy + initial deposit). Paste `setupUrl` into the chat verbatim.
-   */
-  async createSetupSession(input) {
-    const session = await this.postJson(
-      "prepare",
-      `/v1/wallets/${this.signer.walletAddress}/setup-sessions`,
-      {
-        vault: this.vault.address,
-        ...input.policy === void 0 ? {} : { policy: input.policy },
-        ...input.enforcementMode === void 0 ? {} : { enforcementMode: input.enforcementMode },
-        ...input.mandateTtlDays === void 0 ? {} : { mandateTtlDays: input.mandateTtlDays },
-        ...input.initialDepositRawUsdc === void 0 ? {} : { initialDepositRawUsdc: input.initialDepositRawUsdc }
-      }
+  return {
+    requirement,
+    amountRawUsdc: BigInt(requirement.amount),
+    payTo: requirement.payTo,
+    feePayer
+  };
+}
+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)])
     );
-    if (session.vault !== this.vault.address || session.wallet !== this.signer.walletAddress) {
-      throw new VaultFlowClientError("prepare", "Relayer returned a setup session for a different wallet or vault");
-    }
-    return session;
   }
-  /** Polls a setup session (public capability URL — no auth needed). */
-  async getSetupSession(sessionId) {
-    const url2 = `${this.baseUrl}/v1/setup-sessions/${encodeURIComponent(sessionId)}`;
-    const response = await this.fetchImpl(url2);
-    const text = await response.text();
-    if (response.status !== 200) {
-      const parsed = parseRelayerError(text);
-      throw new VaultFlowClientError(
-        "read",
-        parsed.message ?? `setup session read failed with ${response.status}`,
-        text,
-        parsed.code,
-        parsed.details
-      );
-    }
-    return JSON.parse(text);
+  return value;
+}
+
+// ../../src/client/standard-x402-payer.ts
+var StandardX402PayError = class extends Error {
+  constructor(reason, message, detail = null) {
+    super(message);
+    this.reason = reason;
+    this.detail = detail;
+    this.name = "StandardX402PayError";
   }
-  /**
-   * Finds an APPROVED, unconsumed deposit approval bound to exactly this
-   * amount — the shape the mandate's initialDeposit approval has.
-   */
-  async findApprovedDepositApproval(amountRawUsdc) {
-    try {
-      const approvals = await this.listApprovals("approved");
-      const match = approvals.find((approval) => {
-        const binding = approval.binding;
-        return binding?.kind === "deposit" && binding.amountRawUsdc === amountRawUsdc.toString();
-      });
-      return match?.approvalId;
-    } catch {
-      return void 0;
+  reason;
+  detail;
+};
+var StandardX402Payer = class {
+  realizer;
+  x402Fetch;
+  probeFetch;
+  defaultMaxAmountRawUsdc;
+  network;
+  usdcMint;
+  stateStore;
+  pending = /* @__PURE__ */ new Map();
+  inFlight = /* @__PURE__ */ new Map();
+  nowMs;
+  constructor(config) {
+    this.realizer = config.realizer;
+    this.x402Fetch = config.x402Fetch;
+    this.probeFetch = config.probeFetch ?? fetch;
+    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);
+      }
     }
   }
-  /**
-   * 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 url2 = `${this.baseUrl}${path}`;
-      const response = await this.fetchImpl(url2, {
-        headers: await walletAuthHeaders({
-          signer: this.signer,
-          method: "GET",
-          url: url2
-        })
-      });
-      if (response.status !== 200) {
-        continue;
+  pay(input, realizer = this.realizer) {
+    const method2 = (input.method ?? "GET").toUpperCase();
+    const requestBodyHash = requestBodyHashFor(input.body ?? null);
+    const pendingKey = pendingPaymentKey({
+      url: input.url,
+      method: method2,
+      requestBodyHash
+    });
+    const existingFlow = this.inFlight.get(pendingKey);
+    if (existingFlow !== void 0) {
+      return existingFlow;
+    }
+    const run = async () => {
+      if (this.stateStore?.withExclusiveLock) {
+        this.pending.clear();
+        for (const record of this.stateStore.load()) this.pending.set(record.key, record);
+      }
+      return this.run(input, { method: method2, requestBodyHash, pendingKey }, realizer);
+    };
+    const flow = (this.stateStore?.withExclusiveLock ? this.stateStore.withExclusiveLock(run) : run()).finally(() => {
+      this.inFlight.delete(pendingKey);
+    });
+    this.inFlight.set(pendingKey, flow);
+    return flow;
+  }
+  async run(input, computed, realizer) {
+    const { method: method2, requestBodyHash, pendingKey } = computed;
+    const existingPending = this.pending.get(pendingKey);
+    const resuming = existingPending?.recovery !== void 0 && existingPending.status !== "external_outcome_unknown";
+    const requestHeadersHash = canonicalJsonHash(input.headers ?? {});
+    if (resuming) {
+      const recovery = existingPending.recovery;
+      if (canonicalJsonHash(recovery.context) !== canonicalJsonHash(realizer.realizationContext ?? null) || recovery.requestHeadersHash !== requestHeadersHash || existingPending.url !== input.url || existingPending.method !== method2 || existingPending.requestBodyHash !== requestBodyHash) {
+        throw new StandardX402PayError(
+          "payment_outcome_unknown",
+          "The pending realization belongs to a different wallet, vault, relayer or request; refusing to resume or discard it.",
+          publicPendingPayment(existingPending)
+        );
+      }
+      if (existingPending.status === "realizing" && recovery.prepared === void 0) {
+        throw new StandardX402PayError(
+          "payment_outcome_unknown",
+          "Realization was interrupted before its withdrawal ID was saved. Reconcile the original operation before retrying; forceNewPayment cannot discard an incomplete realization.",
+          publicPendingPayment(existingPending)
+        );
+      }
+    } else if (existingPending !== void 0) {
+      if (input.forceNewPayment !== true || existingPending.status === "realizing") {
+        throw new StandardX402PayError(
+          "payment_outcome_unknown",
+          "A previous payment or realization has an unknown outcome. Verify it before purchasing again.",
+          publicPendingPayment(existingPending)
+        );
       }
       try {
-        latest = await response.json();
-      } catch {
-        continue;
+        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
+        );
       }
-      if (latest.status !== "submitted") {
-        return latest;
+    }
+    const init = {
+      method: method2,
+      ...input.body === void 0 ? {} : { body: input.body },
+      ...input.headers === void 0 ? {} : { headers: input.headers }
+    };
+    const probe = await this.probeFetch(input.url, init);
+    if (probe.status !== 402) {
+      if (resuming) {
+        throw new StandardX402PayError(
+          "payment_outcome_unknown",
+          "The seller no longer offers the original payment challenge; the saved realization is retained for reconciliation.",
+          publicPendingPayment(existingPending)
+        );
       }
+      return { paid: false, status: probe.status, body: await probe.text() };
     }
-    return latest;
-  }
-  async postJson(step, path, body2) {
-    const url2 = `${this.baseUrl}${path}`;
-    const serialized = JSON.stringify(body2);
-    const response = await this.fetchImpl(url2, {
-      method: "POST",
-      headers: {
-        ...await walletAuthHeaders({
-          signer: this.signer,
-          method: "POST",
-          url: url2,
-          body: serialized
-        }),
-        "content-type": "application/json"
-      },
-      body: serialized
-    });
-    const text = await response.text();
-    if (response.status !== 200) {
-      const parsed = parseRelayerError(text);
-      throw new VaultFlowClientError(
-        step,
-        parsed.message === null ? `${path} failed with ${response.status}: ${text}` : `${path} failed (${parsed.code ?? response.status}): ${parsed.message}`,
-        text,
-        parsed.code,
-        parsed.details
+    const selected = await this.selectRequirement(probe);
+    if (resuming && (!standardRequirementMatchesSelected(existingPending.recovery.requirement, selected) || existingPending.amountRawUsdc !== selected.amountRawUsdc.toString() || existingPending.payTo !== selected.payTo || existingPending.feePayer !== selected.feePayer)) {
+      throw new StandardX402PayError(
+        "payment_outcome_unknown",
+        "The seller's payment challenge differs from the saved realization; refusing to fund a different payment.",
+        publicPendingPayment(existingPending)
       );
     }
-    try {
-      return JSON.parse(text);
-    } catch {
-      throw new VaultFlowClientError(
-        step,
-        `${path} returned 200 with a non-JSON body`,
-        text
+    const cap = input.maxAmountRawUsdc ?? this.defaultMaxAmountRawUsdc;
+    if (selected.amountRawUsdc > cap) {
+      throw new StandardX402PayError(
+        "amount_exceeds_client_cap",
+        `the challenge demands ${selected.amountRawUsdc} raw USDC, above the client cap of ${cap}; no new payment was attempted`,
+        { amountRawUsdc: selected.amountRawUsdc.toString(), payTo: selected.payTo }
       );
     }
-  }
-  async getJson(path) {
-    const url2 = `${this.baseUrl}${path}`;
-    const response = await this.fetchImpl(url2, {
-      headers: await walletAuthHeaders({
-        signer: this.signer,
-        method: "GET",
-        url: url2
-      })
-    });
-    const text = await response.text();
-    if (response.status !== 200) {
-      const parsed = parseRelayerError(text);
-      throw new VaultFlowClientError(
-        "read",
-        parsed.message === null ? `${path} failed with ${response.status}: ${text}` : `${path} failed (${parsed.code ?? response.status}): ${parsed.message}`,
-        text,
-        parsed.code,
-        parsed.details
-      );
+    const payment = {
+      payTo: selected.payTo,
+      amountRawUsdc: selected.amountRawUsdc.toString(),
+      resourceUrlHash: sha256HexOf(input.url),
+      method: method2
+    };
+    let pendingRecord = resuming ? existingPending : {
+      key: pendingKey,
+      url: input.url,
+      method: method2,
+      requestBodyHash,
+      amountRawUsdc: selected.amountRawUsdc.toString(),
+      payTo: selected.payTo,
+      feePayer: selected.feePayer,
+      realizedRawUsdc: "0",
+      realizeTxSignature: null,
+      status: "realizing",
+      createdAtMs: this.nowMs(),
+      updatedAtMs: this.nowMs(),
+      ...realizer.realizationContext === void 0 ? {} : {
+        recovery: {
+          version: 1,
+          context: { ...realizer.realizationContext },
+          requestHeadersHash,
+          requirement: structuredClone(selected.requirement)
+        }
+      }
+    };
+    if (!resuming) this.persistCheckpoint(pendingRecord);
+    let realized;
+    if (resuming && pendingRecord.status === "realized") {
+      realized = {
+        realizedRawUsdc: BigInt(pendingRecord.realizedRawUsdc),
+        txSignature: pendingRecord.realizeTxSignature,
+        withdrawalId: pendingRecord.recovery?.prepared?.withdrawalId ?? null
+      };
+    } else {
+      try {
+        if (resuming) {
+          if (realizer.resumeUsdcAvailable === void 0) {
+            throw new Error("This realizer cannot reconcile the saved withdrawal");
+          }
+          realized = await realizer.resumeUsdcAvailable({
+            amountRawUsdc: selected.amountRawUsdc,
+            payment,
+            prepared: pendingRecord.recovery.prepared
+          });
+        } else {
+          realized = await realizer.ensureUsdcAvailable({
+            amountRawUsdc: selected.amountRawUsdc,
+            payment,
+            ...input.approvalId === void 0 ? {} : { approvalId: input.approvalId },
+            onPrepared: async (prepared) => {
+              if (pendingRecord.recovery === void 0) {
+                throw new StandardX402PayError("state_persist_failed", "Cannot save a withdrawal without a pinned funding context");
+              }
+              const checkpoint = {
+                ...pendingRecord,
+                updatedAtMs: this.nowMs(),
+                recovery: { ...pendingRecord.recovery, prepared: structuredClone(prepared) }
+              };
+              this.persistCheckpoint(checkpoint);
+              pendingRecord = checkpoint;
+            }
+          });
+        }
+      } catch (error) {
+        if (error instanceof StandardX402PayError && error.reason === "state_persist_failed") throw error;
+        const failure = error;
+        const safeToRetry = !resuming && (failure.realizationSafeToRetry === true || failure.code === "approval_required" && pendingRecord.recovery?.prepared === void 0);
+        if (safeToRetry) {
+          try {
+            this.untrack(pendingKey);
+          } catch (persistError) {
+            throw new StandardX402PayError("state_persist_failed", "Could not clear the safely refused realization", persistError);
+          }
+        }
+        if (safeToRetry && failure.code === "approval_required") {
+          throw new StandardX402PayError(
+            "approval_required",
+            "This payment needs the owner's approval; nothing was paid. Ask the owner to open approveUrl, then retry the same call with approvalId.",
+            failure.detail ?? null
+          );
+        }
+        throw new StandardX402PayError(
+          safeToRetry ? "realize_failed" : "payment_outcome_unknown",
+          safeToRetry ? "Yield realization failed before submission; no payment was attempted." : "The original yield realization has not been confirmed. Its saved withdrawal must be reconciled before any new withdrawal or payment.",
+          { error, pendingPayment: safeToRetry ? null : publicPendingPayment(pendingRecord) }
+        );
+      }
     }
-    try {
-      return JSON.parse(text);
-    } catch {
-      throw new VaultFlowClientError(
-        "read",
-        `${path} returned 200 with a non-JSON body`,
-        text
+    pendingRecord = {
+      ...pendingRecord,
+      status: "realized",
+      realizedRawUsdc: realized.realizedRawUsdc.toString(),
+      realizeTxSignature: realized.txSignature,
+      updatedAtMs: this.nowMs()
+    };
+    this.persistCheckpoint(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: publicPendingPayment(pendingRecord) }
       );
     }
-  }
-};
-function parseRelayerError(text) {
-  try {
-    const parsed = JSON.parse(text);
-    return {
-      code: typeof parsed.error?.code === "string" ? parsed.error.code : null,
-      message: typeof parsed.error?.message === "string" ? parsed.error.message : null,
-      details: parsed.error?.details ?? null
-    };
-  } catch {
-    return { code: null, message: null, details: null };
-  }
-}
-
-// ../../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 {
-  get vault() {
-    return this.vaultFlows.vault.address;
-  }
-  vaultFlows;
-  constructor(config) {
-    this.vaultFlows = new VaultFlowClient({
-      relayerBaseUrl: config.relayerBaseUrl,
-      signer: config.signer,
-      rpc: config.rpc,
-      ...config.fetchImpl === void 0 ? {} : { fetchImpl: config.fetchImpl },
-      ...config.lookupTablesFor === void 0 ? {} : { lookupTablesFor: config.lookupTablesFor }
+    this.persistCheckpoint({
+      ...pendingRecord,
+      status: "external_outcome_unknown",
+      updatedAtMs: this.nowMs()
     });
-  }
-  async ensureUsdcAvailable(input) {
-    const shortfallRawUsdc = input.amountRawUsdc;
-    await this.assertSpendableYield(shortfallRawUsdc);
-    let outcome;
+    let response;
     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",
-        // Declares what is being paid so the relayer's spending-mandate layer
-        // can enforce caps/payee and keep the mandate → payment audit chain.
-        ...input.payment === void 0 ? {} : { payment: input.payment },
-        ...input.approvalId === void 0 ? {} : { approvalId: input.approvalId }
-      });
+      response = await this.x402Fetch(input.url, init, selected);
     } 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
+      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();
+    const receipt = readSettlementReceipt(response);
+    if (response.status < 200 || response.status >= 300 || receipt.status === "failed" || receipt.status === "invalid") {
+      const persistError = this.tryMarkUnknown(pendingKey, {
+        status: response.status,
+        body: bodyText,
+        receiptStatus: receipt.status
+      });
+      throw new StandardX402PayError(
+        "payment_outcome_unknown",
+        `the x402 payment attempt returned HTTP ${response.status} with a ${receipt.status} receipt; verify whether it settled before paying again`,
+        { status: response.status, body: bodyText, receiptStatus: receipt.status, persistError }
       );
     }
+    this.clearDelivered(pendingKey);
+    const paymentTxSignature = receipt.txSignature;
+    if (paymentTxSignature !== null && typeof realized.withdrawalId === "string" && realizer.reportPayment !== void 0) {
+      try {
+        await realizer.reportPayment({
+          withdrawalId: realized.withdrawalId,
+          paymentTxSignature
+        });
+      } catch (error) {
+        console.error(
+          `[subly-x402] payment report-back failed (audit only, payment ok): ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    }
     return {
-      realizedRawUsdc: BigInt(outcome.actualWithdrawRawUsdc ?? "0"),
-      txSignature: outcome.txSignature,
-      withdrawalId: outcome.withdrawalId
+      paid: true,
+      ...realizer.vault === void 0 ? {} : { fundingVault: realizer.vault },
+      status: response.status,
+      body: bodyText,
+      payment: {
+        amountRawUsdc: selected.amountRawUsdc.toString(),
+        payTo: selected.payTo,
+        feePayer: selected.feePayer,
+        realizedRawUsdc: realized.realizedRawUsdc.toString(),
+        realizeTxSignature: realized.txSignature,
+        paymentTxSignature
+      }
     };
   }
-  /**
-   * Best-effort report-back of the x402 payment tx this realize funded —
-   * closes the relayer's mandate → realize → payment audit chain. Callers
-   * must never let a failure here affect the payment result.
-   */
-  async reportPayment(input) {
-    await this.vaultFlows.reportPayment(input);
-  }
-  /**
-   * 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;
+  /** Reads the challenge from the header (preferred) or the JSON body. */
+  async selectRequirement(probe) {
+    const header = probe.headers.get(PAYMENT_REQUIRED_HEADER);
+    let requirements;
     try {
-      const budget = await this.vaultFlows.getBudget();
-      spendable = BigInt(budget.spendableYieldRawUsdc);
+      if (header !== null) {
+        requirements = decodeStandardPaymentRequiredHeader(header).solanaExactRequirements;
+      } else {
+        requirements = parseStandardChallenge(
+          await probe.json()
+        ).solanaExactRequirements;
+      }
     } catch (error) {
-      throw new RelayerRealizeError(
-        "budget_unavailable",
-        "could not read the spendable-yield budget",
+      throw new StandardX402PayError(
+        error instanceof StandardX402ChallengeError ? error.reason : "invalid_challenge",
+        "could not parse the x402 402 challenge",
         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)}`,
+    try {
+      return selectPayableSolanaRequirement(requirements, {
+        network: this.network,
+        usdcMint: this.usdcMint
+      });
+    } catch (error) {
+      throw new StandardX402PayError(
+        "no_payable_requirement",
+        error instanceof Error ? error.message : String(error),
         error
       );
     }
-    const serverCode = error.code ?? errorCodeFrom(error.detail);
-    if (serverCode === "approval_required") {
-      return new RelayerRealizeError(
-        "approval_required",
-        "this payment exceeds the owner-approval threshold; nothing was realized or paid. Ask the owner to approve, then retry with the approvalId",
-        error.errorDetails ?? 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
+  }
+  persistCheckpoint(record) {
+    try {
+      this.track(record);
+    } catch (error) {
+      throw new StandardX402PayError(
+        "state_persist_failed",
+        "Could not persist payment recovery state; refusing the next financial operation.",
+        { error, pendingPayment: publicPendingPayment(record) }
       );
     }
-    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/lib/canonical-json.ts
-import { createHash as createHash4 } from "node:crypto";
-
-// ../../src/lib/hash.ts
-import { createHash as createHash3 } from "node:crypto";
-var EMPTY_BODY_HASH = "sha256-e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
-function sha256TaggedHex(data) {
-  return `sha256-${createHash3("sha256").update(data).digest("hex")}`;
-}
-function stableStringify(value) {
-  if (value === null) {
-    return "null";
-  }
-  if (typeof value === "bigint") {
-    return JSON.stringify(value.toString());
   }
-  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
-    return JSON.stringify(value);
+  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;
+    }
   }
-  if (Array.isArray(value)) {
-    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  markUnknown(key, detail) {
+    const current = this.pending.get(key);
+    if (current === void 0) {
+      return;
+    }
+    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;
+    }
   }
-  const keys = Object.keys(value).filter((key) => value[key] !== void 0).sort();
-  return `{${keys.map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(",")}}`;
-}
-function hashStableJson(value) {
-  return sha256TaggedHex(stableStringify(value));
-}
-
-// ../../src/lib/canonical-json.ts
-function sha256HexOf(data) {
-  return createHash4("sha256").update(data, "utf8").digest("hex");
-}
-
-// ../../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;
-  constructor(reason, message) {
-    super(message);
-    this.name = "X402HeaderError";
-    this.reason = reason;
+  tryMarkUnknown(key, detail) {
+    try {
+      this.markUnknown(key, detail);
+      return null;
+    } catch (error) {
+      return error;
+    }
   }
-};
-var sublyPaymentRequirementsSchema = z2.object({
-  scheme: z2.literal(PAYMENT_SCHEME),
-  network: z2.string().min(1),
-  asset: z2.string().min(32),
-  /** Exact seller amount in raw USDC; the scheme settles exactly this. */
-  amountRawUsdc: z2.string().regex(/^[1-9]\d*$/),
-  resource: z2.string().url(),
-  description: z2.string().optional(),
-  mimeType: z2.string().optional(),
-  payTo: z2.string().min(32),
-  maxTimeoutSeconds: z2.number().int().positive(),
-  extra: z2.object({
-    sellerRequestId: z2.string().min(1),
-    seller: z2.string().min(32),
-    sellerUsdcAta: z2.string().min(32),
-    vault: z2.string().min(32),
-    shareMint: z2.string().min(32)
-  })
-}).loose();
-var paymentRequiredSchema = z2.object({
-  x402Version: z2.number().int(),
-  accepts: z2.array(z2.unknown()),
-  error: z2.string().optional()
-}).loose();
-var sublyPaymentPayloadSchema = z2.object({
-  x402Version: z2.number().int(),
-  scheme: z2.literal(PAYMENT_SCHEME),
-  network: z2.string().min(1),
-  payload: z2.object({
-    paymentId: z2.string().min(1),
-    requestBindingHash: z2.string().min(1),
-    preparedMessageHash: z2.string().min(1),
-    serializedTransaction: z2.string().min(1).max(4096),
-    agentSignature: z2.string().min(1).max(128),
-    temporarySettlementSignature: z2.string().min(1).max(128)
-  })
-}).loose();
-function decodeX402Header(headerValue) {
-  if (headerValue.length > Math.ceil(MAX_HEADER_JSON_BYTES * 4 / 3) + 4) {
-    throw new X402HeaderError(
-      "header_too_large",
-      `x402 header exceeds ${MAX_HEADER_JSON_BYTES} encoded 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;
+    }
   }
-  const json = Buffer.from(headerValue, "base64").toString("utf8");
-  try {
-    return JSON.parse(json);
-  } catch {
-    throw new X402HeaderError(
-      "invalid_header_encoding",
-      "x402 header is not base64-encoded JSON"
-    );
+  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)}`
+      );
+    }
+  }
+  persist() {
+    if (this.stateStore === null) {
+      return;
+    }
+    this.stateStore.save([...this.pending.values()]);
   }
+};
+function publicPendingPayment(record) {
+  return {
+    url: record.url,
+    method: record.method,
+    requestBodyHash: record.requestBodyHash,
+    amountRawUsdc: record.amountRawUsdc,
+    payTo: record.payTo,
+    feePayer: record.feePayer,
+    realizedRawUsdc: record.realizedRawUsdc,
+    realizeTxSignature: record.realizeTxSignature,
+    status: record.status,
+    createdAtMs: record.createdAtMs,
+    updatedAtMs: record.updatedAtMs,
+    withdrawalId: record.recovery?.prepared?.withdrawalId ?? null,
+    fundingSource: record.recovery?.context ?? null
+  };
 }
-function requestBodyHashFor(body2) {
-  if (body2 === null || body2 === void 0 || body2.length === 0) {
-    return EMPTY_BODY_HASH;
+function pendingPaymentKey(input) {
+  return `${input.method}:${input.url}:${input.requestBodyHash}`;
+}
+function readSettlementReceipt(response) {
+  const header = response.headers.get(PAYMENT_RESPONSE_HEADER) ?? response.headers.get("x-payment-response");
+  if (header === null) {
+    return { status: "absent", txSignature: null };
+  }
+  try {
+    const decoded = decodeX402Header(header);
+    if (decoded === null || typeof decoded !== "object" || Array.isArray(decoded) || !("success" in decoded) || typeof decoded.success !== "boolean") {
+      return { status: "invalid", txSignature: null };
+    }
+    if (!decoded.success) return { status: "failed", txSignature: null };
+    const receipt = decoded;
+    if (typeof receipt.transaction === "string" && receipt.transaction.length > 0) {
+      return { status: "success", txSignature: receipt.transaction };
+    }
+    if (typeof receipt.txHash === "string" && receipt.txHash.length > 0) {
+      return { status: "success", txSignature: receipt.txHash };
+    }
+    return { status: "invalid", txSignature: null };
+  } catch {
+    return { status: "invalid", txSignature: null };
   }
-  return sha256TaggedHex(
-    typeof body2 === "string" ? Buffer.from(body2, "utf8") : Buffer.from(body2)
-  );
 }
 
-// ../../src/x402/standard-requirements.ts
-import { z as z3 } from "zod";
-var STANDARD_EXACT_SCHEME = "exact";
-var standardExactRequirementSchema = z3.object({
-  scheme: z3.literal(STANDARD_EXACT_SCHEME),
-  /** CAIP-2 chain id, e.g. "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp". */
-  network: z3.string().min(1),
-  /** SPL mint (Solana) or token contract (EVM); Subly only pays USDC/Solana. */
-  asset: z3.string().min(1),
-  /** Exact price in the asset's atomic units, as a decimal string. */
-  amount: z3.string().regex(/^[1-9]\d*$/),
-  /** Recipient wallet; the transfer destination ATA is derived from it. */
-  payTo: z3.string().min(1),
-  maxTimeoutSeconds: z3.number().int().positive().optional(),
-  extra: z3.object({
-    /** Facilitator address that pays the tx fee (gas sponsorship). */
-    feePayer: z3.string().min(1).optional()
-  }).loose().optional()
-}).loose();
-var standardPaymentRequiredSchema = z3.object({
-  x402Version: z3.number().int(),
-  accepts: z3.array(z3.unknown()),
-  error: z3.string().optional(),
-  resource: z3.object({ url: z3.string().optional() }).loose().optional()
-}).loose();
-var StandardX402ChallengeError = class extends Error {
-  reason;
-  constructor(reason, message) {
-    super(message);
-    this.name = "StandardX402ChallengeError";
-    this.reason = reason;
-  }
-};
-function parseStandardChallenge(challenge) {
-  const parsed = standardPaymentRequiredSchema.safeParse(challenge);
-  if (!parsed.success) {
-    throw new StandardX402ChallengeError(
-      "invalid_payment_required",
-      "Response is not a valid x402 PaymentRequired object"
+// ../../src/lib/associated-token-account.ts
+import { createHash as createHash4 } from "node:crypto";
+import bs582 from "bs58";
+var PDA_MARKER = Buffer.from("ProgramDerivedAddress", "utf8");
+var ED25519_P = (1n << 255n) - 19n;
+var ED25519_D = mod(-121665n * modPow(121666n, ED25519_P - 2n, ED25519_P), ED25519_P);
+function deriveAssociatedTokenAddress(params) {
+  const owner = decodePublicKey(params.owner, "owner");
+  const mint = decodePublicKey(params.mint ?? SUBLY_VAULT.usdcMint, "mint");
+  const tokenProgramId = decodePublicKey(
+    params.tokenProgramId ?? SPL_TOKEN_PROGRAM_ID,
+    "tokenProgramId"
+  );
+  const associatedTokenProgramId = decodePublicKey(
+    ASSOCIATED_TOKEN_PROGRAM_ID,
+    "associatedTokenProgramId"
+  );
+  for (let bump = 255; bump >= 0; bump -= 1) {
+    const address3 = createProgramAddress(
+      [owner, tokenProgramId, mint, Uint8Array.of(bump)],
+      associatedTokenProgramId
     );
-  }
-  const solanaExactRequirements = parsed.data.accepts.flatMap((candidate) => {
-    const requirement = standardExactRequirementSchema.safeParse(candidate);
-    if (!requirement.success) {
-      return [];
+    if (address3 !== null) {
+      return bs582.encode(address3);
     }
-    return requirement.data.network.startsWith("solana:") ? [requirement.data] : [];
-  });
-  return { paymentRequired: parsed.data, solanaExactRequirements };
+  }
+  throw new Error("Unable to derive associated token account address");
 }
-function decodeStandardPaymentRequiredHeader(headerValue) {
-  let decoded;
-  try {
-    decoded = decodeX402Header(headerValue);
-  } catch (error) {
-    throw new StandardX402ChallengeError(
-      error instanceof X402HeaderError ? error.reason : "invalid_header",
-      "Cannot decode the payment-required header"
-    );
+function createProgramAddress(seeds, programId) {
+  const hash = createHash4("sha256");
+  for (const seed of seeds) {
+    hash.update(seed);
   }
-  return parseStandardChallenge(decoded);
+  hash.update(programId);
+  hash.update(PDA_MARKER);
+  const digest = hash.digest();
+  return isEd25519Point(digest) ? null : new Uint8Array(digest);
 }
-function selectPayableSolanaRequirement(requirements, options) {
-  const network = options?.network ?? SOLANA_MAINNET_NETWORK;
-  const usdcMint = options?.usdcMint ?? SUBLY_VAULT.usdcMint;
-  const matchingRequirements = requirements.filter(
-    (candidate) => candidate.network === network && candidate.asset === usdcMint
-  );
-  if (matchingRequirements.length === 0) {
-    throw new StandardX402ChallengeError(
-      "no_payable_requirement",
-      `The challenge has no Solana exact requirement on ${network} paying ${usdcMint}`
-    );
+function decodePublicKey(value, fieldName) {
+  const decoded = bs582.decode(value);
+  if (decoded.length !== 32) {
+    throw new Error(`${fieldName} must be a 32-byte public key`);
   }
-  const requirement = matchingRequirements.find(
-    (candidate) => candidate.extra?.feePayer !== void 0
-  ) ?? null;
-  if (requirement === null) {
-    throw new StandardX402ChallengeError(
-      "missing_svm_fee_payer",
-      "The Solana exact requirement does not include extra.feePayer, which the official @x402/svm client requires for gas sponsorship"
-    );
+  return decoded;
+}
+function isEd25519Point(bytes) {
+  if (bytes.length !== 32) {
+    return false;
   }
-  const feePayer = requirement.extra?.feePayer;
-  if (feePayer === void 0) {
-    throw new StandardX402ChallengeError(
-      "missing_svm_fee_payer",
-      "The Solana exact requirement does not include extra.feePayer, which the official @x402/svm client requires for gas sponsorship"
-    );
+  const yBytes = Uint8Array.from(bytes);
+  yBytes[31] = yBytes[31] & 127;
+  const y = littleEndianToBigInt(yBytes);
+  if (y >= ED25519_P) {
+    return false;
   }
-  return {
-    requirement,
-    amountRawUsdc: BigInt(requirement.amount),
-    payTo: requirement.payTo,
-    feePayer
-  };
+  const ySquared = mod(y * y, ED25519_P);
+  const numerator = mod(ySquared - 1n, ED25519_P);
+  const denominator = mod(ED25519_D * ySquared + 1n, ED25519_P);
+  if (denominator === 0n) {
+    return false;
+  }
+  const xSquared = mod(
+    numerator * modPow(denominator, ED25519_P - 2n, ED25519_P),
+    ED25519_P
+  );
+  return xSquared === 0n || modPow(xSquared, (ED25519_P - 1n) / 2n, ED25519_P) === 1n;
 }
-function standardRequirementMatchesSelected(candidate, selected) {
-  const parsed = standardExactRequirementSchema.safeParse(candidate);
-  return parsed.success && stableJson(parsed.data) === stableJson(selected.requirement);
+function littleEndianToBigInt(bytes) {
+  let value = 0n;
+  for (let index = bytes.length - 1; index >= 0; index -= 1) {
+    value = (value << 8n) + BigInt(bytes[index]);
+  }
+  return value;
+}
+function mod(value, modulus) {
+  const result = value % modulus;
+  return result >= 0n ? result : result + modulus;
+}
+function modPow(base, exponent, modulus) {
+  let result = 1n;
+  let nextBase = mod(base, modulus);
+  let nextExponent = exponent;
+  while (nextExponent > 0n) {
+    if ((nextExponent & 1n) === 1n) {
+      result = mod(result * nextBase, modulus);
+    }
+    nextBase = mod(nextBase * nextBase, modulus);
+    nextExponent >>= 1n;
+  }
+  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
+async function assertWithdrawalPreview(input) {
+  const destination = deriveAssociatedTokenAddress({ owner: input.wallet, mint: input.vault.usdcMint });
+  const simulation = await input.rpc.simulateTransaction(
+    input.serializedTransaction,
+    {
+      encoding: "base64",
+      commitment: "confirmed",
+      sigVerify: false,
+      replaceRecentBlockhash: false,
+      innerInstructions: true
+    }
+  ).send({ abortSignal: AbortSignal.timeout(15e3) });
+  if (simulation.value.err !== null) {
+    throw new Error("Withdrawal preview failed on the client RPC; no transaction was signed. Check liquidity, RPC and blockhash, then prepare again.");
+  }
+  let received = 0n;
+  for (const group of simulation.value.innerInstructions ?? []) {
+    for (const instruction of group.instructions) {
+      if (!("parsed" in instruction) || instruction.programId !== SPL_TOKEN_PROGRAM_ID) continue;
+      const parsed = instruction.parsed;
+      if (parsed.type !== "transfer" && parsed.type !== "transferChecked") continue;
+      const info = parsed.info;
+      if (!info || info.destination !== destination && info.source !== destination) continue;
+      const raw = parsed.type === "transferChecked" ? info.tokenAmount?.amount : info.amount;
+      if (typeof raw !== "string" || !/^\d+$/.test(raw)) {
+        throw new Error("Withdrawal preview returned an invalid token amount");
+      }
+      const amount = BigInt(raw);
+      if (info.destination === destination) received += amount;
+      if (info.source === destination) received -= amount;
+    }
+  }
+  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");
+  }
 }
-function stableJson(value) {
-  return JSON.stringify(sortJson(value));
+
+// ../../src/client/lookup-tables.ts
+import { fetchAllMaybeAddressLookupTable } from "@solana-program/address-lookup-table";
+import { address, getCompiledTransactionMessageDecoder } 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 = getCompiledTransactionMessageDecoder().decode(messageBytes);
+  const lookups = compiled.addressTableLookups ?? [];
+  return lookups.map((lookup) => String(lookup.lookupTableAddress));
 }
-function sortJson(value) {
-  if (Array.isArray(value)) {
-    return value.map(sortJson);
+async function fetchLookupTablesForTransaction(rpc2, serializedTransaction) {
+  const addresses = lookupTableAddressesForTransaction(serializedTransaction);
+  if (addresses.length === 0) {
+    return {};
   }
-  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)])
-    );
+  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 value;
+  return result;
 }
 
-// ../../src/client/standard-x402-payer.ts
-var StandardX402PayError = class extends Error {
-  constructor(reason, message, detail = null) {
+// ../../src/client/vault-flows.ts
+var VaultFlowClientError = class extends Error {
+  constructor(step, message, detail = null, code = null, errorDetails = null) {
     super(message);
-    this.reason = reason;
+    this.step = step;
     this.detail = detail;
-    this.name = "StandardX402PayError";
+    this.code = code;
+    this.errorDetails = errorDetails;
+    this.name = "VaultFlowClientError";
   }
-  reason;
+  step;
   detail;
+  code;
+  errorDetails;
 };
-var StandardX402Payer = class {
-  realizer;
-  x402Fetch;
-  probeFetch;
-  defaultMaxAmountRawUsdc;
-  network;
-  usdcMint;
-  stateStore;
-  pending = /* @__PURE__ */ new Map();
-  inFlight = /* @__PURE__ */ new Map();
-  nowMs;
+function vaultOperationKind(intentId) {
+  if (/^dep_[0-9a-f]{32}$/.test(intentId)) return "deposit";
+  if (/^wdr_[0-9a-f]{32}$/.test(intentId)) return "withdrawal";
+  throw new VaultFlowClientError("read", "intentId must be the original dep_ or wdr_ ID followed by 32 lowercase hexadecimal characters");
+}
+var VaultFlowClient = class {
+  vault;
+  rpc;
+  baseUrl;
+  signer;
+  fetchImpl;
+  lookupTablesFor;
+  pollTimeoutMs;
+  pollIntervalMs;
   constructor(config) {
-    this.realizer = config.realizer;
-    this.x402Fetch = config.x402Fetch;
-    this.probeFetch = config.probeFetch ?? fetch;
-    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);
-      }
+    this.rpc = config.rpc;
+    this.vault = config.vault ?? config.signer.vault ?? SUBLY_VAULT;
+    if (config.signer.vault && config.signer.vault.address !== this.vault.address) {
+      throw new Error("Vault flow client and signer must select the same vault");
     }
+    this.baseUrl = config.relayerBaseUrl.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;
   }
-  pay(input, realizer = this.realizer) {
-    const method2 = (input.method ?? "GET").toUpperCase();
-    const requestBodyHash = requestBodyHashFor(input.body ?? null);
-    const pendingKey = pendingPaymentKey({
-      url: input.url,
-      method: method2,
-      requestBodyHash
+  /**
+   * Moves USDC from the agent wallet into the vault (fee sponsored). Under
+   * depositPolicy "owner_approval_required" the relayer refuses to prepare
+   * without an owner approval; when the caller passes none, an already
+   * APPROVED deposit approval for this exact amount (e.g. the mandate's
+   * initialDeposit — "one Face ID covers mandate + first deposit") is looked
+   * up and used automatically before surfacing deposit_approval_required.
+   */
+  async deposit(input) {
+    let approvalId2 = input.approvalId;
+    let prepared;
+    try {
+      prepared = await this.postJson("prepare", "/v1/deposits/prepare", {
+        wallet: this.signer.walletAddress,
+        vault: this.vault.address,
+        amountRawUsdc: input.amountRawUsdc.toString(),
+        ...approvalId2 === void 0 ? {} : { approvalId: approvalId2 }
+      });
+    } catch (error) {
+      if (!(error instanceof VaultFlowClientError) || error.code !== "deposit_approval_required" || approvalId2 !== void 0) {
+        throw error;
+      }
+      approvalId2 = await this.findApprovedDepositApproval(input.amountRawUsdc);
+      if (approvalId2 === void 0) {
+        throw error;
+      }
+      prepared = await this.postJson("prepare", "/v1/deposits/prepare", {
+        wallet: this.signer.walletAddress,
+        vault: this.vault.address,
+        amountRawUsdc: input.amountRawUsdc.toString(),
+        approvalId: approvalId2
+      });
+    }
+    if (prepared.signingIntent?.wallet !== this.signer.walletAddress || prepared.signingIntent.vault !== this.vault.address || prepared.signingIntent.amountRawUsdc !== input.amountRawUsdc.toString()) {
+      throw new VaultFlowClientError("prepare", "Prepared deposit differs from the requested wallet, vault or amount");
+    }
+    const signed = await this.signer.signDeposit({
+      intent: prepared.signingIntent,
+      serializedTransaction: prepared.serializedTransaction,
+      lookupTables: await this.lookupTablesFor(prepared.serializedTransaction)
     });
-    const existingFlow = this.inFlight.get(pendingKey);
-    if (existingFlow !== void 0) {
-      return existingFlow;
+    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
+      );
     }
-    const run = async () => {
-      if (this.stateStore?.withExclusiveLock) {
-        this.pending.clear();
-        for (const record of this.stateStore.load()) this.pending.set(record.key, record);
-      }
-      return this.run(input, { method: method2, requestBodyHash, pendingKey }, realizer);
+    return {
+      depositId: prepared.depositId,
+      status: outcome.status,
+      txSignature: outcome.txSignature ?? null,
+      actualDepositRawUsdc: outcome.actualDepositRawUsdc ?? null,
+      sharesMintedRaw: outcome.sharesMintedRaw ?? null,
+      errorCode: outcome.errorCode ?? null
     };
-    const flow = (this.stateStore?.withExclusiveLock ? this.stateStore.withExclusiveLock(run) : run()).finally(() => {
-      this.inFlight.delete(pendingKey);
-    });
-    this.inFlight.set(pendingKey, flow);
-    return flow;
   }
-  async run(input, computed, realizer) {
-    const { method: method2, 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
+  /**
+   * 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,
+        vault: this.vault.address,
+        amountRawUsdc: input.amountRawUsdc.toString(),
+        ...input.purpose === void 0 ? {} : { purpose: input.purpose },
+        ...input.payment === void 0 ? {} : { payment: input.payment },
+        ...input.approvalId === void 0 ? {} : { approvalId: input.approvalId }
+      }
+    );
+    this.assertPreparedWithdrawal(prepared, input);
+    await input.onPrepared?.(prepared);
+    return this.submitPreparedWithdrawal(prepared, input);
+  }
+  /** Reconcile or submit the original intent; never prepare a replacement. */
+  async resumeWithdrawal(prepared, input) {
+    this.assertPreparedWithdrawal(prepared, input);
+    const current = await this.getJson(
+      `/v1/withdrawals/${encodeURIComponent(prepared.withdrawalId)}`
+    );
+    if (current.withdrawalId !== prepared.withdrawalId || current.wallet !== this.signer.walletAddress || current.vault !== this.vault.address || current.requestedWithdrawRawUsdc !== input.amountRawUsdc.toString() || current.purpose !== (input.purpose ?? "normal") || canonicalJsonHash(current.paymentBinding ?? null) !== canonicalJsonHash(input.payment ?? null) || current.serializedTransaction !== prepared.serializedTransaction || current.preparedMessageHash !== prepared.signingIntent.preparedMessageHash || current.destinationUsdcAta !== prepared.destinationUsdcAta) {
+      throw new VaultFlowClientError("read", "Saved withdrawal differs from the original operation; refusing to resume");
+    }
+    if (current.status === "prepared") {
+      return this.submitPreparedWithdrawal(prepared, input);
+    }
+    if (!["submitted", "confirmed", "failed", "failed_not_submitted", "expired", "quarantined"].includes(current.status)) {
+      throw new VaultFlowClientError("read", "Relayer returned an unknown withdrawal status");
+    }
+    return this.withdrawalOutcome(prepared, current);
+  }
+  assertPreparedWithdrawal(prepared, input) {
+    if (prepared.signingIntent?.wallet !== this.signer.walletAddress || prepared.signingIntent.vault !== this.vault.address || prepared.requestedWithdrawRawUsdc !== input.amountRawUsdc.toString() || prepared.purpose !== (input.purpose ?? "normal") || input.purpose === "yield_realize" && prepared.signingIntent.allowFullExit) {
+      throw new VaultFlowClientError("prepare", "Prepared withdrawal differs from the requested operation");
+    }
+    if (typeof prepared.withdrawalId !== "string" || prepared.withdrawalId.length === 0) {
+      throw new VaultFlowClientError("prepare", "Prepared withdrawal has no withdrawal ID");
+    }
+  }
+  async submitPreparedWithdrawal(prepared, input) {
+    await assertWithdrawalPreview({
+      rpc: this.rpc,
+      serializedTransaction: prepared.serializedTransaction,
+      wallet: this.signer.walletAddress,
+      vault: this.vault,
+      amountRawUsdc: input.amountRawUsdc,
+      ...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)
+    });
+    input.onBeforeSubmit?.();
+    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
       );
     }
-    if (existingPending !== void 0 && input.forceNewPayment === true) {
+    return this.withdrawalOutcome(prepared, outcome);
+  }
+  withdrawalOutcome(prepared, 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
+    };
+  }
+  /** Authenticated read/reconciliation only: never prepare, sign or submit a transaction. */
+  async getOperationStatus(intentId) {
+    const kind = vaultOperationKind(intentId);
+    const raw = await this.getJson(`/v1/${kind === "deposit" ? "deposits" : "withdrawals"}/${intentId}?resubmit=false`);
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+      throw new VaultFlowClientError("read", "Relayer returned an invalid operation status");
+    }
+    const record = raw;
+    if (record[kind === "deposit" ? "depositId" : "withdrawalId"] !== intentId || record.wallet !== this.signer.walletAddress || record.vault !== this.vault.address) {
+      throw new VaultFlowClientError("read", "Operation does not match the requested ID, current wallet or selected vault; use the original wallet, vault and relayer");
+    }
+    const requested = record[kind === "deposit" ? "amountRawUsdc" : "requestedWithdrawRawUsdc"];
+    const actual = record[kind === "deposit" ? "actualDepositRawUsdc" : "actualWithdrawRawUsdc"];
+    if (typeof record.status !== "string" || !["prepared", "submitted", "confirmed", "failed", "expired", "failed_not_submitted"].includes(record.status) || typeof requested !== "string" || !/^\d+$/.test(requested) || actual !== null && (typeof actual !== "string" || !/^\d+$/.test(actual)) || record.txSignature !== null && (typeof record.txSignature !== "string" || record.txSignature.length === 0) || record.errorCode !== null && typeof record.errorCode !== "string" || record.status === "confirmed" && (actual === null || record.txSignature === null)) {
+      throw new VaultFlowClientError("read", "Relayer returned incomplete or invalid operation status fields");
+    }
+    const status = record.status;
+    const nextAction = status === "confirmed" ? "done" : status === "submitted" || status === "prepared" ? "check_again" : "reconcile_with_operator";
+    const message = status === "confirmed" ? `The original ${kind} is confirmed.` : status === "submitted" ? "The original transaction is still confirming. Check this same intent ID again; do not repeat the deposit or withdrawal." : status === "prepared" ? "The original intent is prepared. This status check does not submit it. Check the same ID again or ask the operator to reconcile it before starting another operation." : "The original operation ended without a confirmed result. Reconcile its intent ID and transaction with the operator before starting another operation.";
+    return {
+      intentId,
+      kind,
+      wallet: this.signer.walletAddress,
+      vault: this.vault.address,
+      status,
+      requestedAmountRawUsdc: requested,
+      actualAmountRawUsdc: actual,
+      txSignature: record.txSignature,
+      errorCode: record.errorCode,
+      stillConfirming: status === "submitted",
+      nextAction,
+      message
+    };
+  }
+  /**
+   * 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 {
-        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
+        await this.postJson(
+          "sync",
+          `/v1/wallets/${this.signer.walletAddress}/sync`,
+          { source: "chain", vault: this.vault.address }
         );
+      } catch {
       }
     }
-    const init = {
-      method: method2,
-      ...input.body === void 0 ? {} : { body: input.body },
-      ...input.headers === void 0 ? {} : { headers: input.headers }
-    };
-    const probe = await this.probeFetch(input.url, init);
-    if (probe.status !== 402) {
-      return { paid: false, status: probe.status, body: await probe.text() };
-    }
-    const selected = await this.selectRequirement(probe);
-    const cap = input.maxAmountRawUsdc ?? this.defaultMaxAmountRawUsdc;
-    if (selected.amountRawUsdc > cap) {
-      throw new StandardX402PayError(
-        "amount_exceeds_client_cap",
-        `the challenge demands ${selected.amountRawUsdc} raw USDC, above the client cap of ${cap}; nothing was paid`,
-        { amountRawUsdc: selected.amountRawUsdc.toString(), payTo: selected.payTo }
+    const url2 = `${this.baseUrl}/v1/wallets/${this.signer.walletAddress}/budget?vault=${this.vault.address}`;
+    const response = await this.fetchImpl(url2, {
+      headers: await walletAuthHeaders({
+        signer: this.signer,
+        method: "GET",
+        url: url2
+      })
+    });
+    const text = await response.text();
+    if (response.status !== 200) {
+      throw new VaultFlowClientError(
+        "budget",
+        `budget endpoint returned ${response.status}: ${text}`
       );
     }
-    let realized;
+    let parsed;
     try {
-      realized = await realizer.ensureUsdcAvailable({
-        amountRawUsdc: selected.amountRawUsdc,
-        payment: {
-          payTo: selected.payTo,
-          amountRawUsdc: selected.amountRawUsdc.toString(),
-          resourceUrlHash: sha256HexOf(input.url),
-          method: method2
-        },
-        ...input.approvalId === void 0 ? {} : { approvalId: input.approvalId }
-      });
-    } catch (error) {
-      if (error.code === "approval_required") {
-        throw new StandardX402PayError(
-          "approval_required",
-          "this payment exceeds the owner-approval threshold; NOTHING was paid. Ask the owner to open the approveUrl, then retry the same call with the approvalId",
-          error.detail ?? null
-        );
-      }
-      throw new StandardX402PayError(
-        "realize_failed",
-        `could not realize yield to cover ${selected.amountRawUsdc} raw USDC: ${error instanceof Error ? error.message : String(error)}`,
-        error
+      parsed = JSON.parse(text);
+    } catch {
+      throw new VaultFlowClientError(
+        "budget",
+        "budget endpoint returned 200 with a non-JSON body",
+        text
       );
     }
-    const pendingRecord = {
-      key: pendingKey,
-      url: input.url,
-      method: method2,
-      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()
+    const body2 = parsed;
+    if (body2.position?.vault !== void 0 && body2.position.vault !== this.vault.address) {
+      throw new VaultFlowClientError("budget", "Relayer returned the budget for a different vault");
+    }
+    return {
+      wallet: this.signer.walletAddress,
+      vault: this.vault.address,
+      principalBasisRawUsdc: body2.position?.principalBasisRawUsdc ?? "0",
+      positionValueRawUsdc: body2.budget?.positionValueRawUsdc ?? "0",
+      grossYieldRawUsdc: body2.budget?.grossYieldRawUsdc ?? "0",
+      spendableYieldRawUsdc: body2.budget?.spendableYieldRawUsdc ?? "0"
     };
-    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 }
-      );
+  }
+  /** Best-effort audit link: reports the x402 payment tx a realize funded. */
+  async reportPayment(input) {
+    await this.postJson("submit", "/v1/payments/report", {
+      wallet: this.signer.walletAddress,
+      withdrawalId: input.withdrawalId,
+      paymentTxSignature: input.paymentTxSignature
+    });
+  }
+  /** Wallet's approvals as the relayer sees them (optionally by status). */
+  async listApprovals(status) {
+    const body2 = await this.getJson(
+      `/v1/wallets/${this.signer.walletAddress}/approvals${`?vault=${this.vault.address}${status === void 0 ? "" : `&status=${encodeURIComponent(status)}`}`}`
+    );
+    return body2.approvals ?? [];
+  }
+  /**
+   * Creates the owner-onboarding setup link (wallet-auth pins the agreed
+   * policy + initial deposit). Paste `setupUrl` into the chat verbatim.
+   */
+  async createSetupSession(input) {
+    const session = await this.postJson(
+      "prepare",
+      `/v1/wallets/${this.signer.walletAddress}/setup-sessions`,
+      {
+        vault: this.vault.address,
+        ...input.policy === void 0 ? {} : { policy: input.policy },
+        ...input.enforcementMode === void 0 ? {} : { enforcementMode: input.enforcementMode },
+        ...input.mandateTtlDays === void 0 ? {} : { mandateTtlDays: input.mandateTtlDays },
+        ...input.initialDepositRawUsdc === void 0 ? {} : { initialDepositRawUsdc: input.initialDepositRawUsdc }
+      }
+    );
+    if (session.vault !== this.vault.address || session.wallet !== this.signer.walletAddress) {
+      throw new VaultFlowClientError("prepare", "Relayer returned a setup session for a different wallet or vault");
     }
-    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 }
+    return session;
+  }
+  /** Polls a setup session (public capability URL — no auth needed). */
+  async getSetupSession(sessionId) {
+    const url2 = `${this.baseUrl}/v1/setup-sessions/${encodeURIComponent(sessionId)}`;
+    const response = await this.fetchImpl(url2);
+    const text = await response.text();
+    if (response.status !== 200) {
+      const parsed = parseRelayerError(text);
+      throw new VaultFlowClientError(
+        "read",
+        parsed.message ?? `setup session read failed with ${response.status}`,
+        text,
+        parsed.code,
+        parsed.details
       );
     }
-    let response;
+    return JSON.parse(text);
+  }
+  /**
+   * Finds an APPROVED, unconsumed deposit approval bound to exactly this
+   * amount — the shape the mandate's initialDeposit approval has.
+   */
+  async findApprovedDepositApproval(amountRawUsdc) {
     try {
-      response = await this.x402Fetch(input.url, init, selected);
-    } catch (error) {
-      const persistError = this.tryMarkUnknown(pendingKey, {
-        message: error instanceof Error ? error.message : String(error)
+      const approvals = await this.listApprovals("approved");
+      const match = approvals.find((approval) => {
+        const binding = approval.binding;
+        return binding?.kind === "deposit" && binding.amountRawUsdc === amountRawUsdc.toString();
       });
-      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 }
-      );
+      return match?.approvalId;
+    } catch {
+      return void 0;
     }
-    const bodyText = await response.text();
-    if (response.status !== 200) {
-      const persistError = this.tryMarkUnknown(pendingKey, {
-        status: response.status,
-        body: bodyText
+  }
+  /**
+   * 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 url2 = `${this.baseUrl}${path}`;
+      const response = await this.fetchImpl(url2, {
+        headers: await walletAuthHeaders({
+          signer: this.signer,
+          method: "GET",
+          url: url2
+        })
       });
-      throw new StandardX402PayError(
-        "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);
-    const paymentTxSignature = extractSettledPaymentTxSignature(response);
-    if (paymentTxSignature !== null && typeof realized.withdrawalId === "string" && realizer.reportPayment !== void 0) {
+      if (response.status !== 200) {
+        continue;
+      }
       try {
-        await realizer.reportPayment({
-          withdrawalId: realized.withdrawalId,
-          paymentTxSignature
-        });
-      } catch (error) {
-        console.error(
-          `[subly-x402] payment report-back failed (audit only, payment ok): ${error instanceof Error ? error.message : String(error)}`
-        );
+        latest = await response.json();
+      } catch {
+        continue;
       }
-    }
-    return {
-      paid: true,
-      ...realizer.vault === void 0 ? {} : { fundingVault: realizer.vault },
-      status: response.status,
-      body: bodyText,
-      payment: {
-        amountRawUsdc: selected.amountRawUsdc.toString(),
-        payTo: selected.payTo,
-        feePayer: selected.feePayer,
-        realizedRawUsdc: realized.realizedRawUsdc.toString(),
-        realizeTxSignature: realized.txSignature,
-        paymentTxSignature
+      if (latest.status !== "submitted") {
+        return latest;
       }
-    };
+    }
+    return latest;
   }
-  /** Reads the challenge from the header (preferred) or the JSON body. */
-  async selectRequirement(probe) {
-    const header = probe.headers.get(PAYMENT_REQUIRED_HEADER);
-    let requirements;
-    try {
-      if (header !== null) {
-        requirements = decodeStandardPaymentRequiredHeader(header).solanaExactRequirements;
-      } else {
-        requirements = parseStandardChallenge(
-          await probe.json()
-        ).solanaExactRequirements;
-      }
-    } catch (error) {
-      throw new StandardX402PayError(
-        error instanceof StandardX402ChallengeError ? error.reason : "invalid_challenge",
-        "could not parse the x402 402 challenge",
-        error
+  async postJson(step, path, body2) {
+    const url2 = `${this.baseUrl}${path}`;
+    const serialized = JSON.stringify(body2);
+    const response = await this.fetchImpl(url2, {
+      method: "POST",
+      headers: {
+        ...await walletAuthHeaders({
+          signer: this.signer,
+          method: "POST",
+          url: url2,
+          body: serialized
+        }),
+        "content-type": "application/json"
+      },
+      body: serialized
+    });
+    const text = await response.text();
+    if (response.status !== 200) {
+      const parsed = parseRelayerError(text);
+      throw new VaultFlowClientError(
+        step,
+        parsed.message === null ? `${path} failed with ${response.status}: ${text}` : `${path} failed (${parsed.code ?? response.status}): ${parsed.message}`,
+        text,
+        parsed.code,
+        parsed.details
       );
     }
     try {
-      return selectPayableSolanaRequirement(requirements, {
-        network: this.network,
-        usdcMint: this.usdcMint
-      });
-    } catch (error) {
-      throw new StandardX402PayError(
-        "no_payable_requirement",
-        error instanceof Error ? error.message : String(error),
-        error
+      return JSON.parse(text);
+    } catch {
+      throw new VaultFlowClientError(
+        step,
+        `${path} returned 200 with a non-JSON body`,
+        text
       );
     }
   }
-  track(record) {
-    const previous = this.pending.get(record.key);
-    this.pending.set(record.key, record);
+  async getJson(path) {
+    const url2 = `${this.baseUrl}${path}`;
+    const response = await this.fetchImpl(url2, {
+      headers: await walletAuthHeaders({
+        signer: this.signer,
+        method: "GET",
+        url: url2
+      })
+    });
+    const text = await response.text();
+    if (response.status !== 200) {
+      const parsed = parseRelayerError(text);
+      throw new VaultFlowClientError(
+        "read",
+        parsed.message === null ? `${path} failed with ${response.status}: ${text}` : `${path} failed (${parsed.code ?? response.status}): ${parsed.message}`,
+        text,
+        parsed.code,
+        parsed.details
+      );
+    }
     try {
-      this.persist();
-    } catch (error) {
-      if (previous === void 0) {
-        this.pending.delete(record.key);
-      } else {
-        this.pending.set(record.key, previous);
-      }
-      throw error;
+      return JSON.parse(text);
+    } catch {
+      throw new VaultFlowClientError(
+        "read",
+        `${path} returned 200 with a non-JSON body`,
+        text
+      );
     }
   }
-  markUnknown(key, detail) {
-    const current = this.pending.get(key);
-    if (current === void 0) {
-      return;
-    }
-    const next = {
-      ...current,
-      status: "external_outcome_unknown",
-      updatedAtMs: this.nowMs(),
-      detail
+};
+function parseRelayerError(text) {
+  try {
+    const parsed = JSON.parse(text);
+    return {
+      code: typeof parsed.error?.code === "string" ? parsed.error.code : null,
+      message: typeof parsed.error?.message === "string" ? parsed.error.message : null,
+      details: parsed.error?.details ?? null
     };
-    this.pending.set(key, next);
-    try {
-      this.persist();
-    } catch (error) {
-      this.pending.set(key, current);
-      throw error;
-    }
+  } catch {
+    return { code: null, message: null, details: null };
   }
-  tryMarkUnknown(key, detail) {
+}
+
+// ../../src/client/relayer-yield-realizer.ts
+var REALIZE_OVERHEAD_RAW_USDC = 2500n;
+var RelayerRealizeError = class extends Error {
+  constructor(code, message, detail = null, realizationSafeToRetry = false) {
+    super(message);
+    this.code = code;
+    this.detail = detail;
+    this.realizationSafeToRetry = realizationSafeToRetry;
+    this.name = "RelayerRealizeError";
+  }
+  code;
+  detail;
+  realizationSafeToRetry;
+};
+var RelayerYieldRealizer = class {
+  get vault() {
+    return this.vaultFlows.vault.address;
+  }
+  realizationContext;
+  vaultFlows;
+  constructor(config) {
+    this.vaultFlows = new VaultFlowClient({
+      relayerBaseUrl: config.relayerBaseUrl,
+      signer: config.signer,
+      rpc: config.rpc,
+      ...config.fetchImpl === void 0 ? {} : { fetchImpl: config.fetchImpl },
+      ...config.lookupTablesFor === void 0 ? {} : { lookupTablesFor: config.lookupTablesFor }
+    });
+    this.realizationContext = Object.freeze({
+      wallet: config.signer.walletAddress,
+      vault: this.vaultFlows.vault.address,
+      relayerBaseUrl: config.relayerBaseUrl.replace(/\/$/, "")
+    });
+  }
+  async ensureUsdcAvailable(input) {
+    const shortfallRawUsdc = input.amountRawUsdc;
+    await this.assertSpendableYield(shortfallRawUsdc);
+    let outcome;
+    let submissionPossible = false;
     try {
-      this.markUnknown(key, detail);
-      return null;
+      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",
+        // Declares what is being paid so the relayer's spending-mandate layer
+        // can enforce caps/payee and keep the mandate → payment audit chain.
+        ...input.payment === void 0 ? {} : { payment: input.payment },
+        ...input.approvalId === void 0 ? {} : { approvalId: input.approvalId },
+        ...input.onPrepared === void 0 ? {} : { onPrepared: input.onPrepared },
+        onBeforeSubmit: () => {
+          submissionPossible = true;
+        }
+      });
     } catch (error) {
-      return error;
+      if (error instanceof StandardX402PayError) throw error;
+      throw this.mapWithdrawError(error, !submissionPossible);
     }
+    return this.confirmedRealization(outcome);
   }
-  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;
+  async resumeUsdcAvailable(input) {
+    const outcome = await this.vaultFlows.resumeWithdrawal(input.prepared, {
+      amountRawUsdc: input.amountRawUsdc,
+      purpose: "yield_realize",
+      payment: input.payment
+    });
+    return this.confirmedRealization(outcome);
+  }
+  confirmedRealization(outcome) {
+    if (outcome.status !== "confirmed" || outcome.txSignature === null) {
+      throw new RelayerRealizeError(
+        "realize_not_confirmed",
+        `yield realize withdrawal did not confirm (status=${outcome.status})`,
+        outcome
+      );
     }
+    return {
+      realizedRawUsdc: BigInt(outcome.actualWithdrawRawUsdc ?? "0"),
+      txSignature: outcome.txSignature,
+      withdrawalId: outcome.withdrawalId
+    };
   }
-  clearDelivered(key) {
-    const previous = this.pending.get(key);
-    this.pending.delete(key);
+  /**
+   * Best-effort report-back of the x402 payment tx this realize funded —
+   * closes the relayer's mandate → realize → payment audit chain. Callers
+   * must never let a failure here affect the payment result.
+   */
+  async reportPayment(input) {
+    await this.vaultFlows.reportPayment(input);
+  }
+  /**
+   * 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 {
-      this.persist();
+      const budget = await this.vaultFlows.getBudget();
+      spendable = BigInt(budget.spendableYieldRawUsdc);
     } 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)}`
+      throw new RelayerRealizeError(
+        "budget_unavailable",
+        "could not read the spendable-yield budget",
+        error,
+        true
+      );
+    }
+    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() },
+        true
       );
     }
   }
-  persist() {
-    if (this.stateStore === null) {
-      return;
+  mapWithdrawError(error, safeToRetry) {
+    if (!(error instanceof VaultFlowClientError)) {
+      return new RelayerRealizeError(
+        "prepare_failed",
+        `yield realize failed: ${error instanceof Error ? error.message : String(error)}`,
+        error,
+        safeToRetry
+      );
     }
-    this.stateStore.save([...this.pending.values()]);
+    const serverCode = error.code ?? errorCodeFrom(error.detail);
+    if (serverCode === "approval_required") {
+      return new RelayerRealizeError(
+        "approval_required",
+        "this payment exceeds the owner-approval threshold; nothing was realized or paid. Ask the owner to approve, then retry with the approvalId",
+        error.errorDetails ?? error.detail,
+        safeToRetry
+      );
+    }
+    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,
+        safeToRetry
+      );
+    }
+    return new RelayerRealizeError(
+      error.step === "submit" ? "submit_failed" : "prepare_failed",
+      error.message,
+      error.detail,
+      safeToRetry
+    );
   }
 };
-function pendingPaymentKey(input) {
-  return `${input.method}:${input.url}:${input.requestBodyHash}`;
-}
-function extractSettledPaymentTxSignature(response) {
-  const header = response.headers.get(PAYMENT_RESPONSE_HEADER) ?? response.headers.get("x-payment-response");
-  if (header === null || header.length === 0) {
+function errorCodeFrom(detail) {
+  if (typeof detail !== "string") {
     return null;
   }
   try {
-    const decoded = JSON.parse(
-      Buffer.from(header, "base64").toString("utf8")
-    );
-    if (typeof decoded.transaction === "string" && decoded.transaction.length > 0) {
-      return decoded.transaction;
-    }
-    if (typeof decoded.txHash === "string" && decoded.txHash.length > 0) {
-      return decoded.txHash;
-    }
-    return null;
+    const parsed = JSON.parse(detail);
+    return typeof parsed.error?.code === "string" ? parsed.error.code : null;
   } catch {
     return null;
   }
@@ -2799,13 +3026,13 @@ async function createCircleSignerTransport(config) {
 import { createPrivateKey, createSign } from "node:crypto";
 var PROVIDER2 = "privy";
 var DEFAULT_BASE_URL2 = "https://api.privy.io";
-function canonicalJson(value) {
+function canonicalJson2(value) {
   if (Array.isArray(value)) {
-    return `[${value.map(canonicalJson).join(",")}]`;
+    return `[${value.map(canonicalJson2).join(",")}]`;
   }
   if (value !== null && typeof value === "object") {
     const entries = Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
-    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(",")}}`;
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson2(v)}`).join(",")}}`;
   }
   return JSON.stringify(value);
 }
@@ -2834,7 +3061,7 @@ function authorizationSignature(params) {
     headers: { "privy-app-id": params.appId }
   };
   const signer2 = createSign("sha256");
-  signer2.update(canonicalJson(payload));
+  signer2.update(canonicalJson2(payload));
   return signer2.sign(params.key).toString("base64");
 }
 async function createPrivySignerTransport(config) {
@@ -3009,7 +3236,7 @@ async function agentWalletSignerFromEnv(env = process.env) {
 }
 
 // ../../src/client/standard-x402-state-store.ts
-import { closeSync, mkdirSync, openSync, readFileSync as readFileSync3, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync as readFileSync3, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 function fileStandardX402StateStore(path) {
   return {
@@ -3054,6 +3281,9 @@ function fileStandardX402StateStore(path) {
           );
         }
       }
+      if (new Set(parsed.map((record) => record.key)).size !== parsed.length) {
+        throw new Error(`pending payment state has duplicate request keys: ${path}`);
+      }
       return parsed;
     },
     save(records) {
@@ -3063,8 +3293,29 @@ function fileStandardX402StateStore(path) {
         directory,
         `.${basename(path)}.${process.pid}.${Date.now()}.tmp`
       );
-      writeFileSync(tempPath, JSON.stringify(records, null, 2), { mode: 384, flag: "wx" });
-      renameSync(tempPath, path);
+      try {
+        const fd = openSync(tempPath, "wx", 384);
+        try {
+          writeFileSync(fd, JSON.stringify(records, null, 2));
+          fsyncSync(fd);
+        } finally {
+          closeSync(fd);
+        }
+        renameSync(tempPath, path);
+        if (process.platform !== "win32") {
+          const directoryFd = openSync(directory, "r");
+          try {
+            fsyncSync(directoryFd);
+          } finally {
+            closeSync(directoryFd);
+          }
+        }
+      } finally {
+        try {
+          unlinkSync(tempPath);
+        } catch {
+        }
+      }
     }
   };
 }
@@ -3076,7 +3327,20 @@ function isPendingPaymentRecord(value) {
     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";
+  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 === "realizing" || record.status === "realized" || record.status === "external_outcome_unknown") && (record.recovery === void 0 || isRecoveryRecord(record.recovery) && record.key === `${record.method}:${record.url}:${record.requestBodyHash}` && /^\d+$/.test(String(record.realizedRawUsdc)) && /^\d+$/.test(String(record.amountRawUsdc))) && typeof record.createdAtMs === "number" && typeof record.updatedAtMs === "number";
+}
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isRecoveryRecord(value) {
+  if (!isObject(value) || value.version !== 1 || !isObject(value.context)) return false;
+  const context = value.context;
+  if (!["wallet", "vault", "relayerBaseUrl"].every((key) => typeof context[key] === "string" && context[key] !== "") || typeof value.requestHeadersHash !== "string" || !/^[0-9a-f]{64}$/.test(value.requestHeadersHash) || !standardExactRequirementSchema.safeParse(value.requirement).success) return false;
+  if (value.prepared === void 0) return true;
+  const prepared = value.prepared;
+  if (!isObject(prepared) || !isObject(prepared.signingIntent) || prepared.purpose !== "yield_realize" || !["withdrawalId", "serializedTransaction", "destinationUsdcAta", "requestedWithdrawRawUsdc"].every((key) => typeof prepared[key] === "string" && prepared[key] !== "")) return false;
+  const intent = prepared.signingIntent;
+  return intent.allowFullExit === false && ["wallet", "vault", "farm", "shareMint", "asset", "destinationUsdcAta", "maxSharesToRedeemRaw", "feePayer", "expiresAt", "preparedMessageHash"].every((key) => typeof intent[key] === "string" && intent[key] !== "");
 }
 
 // ../../src/solana/rpc.ts
@@ -3153,6 +3417,13 @@ function selectExpectedRequirement(requirements, expected) {
   return match;
 }
 
+// ../../demo/cli-command.ts
+import { readFileSync as readFileSync4 } from "node:fs";
+var { version } = JSON.parse(
+  readFileSync4(new URL("../package.json", import.meta.url), "utf8")
+);
+var PAY_COMMAND = `npx -y @subly_fi/pay@${version}`;
+
 // src/pay.ts
 function fail(message) {
   process.stderr.write(`${message}
@@ -3161,7 +3432,7 @@ function fail(message) {
 }
 var url = process.argv[2];
 if (url === void 0 || !/^https?:\/\//.test(url)) {
-  fail("Usage: pay fetch <url> [maxAmountRawUsdc] [apr_<approvalId>]");
+  fail(`Usage: ${PAY_COMMAND} fetch <url> [maxAmountRawUsdc] [apr_<approvalId>]`);
 }
 var maxAmountArg;
 var approvalId;
@@ -3172,7 +3443,7 @@ for (const arg of process.argv.slice(3)) {
     maxAmountArg = arg;
   } else {
     fail(`unrecognized argument: ${arg}
-Usage: pay fetch <url> [maxAmountRawUsdc] [apr_<approvalId>]`);
+Usage: ${PAY_COMMAND} fetch <url> [maxAmountRawUsdc] [apr_<approvalId>]`);
   }
 }
 var relayerBaseUrl = process.env.SUBLY_RELAYER_URL ?? process.env.SUBLY_FACILITATOR_URL ?? "https://api.demo.sublyfi.com";
@@ -3228,7 +3499,7 @@ try {
           message: error.message,
           detail: error.detail ?? null,
           ...refusalApprovalId === void 0 ? {} : {
-            retry: `pay fetch "${url}"${maxAmountArg === void 0 ? "" : ` ${maxAmountArg}`} ${refusalApprovalId}`
+            retry: `${PAY_COMMAND} fetch "${url}"${maxAmountArg === void 0 ? "" : ` ${maxAmountArg}`} ${refusalApprovalId}`
           }
         },
         null,