@spield/sdk 0.4.0

package/dist/index.js

@@ -0,0 +1,1474 @@
+// src/errors.ts
+var SpieldSdkError = class extends Error {
+  constructor(message, code, cause) {
+    super(message);
+    this.code = code;
+    this.cause = cause;
+    this.name = "SpieldSdkError";
+  }
+  code;
+  cause;
+};
+var SpieldValidationError = class extends SpieldSdkError {
+  constructor(message, cause) {
+    super(message, "validation_error", cause);
+    this.name = "SpieldValidationError";
+  }
+};
+var SpieldSignerError = class extends SpieldSdkError {
+  constructor(message, cause) {
+    super(message, "signer_error", cause);
+    this.name = "SpieldSignerError";
+  }
+};
+var SpieldRpcError = class extends SpieldSdkError {
+  constructor(message, cause) {
+    super(message, "rpc_error", cause);
+    this.name = "SpieldRpcError";
+  }
+};
+var SpieldContractError = class extends SpieldSdkError {
+  constructor(message, cause) {
+    super(message, "contract_error", cause);
+    this.name = "SpieldContractError";
+  }
+};
+var SpieldConfigurationError = class extends SpieldSdkError {
+  constructor(message, cause) {
+    super(message, "configuration_error", cause);
+    this.name = "SpieldConfigurationError";
+  }
+};
+
+// src/amount.ts
+var toBaseUnits = (amount, decimals = 7) => {
+  if (typeof amount === "bigint") return amount;
+  const s = String(amount).trim();
+  if (!/^-?\d+(\.\d+)?$/.test(s)) {
+    throw new SpieldValidationError(`Invalid token amount: ${String(amount)}`);
+  }
+  const neg = s.startsWith("-");
+  const [wholeRaw, fracRaw = ""] = s.replace("-", "").split(".");
+  if (fracRaw.length > decimals) {
+    throw new SpieldValidationError(`Amount has more than ${decimals} decimal places.`);
+  }
+  const scale = 10n ** BigInt(decimals);
+  const whole = BigInt(wholeRaw || "0") * scale;
+  const frac = BigInt((fracRaw + "0".repeat(decimals)).slice(0, decimals) || "0");
+  const value = whole + frac;
+  return neg ? -value : value;
+};
+var assertPositiveAmount = (amount, decimals = 7) => {
+  const raw = toBaseUnits(amount, decimals);
+  if (raw <= 0n) throw new SpieldValidationError("Amount must be greater than zero.");
+  return raw;
+};
+var assertNonNegativeAmount = (amount, decimals = 7) => {
+  const raw = toBaseUnits(amount, decimals);
+  if (raw < 0n) throw new SpieldValidationError("Amount must be zero or greater.");
+  return raw;
+};
+var fromBaseUnits = (units, decimals = 7) => {
+  const value = BigInt(units);
+  const sign = value < 0n ? "-" : "";
+  const abs = value < 0n ? -value : value;
+  const scale = 10n ** BigInt(decimals);
+  const whole = abs / scale;
+  const frac = (abs % scale).toString().padStart(decimals, "0").replace(/0+$/, "");
+  return `${sign}${whole.toString()}${frac ? `.${frac}` : ""}`;
+};
+var tokenAmount = (raw, symbol, decimals = 7) => ({
+  raw: BigInt(raw),
+  formatted: fromBaseUnits(raw, decimals),
+  decimals,
+  symbol
+});
+
+// src/soroban.ts
+import {
+  Account,
+  Address,
+  BASE_FEE,
+  Contract,
+  TransactionBuilder,
+  nativeToScVal,
+  rpc,
+  scValToNative
+} from "@stellar/stellar-sdk";
+
+// src/config.ts
+var STELLAR_NETWORK_PASSPHRASES = {
+  PUBLIC: "Public Global Stellar Network ; September 2015",
+  TESTNET: "Test SDF Network ; September 2015"
+};
+var testnet = () => ({
+  key: "testnet",
+  networkName: "TESTNET",
+  networkPassphrase: STELLAR_NETWORK_PASSPHRASES.TESTNET,
+  rpcUrl: "https://soroban-testnet.stellar.org",
+  horizonUrl: "https://horizon-testnet.stellar.org",
+  explorerUrl: "https://stellar.expert/explorer/testnet",
+  contracts: {
+    sr: "CDYAM3NGY5I3SUGPCDQUS25MGCIWT2YOBDSWYT6SJNIPN6A6OOUSSCZY",
+    strategy: "CDPNSWSBVBRF52SED6UD7T2VQH6XODLEHXSCFTZHQP73SNYTKIHP5R2B",
+    yieldEngine: "CDS2Q6L3QCUK4KX633M7QH53GC76EVOUAK7WJ54T3AP3J6IGXIM3LURD",
+    market: "CBL7Z3BONITNSWO7NJLT67464HLVVQF5G3REI3XT6KUCK7YNHPICJX5A",
+    vault: "CDKV7Z7FF3DA57LSO2JA6GFKAIDDIDMZD5XWCMV7G5I3E4ZA3NN2NMH7",
+    router: "CDP3VUYH3GEGNOF4XUHKMP5GBTH3SBCL5R3GM5ZTVQAGV7FOAPAQJTGE",
+    pt: "CB3T6FOMAH77Z2FMSA2IEVLQEIYOQRRFP7JMJMJGMUCO6HGOOZJZJ7OC",
+    usdc: "CAQCFVLOBK5GIULPNZRGATJJMIZL5BSP7X5YJVMGCPTUEPFM4AVSRCJU"
+  },
+  assets: {
+    pt: { code: "SPLDPT7", issuer: "GDTM2UMJEO6LV5HE2SI56IEWNX5OAF5HV2XNZMVZEDXMMPHZUWXSSLQU" }
+  },
+  decimals: 7
+});
+var customNetwork = (config) => config;
+var explorerTx = (network, hash) => `${network.explorerUrl}/tx/${hash}`;
+
+// src/soroban.ts
+var DEFAULT_SIMULATION_SOURCE = "GBNK7ZOQIZL3HM2LPY7WWJJL3C5YCOEUIJAF4UBSPIEWCEIC2HFSBVVI";
+var DEFAULT_CONFIRMATION_TIMEOUT_MS = 12e4;
+var DEFAULT_CONFIRMATION_POLL_INTERVAL_MS = 1e3;
+var createRpcServer = (network) => new rpc.Server(network.rpcUrl, { allowHttp: network.rpcUrl.startsWith("http://") });
+var i128 = (v) => nativeToScVal(v, { type: "i128" });
+var u64 = (v) => nativeToScVal(BigInt(v), { type: "u64" });
+var u32 = (v) => nativeToScVal(v, { type: "u32" });
+var addr = (a) => new Address(a).toScVal();
+var toBig = (v) => {
+  if (typeof v === "bigint") return v;
+  if (typeof v === "number") return BigInt(Math.trunc(v));
+  if (typeof v === "string") return BigInt(v);
+  return 0n;
+};
+var toNum = (v) => Number(toBig(v));
+var SorobanClient = class {
+  constructor(context) {
+    this.context = context;
+    this.server = createRpcServer(context.network);
+  }
+  context;
+  server;
+  async read(contractId, method, args = []) {
+    const contract = new Contract(contractId);
+    const account = new Account(this.context.simulationSource, "0");
+    const tx = new TransactionBuilder(account, {
+      fee: BASE_FEE,
+      networkPassphrase: this.context.network.networkPassphrase
+    }).addOperation(contract.call(method, ...args)).setTimeout(30).build();
+    let sim;
+    try {
+      sim = await this.server.simulateTransaction(tx);
+    } catch (err) {
+      throw new SpieldContractError(
+        `${method} response could not be parsed (SDK/protocol version mismatch): ${err instanceof Error ? err.message : String(err)}`,
+        err
+      );
+    }
+    if (rpc.Api.isSimulationError(sim)) {
+      throw new SpieldContractError(`${method} failed: ${sim.error}`, sim.error);
+    }
+    const retval = sim.result?.retval;
+    return retval ? scValToNative(retval) : void 0;
+  }
+  /**
+   * **Simulate a value-moving entry point AS `invoker`, and return what it would actually pay.**
+   *
+   * The `quote_*` views cannot synchronize SR — a view may not write — so they price on SR's stored
+   * high-water rate, which lags whenever nothing has synced since the last mutation. The real entry
+   * points *do* synchronize (`FINAL_CHECK.md` V2-01), so a quote can OVER-state a sale: derive
+   * `minOut` from it and the trade can trip its own slippage bound and revert.
+   *
+   * Simulating the real function runs the same synchronized code the submission will. Nothing is
+   * signed and nothing is sent.
+   *
+   * Unlike {@link read}, this simulates as the **user** rather than the shared simulation source,
+   * because the result depends on their balances.
+   *
+   * Returns `null` whenever the simulation cannot run — an unaffordable size, a route the pool
+   * cannot fill, a deployment predating the entry point — so callers fall back to the quote instead
+   * of failing the trade.
+   */
+  async simulateAs(invoker, contractId, method, args = []) {
+    try {
+      const tx = new TransactionBuilder(new Account(invoker, "0"), {
+        fee: BASE_FEE,
+        networkPassphrase: this.context.network.networkPassphrase
+      }).addOperation(new Contract(contractId).call(method, ...args)).setTimeout(30).build();
+      const sim = await this.server.simulateTransaction(tx);
+      if (rpc.Api.isSimulationError(sim)) return null;
+      const retval = sim.result?.retval;
+      if (!retval) return null;
+      const native = scValToNative(retval);
+      return typeof native === "bigint" ? native : BigInt(String(native));
+    } catch {
+      return null;
+    }
+  }
+  async write(contractId, method, args = [], signer = this.context.signer) {
+    if (!signer) throw new SpieldSignerError("A signer is required for write transactions.");
+    const walletAddress = await signer.getAddress();
+    const contract = new Contract(contractId);
+    const sourceAccount = await this.server.getAccount(walletAddress);
+    const built = new TransactionBuilder(sourceAccount, {
+      fee: BASE_FEE,
+      networkPassphrase: this.context.network.networkPassphrase
+    }).addOperation(contract.call(method, ...args)).setTimeout(60).build();
+    const sim = await this.server.simulateTransaction(built);
+    if (rpc.Api.isSimulationError(sim)) {
+      throw new SpieldContractError(parseContractError(sim.error, method, this.context.network), sim.error);
+    }
+    const prepared = rpc.assembleTransaction(built, sim).build();
+    const { signedTxXdr } = await signer.signTransaction(prepared.toXDR(), {
+      networkPassphrase: this.context.network.networkPassphrase,
+      address: walletAddress
+    });
+    const signed = TransactionBuilder.fromXDR(signedTxXdr, this.context.network.networkPassphrase);
+    const sent = await this.server.sendTransaction(signed);
+    if (sent.status === "ERROR") {
+      throw new SpieldRpcError(`Submission failed: ${JSON.stringify(sent.errorResult)}`, sent.errorResult);
+    }
+    return this.waitForConfirmation(sent.hash);
+  }
+  async waitForConfirmation(hash) {
+    const timeoutMs = positiveMs(this.context.confirmationTimeoutMs, DEFAULT_CONFIRMATION_TIMEOUT_MS);
+    const pollIntervalMs = positiveMs(this.context.confirmationPollIntervalMs, DEFAULT_CONFIRMATION_POLL_INTERVAL_MS);
+    const deadline = Date.now() + timeoutMs;
+    let lastRpcError;
+    do {
+      try {
+        const result = await this.server.getTransaction(hash);
+        if (result.status === rpc.Api.GetTransactionStatus.SUCCESS) {
+          return { hash, status: "success", explorerUrl: explorerTx(this.context.network, hash) };
+        }
+        if (result.status === rpc.Api.GetTransactionStatus.FAILED) {
+          throw new SpieldRpcError(`Transaction failed on-chain: ${hash}`, result);
+        }
+      } catch (err) {
+        if (err instanceof SpieldRpcError) throw err;
+        lastRpcError = err;
+      }
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) break;
+      await sleep(Math.min(pollIntervalMs, remaining));
+    } while (Date.now() <= deadline);
+    throw new SpieldRpcError(
+      `Timed out waiting ${timeoutMs}ms for transaction confirmation: ${hash}. The transaction was submitted and may still settle; check the explorer before resubmitting.`,
+      lastRpcError
+    );
+  }
+};
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var positiveMs = (value, fallback) => Number.isFinite(value) && (value ?? 0) > 0 ? Math.floor(value) : fallback;
+var CONTRACT_ERRORS = {
+  1: "The contract is already initialized.",
+  2: "The contract is not initialized yet.",
+  3: "The caller is not authorized for this operation.",
+  4: "The protocol is currently paused.",
+  5: "Amount must be greater than zero.",
+  6: "The operation overflowed.",
+  11: "The token does not use the 7 decimals the protocol is calibrated for.",
+  22: "PT can only be redeemed at or after maturity.",
+  23: "Insufficient balance for this operation.",
+  24: "The operation would break the solvency invariant and was refused.",
+  40: "Blend reported a rate outside the configured sanity bound.",
+  41: "The strategy holds no Blend position for this asset.",
+  42: "Blend returned less underlying than required. Try a smaller amount.",
+  60: "That vault receipt does not exist.",
+  61: "The caller does not own that vault receipt.",
+  62: "The vault has not matured yet.",
+  63: "That vault receipt has already been redeemed.",
+  64: "The vault lacks the spare PT to back a coupon for this deposit.",
+  65: "The quoted fixed rate is outside the allowed range.",
+  66: "The vault series has expired; deposits are closed.",
+  80: "Not enough market liquidity for this trade.",
+  81: "The output fell below your slippage floor and the trade was reverted.",
+  82: "The market has expired; PT now redeems at face value instead of trading.",
+  83: "You do not hold that many LP shares.",
+  84: "Liquidity must be added in the pool's current PT/SR proportion.",
+  100: "The spender allowance is smaller than the amount being moved.",
+  101: "The series has expired; this operation is only valid before expiry.",
+  102: "This operation is only valid at or after the series expiry.",
+  103: "The caller is not the contract permitted to drive this entrypoint.",
+  105: "The output fell below your minimum and the transaction was reverted.",
+  106: "The amount rounds to zero at the current exchange rate. Use a larger amount.",
+  107: "The deposit would exceed the SR deposit cap. Check the remaining headroom."
+};
+var parseContractError = (raw, method, network) => {
+  const text = raw || "";
+  const events = [...text.matchAll(
+    /contract:(C[A-Z2-7]{55}), topics:\[error, Error\(Contract, #(\d+)\)\], data:(?:"([^"]*)"|\[)/g
+  )];
+  const root = events.at(-1);
+  const rootContract = root?.[1];
+  const rootCode = root ? Number(root[2]) : void 0;
+  const rootMessage = root?.[3];
+  const assetOf = (id) => id === network.contracts.usdc ? "USDC" : id === network.contracts.pt ? "PT" : void 0;
+  if (/trustline entry is missing/.test(text)) {
+    const asset = assetOf(rootContract) ?? assetOf(/contract:(C[A-Z2-7]{55})[^\n]*trustline entry is missing/.exec(text)?.[1]);
+    if (asset === "PT") {
+      return "The wallet needs a PT trustline before it can hold PT. Call tokens.ensurePtTrustline().";
+    }
+    if (asset === "USDC") {
+      return "The wallet needs a USDC trustline (and a USDC balance) for this transaction.";
+    }
+    return "The wallet is missing a required asset trustline for this transaction.";
+  }
+  const isSpieldContract = !!rootContract && ["sr", "strategy", "yieldEngine", "market", "vault", "router"].some((key) => network.contracts[key] === rootContract);
+  if (rootCode !== void 0 && isSpieldContract) {
+    const mapped = CONTRACT_ERRORS[rootCode];
+    if (mapped) return mapped;
+    return `${method} failed with Spield contract error #${rootCode}.`;
+  }
+  if (rootMessage) return `${method} failed: ${rootMessage}`;
+  const code = /Error\(Contract, #(\d+)\)/.exec(text);
+  if (code) return `${method} failed with contract error #${code[1]}.`;
+  return `${method} simulation failed: ${text.slice(0, 200)}`;
+};
+
+// src/blend-strategy.ts
+var BlendStrategyClient = class {
+  constructor(network, soroban) {
+    this.network = network;
+    this.soroban = soroban;
+  }
+  network;
+  soroban;
+  get contract() {
+    return this.network.contracts.strategy;
+  }
+  async getAvailableLiquidity() {
+    const value = await this.soroban.read(this.contract, "available_liquidity");
+    return tokenAmount(toBig(value), "USDC", this.network.decimals);
+  }
+  /**
+   * **BLND accrued to the protocol and not yet claimed.**
+   *
+   * Measured on mainnet 2026-08-30: Blend allocates emissions to XLM *suppliers* and USDC
+   * *borrowers*, not USDC suppliers — which is the side Spield is on — so this reads `0` and has
+   * never been anything else. Allocations carry an expiration and rotate each cycle, so it will not
+   * necessarily stay zero.
+   *
+   * Claiming is permissionless and pays a destination fixed in contract storage, so an integrator
+   * can trigger it but can never redirect it.
+   */
+  async getClaimableEmissions() {
+    try {
+      const value = await this.soroban.read(this.contract, "claimable_emissions");
+      return tokenAmount(toBig(value), "BLND", this.network.decimals);
+    } catch {
+      return tokenAmount(0n, "BLND", this.network.decimals);
+    }
+  }
+  /**
+   * **What the whole Blend position is really worth**, live rate, no monotonicity guard, no write.
+   * Unlike {@link getPositionValue} this keeps answering while a rate decrease has exits frozen.
+   */
+  async getPositionValueUnguarded() {
+    try {
+      const value = await this.soroban.read(this.contract, "position_value_unguarded");
+      return tokenAmount(toBig(value), "USDC", this.network.decimals);
+    } catch {
+      return null;
+    }
+  }
+  async getRateBound() {
+    const tuple = await this.soroban.read(this.contract, "rate_bound");
+    const [lastRate, lastTimestamp, maxAprBps] = tuple ?? [];
+    return {
+      lastRate: toBig(lastRate),
+      lastTimestamp: toNum(lastTimestamp),
+      maxAprBps: toNum(maxAprBps)
+    };
+  }
+  async getPositionValue(input) {
+    const shares = assertPositiveAmount(input.shares, this.network.decimals);
+    const value = await this.soroban.read(this.contract, "position_value", [i128(shares)]);
+    return tokenAmount(toBig(value), "USDC", this.network.decimals);
+  }
+  async getState() {
+    const [currentRate, shares, liquidity, underlying, pool, rateBound] = await Promise.all([
+      this.soroban.read(this.contract, "current_rate"),
+      this.soroban.read(this.contract, "total_shares"),
+      this.getAvailableLiquidity(),
+      this.soroban.read(this.contract, "underlying"),
+      this.soroban.read(this.contract, "pool"),
+      this.getRateBound()
+    ]);
+    return {
+      currentRate: toBig(currentRate),
+      totalShares: tokenAmount(toBig(shares), "STRATEGY_SHARES", this.network.decimals),
+      availableLiquidity: liquidity,
+      underlying: String(underlying),
+      pool: String(pool),
+      rateBound
+    };
+  }
+};
+
+// src/horizon.ts
+import { Asset, BASE_FEE as BASE_FEE2, Horizon, Operation, TransactionBuilder as TransactionBuilder2 } from "@stellar/stellar-sdk";
+var HorizonClient = class {
+  constructor(network) {
+    this.network = network;
+    this.horizon = new Horizon.Server(network.horizonUrl);
+  }
+  network;
+  horizon;
+  async getPtTrustline(address) {
+    const { code, issuer } = this.network.assets.pt;
+    try {
+      const account = await this.horizon.loadAccount(address);
+      const pt = account.balances.some(
+        (balance) => "asset_code" in balance && balance.asset_code === code && "asset_issuer" in balance && balance.asset_issuer === issuer
+      );
+      return { pt, ready: pt };
+    } catch {
+      return { pt: false, ready: false };
+    }
+  }
+  async setupPtTrustline(address, signer) {
+    if (!signer) throw new SpieldSignerError("A signer is required to setup the PT trustline.");
+    if ((await this.getPtTrustline(address)).ready) return null;
+    const { code, issuer } = this.network.assets.pt;
+    const account = await this.horizon.loadAccount(address);
+    const tx = new TransactionBuilder2(account, {
+      fee: BASE_FEE2,
+      networkPassphrase: this.network.networkPassphrase
+    }).addOperation(Operation.changeTrust({ asset: new Asset(code, issuer) })).setTimeout(120).build();
+    const { signedTxXdr } = await signer.signTransaction(tx.toXDR(), {
+      networkPassphrase: this.network.networkPassphrase,
+      address
+    });
+    const signed = TransactionBuilder2.fromXDR(signedTxXdr, this.network.networkPassphrase);
+    const result = await this.horizon.submitTransaction(
+      signed
+    );
+    return { hash: result.hash, status: "success", explorerUrl: explorerTx(this.network, result.hash) };
+  }
+};
+
+// src/internal.ts
+var signerAddress = async (signer) => {
+  if (!signer) throw new SpieldSignerError("A signer is required for this transaction.");
+  return signer.getAddress();
+};
+
+// src/sr.ts
+var SCALAR_12 = 10n ** 12n;
+var fromScalar12 = (v) => Number(v) / Number(SCALAR_12);
+var StandardizedReturnClient = class {
+  constructor(network, soroban, signer) {
+    this.network = network;
+    this.soroban = soroban;
+    this.signer = signer;
+  }
+  network;
+  soroban;
+  signer;
+  get contract() {
+    return this.network.contracts.sr;
+  }
+  async getExchangeRate() {
+    return toBig(await this.soroban.read(this.contract, "exchange_rate"));
+  }
+  /**
+   * **The honest twin of {@link getExchangeRate} — what a share is ACTUALLY worth.**
+   *
+   * `exchange_rate` is a high-water mark: it ratchets up and never falls. That stops the protocol
+   * repricing on a transient dip, but it means every value built on it — `previewRedeem`,
+   * `getAssetsOf` — reports MORE underlying than a redemption pays once Blend has taken a real loss.
+   *
+   * This reads the venue with no monotonicity guard, so unlike the guarded paths it keeps answering
+   * while exits are frozen — which is exactly when somebody needs the number.
+   *
+   * Returns `0n` on a deployment predating it. Sitting slightly ABOVE `exchange_rate` in normal
+   * operation is expected (it sees accrual the stored rate has not synced); only the other
+   * direction is interesting.
+   */
+  async getRealizableRate() {
+    try {
+      return toBig(await this.soroban.read(this.contract, "realizable_rate"));
+    } catch {
+      return 0n;
+    }
+  }
+  /** A holder's actual pro-rata claim. See {@link getRealizableRate}. `null` if unavailable. */
+  async getRealizableValue(input) {
+    const shares = assertPositiveAmount(input.shares, this.network.decimals);
+    try {
+      const value = await this.soroban.read(this.contract, "realizable_value", [i128(shares)]);
+      return tokenAmount(toBig(value), "USDC", this.network.decimals);
+    } catch {
+      return null;
+    }
+  }
+  srToUnderlying(shares, rate) {
+    return rate > 0n ? shares * rate / SCALAR_12 : 0n;
+  }
+  underlyingToSr(amount, rate) {
+    return rate > 0n ? amount * SCALAR_12 / rate : 0n;
+  }
+  async previewDeposit(input) {
+    const amount = assertPositiveAmount(input.amount, this.network.decimals);
+    const raw = await this.soroban.read(this.contract, "preview_deposit", [i128(amount)]);
+    return tokenAmount(toBig(raw), "SR", this.network.decimals);
+  }
+  async previewRedeem(input) {
+    const shares = assertPositiveAmount(input.shares, this.network.decimals);
+    const raw = await this.soroban.read(this.contract, "preview_redeem", [i128(shares)]);
+    return tokenAmount(toBig(raw), "USDC", this.network.decimals);
+  }
+  async getBalance(input) {
+    const raw = await this.soroban.read(this.contract, "balance", [addr(input.owner)]);
+    return tokenAmount(toBig(raw), "SR", this.network.decimals);
+  }
+  async getAssetsOf(input) {
+    const raw = await this.soroban.read(this.contract, "assets_of", [addr(input.owner)]);
+    return tokenAmount(toBig(raw), "USDC", this.network.decimals);
+  }
+  async getState() {
+    const [rateRaw, supplyRaw, assetsRaw, maxRaw, capRaw, headroomRaw, paused] = await Promise.all([
+      this.soroban.read(this.contract, "exchange_rate"),
+      this.soroban.read(this.contract, "total_supply"),
+      this.soroban.read(this.contract, "total_assets"),
+      this.soroban.read(this.contract, "max_redeemable"),
+      this.soroban.read(this.contract, "deposit_cap"),
+      this.soroban.read(this.contract, "deposit_headroom"),
+      this.soroban.read(this.contract, "is_paused")
+    ]);
+    const rate = toBig(rateRaw);
+    const max = toBig(maxRaw);
+    const cap = toBig(capRaw);
+    const headroom = toBig(headroomRaw);
+    return {
+      exchangeRate: rate,
+      exchangeRateNumber: Number(rate) / Number(SCALAR_12),
+      totalSupply: tokenAmount(toBig(supplyRaw), "SR", this.network.decimals),
+      totalAssets: tokenAmount(toBig(assetsRaw), "USDC", this.network.decimals),
+      maxRedeemable: max === (1n << 127n) - 1n ? null : tokenAmount(max, "SR", this.network.decimals),
+      depositCap: cap === 0n ? null : tokenAmount(cap, "USDC", this.network.decimals),
+      depositHeadroom: cap === 0n ? null : tokenAmount(headroom, "USDC", this.network.decimals),
+      depositCapReached: cap > 0n && headroom === 0n,
+      paused
+    };
+  }
+  async deposit(input) {
+    const signer = input.signer ?? this.signer;
+    const from = await signerAddress(signer);
+    return this.soroban.write(this.contract, "deposit", [
+      addr(from),
+      addr(input.receiver ?? from),
+      i128(assertPositiveAmount(input.amount, this.network.decimals)),
+      i128(assertNonNegativeAmount(input.minSharesOut ?? 0n, this.network.decimals))
+    ], signer);
+  }
+  async redeem(input) {
+    const signer = input.signer ?? this.signer;
+    const from = await signerAddress(signer);
+    return this.soroban.write(this.contract, "redeem", [
+      addr(from),
+      addr(input.receiver ?? from),
+      i128(assertPositiveAmount(input.shares, this.network.decimals)),
+      i128(assertNonNegativeAmount(input.minUnderlyingOut ?? 0n, this.network.decimals))
+    ], signer);
+  }
+  async redeemPartial(input) {
+    const signer = input.signer ?? this.signer;
+    const from = await signerAddress(signer);
+    return this.soroban.write(this.contract, "redeem_partial", [
+      addr(from),
+      addr(input.receiver ?? from),
+      i128(assertPositiveAmount(input.shares, this.network.decimals)),
+      i128(assertNonNegativeAmount(input.minUnderlyingOut ?? 0n, this.network.decimals))
+    ], signer);
+  }
+  /** Permissionless update of SR's stored high-water exchange rate. */
+  syncRate(input = {}) {
+    return this.soroban.write(this.contract, "sync_rate", [], input.signer ?? this.signer);
+  }
+  /** Permissionless keep-alive for an SR holder's persistent balance entry. */
+  bumpHolder(input = {}) {
+    const signer = input.signer ?? this.signer;
+    return signerAddress(signer).then((signerOwner) => this.soroban.write(
+      this.contract,
+      "bump_holder",
+      [addr(input.owner ?? signerOwner)],
+      signer
+    ));
+  }
+};
+
+// src/sr-market.ts
+var YT_MAX_IN_PAD_BPS = 300n;
+var SrMarketClient = class {
+  constructor(network, soroban, signer) {
+    this.network = network;
+    this.soroban = soroban;
+    this.signer = signer;
+  }
+  network;
+  soroban;
+  signer;
+  latestLiquidityAbi;
+  get contract() {
+    return this.network.contracts.market;
+  }
+  async getStats() {
+    const [reserves, assetRaw, sharesRaw, priceRaw, apyRaw, expiryRaw, earnedRaw, feeShareRaw, paused] = await Promise.all([
+      this.soroban.read(this.contract, "reserves"),
+      this.soroban.read(this.contract, "asset_reserve"),
+      this.soroban.read(this.contract, "total_shares"),
+      this.soroban.read(this.contract, "pt_price"),
+      this.soroban.read(this.contract, "implied_apy"),
+      this.soroban.read(this.contract, "expiry"),
+      this.soroban.read(this.contract, "treasury_earned"),
+      this.soroban.read(this.contract, "treasury_fee_share_bps"),
+      this.soroban.read(this.contract, "is_paused")
+    ]);
+    const [ptRaw, srRaw] = reserves ?? [];
+    const price = toBig(priceRaw);
+    const apy = toBig(apyRaw);
+    const expiry = toNum(expiryRaw);
+    return {
+      ptReserve: tokenAmount(toBig(ptRaw), "PT", this.network.decimals),
+      srReserve: tokenAmount(toBig(srRaw), "SR", this.network.decimals),
+      assetReserve: tokenAmount(toBig(assetRaw), "USDC", this.network.decimals),
+      totalShares: tokenAmount(toBig(sharesRaw), "LP", this.network.decimals),
+      ptPrice: price,
+      ptPriceNumber: Number(price) / Number(SCALAR_12),
+      impliedApy: apy,
+      impliedApyPct: Number(apy) / Number(SCALAR_12) * 100,
+      expiry,
+      expiryDate: new Date(expiry * 1e3),
+      treasuryEarned: tokenAmount(toBig(earnedRaw), "SR", this.network.decimals),
+      treasuryFeeShareBps: toNum(feeShareRaw),
+      paused
+    };
+  }
+  async quote(method, amount, inputSymbol, outputSymbol) {
+    const input = assertPositiveAmount(amount, this.network.decimals);
+    const output = toBig(await this.soroban.read(this.contract, method, [i128(input)]));
+    return {
+      input: tokenAmount(input, inputSymbol, this.network.decimals),
+      output: tokenAmount(output, outputSymbol, this.network.decimals),
+      available: output > 0n
+    };
+  }
+  quoteBuyPt(input) {
+    return this.quote("quote_buy_pt", input.srIn, "SR", "PT");
+  }
+  quoteSellPt(input) {
+    return this.quote("quote_sell_pt", input.ptIn, "PT", "SR");
+  }
+  quoteBuyYt(input) {
+    return this.quote("quote_buy_yt", input.ytOut, "YT", "SR");
+  }
+  quoteSellYt(input) {
+    return this.quote("quote_sell_yt", input.ytIn, "YT", "SR");
+  }
+  async getLpPosition(input) {
+    const tuple = await this.soroban.read(this.contract, "lp_position", [addr(input.owner)]);
+    const [shares, ptClaim, srClaim] = tuple ?? [];
+    return {
+      shares: tokenAmount(toBig(shares), "LP", this.network.decimals),
+      ptClaim: tokenAmount(toBig(ptClaim), "PT", this.network.decimals),
+      srClaim: tokenAmount(toBig(srClaim), "SR", this.network.decimals)
+    };
+  }
+  async buyPt(input) {
+    const signer = input.signer ?? this.signer;
+    const owner = await signerAddress(signer);
+    return this.soroban.write(this.contract, "swap_exact_sr_for_pt", [
+      addr(owner),
+      i128(assertPositiveAmount(input.srIn, this.network.decimals)),
+      i128(assertNonNegativeAmount(input.minPtOut ?? 0n, this.network.decimals)),
+      u32(input.deadlineLedger ?? 0)
+    ], signer);
+  }
+  async sellPt(input) {
+    const signer = input.signer ?? this.signer;
+    const owner = await signerAddress(signer);
+    return this.soroban.write(this.contract, "swap_exact_pt_for_sr", [
+      addr(owner),
+      i128(assertPositiveAmount(input.ptIn, this.network.decimals)),
+      i128(assertNonNegativeAmount(input.minSrOut ?? 0n, this.network.decimals)),
+      u32(input.deadlineLedger ?? 0)
+    ], signer);
+  }
+  async buyYt(input) {
+    const signer = input.signer ?? this.signer;
+    const owner = await signerAddress(signer);
+    const ytOut = assertPositiveAmount(input.ytOut, this.network.decimals);
+    let maxSrIn;
+    if (input.maxSrIn === void 0) {
+      const quoted = (await this.quoteBuyYt({ ytOut })).output.raw;
+      if (quoted <= 0n) throw new Error("No YT quote is available for that size.");
+      maxSrIn = quoted + quoted * YT_MAX_IN_PAD_BPS / 10000n + 1n;
+    } else {
+      maxSrIn = assertPositiveAmount(input.maxSrIn, this.network.decimals);
+    }
+    return this.soroban.write(this.contract, "buy_yt_exact_out", [
+      addr(owner),
+      i128(ytOut),
+      i128(maxSrIn),
+      u32(input.deadlineLedger ?? 0)
+    ], signer);
+  }
+  async sellYt(input) {
+    const signer = input.signer ?? this.signer;
+    const owner = await signerAddress(signer);
+    return this.soroban.write(this.contract, "sell_yt_exact_in", [
+      addr(owner),
+      i128(assertPositiveAmount(input.ytIn, this.network.decimals)),
+      i128(assertNonNegativeAmount(input.minSrOut ?? 0n, this.network.decimals)),
+      u32(input.deadlineLedger ?? 0)
+    ], signer);
+  }
+  async addLiquidity(input) {
+    const signer = input.signer ?? this.signer;
+    const owner = await signerAddress(signer);
+    const minShares = assertNonNegativeAmount(input.minShares ?? 0n, this.network.decimals);
+    const args = [
+      addr(owner),
+      i128(assertPositiveAmount(input.ptIn, this.network.decimals)),
+      i128(assertPositiveAmount(input.srIn, this.network.decimals))
+    ];
+    if (await this.supportsLatestLiquidityAbi(owner)) {
+      return this.soroban.write(this.contract, "add_liquidity", [...args, i128(minShares)], signer);
+    }
+    if (minShares > 0n) {
+      throw new SpieldConfigurationError(
+        "This market deployment predates addLiquidity.minShares; use minShares=0 or upgrade the market contract."
+      );
+    }
+    return this.soroban.write(this.contract, "add_liquidity", args, signer);
+  }
+  async removeLiquidity(input) {
+    const signer = input.signer ?? this.signer;
+    const owner = await signerAddress(signer);
+    return this.soroban.write(this.contract, "remove_liquidity", [
+      addr(owner),
+      i128(assertPositiveAmount(input.shares, this.network.decimals)),
+      i128(assertNonNegativeAmount(input.minPtOut ?? 0n, this.network.decimals)),
+      i128(assertNonNegativeAmount(input.minSrOut ?? 0n, this.network.decimals))
+    ], signer);
+  }
+  /** Permissionless keep-alive for an LP share entry. */
+  async bumpLp(input = {}) {
+    const signer = input.signer ?? this.signer;
+    const signerOwner = await signerAddress(signer);
+    return this.soroban.write(this.contract, "bump_lp", [addr(input.owner ?? signerOwner)], signer);
+  }
+  supportsLatestLiquidityAbi(owner) {
+    this.latestLiquidityAbi ??= this.soroban.read(this.contract, "bump_lp", [addr(owner)]).then(() => true, () => false);
+    return this.latestLiquidityAbi;
+  }
+};
+
+// src/sr-portfolio.ts
+var SrPortfolioClient = class {
+  constructor(tokens, sr, yieldEngine, market, vault, decimals) {
+    this.tokens = tokens;
+    this.sr = sr;
+    this.yieldEngine = yieldEngine;
+    this.market = market;
+    this.vault = vault;
+    this.decimals = decimals;
+  }
+  tokens;
+  sr;
+  yieldEngine;
+  market;
+  vault;
+  decimals;
+  async getPortfolio(input) {
+    const [balances, rate, claimableYield, interest, lpPosition, fixedReceipts, trustline] = await Promise.all([
+      this.tokens.getBalances({ owner: input.owner }),
+      this.sr.getExchangeRate(),
+      this.yieldEngine.getClaimableInterest({ owner: input.owner }),
+      this.yieldEngine.getInterest({ owner: input.owner }),
+      this.market.getLpPosition({ owner: input.owner }),
+      this.vault.getOwnerReceipts({ owner: input.owner, maxScan: input.maxReceiptScan }),
+      this.tokens.getPtTrustline({ owner: input.owner })
+    ]);
+    return {
+      owner: input.owner,
+      balances,
+      srAsUsdc: tokenAmount(this.sr.srToUnderlying(balances.sr.raw, rate), "USDC", this.decimals),
+      claimableYield,
+      claimableYieldAsUsdc: tokenAmount(this.sr.srToUnderlying(claimableYield.raw, rate), "USDC", this.decimals),
+      interest,
+      lpPosition,
+      fixedReceipts,
+      hasPtTrustline: trustline.ready
+    };
+  }
+};
+
+// src/sr-protocol.ts
+var SrProtocolClient = class {
+  constructor(sr, strategy, yieldEngine, market, vault) {
+    this.sr = sr;
+    this.strategy = strategy;
+    this.yieldEngine = yieldEngine;
+    this.market = market;
+    this.vault = vault;
+  }
+  sr;
+  strategy;
+  yieldEngine;
+  market;
+  vault;
+  async getHealth() {
+    const [sr, strategy, yieldEngine, market, vault] = await Promise.all([
+      this.sr.getState(),
+      this.strategy.getState(),
+      this.yieldEngine.getState(),
+      this.market.getStats(),
+      this.vault.getStats()
+    ]);
+    return { sr, strategy, yieldEngine, market, vault };
+  }
+  getSolvency() {
+    return this.yieldEngine.getSolvency();
+  }
+};
+
+// src/sr-router.ts
+var DEFAULT_ROUTER_SLIPPAGE_BPS = 100;
+var assertSlippageBps = (bps) => {
+  if (!Number.isInteger(bps) || bps < 0 || bps > 1e4) {
+    throw new SpieldValidationError("slippageBps must be an integer between 0 and 10000.");
+  }
+  return bps;
+};
+var slippageFloor = (quote, bps) => {
+  assertSlippageBps(bps);
+  return quote - quote * BigInt(bps) / 10000n;
+};
+var SrRouterClient = class {
+  constructor(network, soroban, signer) {
+    this.network = network;
+    this.soroban = soroban;
+    this.signer = signer;
+  }
+  network;
+  soroban;
+  signer;
+  get contract() {
+    return this.network.contracts.router;
+  }
+  /**
+   * The basis for `minOut`: what the REAL entry point would pay, falling back to the quote.
+   *
+   * `FINAL_CHECK.md` V2-01 — the market synchronizes SR on every value-moving call, but `quote_*`
+   * is a view and cannot. A quote therefore lags, and for a sale it reports MORE than the trade
+   * will pay; sizing `minOut` from it can revert the trade on its own slippage bound.
+   *
+   * Simulation runs the same synchronized code path the submission runs, so its answer is the one
+   * that executes. It legitimately returns `null` (unaffordable size, unfillable route, older
+   * deployment) — in which case the quote is used exactly as before.
+   */
+  async executableBasis(owner, method, args, quoted) {
+    if (typeof this.soroban.simulateAs !== "function") return quoted;
+    const simulated = await this.soroban.simulateAs(owner, this.contract, method, args);
+    return simulated !== null && simulated > 0n ? simulated : quoted;
+  }
+  async quote(method, amount, symbol) {
+    const raw = await this.soroban.read(this.contract, method, [i128(amount)]);
+    return tokenAmount(toBig(raw), symbol, this.network.decimals);
+  }
+  quoteBuyPt(input) {
+    return this.quote(
+      "quote_buy_pt_with_usdc",
+      assertPositiveAmount(input.usdcIn, this.network.decimals),
+      "PT"
+    );
+  }
+  quoteBuyYt(input) {
+    return this.quote(
+      "quote_buy_yt_with_usdc",
+      assertPositiveAmount(input.ytOut, this.network.decimals),
+      "USDC"
+    );
+  }
+  quoteSellPt(input) {
+    return this.quote(
+      "quote_sell_pt_for_usdc",
+      assertPositiveAmount(input.ptIn, this.network.decimals),
+      "USDC"
+    );
+  }
+  quoteSellYt(input) {
+    return this.quote(
+      "quote_sell_yt_for_usdc",
+      assertPositiveAmount(input.ytIn, this.network.decimals),
+      "USDC"
+    );
+  }
+  quoteRedeemPy(input) {
+    return this.quote(
+      "quote_redeem_py_for_usdc",
+      assertPositiveAmount(input.amount, this.network.decimals),
+      "USDC"
+    );
+  }
+  async quoteClaimYield(input) {
+    const raw = await this.soroban.read(this.contract, "quote_claim_yield", [addr(input.owner)]);
+    return tokenAmount(toBig(raw), "USDC", this.network.decimals);
+  }
+  async buyPt(input) {
+    const signer = input.signer ?? this.signer;
+    const owner = await signerAddress(signer);
+    const usdcIn = assertPositiveAmount(input.usdcIn, this.network.decimals);
+    assertSlippageBps(input.slippageBps ?? DEFAULT_ROUTER_SLIPPAGE_BPS);
+    const minOut = input.minPtOut === void 0 ? slippageFloor(
+      await this.executableBasis(
+        owner,
+        "buy_pt_with_usdc",
+        [addr(owner), i128(usdcIn), i128(0n), u32(input.deadlineLedger ?? 0)],
+        (await this.quoteBuyPt({ usdcIn })).raw
+      ),
+      input.slippageBps ?? DEFAULT_ROUTER_SLIPPAGE_BPS
+    ) : assertNonNegativeAmount(input.minPtOut, this.network.decimals);
+    if (minOut <= 0n) throw new Error("No PT quote is available for that size.");
+    return this.soroban.write(this.contract, "buy_pt_with_usdc", [
+      addr(owner),
+      i128(usdcIn),
+      i128(minOut),
+      u32(input.deadlineLedger ?? 0)
+    ], signer);
+  }
+  async sellPt(input) {
+    const signer = input.signer ?? this.signer;
+    const owner = await signerAddress(signer);
+    const ptIn = assertPositiveAmount(input.ptIn, this.network.decimals);
+    assertSlippageBps(input.slippageBps ?? DEFAULT_ROUTER_SLIPPAGE_BPS);
+    const minOut = input.minUsdcOut === void 0 ? slippageFloor(
+      await this.executableBasis(
+        owner,
+        "sell_pt_for_usdc",
+        [addr(owner), i128(ptIn), i128(0n), u32(input.deadlineLedger ?? 0)],
+        (await this.quoteSellPt({ ptIn })).raw
+      ),
+      input.slippageBps ?? DEFAULT_ROUTER_SLIPPAGE_BPS
+    ) : assertNonNegativeAmount(input.minUsdcOut, this.network.decimals);
+    return this.soroban.write(this.contract, "sell_pt_for_usdc", [
+      addr(owner),
+      i128(ptIn),
+      i128(minOut),
+      u32(input.deadlineLedger ?? 0)
+    ], signer);
+  }
+  async redeemPy(input) {
+    const signer = input.signer ?? this.signer;
+    const owner = await signerAddress(signer);
+    const amount = assertPositiveAmount(input.amount, this.network.decimals);
+    assertSlippageBps(input.slippageBps ?? DEFAULT_ROUTER_SLIPPAGE_BPS);
+    const minOut = input.minUsdcOut === void 0 ? slippageFloor(
+      await this.executableBasis(
+        owner,
+        "redeem_py_for_usdc",
+        [addr(owner), i128(amount), i128(0n)],
+        (await this.quoteRedeemPy({ amount })).raw
+      ),
+      input.slippageBps ?? DEFAULT_ROUTER_SLIPPAGE_BPS
+    ) : assertNonNegativeAmount(input.minUsdcOut, this.network.decimals);
+    return this.soroban.write(this.contract, "redeem_py_for_usdc", [addr(owner), i128(amount), i128(minOut)], signer);
+  }
+  async claimYield(input = {}) {
+    const signer = input.signer ?? this.signer;
+    const owner = await signerAddress(signer);
+    const minOut = input.minUsdcOut === void 0 ? slippageFloor((await this.quoteClaimYield({ owner })).raw, input.slippageBps ?? DEFAULT_ROUTER_SLIPPAGE_BPS) : assertNonNegativeAmount(input.minUsdcOut, this.network.decimals);
+    return this.soroban.write(this.contract, "claim_yield_to_usdc", [addr(owner), i128(minOut)], signer);
+  }
+};
+
+// src/sr-tokens.ts
+var SrTokensClient = class {
+  constructor(network, soroban, horizon, signer) {
+    this.network = network;
+    this.soroban = soroban;
+    this.horizon = horizon;
+    this.signer = signer;
+  }
+  network;
+  soroban;
+  horizon;
+  signer;
+  async getBalance(input) {
+    const contracts = this.network.contracts;
+    const contract = {
+      USDC: contracts.usdc,
+      SR: contracts.sr,
+      PT: contracts.pt,
+      // The yield engine itself implements SEP-41 and is the YT token.
+      YT: contracts.yieldEngine
+    }[input.token];
+    try {
+      const raw = await this.soroban.read(contract, "balance", [addr(input.owner)]);
+      return tokenAmount(toBig(raw), input.token, this.network.decimals);
+    } catch {
+      return tokenAmount(0n, input.token, this.network.decimals);
+    }
+  }
+  async getBalances(input) {
+    const [usdc, sr, pt, yt] = await Promise.all([
+      this.getBalance({ token: "USDC", owner: input.owner }),
+      this.getBalance({ token: "SR", owner: input.owner }),
+      this.getBalance({ token: "PT", owner: input.owner }),
+      this.getBalance({ token: "YT", owner: input.owner })
+    ]);
+    return { usdc, sr, pt, yt };
+  }
+  getPtTrustline(input) {
+    return this.horizon.getPtTrustline(input.owner);
+  }
+  /** Set up the sole v2 trustline. YT is a contract token and must not get a trustline. */
+  async ensurePtTrustline(input = {}) {
+    const signer = input.signer ?? this.signer;
+    const owner = input.owner ?? await signerAddress(signer);
+    return this.horizon.setupPtTrustline(owner, signer);
+  }
+};
+
+// src/sr-vault.ts
+var SrVaultClient = class {
+  constructor(network, soroban, signer) {
+    this.network = network;
+    this.soroban = soroban;
+    this.signer = signer;
+  }
+  network;
+  soroban;
+  signer;
+  get contract() {
+    return this.network.contracts.vault;
+  }
+  async quoteFixedRate(input) {
+    const amount = assertPositiveAmount(input.amount, this.network.decimals);
+    const tuple = await this.soroban.read(this.contract, "quote", [i128(amount)]);
+    const [payoutRaw, couponRaw, rateRaw] = tuple ?? [];
+    const rateBps = toNum(rateRaw);
+    return {
+      input: tokenAmount(amount, "USDC", this.network.decimals),
+      payout: tokenAmount(toBig(payoutRaw), "USDC", this.network.decimals),
+      coupon: tokenAmount(toBig(couponRaw), "USDC", this.network.decimals),
+      rateBps,
+      ratePct: rateBps / 100
+    };
+  }
+  async getStats() {
+    const [raw, paused] = await Promise.all([
+      this.soroban.read(this.contract, "stats"),
+      this.soroban.read(this.contract, "is_paused")
+    ]);
+    const maturity = toNum(raw.maturity);
+    const rateBps = toNum(raw.rate_bps);
+    return {
+      ptInventory: tokenAmount(toBig(raw.pt_inventory), "PT", this.network.decimals),
+      ytInventory: tokenAmount(toBig(raw.yt_inventory), "YT", this.network.decimals),
+      totalLiability: tokenAmount(toBig(raw.total_liability), "USDC", this.network.decimals),
+      totalCollected: tokenAmount(toBig(raw.total_collected), "USDC", this.network.decimals),
+      couponCapacity: tokenAmount(toBig(raw.coupon_capacity), "PT", this.network.decimals),
+      rateBps,
+      ratePct: rateBps / 100,
+      maturity,
+      maturityDate: new Date(maturity * 1e3),
+      openReceipts: toNum(raw.open_receipts),
+      paused
+    };
+  }
+  async getReceipt(input) {
+    if (!Number.isSafeInteger(input.receiptId) || input.receiptId < 0) {
+      throw new SpieldValidationError("receiptId must be a non-negative safe integer.");
+    }
+    try {
+      const raw = await this.soroban.read(this.contract, "get_receipt", [u64(input.receiptId)]);
+      const maturity = toNum(raw.maturity);
+      const rateBps = toNum(raw.rate_bps);
+      const payout = toBig(raw.payout);
+      const collected = toBig(raw.collected);
+      return {
+        receiptId: input.receiptId,
+        owner: String(raw.owner),
+        principal: tokenAmount(toBig(raw.principal), "USDC", this.network.decimals),
+        payout: tokenAmount(payout, "USDC", this.network.decimals),
+        rateBps,
+        ratePct: rateBps / 100,
+        maturity,
+        maturityDate: new Date(maturity * 1e3),
+        open: Boolean(raw.open),
+        collected: tokenAmount(collected, "USDC", this.network.decimals),
+        remaining: tokenAmount(payout > collected ? payout - collected : 0n, "USDC", this.network.decimals)
+      };
+    } catch {
+      return null;
+    }
+  }
+  async getOwnerReceipts(input) {
+    const maxScan = input.maxScan ?? 64;
+    if (!Number.isSafeInteger(maxScan) || maxScan < 0) {
+      throw new SpieldValidationError("maxScan must be a non-negative safe integer.");
+    }
+    const receipts = [];
+    let misses = 0;
+    for (let id = 0; id < maxScan && misses < 5; id += 1) {
+      const receipt = await this.getReceipt({ receiptId: id });
+      if (!receipt) {
+        misses += 1;
+      } else {
+        misses = 0;
+        if (receipt.owner === input.owner && receipt.open) receipts.push(receipt);
+      }
+    }
+    return receipts;
+  }
+  async deposit(input) {
+    const signer = input.signer ?? this.signer;
+    const owner = await signerAddress(signer);
+    return this.soroban.write(this.contract, "deposit", [
+      addr(owner),
+      i128(assertPositiveAmount(input.amount, this.network.decimals))
+    ], signer);
+  }
+  redeemReceipt(input) {
+    if (!Number.isSafeInteger(input.receiptId) || input.receiptId < 0) {
+      throw new SpieldValidationError("receiptId must be a non-negative safe integer.");
+    }
+    return this.soroban.write(this.contract, "redeem", [u64(input.receiptId)], input.signer ?? this.signer);
+  }
+  /** Remaining USDC owed before a receipt can close. Falls back to receipt data on the old ABI. */
+  async getRedeemRemaining(input) {
+    this.assertReceiptId(input.receiptId);
+    try {
+      const raw = await this.soroban.read(this.contract, "redeem_remaining", [u64(input.receiptId)]);
+      return tokenAmount(toBig(raw), "USDC", this.network.decimals);
+    } catch {
+      const receipt = await this.getReceipt(input);
+      return tokenAmount(receipt?.remaining.raw ?? 0n, "USDC", this.network.decimals);
+    }
+  }
+  /** Read surplus SR, YT and USDC that the latest vault ABI can release after expiry. */
+  async getSurplus() {
+    try {
+      const tuple = await this.soroban.read(this.contract, "surplus");
+      const [sr, yt, usdc] = tuple ?? [];
+      return {
+        sr: tokenAmount(toBig(sr), "SR", this.network.decimals),
+        yt: tokenAmount(toBig(yt), "YT", this.network.decimals),
+        usdc: tokenAmount(toBig(usdc), "USDC", this.network.decimals)
+      };
+    } catch {
+      return null;
+    }
+  }
+  /** Permissionless keep-alive for a long-dated vault receipt. */
+  bumpReceipt(input) {
+    this.assertReceiptId(input.receiptId);
+    return this.soroban.write(this.contract, "bump_receipt", [u64(input.receiptId)], input.signer ?? this.signer);
+  }
+  /** Permissionless claim and reinvestment of the vault's YT yield. */
+  harvest(input = {}) {
+    return this.soroban.write(this.contract, "harvest", [], input.signer ?? this.signer);
+  }
+  assertReceiptId(receiptId) {
+    if (!Number.isSafeInteger(receiptId) || receiptId < 0) {
+      throw new SpieldValidationError("receiptId must be a non-negative safe integer.");
+    }
+  }
+};
+
+// src/yield-engine.ts
+var YieldEngineClient = class {
+  constructor(network, soroban, signer) {
+    this.network = network;
+    this.soroban = soroban;
+    this.signer = signer;
+  }
+  network;
+  soroban;
+  signer;
+  get contract() {
+    return this.network.contracts.yieldEngine;
+  }
+  async getYtBalance(input) {
+    const raw = await this.soroban.read(this.contract, "balance", [addr(input.owner)]);
+    return tokenAmount(toBig(raw), "YT", this.network.decimals);
+  }
+  async getClaimableInterest(input) {
+    const raw = await this.soroban.read(this.contract, "claimable_interest", [addr(input.owner)]);
+    return tokenAmount(toBig(raw), "SR", this.network.decimals);
+  }
+  async getInterest(input) {
+    const raw = await this.soroban.read(this.contract, "interest_of", [addr(input.owner)]);
+    return {
+      index: toBig(raw.index),
+      accrued: tokenAmount(toBig(raw.accrued), "SR", this.network.decimals),
+      withdrawn: tokenAmount(toBig(raw.withdrawn), "SR", this.network.decimals)
+    };
+  }
+  async getSolvency() {
+    const tuple = await this.soroban.read(this.contract, "solvency");
+    const [heldRaw, neededRaw, surplusRaw] = tuple ?? [];
+    const held = toBig(heldRaw);
+    const needed = toBig(neededRaw);
+    return {
+      held: tokenAmount(held, "SR", this.network.decimals),
+      needed: tokenAmount(needed, "SR", this.network.decimals),
+      surplus: tokenAmount(toBig(surplusRaw), "SR", this.network.decimals),
+      solvent: held >= needed
+    };
+  }
+  async getState() {
+    const [solvency, totalPyRaw, totalAccruedRaw, indexRaw, feeRaw, expiryRaw, expired, paused] = await Promise.all([
+      this.getSolvency(),
+      this.soroban.read(this.contract, "total_py"),
+      this.soroban.read(this.contract, "total_accrued"),
+      this.soroban.read(this.contract, "py_index"),
+      this.soroban.read(this.contract, "yield_fee_bps"),
+      this.soroban.read(this.contract, "expiry"),
+      this.soroban.read(this.contract, "is_expired"),
+      this.soroban.read(this.contract, "is_paused")
+    ]);
+    const expiry = toNum(expiryRaw);
+    const yieldFeeBps = toNum(feeRaw);
+    return {
+      ...solvency,
+      totalPy: tokenAmount(toBig(totalPyRaw), "PT/YT", this.network.decimals),
+      totalAccrued: tokenAmount(toBig(totalAccruedRaw), "SR", this.network.decimals),
+      pyIndex: toBig(indexRaw),
+      yieldFeeBps,
+      yieldFeePct: yieldFeeBps / 100,
+      expiry,
+      expiryDate: new Date(expiry * 1e3),
+      expired,
+      paused
+    };
+  }
+  async mintPy(input) {
+    const signer = input.signer ?? this.signer;
+    const from = await signerAddress(signer);
+    return this.soroban.write(this.contract, "mint_py", [
+      addr(from),
+      addr(input.receiver ?? from),
+      i128(assertPositiveAmount(input.srIn, this.network.decimals))
+    ], signer);
+  }
+  async redeemPy(input) {
+    const signer = input.signer ?? this.signer;
+    const from = await signerAddress(signer);
+    return this.soroban.write(this.contract, "redeem_py", [
+      addr(from),
+      addr(input.receiver ?? from),
+      i128(assertPositiveAmount(input.amount, this.network.decimals))
+    ], signer);
+  }
+  async claimYield(input = {}) {
+    const signer = input.signer ?? this.signer;
+    const owner = await signerAddress(signer);
+    return this.soroban.write(this.contract, "redeem_due_interest", [addr(owner)], signer);
+  }
+  async transferYt(input) {
+    const signer = input.signer ?? this.signer;
+    const from = await signerAddress(signer);
+    return this.soroban.write(this.contract, "transfer", [
+      addr(from),
+      addr(input.to),
+      i128(assertPositiveAmount(input.amount, this.network.decimals))
+    ], signer);
+  }
+  /** Permissionless expiry-index stamp; only succeeds at or after expiry. */
+  stampExpiryIndex(input = {}) {
+    return this.soroban.write(this.contract, "stamp_expiry_index", [], input.signer ?? this.signer);
+  }
+  /** Keep both a holder's YT balance and interest entries alive. Permissionless on the latest ABI. */
+  async bumpHolder(input = {}) {
+    const signer = input.signer ?? this.signer;
+    const signerOwner = await signerAddress(signer);
+    return this.soroban.write(this.contract, "bump_holder", [addr(input.owner ?? signerOwner)], signer);
+  }
+};
+
+// src/client.ts
+var SpieldClient = class {
+  network;
+  /** Wrap USDC into yield-bearing SR shares, and unwrap fully or partially. */
+  sr;
+  /** Blend rate guard, position value, and currently withdrawable liquidity. */
+  strategy;
+  /** Mint/redeem PT + YT, read and claim interest, transfer YT. */
+  yield;
+  /** PT/SR quotes, PT and YT trades, liquidity. */
+  market;
+  /** Fixed-rate quotes, receipts, deposit, redeem, harvest. */
+  vault;
+  /** One-transaction USDC routes for PT, redemption, and yield claims. */
+  router;
+  /** USDC/SR/PT/YT balances and the single required PT trustline. */
+  tokens;
+  /** Wallet-wide balances, interest, LP position, and vault receipts. */
+  portfolio;
+  /** Cross-contract health and yield-engine solvency. */
+  protocol;
+  signer;
+  constructor(options = {}) {
+    const network = options.network ?? testnet();
+    this.network = network;
+    this.signer = options.signer;
+    const soroban = new SorobanClient({
+      network,
+      signer: options.signer,
+      simulationSource: options.simulationSource ?? DEFAULT_SIMULATION_SOURCE,
+      confirmationTimeoutMs: options.confirmationTimeoutMs,
+      confirmationPollIntervalMs: options.confirmationPollIntervalMs
+    });
+    const horizon = new HorizonClient(network);
+    this.sr = new StandardizedReturnClient(network, soroban, options.signer);
+    this.strategy = new BlendStrategyClient(network, soroban);
+    this.yield = new YieldEngineClient(network, soroban, options.signer);
+    this.market = new SrMarketClient(network, soroban, options.signer);
+    this.vault = new SrVaultClient(network, soroban, options.signer);
+    this.router = new SrRouterClient(network, soroban, options.signer);
+    this.tokens = new SrTokensClient(network, soroban, horizon, options.signer);
+    this.portfolio = new SrPortfolioClient(
+      this.tokens,
+      this.sr,
+      this.yield,
+      this.market,
+      this.vault,
+      network.decimals
+    );
+    this.protocol = new SrProtocolClient(this.sr, this.strategy, this.yield, this.market, this.vault);
+  }
+  /** All-in USDC cost for an exact YT face amount, using the deployed two-step route. */
+  async quoteBuyYtFromUsdc(input) {
+    const quote = await this.market.quoteBuyYt(input);
+    if (!quote.available) return tokenAmount(0n, "USDC", this.network.decimals);
+    const rate = await this.sr.getExchangeRate();
+    return tokenAmount(this.sr.srToUnderlying(quote.output.raw, rate), "USDC", this.network.decimals);
+  }
+  /**
+   * Live-safe YT purchase: wrap only the missing SR, then buy YT. The one-call router version exceeds
+   * the deployed Blend pool's Soroban budget, so this deliberately uses up to two signatures.
+   */
+  async buyYtFromUsdc(input) {
+    const signer = input.signer ?? this.signer;
+    const ytOut = assertPositiveAmount(input.ytOut, this.network.decimals);
+    const quote = await this.market.quoteBuyYt({ ytOut });
+    if (!quote.available) throw new Error("No YT quote is available for that size.");
+    const budget = quote.output.raw + quote.output.raw * YT_MAX_IN_PAD_BPS / 10000n + 1n;
+    const owner = await signer?.getAddress();
+    if (!owner) throw new Error("A signer is required for this transaction.");
+    const held = (await this.tokens.getBalance({ token: "SR", owner })).raw;
+    let first;
+    const needsWrap = held < budget;
+    const total = needsWrap ? 2 : 1;
+    if (needsWrap) {
+      const rate = await this.sr.getExchangeRate();
+      const missing = budget - held;
+      const usdc = (missing * rate + SCALAR_12 - 1n) / SCALAR_12 + 1n;
+      input.onProgress?.("wrap", 1, total);
+      first = await this.sr.deposit({ amount: usdc, signer });
+    }
+    input.onProgress?.("buy", total, total);
+    const second = await this.market.buyYt({ ytOut, maxSrIn: budget, signer });
+    return { first, second };
+  }
+  /**
+   * Live-safe YT exit: sell to SR, then unwrap the actual proceeds. The combined router route no
+   * longer fits the deployed Blend-backed stack after the SR partial-exit/cap upgrade.
+   */
+  async sellYtToUsdc(input) {
+    const signer = input.signer ?? this.signer;
+    const owner = await signer?.getAddress();
+    if (!owner) throw new Error("A signer is required for this transaction.");
+    const quote = await this.market.quoteSellYt(input);
+    if (!quote.available) throw new Error("No YT sale quote is available for that size.");
+    const before = (await this.tokens.getBalance({ token: "SR", owner })).raw;
+    input.onProgress?.("sell", 1, 2);
+    const first = await this.market.sellYt({ ytIn: input.ytIn, minSrOut: quote.output.raw * 99n / 100n, signer });
+    const after = (await this.tokens.getBalance({ token: "SR", owner })).raw;
+    const proceeds = after - before;
+    if (proceeds <= 0n) throw new Error("The YT sale completed but produced no SR to unwrap.");
+    input.onProgress?.("unwrap", 2, 2);
+    const second = await this.sr.redeem({ shares: proceeds, signer });
+    return { first, second };
+  }
+};
+
+// src/signer.ts
+var FreighterSigner = class {
+  constructor(api) {
+    this.api = api;
+  }
+  api;
+  get freighter() {
+    const injected = this.api ?? globalThis.freighterApi;
+    if (!injected) throw new SpieldSignerError("Freighter API is not available.");
+    return injected;
+  }
+  async getAddress() {
+    const getAddress = this.freighter.getAddress;
+    if (!getAddress) throw new SpieldSignerError("Freighter getAddress() is not available.");
+    const result = await getAddress();
+    const address = typeof result === "string" ? result : result.address;
+    if (!address) throw new SpieldSignerError("Freighter did not return an address.");
+    return address;
+  }
+  async signTransaction(xdr2, opts) {
+    const signTransaction = this.freighter.signTransaction;
+    if (!signTransaction) throw new SpieldSignerError("Freighter signTransaction() is not available.");
+    const result = await signTransaction(xdr2, opts);
+    const signedTxXdr = typeof result === "string" ? result : result.signedTxXdr;
+    if (!signedTxXdr) throw new SpieldSignerError("Freighter did not return a signed transaction.");
+    return { signedTxXdr };
+  }
+};
+var ManualSigner = class {
+  constructor(address, sign) {
+    this.address = address;
+    this.sign = sign;
+  }
+  address;
+  sign;
+  async getAddress() {
+    return this.address;
+  }
+  async signTransaction(xdr2, opts) {
+    return this.sign(xdr2, opts);
+  }
+};
+export {
+  BlendStrategyClient,
+  DEFAULT_ROUTER_SLIPPAGE_BPS,
+  FreighterSigner,
+  ManualSigner,
+  SCALAR_12,
+  STELLAR_NETWORK_PASSPHRASES,
+  SpieldClient,
+  SpieldConfigurationError,
+  SpieldContractError,
+  SpieldRpcError,
+  SpieldSdkError,
+  SpieldSignerError,
+  SpieldValidationError,
+  SrMarketClient,
+  SrPortfolioClient,
+  SrProtocolClient,
+  SrRouterClient,
+  SrTokensClient,
+  SrVaultClient,
+  StandardizedReturnClient,
+  YT_MAX_IN_PAD_BPS,
+  YieldEngineClient,
+  assertNonNegativeAmount,
+  customNetwork,
+  fromBaseUnits,
+  fromScalar12,
+  testnet,
+  toBaseUnits,
+  tokenAmount
+};
+//# sourceMappingURL=index.js.map