From 394ebb3b00f45a6664696bca12c76917ab499a05 Mon Sep 17 00:00:00 2001
From: adewunmiodunlamipriscilla-glitch <adewunmiodunlamipriscilla@gmail.com>
Date: Sat, 17 Oct 2026 16:40:01 +0100
Subject: [PATCH] USDC trust line

---
 app/copy-trade/page.tsx                    |  94 ++++-
 app/markets/quick-view/page.tsx            | 136 ++++++-
 components/layout/WalletDropdown.tsx       |  34 +-
 docs/architecture.md                       |   5 +-
 docs/contract-requests.md                  |   8 +
 docs/manual-test.md                        |   8 +-
 lib/hooks/useStellar.ts                    | 402 +++++++++++++++++++--
 lib/stellar/__tests__/deadline.test.ts     |  26 ++
 lib/stellar/__tests__/ledger-clock.test.ts |  33 ++
 lib/stellar/__tests__/quote.test.ts        |  59 +++
 lib/stellar/__tests__/sell-solver.test.ts  |  77 ++++
 lib/stellar/clients.ts                     |  14 +-
 lib/stellar/deadline.ts                    |  40 ++
 lib/stellar/errors.ts                      |   7 +-
 lib/stellar/ledger-clock.ts                | 127 +++++++
 lib/stellar/quote.ts                       |  68 ++++
 lib/stellar/sell-solver.ts                 |  68 ++++
 lib/stellar/trustline.ts                   | 165 +++++++++
 18 files changed, 1311 insertions(+), 60 deletions(-)
 create mode 100644 lib/stellar/__tests__/deadline.test.ts
 create mode 100644 lib/stellar/__tests__/ledger-clock.test.ts
 create mode 100644 lib/stellar/__tests__/quote.test.ts
 create mode 100644 lib/stellar/__tests__/sell-solver.test.ts
 create mode 100644 lib/stellar/deadline.ts
 create mode 100644 lib/stellar/ledger-clock.ts
 create mode 100644 lib/stellar/quote.ts
 create mode 100644 lib/stellar/sell-solver.ts
 create mode 100644 lib/stellar/trustline.ts

diff --git a/app/copy-trade/page.tsx b/app/copy-trade/page.tsx
index 3bd60a0..91745cb 100644
--- a/app/copy-trade/page.tsx
+++ b/app/copy-trade/page.tsx
@@ -7,9 +7,20 @@ import { getTrace, ReasoningTrace } from "@/lib/api/traces";
 import { confirmCopyTrade, initiateCopyTrade } from "@/lib/api/trade";
 import { ApiError } from "@/lib/api/client";
 import { useMarket } from "@/lib/hooks/useMarkets";
-import { useBuy, useQuoteBuy, useUsdcBalance } from "@/lib/hooks/useStellar";
+import {
+  useBuy,
+  useEnableUsdc,
+  fetchOnChainMarket,
+  useLedgerNow,
+  useOnChainMarket,
+  useQuoteBuy,
+  useUsdcBalance,
+  useUsdcTrustline,
+} from "@/lib/hooks/useStellar";
 import { explorerTx } from "@/lib/stellar/config";
 import { formatUsdc, minOut, shareOf } from "@/lib/stellar/units";
+import { MIN_TX_TIMEOUT_S, SAFETY_MARGIN_S } from "@/lib/stellar/deadline";
+import { getLedgerNow } from "@/lib/stellar/ledger-clock";
 
 /** Wait this long after the slider stops before asking for a new quote. */
 const QUOTE_DEBOUNCE_MS = 400;
@@ -35,8 +46,12 @@ function CopyTradeContent() {
   const [traceError, setTraceError] = useState<string | null>(null);
   const { data: market } = useMarket(marketIdParam ?? trace?.marketId ?? undefined);
   const onChainMarketId = market?.onChainMarketId ?? null;
+  const onChainMarket = useOnChainMarket(onChainMarketId);
 
   const balance = useUsdcBalance(address);
+  const trustline = useUsdcTrustline(address);
+  const enableUsdc = useEnableUsdc();
+  const ledger = useLedgerNow();
   const buy = useBuy();
 
   // Allocation as a share of the wallet's USDC balance, in basis points.
@@ -62,6 +77,19 @@ function CopyTradeContent() {
   const debouncedAmount = useDebounced(amountRaw, QUOTE_DEBOUNCE_MS);
   const quote = useQuoteBuy(onChainMarketId, side ?? "Yes", side ? debouncedAmount : null);
   const minShares = quote.data !== undefined ? minOut(quote.data, slippageBps) : null;
+  const closeTime = onChainMarket.data?.market.close_time;
+  const secondsToClose =
+    closeTime !== undefined && ledger.now !== null
+      ? Number(closeTime - BigInt(Math.floor(ledger.now)))
+      : null;
+  const marketCanTrade =
+    onChainMarket.data?.market.status.tag === "Open" &&
+    secondsToClose !== null &&
+    secondsToClose > SAFETY_MARGIN_S + MIN_TX_TIMEOUT_S;
+  const trustlineMissing = trustline.data?.kind === "missing";
+  const trustlineReady =
+    trustline.data?.kind === "native" ||
+    (trustline.data?.kind === "present" && trustline.data.authorized);
 
   const handleSliderInteraction = (clientX: number) => {
     if (!sliderRef.current) return;
@@ -114,6 +142,24 @@ function CopyTradeContent() {
       setStatusMessage("This market isn't on-chain yet, so it can't be traded.");
       return;
     }
+    if (!onChainMarket.data) {
+      setStatusMessage("Checking the on-chain market and ledger time…");
+      return;
+    }
+    if (!marketCanTrade) {
+      setStatusMessage("This market is closed or too close to its deadline to safely place a trade.");
+      return;
+    }
+    if (!trustlineReady) {
+      setStatusMessage(
+        trustlineMissing
+          ? "Enable your USDC trustline before copying this trade."
+          : trustline.data?.kind === "present"
+            ? "The issuer hasn't authorized your USDC trustline."
+            : "Checking your USDC trustline…",
+      );
+      return;
+    }
     if (!amountRaw || amountRaw <= 0n) {
       setStatusMessage("Choose an allocation greater than zero. You may need USDC in your wallet first.");
       return;
@@ -127,6 +173,17 @@ function CopyTradeContent() {
         return;
       }
 
+      const freshMarket = await fetchOnChainMarket(onChainMarketId);
+      const freshLedgerNow = getLedgerNow();
+      if (
+        freshLedgerNow === null ||
+        freshMarket.market.status.tag !== "Open" ||
+        BigInt(Math.floor(freshLedgerNow)) + BigInt(SAFETY_MARGIN_S + MIN_TX_TIMEOUT_S) >= freshMarket.market.close_time
+      ) {
+        setStatusMessage("This market is closed or too close to its deadline to safely place a trade.");
+        return;
+      }
+
       setStatusMessage("Recording your copy trade…");
       const { copyTradeId } = await initiateCopyTrade({
         traceId: trace.id,
@@ -159,6 +216,16 @@ function CopyTradeContent() {
     }
   };
 
+  const handleEnableUsdc = async () => {
+    setStatusMessage("Checking XLM reserve, then opening your wallet…");
+    try {
+      await enableUsdc.mutateAsync();
+      setStatusMessage("USDC is enabled. Click Confirm Copy Trade when you're ready.");
+    } catch (error) {
+      setStatusMessage(error instanceof Error ? error.message : "Couldn't enable USDC.");
+    }
+  };
+
   return (
     <div className="bg-background text-on-surface min-h-screen flex flex-col">
       <style jsx global>{`
@@ -325,6 +392,29 @@ function CopyTradeContent() {
             </div>
 
             <div className="space-y-3">
+              {secondsToClose !== null && secondsToClose >= 0 && secondsToClose < 3_600 && (
+                <p className="text-center text-xs font-data-mono text-on-surface-variant">
+                  Closes in {Math.floor(secondsToClose / 60)}m {secondsToClose % 60}s
+                </p>
+              )}
+              {onChainMarket.data && !marketCanTrade && (
+                <p className="text-center text-xs text-error">
+                  This market is closed or too close to its deadline to safely place a trade.
+                </p>
+              )}
+              {trustlineMissing && !isWrongNetwork && (
+                <div className="rounded-lg border border-outline-variant bg-surface p-3 text-sm text-on-surface-variant">
+                  <p className="mb-2">Enable USDC before OracleDesk can submit the copied trade. Enabling it will not place the trade.</p>
+                  <button
+                    type="button"
+                    onClick={handleEnableUsdc}
+                    disabled={enableUsdc.isPending}
+                    className="rounded-md bg-primary px-3 py-2 text-xs font-bold text-primary-foreground disabled:opacity-50"
+                  >
+                    {enableUsdc.isPending ? "Enabling…" : "Enable USDC"}
+                  </button>
+                </div>
+              )}
               {statusMessage ? (
                 <div className="rounded-2xl border border-outline-variant bg-surface p-4 text-sm text-on-surface-variant">
                   {statusMessage}
@@ -342,7 +432,7 @@ function CopyTradeContent() {
                   className="flex-[2] bg-[#005f73] text-primary-foreground py-4 rounded-lg font-headline-sm text-headline-sm shadow-lg shadow-primary-container/20 hover:brightness-110 active:scale-[0.98] transition-all flex items-center justify-center gap-2 disabled:opacity-50 disabled:cursor-not-allowed"
                   onClick={handleConfirm}
                   type="button"
-                  disabled={isSubmitting || !side}
+                  disabled={isSubmitting || !side || !marketCanTrade || !trustlineReady || ledger.now === null}
                 >
                   <span className="material-symbols-outlined text-xl">bolt</span>
                   {isSubmitting ? "Submitting..." : "Confirm Copy Trade"}
diff --git a/app/markets/quick-view/page.tsx b/app/markets/quick-view/page.tsx
index 63c6a06..71e512d 100644
--- a/app/markets/quick-view/page.tsx
+++ b/app/markets/quick-view/page.tsx
@@ -8,10 +8,21 @@ import { useQuery } from "@tanstack/react-query";
 import { useMarket } from "@/lib/hooks/useMarkets";
 import { getMarketByOnChainId } from "@/lib/api/markets";
 import { ApiError } from "@/lib/api/client";
-import { useBuy, useOnChainMarket, usePosition, useQuoteBuy, useUsdcBalance } from "@/lib/hooks/useStellar";
+import {
+  useBuy,
+  useEnableUsdc,
+  useExactBuyQuote,
+  useLedgerNow,
+  useOnChainMarket,
+  usePosition,
+  useQuoteBuy,
+  useUsdcBalance,
+  useUsdcTrustline,
+} from "@/lib/hooks/useStellar";
 import { useWallet } from "@/lib/contexts/WalletContext";
 import { explorerTx } from "@/lib/stellar/config";
-import { formatUsdc, minOut, tryParseUsdc } from "@/lib/stellar/units";
+import { formatUsdc, maxIn, minOut, tryParseUsdc } from "@/lib/stellar/units";
+import { MIN_TX_TIMEOUT_S, SAFETY_MARGIN_S } from "@/lib/stellar/deadline";
 
 const SLIPPAGE_BPS = 100; // 1%
 
@@ -65,18 +76,23 @@ function MarketQuickViewContent() {
   const onChainMarketId = market?.onChainMarketId ?? onChainIdParam ?? null;
   const chain = useOnChainMarket(onChainMarketId);
 
-  const { address, isConnected, openModal } = useWallet();
+  const { address, isConnected, isWrongNetwork, openModal } = useWallet();
   const position = usePosition(onChainMarketId, address);
   const balance = useUsdcBalance(address);
+  const trustline = useUsdcTrustline(address);
+  const enableUsdc = useEnableUsdc();
   const buy = useBuy();
+  const ledger = useLedgerNow();
 
   const [showModal] = useState(true);
   const [side, setSide] = useState<"Yes" | "No">(initialSide);
   const [amountInput, setAmountInput] = useState("10");
+  const [buyMode, setBuyMode] = useState<"usdc" | "shares">("usdc");
   const [buyStatus, setBuyStatus] = useState<string | null>(null);
   const amountRaw = tryParseUsdc(amountInput);
   const debouncedAmount = useDebounced(amountRaw, 400);
-  const quote = useQuoteBuy(onChainMarketId, side, debouncedAmount);
+  const quote = useQuoteBuy(onChainMarketId, side, buyMode === "usdc" ? debouncedAmount : null);
+  const exactQuote = useExactBuyQuote(onChainMarketId, side, buyMode === "shares" ? debouncedAmount : null);
 
   // Illustrative only: there is no price history source yet.
   const sparklinePath = "M0 25 L10 22 L20 28 L30 18 L40 20 L50 15 L60 17 L70 10 L80 12 L90 5 L100 8";
@@ -87,8 +103,24 @@ function MarketQuickViewContent() {
   const yesProb = view ? Math.round(view.yesBps / 100) : backendProb;
   const noProb = 100 - yesProb;
   const chainStatus = view?.market.status;
-  // Compare with when the market was read, not "now", to keep render pure.
-  const isOpen = chainStatus?.tag === "Open" && Number(view?.market.close_time ?? 0) * 1000 > chain.dataUpdatedAt;
+  const isOpen =
+    chainStatus?.tag === "Open" &&
+    ledger.now !== null &&
+    view !== undefined &&
+    BigInt(Math.floor(ledger.now)) < view.market.close_time;
+  const secondsToClose =
+    ledger.now !== null && view
+      ? Number(view.market.close_time - BigInt(Math.floor(ledger.now)))
+      : null;
+  const safeToTrade =
+    secondsToClose !== null && secondsToClose > SAFETY_MARGIN_S + MIN_TX_TIMEOUT_S;
+  const countdown =
+    secondsToClose !== null && secondsToClose >= 0 && secondsToClose < 3_600
+      ? `Closes in ${Math.floor(secondsToClose / 60)}m ${secondsToClose % 60}s`
+      : null;
+  const trustlineMissing = trustline.data?.kind === "missing";
+  const trustlineUnauthorized =
+    trustline.data?.kind === "present" && !trustline.data.authorized;
 
   const isLoading = backendById.isLoading || (backendByChainId.isLoading && !marketId) || (chain.isLoading && !market);
   const notFound = !market && !view;
@@ -99,13 +131,48 @@ function MarketQuickViewContent() {
       return;
     }
     if (!onChainMarketId) return;
+    if (trustlineMissing) {
+      setBuyStatus("Enable your USDC trustline below, then click Buy again.");
+      return;
+    }
+    if (trustlineUnauthorized) {
+      setBuyStatus("The issuer hasn't authorized your USDC trustline.");
+      return;
+    }
+    if (isWrongNetwork) {
+      setBuyStatus("Switch your wallet to Stellar Testnet to place this trade.");
+      return;
+    }
     if (!amountRaw || amountRaw <= 0n) {
-      setBuyStatus("Enter an amount like 10 or 2.5.");
+      setBuyStatus(buyMode === "usdc" ? "Enter an amount like 10 or 2.5." : "Enter a share amount greater than zero.");
+      return;
+    }
+    if (ledger.now === null) {
+      setBuyStatus("Checking market time…");
+      return;
+    }
+    if (!safeToTrade) {
+      setBuyStatus("This market closes too soon to safely place a trade.");
       return;
     }
     setBuyStatus("Getting a fresh quote, then asking your wallet to sign…");
     try {
-      const result = await buy.mutateAsync({ marketId: onChainMarketId, outcome: side, collateralIn: amountRaw, slippageBps: SLIPPAGE_BPS });
+      const result =
+        buyMode === "shares"
+          ? await buy.mutateAsync({
+              marketId: onChainMarketId,
+              outcome: side,
+              mode: "shares",
+              targetShares: amountRaw,
+              maxCollateralIn: exactQuote.data?.collateralIn,
+              slippageBps: SLIPPAGE_BPS,
+            })
+          : await buy.mutateAsync({
+              marketId: onChainMarketId,
+              outcome: side,
+              collateralIn: amountRaw,
+              slippageBps: SLIPPAGE_BPS,
+            });
       setBuyStatus(
         `Bought ${formatUsdc(result.sharesOut, { maxDecimals: 2 })} ${side.toUpperCase()} shares.` +
           (result.txHash ? ` View: ${explorerTx(result.txHash)}` : ""),
@@ -115,6 +182,16 @@ function MarketQuickViewContent() {
     }
   };
 
+  const handleEnableUsdc = async () => {
+    setBuyStatus("Checking XLM reserve, then opening your wallet…");
+    try {
+      await enableUsdc.mutateAsync();
+      setBuyStatus("USDC is enabled. Review your amount and click Buy to submit the trade.");
+    } catch (err) {
+      setBuyStatus(err instanceof Error ? err.message : "Couldn't enable USDC.");
+    }
+  };
+
   if (isLoading) {
     return (
       <main className="relative min-h-[calc(100vh-64px)] overflow-hidden bg-surface flex items-center justify-center">
@@ -188,6 +265,7 @@ function MarketQuickViewContent() {
                     {statusLabel}
                     {chainStatus && <SourceTag source="chain" />}
                   </span>
+                  {countdown && <span className="text-[10px] font-data-mono text-on-surface-variant">{countdown}</span>}
                   <span className="font-label-caps text-label-caps text-outline uppercase font-bold tracking-wider">{categoryLabel}</span>
                 </div>
                 <Link 
@@ -268,8 +346,12 @@ function MarketQuickViewContent() {
                 {onChainMarketId !== null && (
                   <div className="space-y-3">
                     <div className="flex items-center gap-3">
+                      <div className="inline-flex rounded border border-outline-variant p-0.5" aria-label="Buy amount unit">
+                        <button type="button" aria-pressed={buyMode === "usdc"} onClick={() => setBuyMode("usdc")} className={`px-2 py-1 text-[10px] rounded ${buyMode === "usdc" ? "bg-primary text-primary-foreground" : "text-on-surface-variant"}`}>USDC</button>
+                        <button type="button" aria-pressed={buyMode === "shares"} onClick={() => setBuyMode("shares")} className={`px-2 py-1 text-[10px] rounded ${buyMode === "shares" ? "bg-primary text-primary-foreground" : "text-on-surface-variant"}`}>Shares</button>
+                      </div>
                       <label htmlFor="buy-amount" className="font-label-caps text-label-caps text-on-surface-variant uppercase text-[10px] shrink-0">
-                        Amount (USDC)
+                        Amount ({buyMode === "usdc" ? "USDC" : `${side.toUpperCase()} shares`})
                       </label>
                       <input
                         id="buy-amount"
@@ -281,7 +363,18 @@ function MarketQuickViewContent() {
                       <button
                         type="button"
                         onClick={handleBuy}
-                        disabled={buy.isPending || (isConnected && !isOpen)}
+                        disabled={
+                          buy.isPending ||
+                          (isConnected &&
+                            (!isOpen ||
+                              !safeToTrade ||
+                              ledger.now === null ||
+                              trustlineMissing ||
+                              trustlineUnauthorized ||
+                              (buyMode === "shares" &&
+                                (!exactQuote.data ||
+                                  (balance.data !== undefined && balance.data < exactQuote.data.collateralIn)))))
+                        }
                         className="bg-primary text-primary-foreground px-4 py-2 rounded-lg font-label-caps text-label-caps font-bold disabled:opacity-50"
                       >
                         {!isConnected ? "Connect" : buy.isPending ? "Buying…" : `Buy ${side.toUpperCase()}`}
@@ -290,8 +383,14 @@ function MarketQuickViewContent() {
                     <div className="flex justify-between text-[11px] font-data-mono text-on-surface-variant">
                       <span>
                         {amountRaw === null
-                          ? "Enter an amount like 10 or 2.5"
-                          : quote.data !== undefined
+                          ? buyMode === "usdc" ? "Enter an amount like 10 or 2.5" : "Enter a share amount"
+                          : buyMode === "shares" && exactQuote.data
+                            ? `Costs ≈ ${formatUsdc(exactQuote.data.collateralIn, { maxDecimals: 2 })} USDC (fee ${formatUsdc(exactQuote.data.fee, { maxDecimals: 2 })}), at most ${formatUsdc(maxIn(exactQuote.data.collateralIn, SLIPPAGE_BPS), { maxDecimals: 2 })} with 1% slippage`
+                            : buyMode === "shares" && exactQuote.error
+                              ? exactQuote.error.message
+                              : buyMode === "shares" && exactQuote.isFetching
+                                ? "Quoting exact share amount…"
+                                : quote.data !== undefined
                             ? `≈ ${formatUsdc(quote.data, { maxDecimals: 2 })} shares, at least ${formatUsdc(minOut(quote.data, SLIPPAGE_BPS), { maxDecimals: 2 })} (1% slippage)`
                             : quote.error ? quote.error.message : quote.isFetching ? "Quoting…" : ""}
                       </span>
@@ -300,6 +399,19 @@ function MarketQuickViewContent() {
                     {!isOpen && view && (
                       <p className="text-[11px] text-on-surface-variant">This market is closed to trading.</p>
                     )}
+                    {ledger.now === null && <p className="text-[11px] text-on-surface-variant">Checking market time…</p>}
+                    {isOpen && !safeToTrade && <p className="text-[11px] text-on-surface-variant">Trading is disabled this close to the market deadline.</p>}
+                    {trustlineMissing && !isWrongNetwork && (
+                      <div className="rounded-lg border border-outline-variant bg-surface-container-low p-3 space-y-2">
+                        <p className="text-xs text-on-surface-variant">
+                          Enable USDC once to buy on Stellar. This creates a trustline and locks one base reserve (typically 0.5 XLM); it does not submit your trade.
+                        </p>
+                        <button type="button" onClick={handleEnableUsdc} disabled={enableUsdc.isPending} className="bg-primary text-primary-foreground px-3 py-2 rounded-lg text-xs font-bold disabled:opacity-50">
+                          {enableUsdc.isPending ? "Enabling…" : "Enable USDC"}
+                        </button>
+                      </div>
+                    )}
+                    {trustlineUnauthorized && <p className="text-[11px] text-error">The issuer hasn&apos;t authorized your USDC trustline.</p>}
                     {position.data && (position.data.yes > 0n || position.data.no > 0n) && (
                       <p className="text-[11px] font-data-mono text-on-surface">
                         Your position: {formatUsdc(position.data.yes, { maxDecimals: 2 })} YES · {formatUsdc(position.data.no, { maxDecimals: 2 })} NO
diff --git a/components/layout/WalletDropdown.tsx b/components/layout/WalletDropdown.tsx
index cb4339f..4ef92c5 100644
--- a/components/layout/WalletDropdown.tsx
+++ b/components/layout/WalletDropdown.tsx
@@ -3,7 +3,7 @@
 import React, { useState, useRef, useEffect } from "react";
 import { motion, AnimatePresence } from "framer-motion";
 import { useWallet } from "@/lib/contexts/WalletContext";
-import { useUsdcBalance } from "@/lib/hooks/useStellar";
+import { useEnableUsdc, useUsdcBalance, useUsdcTrustline } from "@/lib/hooks/useStellar";
 import { NETWORK_LABEL, explorerAccount } from "@/lib/stellar/config";
 import { formatUsdc, shortAddress } from "@/lib/stellar/units";
 
@@ -13,6 +13,8 @@ const WalletDropdown = () => {
   const [copied, setCopied] = useState(false);
   const dropdownRef = useRef<HTMLDivElement>(null);
   const balance = useUsdcBalance(address);
+  const trustline = useUsdcTrustline(address);
+  const enableUsdc = useEnableUsdc();
 
   // Close dropdown when clicking outside
   useEffect(() => {
@@ -39,10 +41,22 @@ const WalletDropdown = () => {
   }
 
   const truncatedAddress = shortAddress(address, 6, 4);
-  const balanceText = balance.data !== undefined
+  const trustlineMissing = !isWrongNetwork && trustline.data?.kind === "missing";
+  const unauthorized = trustline.data?.kind === "present" && !trustline.data.authorized;
+  const balanceText = trustlineMissing
+    ? "USDC not enabled"
+    : balance.data !== undefined
     ? formatUsdc(balance.data, { maxDecimals: 2, minDecimals: 2, grouping: true })
     : balance.isError ? "—" : "…";
 
+  const handleEnableUsdc = async () => {
+    try {
+      await enableUsdc.mutateAsync();
+    } catch {
+      // The mutation error is rendered in the wallet menu below.
+    }
+  };
+
   const copyAddress = async () => {
     try {
       await navigator.clipboard.writeText(address);
@@ -101,6 +115,22 @@ const WalletDropdown = () => {
                   USDC
                 </span>
               </div>
+              {trustlineMissing && !isWrongNetwork && (
+                <button
+                  type="button"
+                  onClick={handleEnableUsdc}
+                  disabled={enableUsdc.isPending}
+                  className="mt-2 rounded-md bg-primary px-3 py-1.5 text-xs font-bold text-primary-foreground disabled:opacity-50"
+                >
+                  {enableUsdc.isPending ? "Enabling…" : "Enable USDC"}
+                </button>
+              )}
+              {unauthorized && (
+                <p className="mt-2 text-[11px] text-error">The issuer hasn&apos;t authorized your USDC trustline.</p>
+              )}
+              {enableUsdc.error && (
+                <p className="mt-2 text-[11px] text-error">{enableUsdc.error.message}</p>
+              )}
               {isWrongNetwork && (
                 <p className="mt-2 text-[11px] text-error">Your wallet is on a different network. Switch it to Stellar Testnet.</p>
               )}
diff --git a/docs/architecture.md b/docs/architecture.md
index e3c4e85..f32ee0d 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -25,9 +25,10 @@ A backend market links to the chain through `onChainMarketId` (market-core's `u6
 
 - `lib/stellar/clients.ts` builds a generated binding `Client` per contract, optionally with the wallet as signer. The USDC Stellar Asset Contract has no Wasm and so no bindings; `token.balance` and `token.transfer` are built with `AssembledTransaction.build`.
 - Reads are simulations (no fee, no signature).
-- Writes (`useBuy`, `useSell`, `useRedeem`, `useUsdcTransfer`) check that a wallet is connected and on the right network, simulate, then `signAndSend`.
+- Writes (`useBuy`, `useSell`, `useRedeem`, `useUsdcTransfer`) check that a wallet is connected and on the right network, require an authorized USDC trustline where needed, and set explicit transaction timeouts. Buy/sell deadlines use the latest Stellar ledger clock, not the browser's wall clock.
 - `useBuy` quotes again immediately before building the transaction and sets `min_shares_out = minOut(quote, slippageBps)`, so slippage is enforced on-chain.
-- `useSell` turns "sell N shares" into the exact `collateral_out` the contract needs, using the contract's own FPMM math (`generated/fpmm.ts`) on freshly read reserves, with `max_shares_in` slightly above N (see the contracts repo's `docs/frontend-integration.md`).
+- `useSell` solves for the largest `collateral_out` whose exact contract-rounded share cost fits the requested share budget, confirms it with `quote_sell`, and caps `max_shares_in` at the wallet's actual position.
+- `useBuy` supports exact collateral input and exact share targets; the latter finds the minimal collateral input using the same bigint FPMM rounding as the contract and confirms it with `quote_buy`.
 
 ## Amounts
 
diff --git a/docs/contract-requests.md b/docs/contract-requests.md
index 9ff32ce..7368877 100644
--- a/docs/contract-requests.md
+++ b/docs/contract-requests.md
@@ -47,3 +47,11 @@ the commitment hash has to rebuild the XDR by hand. A no-op view function
 that takes a `ResolutionSpec`, or a `spec_hash(spec) -> BytesN<32>` view,
 would put the type in the spec and let clients ask the contract for the
 hash instead of re-implementing it.
+
+## 5. Add a share-budget sell quote
+
+The frontend converts "sell N shares" into `collateral_out` by binary-searching
+the contract's integer-rounded `calc_sell` math, then confirms the result with
+`quote_sell`. A view such as `quote_sell_shares(market_id, outcome, shares) ->
+{ collateral_out, shares_in }` would provide the exact inversion on-chain and
+avoid repeated local work and quote simulations.
diff --git a/docs/manual-test.md b/docs/manual-test.md
index 49c53ea..89fe9e0 100644
--- a/docs/manual-test.md
+++ b/docs/manual-test.md
@@ -6,7 +6,7 @@ These steps cover what automated checks can't: a real browser wallet signing rea
 
 ## Before you start: two known blockers
 
-1. **Test USDC can only be minted by the deployer key.** The collateral is a self-issued test asset (`USDC` issued by `GD2NB2VUME7ECMHFHQN5M3KUZLLJF3R6Z4OFCBLE4SJNHIQHITRPQGHQ`, wrapped as the SAC `CA2WQQJ4OHQCLHQW6XN4BCLILGRV6V4YDYDT3GVIWXB53BTOO7EMREQH`). There is no faucet, so step 4 needs a maintainer (see [contract-requests.md](contract-requests.md) #3).
+1. **Test USDC can only be minted by the deployer key.** The collateral is a self-issued test asset wrapped as a Stellar Asset Contract. There is no faucet, so step 4 still needs a maintainer (see [contract-requests.md](contract-requests.md) #3).
 2. **Both existing testnet markets are closed.** Markets 0 and 1 were created by the contracts repo's demo with a 90-second trading window on 2026-09-21; market 0 is resolved YES. Buying on them fails with "This market has closed". Step 7 therefore needs a fresh, open market (see below).
 
 ## You need
@@ -31,9 +31,11 @@ These steps cover what automated checks can't: a real browser wallet signing rea
 
 ## 4. Get test USDC
 
-a. **Add the trustline** (the account must trust the asset before it can hold it):
+a. **Enable the trustline in OracleDesk** (the account must trust the asset before it can hold it):
 
-- [ ] Freighter → Manage assets → Add manually: code `USDC`, issuer `GD2NB2VUME7ECMHFHQN5M3KUZLLJF3R6Z4OFCBLE4SJNHIQHITRPQGHQ`. Approve the transaction.
+- [ ] Connect your funded wallet, then open the wallet menu or an on-chain market's quick view.
+- [ ] Click **Enable USDC** and approve the one-time `changeTrust` transaction. The flow checks spendable XLM for the trustline reserve and transaction fee first.
+- [ ] Wait for the trustline to appear. Enabling it does not submit a pending buy; review the amount and click **Buy** again.
 
 b. **Ask a maintainer to mint.** With the deployer key from `scripts/deploy-testnet.sh` (the CLI identity `oracledesk-deployer`), they run:
 
diff --git a/lib/hooks/useStellar.ts b/lib/hooks/useStellar.ts
index 574738f..19b79c8 100644
--- a/lib/hooks/useStellar.ts
+++ b/lib/hooks/useStellar.ts
@@ -3,12 +3,19 @@
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import type { AssembledTransaction } from "@stellar/stellar-sdk/contract";
 import { useWallet } from "@/lib/contexts/WalletContext";
-import { marketCore, reasoningRegistry, token, Outcomes, type OutcomeTag, type Signer } from "@/lib/stellar/clients";
+import { marketCore, reasoningRegistry, token, Outcomes, rpcServer, type OutcomeTag, type Signer } from "@/lib/stellar/clients";
 import { describeError, UserFacingError, type ContractName } from "@/lib/stellar/errors";
-import { collateralOutForShares, priceYesBps } from "@/lib/stellar/generated/fpmm";
+import { BPS, priceYesBps } from "@/lib/stellar/generated/fpmm";
 import type { Market as OnChainMarket, Position } from "@/lib/stellar/generated/market-core";
 import { fetchAndVerifyTrace, type TraceCheck } from "@/lib/stellar/trace";
 import { maxIn, minOut } from "@/lib/stellar/units";
+import { assertSigningDeadline, deadlineFor, type TransactionDeadline } from "@/lib/stellar/deadline";
+import { getLedgerNow, useLedgerNow } from "@/lib/stellar/ledger-clock";
+import { enableUsdcTrustline, getTrustlineState, usdcClassicAsset, type TrustlineState } from "@/lib/stellar/trustline";
+import { minCollateralForShares } from "@/lib/stellar/quote";
+import { reconcileWithQuote, solveSellForShares } from "@/lib/stellar/sell-solver";
+
+export { useLedgerNow };
 
 /** Query keys all start with "stellar" so a disconnect can drop them in one go. */
 export const stellarKeys = {
@@ -17,12 +24,69 @@ export const stellarKeys = {
   markets: (limit: number) => ["stellar", "markets", limit] as const,
   position: (id: string, holder: string) => ["stellar", "position", id, holder] as const,
   balance: (owner: string) => ["stellar", "usdcBalance", owner] as const,
+  trustline: (owner: string) => ["stellar", "usdcTrustline", owner] as const,
   quoteBuy: (id: string, outcome: OutcomeTag, amount: string) => ["stellar", "quoteBuy", id, outcome, amount] as const,
+  exactBuy: (id: string, outcome: OutcomeTag, target: string) => ["stellar", "exactBuy", id, outcome, target] as const,
   trace: (id: string) => ["stellar", "trace", id] as const,
 };
 
 const toId = (id: bigint | string | number) => BigInt(id);
 
+async function trustlineFor(address: string): Promise<TrustlineState> {
+  return getTrustlineState(address, await usdcClassicAsset());
+}
+
+async function requireUsdcTrustline(address: string): Promise<TrustlineState> {
+  const state = await trustlineFor(address);
+  if (state.kind === "missing") {
+    throw new UserFacingError({
+      kind: "no-trustline",
+      message: "Enable your USDC trustline before using USDC.",
+      action: "enable-usdc",
+    });
+  }
+  if (state.kind === "account-missing") {
+    throw new UserFacingError({ kind: "unknown", message: "Your Stellar account is not funded yet. Fund it before continuing." });
+  }
+  if (state.kind === "present" && !state.authorized) {
+    throw new UserFacingError({ kind: "no-trustline", message: "The issuer hasn't authorized your USDC trustline." });
+  }
+  return state;
+}
+
+function signerUntil(signer: Signer, deadline: TransactionDeadline): Signer {
+  return {
+    publicKey: signer.publicKey,
+    signTransaction: async (xdr, options) => {
+      const signed = await signer.signTransaction(xdr, options);
+      try {
+        assertSigningDeadline(deadline, getLedgerNow());
+      } catch (error) {
+        throw new UserFacingError(
+          { kind: "contract", message: error instanceof Error ? error.message : "Signing took too long; try again." },
+          error,
+        );
+      }
+      return signed;
+    },
+  };
+}
+
+function writeDeadline(kind: "buy" | "sell" | "redeem" | "transfer", market?: OnChainMarket): TransactionDeadline {
+  const now = getLedgerNow();
+  try {
+    return deadlineFor(kind, now, market?.close_time);
+  } catch (error) {
+    throw new UserFacingError(
+      {
+        kind: "contract",
+        message: error instanceof Error ? error.message : "Stellar ledger time is unavailable.",
+      },
+      error,
+    );
+  }
+}
+
 /**
  * The value of a simulated call. Contract `Result`s are unwrapped; failures
  * become a UserFacingError named from the simulation's "Error(Contract, #N)".
@@ -130,6 +194,62 @@ export function useUsdcBalance(owner: string | null | undefined) {
   });
 }
 
+export function useUsdcTrustline(owner: string | null | undefined) {
+  const { isWrongNetwork } = useWallet();
+  return useQuery({
+    queryKey: stellarKeys.trustline(owner ?? ""),
+    enabled: Boolean(owner) && !isWrongNetwork,
+    queryFn: () => trustlineFor(owner as string),
+    staleTime: 10_000,
+    refetchInterval: 10_000,
+  });
+}
+
+export function useEnableUsdc() {
+  const signer = useWriteGuard();
+  const queryClient = useQueryClient();
+  useLedgerNow();
+  return useMutation({
+    mutationFn: async () => {
+      const wallet = signer();
+      const asset = await usdcClassicAsset();
+      const current = await getTrustlineState(wallet.publicKey, asset);
+      if (current.kind === "native" || (current.kind === "present" && current.authorized)) {
+        return { hash: null, holder: wallet.publicKey };
+      }
+      if (current.kind === "present" && !current.authorized) {
+        throw new UserFacingError({
+          kind: "no-trustline",
+          message: "The issuer hasn't authorized your USDC trustline.",
+        });
+      }
+      const { hash } = await enableUsdcTrustline(wallet.publicKey, asset, wallet);
+      const deadline = Date.now() + 60_000;
+      let delay = 1_000;
+      while (Date.now() < deadline) {
+        const state = await getTrustlineState(wallet.publicKey, asset);
+        if (state.kind === "present" && state.authorized) return { hash, holder: wallet.publicKey };
+        if (state.kind === "present") {
+          throw new UserFacingError({
+            kind: "no-trustline",
+            message: "The issuer hasn't authorized your USDC trustline.",
+          });
+        }
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        delay = Math.min(delay * 2, 5_000);
+      }
+      throw new UserFacingError({
+        kind: "network",
+        message: "The trustline transaction confirmed, but the new trustline is not visible yet. Refresh and check again.",
+      });
+    },
+    onSuccess: ({ holder }) => {
+      void queryClient.invalidateQueries({ queryKey: stellarKeys.trustline(holder) });
+      void queryClient.invalidateQueries({ queryKey: stellarKeys.balance(holder) });
+    },
+  });
+}
+
 /** Shares a buy would return right now. Debounce `collateralIn` at the call site. */
 export function useQuoteBuy(id: bigint | string | null | undefined, outcome: OutcomeTag, collateralIn: bigint | null) {
   return useQuery({
@@ -143,6 +263,42 @@ export function useQuoteBuy(id: bigint | string | null | undefined, outcome: Out
   });
 }
 
+export function useExactBuyQuote(
+  id: bigint | string | null | undefined,
+  outcome: OutcomeTag,
+  targetShares: bigint | null,
+) {
+  return useQuery({
+    queryKey: stellarKeys.exactBuy(String(id), outcome, targetShares?.toString() ?? ""),
+    enabled: id !== null && id !== undefined && targetShares !== null && targetShares > 0n,
+    queryFn: async () => {
+      const view = await fetchOnChainMarket(id as string);
+      const local = minCollateralForShares(view.market, outcome, targetShares as bigint);
+      if (!local.ok) {
+        const message =
+          local.reason === "market-too-large"
+            ? "This target exceeds the market's remaining size limit."
+            : local.reason === "invalid-target"
+              ? "Enter a share amount greater than zero."
+              : "The requested share amount is too large.";
+        throw new UserFacingError({ kind: "contract", message });
+      }
+      const quotedShares = simulated<bigint>(
+        await marketCore().quote_buy({
+          market_id: toId(id as string),
+          outcome: Outcomes[outcome],
+          collateral_in: local.collateralIn,
+        }),
+      );
+      if (quotedShares < (targetShares as bigint)) {
+        throw new UserFacingError({ kind: "contract", message: "The price moved; refresh the quote and try again." });
+      }
+      return { ...local, quotedShares, market: view.market };
+    },
+    staleTime: 5_000,
+  });
+}
+
 export interface VerifiedTrace {
   onChainTraceId: string;
   marketId: string;
@@ -209,12 +365,14 @@ function useInvalidateAfterTrade() {
   };
 }
 
-export interface BuyParams {
+export type BuyParams = {
   marketId: bigint | string;
   outcome: OutcomeTag;
-  collateralIn: bigint;
   slippageBps: number;
-}
+} & (
+  | { collateralIn: bigint; mode?: "usdc" }
+  | { mode: "shares"; targetShares: bigint; maxCollateralIn?: bigint }
+);
 
 /**
  * Re-quotes right before building the transaction and sets
@@ -224,69 +382,228 @@ export interface BuyParams {
 export function useBuy() {
   const guard = useWriteGuard();
   const invalidate = useInvalidateAfterTrade();
+  useLedgerNow();
   return useMutation({
-    mutationFn: async ({ marketId, outcome, collateralIn, slippageBps }: BuyParams) => {
+    mutationFn: async (params: BuyParams) => {
+      const { marketId, outcome, slippageBps } = params;
       const signer = guard();
-      if (collateralIn <= 0n) throw new UserFacingError({ kind: "contract", message: "Enter an amount greater than zero." });
+      await requireUsdcTrustline(signer.publicKey);
       const id = toId(marketId);
-      const quote = simulated<bigint>(
-        await marketCore().quote_buy({ market_id: id, outcome: Outcomes[outcome], collateral_in: collateralIn }),
-      );
-      const minSharesOut = minOut(quote, slippageBps);
-      const tx = await marketCore(signer).buy({
+      let collateralIn: bigint;
+      let quote: bigint;
+      let targetShares: bigint | undefined;
+      let market: OnChainMarket;
+
+      if (params.mode === "shares") {
+        if (params.targetShares <= 0n) throw new UserFacingError({ kind: "contract", message: "Enter a share amount greater than zero." });
+        targetShares = params.targetShares;
+        let solved = false;
+        let lastQuote = 0n;
+        market = (await fetchOnChainMarket(id)).market;
+        for (let attempt = 0; attempt < 2; attempt++) {
+          const exact = minCollateralForShares(market, outcome, targetShares);
+          if (!exact.ok) {
+            const message =
+              exact.reason === "market-too-large"
+                ? "This target exceeds the market's remaining size limit."
+                : exact.reason === "invalid-target"
+                  ? "Enter a share amount greater than zero."
+                  : "The requested share amount is too large.";
+            throw new UserFacingError({ kind: "contract", message });
+          }
+          collateralIn = exact.collateralIn;
+          if (params.maxCollateralIn !== undefined && collateralIn > maxIn(params.maxCollateralIn, slippageBps)) {
+            throw new UserFacingError({
+              kind: "contract",
+              message: "The cost moved beyond your slippage limit. Review the new quote before buying.",
+            });
+          }
+          lastQuote = simulated<bigint>(
+            await marketCore().quote_buy({ market_id: id, outcome: Outcomes[outcome], collateral_in: collateralIn }),
+          );
+          if (lastQuote >= targetShares) {
+            solved = true;
+            break;
+          }
+          if (attempt === 0) market = (await fetchOnChainMarket(id)).market;
+        }
+        if (!solved) throw new UserFacingError({ kind: "contract", message: "The price moved; review the new cost and try again." });
+        quote = lastQuote;
+      } else {
+        collateralIn = params.collateralIn;
+        if (collateralIn <= 0n) throw new UserFacingError({ kind: "contract", message: "Enter an amount greater than zero." });
+        market = (await fetchOnChainMarket(id)).market;
+        quote = simulated<bigint>(
+          await marketCore().quote_buy({ market_id: id, outcome: Outcomes[outcome], collateral_in: collateralIn }),
+        );
+      }
+
+      const deadline = writeDeadline("buy", market);
+      const minSharesOut = minOut(targetShares ?? quote, slippageBps);
+      const tx = await marketCore(signerUntil(signer, deadline)).buy({
         trader: signer.publicKey,
         market_id: id,
         outcome: Outcomes[outcome],
         collateral_in: collateralIn,
         min_shares_out: minSharesOut,
-      });
+      }, { timeoutInSeconds: deadline.timeoutInSeconds });
       const { value, txHash } = await send<bigint>(tx);
-      return { sharesOut: value, quotedShares: quote, minSharesOut, txHash, holder: signer.publicKey };
+      return { sharesOut: value, quotedShares: quote, minSharesOut, targetShares, collateralIn, txHash, holder: signer.publicKey };
     },
     onSuccess: (d, v) => invalidate(String(v.marketId), d.holder),
   });
 }
 
-export interface SellParams {
+export type SellParams = {
   marketId: bigint | string;
   outcome: OutcomeTag;
-  /** Exact number of shares to sell. */
-  shares: bigint;
   slippageBps: number;
-}
+} & (
+  | { mode: "all"; shares?: never }
+  | { mode?: "exact-shares"; shares: bigint }
+);
 
 /**
- * `sell` takes an exact collateral_out, not a share count. Per the contracts
- * repo's frontend-integration.md: read fresh reserves, compute
- * collateral_out for the share count with the contract's FPMM math, and cap
- * max_shares_in a little above the target.
+ * `sell` takes collateral_out rather than shares. The local solver searches
+ * using the contract's exact ceiling-rounded math; quote_sell confirms the
+ * required shares before submission. The slippage bound is capped at the
+ * wallet's held position, so "sell all" can never authorize spending shares
+ * the account does not own.
  */
 export function useSell() {
   const guard = useWriteGuard();
   const invalidate = useInvalidateAfterTrade();
+  useLedgerNow();
   return useMutation({
-    mutationFn: async ({ marketId, outcome, shares, slippageBps }: SellParams) => {
+    mutationFn: async ({ marketId, outcome, slippageBps, ...params }: SellParams) => {
       const signer = guard();
+      await requireUsdcTrustline(signer.publicKey);
       const id = toId(marketId);
-      const { market } = await fetchOnChainMarket(id);
+      let { market } = await fetchOnChainMarket(id);
+      const position = simulated<Position>(
+        await marketCore().get_position({ market_id: id, holder: signer.publicKey }),
+      );
+      const heldShares = outcome === "Yes" ? position.yes : position.no;
+      const shares = params.mode === "all" ? heldShares : params.shares;
+      if (shares <= 0n) {
+        throw new UserFacingError({ kind: "contract", code: "InvalidAmount", message: "Enter a share amount greater than zero." });
+      }
+      if (shares > heldShares) {
+        throw new UserFacingError({ kind: "contract", code: "InsufficientShares", message: "You don't have enough shares for this sale." });
+      }
       const [rSold, rOther] = outcome === "Yes" ? [market.reserve_yes, market.reserve_no] : [market.reserve_no, market.reserve_yes];
-      let collateralOut: bigint;
-      try {
-        collateralOut = collateralOutForShares(rSold, rOther, shares, BigInt(market.fee_bps));
-      } catch {
-        throw new UserFacingError({ kind: "contract", message: "There isn't enough liquidity to sell that many shares." });
+      const feeBps = BigInt(market.fee_bps);
+      let local = solveSellForShares(rSold, rOther, shares, feeBps);
+      if ("error" in local) {
+        throw new UserFacingError({
+          kind: "contract",
+          code: local.error === "too-small" ? "InvalidAmount" : "InsufficientLiquidity",
+          message: local.error === "too-small"
+            ? "That's too few shares to sell after fees."
+            : "There isn't enough liquidity to sell that many shares.",
+        });
+      }
+
+      const quoteAt = async (collateralOut: bigint) =>
+        simulated<bigint>(
+          await marketCore().quote_sell({ market_id: id, outcome: Outcomes[outcome], collateral_out: collateralOut }),
+        );
+      let confirmed = await reconcileWithQuote(local, quoteAt);
+      if (confirmed.sharesIn !== local.sharesIn) {
+        market = (await fetchOnChainMarket(id)).market;
+        const [freshSold, freshOther] =
+          outcome === "Yes" ? [market.reserve_yes, market.reserve_no] : [market.reserve_no, market.reserve_yes];
+        const refreshed = solveSellForShares(freshSold, freshOther, shares, BigInt(market.fee_bps));
+        if ("error" in refreshed) {
+          throw new UserFacingError({
+            kind: "contract",
+            code: refreshed.error === "too-small" ? "InvalidAmount" : "InsufficientLiquidity",
+            message: refreshed.error === "too-small"
+              ? "That's too few shares to sell after fees."
+              : "There isn't enough liquidity to sell that many shares.",
+          });
+        }
+        local = refreshed;
+        confirmed = await reconcileWithQuote(local, quoteAt);
+        if (confirmed.sharesIn !== local.sharesIn) {
+          const maxOut = ((freshOther - 1n) * (BPS - BigInt(market.fee_bps))) / BPS;
+          let low = 0n;
+          let high = maxOut + 1n;
+          let lowQuote = 0n;
+          let probes = 0;
+          let pivot = confirmed.collateralOut;
+          let pivotQuote = confirmed.sharesIn;
+          if (pivotQuote <= shares) {
+            low = pivot;
+            lowQuote = pivotQuote;
+          } else {
+            high = pivot;
+          }
+
+          let step = 1n;
+          while ((low === 0n || high === maxOut + 1n) && probes < 4) {
+            probes++;
+            if (low === 0n) {
+              pivot = high > maxOut ? maxOut : high;
+              const candidate = pivot > step ? pivot - step : 1n;
+              pivotQuote = await quoteAt(candidate);
+              if (pivotQuote <= shares) {
+                low = candidate;
+                lowQuote = pivotQuote;
+              } else high = candidate;
+            } else {
+              const candidate = low + step;
+              if (candidate > maxOut) break;
+              pivotQuote = await quoteAt(candidate);
+              if (pivotQuote > shares) high = candidate;
+              else {
+                low = candidate;
+                lowQuote = pivotQuote;
+              }
+            }
+            step *= 2n;
+          }
+          while (high - low > 1n && probes < 8) {
+            probes++;
+            const mid = (low + high) / 2n;
+            const midQuote = await quoteAt(mid);
+            if (midQuote <= shares) {
+              low = mid;
+              lowQuote = midQuote;
+            } else high = mid;
+          }
+          if (low === 0n || high - low > 1n) {
+            throw new UserFacingError({
+              kind: "network",
+              message: "The market changed while preparing your sale. Refresh the quote and try again.",
+            });
+          }
+          confirmed = { collateralOut: low, sharesIn: lowQuote, dust: shares - lowQuote, iterations: probes };
+        }
+      }
+
+      if (confirmed.sharesIn > shares) {
+        throw new UserFacingError({ kind: "contract", code: "InsufficientShares", message: "You don't have enough shares for this sale." });
       }
-      // +1 covers the off-chain estimate's rounding; slippage covers price moves.
-      const maxSharesIn = maxIn(shares, slippageBps) + 1n;
-      const tx = await marketCore(signer).sell({
+      const deadline = writeDeadline("sell", market);
+      const maxSharesIn = [maxIn(confirmed.sharesIn, slippageBps), heldShares].reduce((a, b) => a < b ? a : b);
+      const tx = await marketCore(signerUntil(signer, deadline)).sell({
         trader: signer.publicKey,
         market_id: id,
         outcome: Outcomes[outcome],
-        collateral_out: collateralOut,
+        collateral_out: confirmed.collateralOut,
         max_shares_in: maxSharesIn,
-      });
+      }, { timeoutInSeconds: deadline.timeoutInSeconds });
       const { value, txHash } = await send<bigint>(tx);
-      return { sharesSold: value, collateralOut, maxSharesIn, txHash, holder: signer.publicKey };
+      return {
+        sharesSold: value,
+        sharesQuoted: confirmed.sharesIn,
+        dust: confirmed.dust,
+        collateralOut: confirmed.collateralOut,
+        maxSharesIn,
+        txHash,
+        holder: signer.publicKey,
+      };
     },
     onSuccess: (d, v) => invalidate(String(v.marketId), d.holder),
   });
@@ -295,10 +612,16 @@ export function useSell() {
 export function useRedeem() {
   const guard = useWriteGuard();
   const invalidate = useInvalidateAfterTrade();
+  useLedgerNow();
   return useMutation({
     mutationFn: async ({ marketId }: { marketId: bigint | string }) => {
       const signer = guard();
-      const tx = await marketCore(signer).redeem({ holder: signer.publicKey, market_id: toId(marketId) });
+      await requireUsdcTrustline(signer.publicKey);
+      const deadline = writeDeadline("redeem");
+      const tx = await marketCore(signerUntil(signer, deadline)).redeem(
+        { holder: signer.publicKey, market_id: toId(marketId) },
+        { timeoutInSeconds: deadline.timeoutInSeconds },
+      );
       const { value, txHash } = await send<bigint>(tx);
       return { payout: value, txHash, holder: signer.publicKey };
     },
@@ -310,11 +633,16 @@ export function useRedeem() {
 export function useUsdcTransfer() {
   const guard = useWriteGuard();
   const queryClient = useQueryClient();
+  useLedgerNow();
   return useMutation({
     mutationFn: async ({ to, amount }: { to: string; amount: bigint }) => {
       const signer = guard();
       if (amount <= 0n) throw new UserFacingError({ kind: "contract", message: "Enter an amount greater than zero." });
-      const tx = await token.transfer({ from: signer.publicKey, to, amount }, signer);
+      await requireUsdcTrustline(signer.publicKey);
+      const deadline = writeDeadline("transfer");
+      const tx = await token.transfer({ from: signer.publicKey, to, amount }, signerUntil(signer, deadline), undefined, {
+        timeoutInSeconds: deadline.timeoutInSeconds,
+      });
       const { txHash } = await send<null>(tx);
       if (!txHash) throw new UserFacingError({ kind: "unknown", message: "The payment was sent but no transaction hash came back." });
       return { txHash, holder: signer.publicKey };
diff --git a/lib/stellar/__tests__/deadline.test.ts b/lib/stellar/__tests__/deadline.test.ts
new file mode 100644
index 0000000..f51615f
--- /dev/null
+++ b/lib/stellar/__tests__/deadline.test.ts
@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import { assertSigningDeadline, deadlineFor } from "../deadline";
+
+describe("deadlineFor", () => {
+  it("uses the default timeout when a market is not near closing", () => {
+    expect(deadlineFor("buy", 1_000, 2_000n)).toEqual({ timeoutInSeconds: 60, maxTime: 1_060 });
+  });
+
+  it("shrinks trade validity to the safe market-close boundary", () => {
+    expect(deadlineFor("sell", 1_000, 1_050n)).toEqual({ timeoutInSeconds: 40, maxTime: 1_040 });
+  });
+
+  it("refuses trades when fewer than the minimum safe seconds remain", () => {
+    expect(() => deadlineFor("buy", 1_000, 1_024n)).toThrow(/under 25 seconds/i);
+  });
+
+  it("sets an explicit timeout on redeem and transfer without a market deadline", () => {
+    expect(deadlineFor("redeem", 1_000)).toEqual({ timeoutInSeconds: 60, maxTime: 1_060 });
+    expect(deadlineFor("transfer", 1_000, 1_001n)).toEqual({ timeoutInSeconds: 60, maxTime: 1_060 });
+  });
+
+  it("rejects a wallet response that arrives too close to expiry", () => {
+    const deadline = deadlineFor("buy", 1_000, 1_200n);
+    expect(() => assertSigningDeadline(deadline, deadline.maxTime - 5)).toThrow(/signing took too long/i);
+  });
+});
diff --git a/lib/stellar/__tests__/ledger-clock.test.ts b/lib/stellar/__tests__/ledger-clock.test.ts
new file mode 100644
index 0000000..273823f
--- /dev/null
+++ b/lib/stellar/__tests__/ledger-clock.test.ts
@@ -0,0 +1,33 @@
+import { describe, expect, it, vi } from "vitest";
+import { LedgerClock } from "../ledger-clock";
+
+describe("LedgerClock", () => {
+  it("estimates from monotonic elapsed time, not wall-clock time", async () => {
+    vi.useFakeTimers();
+    let monotonic = 10;
+    vi.spyOn(performance, "now").mockImplementation(() => monotonic);
+    const clock = new LedgerClock(async () => ({ sequence: 1, closeTime: 100 }));
+    const stop = clock.subscribe(() => undefined);
+    await Promise.resolve();
+    expect(clock.now()).toBe(100);
+    vi.setSystemTime(new Date("2030-01-01T00:00:00Z"));
+    monotonic += 2_500;
+    expect(clock.now()).toBe(102.5);
+    stop();
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it("returns null before a sample and ignores backwards samples", async () => {
+    let sample = { sequence: 10, closeTime: 100 };
+    const clock = new LedgerClock(async () => sample);
+    expect(clock.now()).toBeNull();
+    const stop = clock.subscribe(() => undefined);
+    await Promise.resolve();
+    expect(clock.now()).toBe(100);
+    sample = { sequence: 9, closeTime: 99 };
+    await (clock as unknown as { sample(): Promise<void> }).sample();
+    expect(clock.now()).toBe(100);
+    stop();
+  });
+});
diff --git a/lib/stellar/__tests__/quote.test.ts b/lib/stellar/__tests__/quote.test.ts
new file mode 100644
index 0000000..5185693
--- /dev/null
+++ b/lib/stellar/__tests__/quote.test.ts
@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import type { Market } from "../generated/market-core";
+import { calcBuy, MAX_SETS } from "../generated/fpmm";
+import { minCollateralForShares } from "../quote";
+
+const market = (yes: bigint, no: bigint, fee = 0n, sets = 100_000n) =>
+  ({
+    reserve_yes: yes,
+    reserve_no: no,
+    fee_bps: fee,
+    sets_minted: sets,
+  }) as Market;
+
+describe("minCollateralForShares", () => {
+  it("finds the minimum collateral for a target in the reference pool", () => {
+    const result = minCollateralForShares(market(1_000n, 1_000n), "Yes", 190n);
+    expect(result).toMatchObject({ ok: true, collateralIn: 100n });
+    if (result.ok) {
+      expect(calcBuy(1_000n, 1_000n, result.collateralIn, 0n).sharesOut).toBeGreaterThanOrEqual(190n);
+      expect(calcBuy(1_000n, 1_000n, result.collateralIn - 1n, 0n).sharesOut).toBeLessThan(190n);
+    }
+  });
+
+  it.each([0n, 30n, 100n, 1_000n])("handles fee tier %s and both reserve orientations", (feeBps) => {
+    for (const outcome of ["Yes", "No"] as const) {
+      const result = minCollateralForShares(market(9_900n, 100n, feeBps), outcome, 100n);
+      if (result.ok) {
+        expect(result.overshoot).toBeGreaterThanOrEqual(0n);
+        const reserves = outcome === "Yes" ? [9_900n, 100n] : [100n, 9_900n];
+        expect(calcBuy(reserves[0], reserves[1], result.collateralIn, feeBps).sharesOut).toBe(result.sharesOut);
+        expect(result.collateralIn === 1n || calcBuy(reserves[0], reserves[1], result.collateralIn - 1n, feeBps).sharesOut < 100n).toBe(true);
+      }
+    }
+  });
+
+  it("rejects invalid, oversized and market-capped targets", () => {
+    expect(minCollateralForShares(market(1_000n, 1_000n), "Yes", 0n)).toEqual({ ok: false, reason: "invalid-target" });
+    expect(minCollateralForShares(market(1_000n, 1_000n), "Yes", MAX_SETS + 1n)).toEqual({ ok: false, reason: "market-too-large" });
+    expect(minCollateralForShares(market(1_000n, 1_000n, 0n, MAX_SETS), "Yes", 1n)).toEqual({ ok: false, reason: "market-too-large" });
+  });
+
+  it("preserves bigint precision and minimality for randomized targets", () => {
+    let seed = 0x1234;
+    const random = (max: number) => {
+      seed = (seed * 1_664_525 + 1_013_904_223) >>> 0;
+      return seed % max;
+    };
+    for (let i = 0; i < 2_000; i++) {
+      const yes = BigInt(random(100_000) + 1);
+      const no = BigInt(random(100_000) + 1);
+      const fee = BigInt([0, 30, 100, 1_000][random(4)]);
+      const result = minCollateralForShares(market(yes, no, fee), random(2) ? "Yes" : "No", BigInt(random(10_000) + 1));
+      if (!result.ok) continue;
+      const [bought, other] = result.collateralIn >= 0n && random(2) ? [yes, no] : [no, yes];
+      expect(result.overshoot).toBeGreaterThanOrEqual(0n);
+      expect(calcBuy(bought, other, result.collateralIn, fee).sharesOut).toBeGreaterThanOrEqual(1n);
+    }
+  });
+});
diff --git a/lib/stellar/__tests__/sell-solver.test.ts b/lib/stellar/__tests__/sell-solver.test.ts
new file mode 100644
index 0000000..c93b2c5
--- /dev/null
+++ b/lib/stellar/__tests__/sell-solver.test.ts
@@ -0,0 +1,77 @@
+import { describe, expect, it } from "vitest";
+import { calcSell } from "../generated/fpmm";
+import { reconcileWithQuote, solveSellForShares } from "../sell-solver";
+
+describe("solveSellForShares", () => {
+  it("returns the maximal collateral output allowed by a share budget", () => {
+    const result = solveSellForShares(1_000n, 1_000n, 375n, 0n);
+    expect("error" in result).toBe(false);
+    if ("error" in result) return;
+    expect(calcSell(1_000n, 1_000n, result.collateralOut, 0n).sharesIn).toBeLessThanOrEqual(375n);
+    expect(calcSell(1_000n, 1_000n, result.collateralOut + 1n, 0n).sharesIn).toBeGreaterThan(375n);
+    expect(result.dust).toBe(375n - result.sharesIn);
+  });
+
+  it("returns zero dust when the reference pool can consume the whole budget", () => {
+    const result = solveSellForShares(1_000n, 1_000n, 999_999n, 0n);
+    expect("error" in result).toBe(false);
+    if (!("error" in result)) expect(result.dust).toBe(0n);
+  });
+
+  it("rejects a budget too small to cover any collateral output", () => {
+    expect(solveSellForShares(1_000n, 1_000n, 1n, 1_000n)).toEqual({ error: "too-small" });
+  });
+
+  it.each([0n, 30n, 100n, 1_000n])("handles fee tier %s bps", (feeBps) => {
+    for (const [rSold, rOther] of [[99n, 9_901n], [9_901n, 99n], [1_000n, 1_000n]] as const) {
+      const result = solveSellForShares(rSold, rOther, 200n, feeBps);
+      if ("error" in result) continue;
+      expect(calcSell(rSold, rOther, result.collateralOut, feeBps).sharesIn).toBe(result.sharesIn);
+      expect(result.iterations).toBeLessThanOrEqual(130);
+    }
+  });
+
+  it("stays exact for bigint positions above the safe integer range", () => {
+    const result = solveSellForShares(10n ** 20n, 10n ** 20n, 10n ** 18n, 30n);
+    expect("error" in result).toBe(false);
+    if (!("error" in result)) expect(calcSell(10n ** 20n, 10n ** 20n, result.collateralOut, 30n).sharesIn).toBe(result.sharesIn);
+  });
+
+  it("keeps sharesIn monotone for a deterministic randomized sample", () => {
+    let seed = 0x51e11;
+    const random = (max: number) => {
+      seed = (seed * 1_664_525 + 1_013_904_223) >>> 0;
+      return seed % max;
+    };
+    for (let i = 0; i < 2_000; i++) {
+      const rSold = BigInt(random(100_000) + 1);
+      const rOther = BigInt(random(100_000) + 2);
+      const fee = BigInt([0, 30, 100, 1_000][random(4)]);
+      let previous = 0n;
+      const maxOut = ((rOther - 1n) * (10_000n - fee)) / 10_000n;
+      const probes = 8;
+      for (let j = 1; j <= probes; j++) {
+        const amount = (maxOut * BigInt(j)) / BigInt(probes);
+        if (amount === 0n) continue;
+        const current = calcSell(rSold, rOther, amount, fee).sharesIn;
+        expect(current).toBeGreaterThanOrEqual(previous);
+        previous = current;
+      }
+      const budget = BigInt(random(1_000_000) + 1);
+      const solution = solveSellForShares(rSold, rOther, budget, fee);
+      if ("error" in solution) continue;
+      expect(calcSell(rSold, rOther, solution.collateralOut, fee).sharesIn).toBeLessThanOrEqual(budget);
+      if (solution.collateralOut < maxOut) {
+        expect(calcSell(rSold, rOther, solution.collateralOut + 1n, fee).sharesIn).toBeGreaterThan(budget);
+      }
+    }
+  });
+
+  it("reconciles its share count with the simulated quote", async () => {
+    const local = solveSellForShares(1_000n, 1_000n, 375n, 0n);
+    expect("error" in local).toBe(false);
+    if ("error" in local) return;
+    const reconciled = await reconcileWithQuote(local, async () => local.sharesIn);
+    expect(reconciled).toEqual(local);
+  });
+});
diff --git a/lib/stellar/clients.ts b/lib/stellar/clients.ts
index a0a9a12..842d88e 100644
--- a/lib/stellar/clients.ts
+++ b/lib/stellar/clients.ts
@@ -1,4 +1,4 @@
-import { Address, nativeToScVal, scValToNative } from "@stellar/stellar-sdk";
+import { Address, nativeToScVal, scValToNative, rpc } from "@stellar/stellar-sdk";
 import { AssembledTransaction } from "@stellar/stellar-sdk/contract";
 import type { ClientOptions, SignTransaction } from "@stellar/stellar-sdk/contract";
 import { Client as MarketCoreClient, type Category, type Outcome } from "./generated/market-core";
@@ -13,6 +13,8 @@ export interface Signer {
   signTransaction: SignTransaction;
 }
 
+export const rpcServer = new rpc.Server(RPC_URL, { allowHttp: RPC_URL.startsWith("http://") });
+
 function options(contractId: string, signer?: Signer): ClientOptions {
   return {
     contractId,
@@ -34,6 +36,14 @@ export const reasoningRegistry = (signer?: Signer) =>
  * bindings; calls are built directly with AssembledTransaction.
  */
 export const token = {
+  name(contractId: string = CONTRACTS.usdc): Promise<AssembledTransaction<string>> {
+    return AssembledTransaction.build<string>({
+      ...options(contractId),
+      method: "name",
+      args: [],
+      parseResultXdr: (v) => String(scValToNative(v)),
+    });
+  },
   balance(owner: string, contractId: string = CONTRACTS.usdc): Promise<AssembledTransaction<bigint>> {
     return AssembledTransaction.build<bigint>({
       ...options(contractId),
@@ -46,9 +56,11 @@ export const token = {
     params: { from: string; to: string; amount: bigint },
     signer: Signer,
     contractId: string = CONTRACTS.usdc,
+    txOptions: { timeoutInSeconds?: number } = {},
   ): Promise<AssembledTransaction<null>> {
     return AssembledTransaction.build<null>({
       ...options(contractId, signer),
+      ...txOptions,
       method: "transfer",
       args: [
         new Address(params.from).toScVal(),
diff --git a/lib/stellar/deadline.ts b/lib/stellar/deadline.ts
new file mode 100644
index 0000000..674e6cb
--- /dev/null
+++ b/lib/stellar/deadline.ts
@@ -0,0 +1,40 @@
+export const DEFAULT_TX_TIMEOUT_S = 60;
+export const SAFETY_MARGIN_S = 10;
+export const MIN_TX_TIMEOUT_S = 15;
+
+export type WriteKind = "buy" | "sell" | "redeem" | "transfer";
+
+export interface TransactionDeadline {
+  timeoutInSeconds: number;
+  maxTime: number;
+}
+
+export function deadlineFor(
+  kind: WriteKind,
+  ledgerNow: number | null,
+  closeTime?: bigint,
+): TransactionDeadline {
+  if (ledgerNow === null || !Number.isFinite(ledgerNow) || ledgerNow < 0) {
+    throw new Error("Stellar ledger time is unavailable.");
+  }
+
+  if ((kind === "buy" || kind === "sell") && closeTime !== undefined) {
+    const now = Math.floor(ledgerNow);
+    const lastSafeSecond = closeTime - BigInt(SAFETY_MARGIN_S);
+    const remaining = lastSafeSecond - BigInt(now);
+    if (remaining < BigInt(MIN_TX_TIMEOUT_S)) {
+      throw new Error("This market closes in under 25 seconds, too soon to safely place a trade.");
+    }
+    const timeoutInSeconds = Math.min(DEFAULT_TX_TIMEOUT_S, Number(remaining));
+    return { timeoutInSeconds, maxTime: now + timeoutInSeconds };
+  }
+
+  const now = Math.floor(ledgerNow);
+  return { timeoutInSeconds: DEFAULT_TX_TIMEOUT_S, maxTime: now + DEFAULT_TX_TIMEOUT_S };
+}
+
+export function assertSigningDeadline(deadline: TransactionDeadline, ledgerNow: number | null): void {
+  if (ledgerNow === null || Math.floor(ledgerNow) >= deadline.maxTime - 5) {
+    throw new Error("Signing took too long; the transaction would expire. Try again.");
+  }
+}
diff --git a/lib/stellar/errors.ts b/lib/stellar/errors.ts
index 8aa78cb..085af48 100644
--- a/lib/stellar/errors.ts
+++ b/lib/stellar/errors.ts
@@ -44,8 +44,9 @@ const FRIENDLY: Record<string, string> = {
 };
 
 export interface DescribedError {
-  kind: "rejected" | "insufficient-balance" | "no-trustline" | "contract" | "wrong-network" | "disconnected" | "network" | "unknown";
+  kind: "rejected" | "insufficient-balance" | "no-trustline" | "low-reserve" | "contract" | "wrong-network" | "disconnected" | "network" | "unknown";
   message: string;
+  action?: "enable-usdc";
   /** Contract error name, e.g. "SlippageExceeded", when known. */
   code?: string;
 }
@@ -81,8 +82,12 @@ export function describeError(err: unknown, contract: ContractName = "marketCore
     return {
       kind: "no-trustline",
       message: "Your account has no USDC trustline. Add the USDC asset in your wallet first.",
+      action: "enable-usdc",
     };
   }
+  if (/op_low_reserve|opLowReserve|txInsufficientBalance|tx_insufficient_balance/i.test(text)) {
+    return { kind: "low-reserve", message: "Your account needs more spendable XLM to add the USDC trustline." };
+  }
   if (/balance is not sufficient|resulting balance is not within the allowed range|insufficient (balance|funds)|BalanceError|op_underfunded/i.test(text)) {
     return { kind: "insufficient-balance", message: "You don't have enough USDC for this." };
   }
diff --git a/lib/stellar/ledger-clock.ts b/lib/stellar/ledger-clock.ts
new file mode 100644
index 0000000..624dbbe
--- /dev/null
+++ b/lib/stellar/ledger-clock.ts
@@ -0,0 +1,127 @@
+import { useSyncExternalStore } from "react";
+import { rpcServer } from "./clients";
+
+export interface LedgerSample {
+  sequence: number;
+  closeTime: number;
+  observedAt: number;
+}
+
+interface LedgerPoint {
+  sequence: number;
+  closeTime: number;
+}
+
+export async function fetchLatestLedger(): Promise<LedgerPoint> {
+  const latest = await rpcServer.getLatestLedger();
+  const closeTime = Number(latest.closeTime);
+  if (!Number.isSafeInteger(latest.sequence) || !Number.isFinite(closeTime) || closeTime < 0) {
+    throw new Error("The Stellar RPC returned an invalid ledger clock sample.");
+  }
+  return { sequence: latest.sequence, closeTime };
+}
+
+export class LedgerClock {
+  private samples: LedgerSample[] = [];
+  private listeners = new Set<() => void>();
+  private pollTimer: ReturnType<typeof setInterval> | null = null;
+  private tickTimer: ReturnType<typeof setInterval> | null = null;
+  private versionValue = 0;
+
+  constructor(
+    private readonly fetchLatest: () => Promise<LedgerPoint>,
+    private readonly opts: { pollMs?: number; avgCloseSeconds?: number } = {},
+  ) {}
+
+  get version() {
+    return this.versionValue;
+  }
+
+  now(): number | null {
+    const sample = this.samples.at(-1);
+    if (!sample) return null;
+    const elapsed = (performance.now() - sample.observedAt) / 1000;
+    if (elapsed < 0.01) return sample.closeTime;
+    if (elapsed > (this.opts.pollMs ?? 10_000) / 500) return null;
+    const growthCap = this.averageCloseSeconds() * 2;
+    return sample.closeTime + Math.min(Math.max(0, elapsed), growthCap);
+  }
+
+  uncertainty(): number {
+    return this.samples.length < 2 ? this.averageCloseSeconds() : this.averageCloseSeconds() / 2;
+  }
+
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+    if (this.listeners.size === 1) this.start();
+    return () => {
+      this.listeners.delete(listener);
+      if (this.listeners.size === 0) this.stop();
+    };
+  };
+
+  start(): void {
+    if (this.pollTimer) return;
+    void this.sample();
+    this.pollTimer = setInterval(() => {
+      if (typeof document === "undefined" || document.visibilityState === "visible") void this.sample();
+    }, this.opts.pollMs ?? 10_000);
+    this.tickTimer = setInterval(() => this.notify(), 1_000);
+    if (typeof document !== "undefined") document.addEventListener("visibilitychange", this.onVisibilityChange);
+  }
+
+  stop(): void {
+    if (this.pollTimer) clearInterval(this.pollTimer);
+    if (this.tickTimer) clearInterval(this.tickTimer);
+    this.pollTimer = null;
+    this.tickTimer = null;
+    if (typeof document !== "undefined") document.removeEventListener("visibilitychange", this.onVisibilityChange);
+  }
+
+  private onVisibilityChange = () => {
+    if (typeof document === "undefined" || document.visibilityState !== "visible") return;
+    this.samples = [];
+    this.notify();
+    void this.sample();
+  };
+
+  private async sample(): Promise<void> {
+    try {
+      const next = await this.fetchLatest();
+      const previous = this.samples.at(-1);
+      if (previous && (next.sequence < previous.sequence || next.closeTime < previous.closeTime)) return;
+      if (previous && next.sequence === previous.sequence) return;
+      this.samples.push({ ...next, observedAt: performance.now() });
+      this.samples = this.samples.slice(-10);
+      this.notify();
+    } catch {
+      // An unavailable RPC must not be replaced with the machine's wall clock.
+      this.notify();
+    }
+  }
+
+  private averageCloseSeconds(): number {
+    if (this.samples.length < 2) return this.opts.avgCloseSeconds ?? 5.5;
+    let elapsed = 0;
+    let ledgers = 0;
+    for (let i = 1; i < this.samples.length; i++) {
+      const before = this.samples[i - 1];
+      const after = this.samples[i];
+      elapsed += after.closeTime - before.closeTime;
+      ledgers += after.sequence - before.sequence;
+    }
+    return ledgers > 0 ? elapsed / ledgers : this.opts.avgCloseSeconds ?? 5.5;
+  }
+
+  private notify(): void {
+    this.versionValue++;
+    this.listeners.forEach((listener) => listener());
+  }
+}
+
+const ledgerClock = new LedgerClock(fetchLatestLedger);
+
+export function useLedgerNow(): { now: number | null; uncertainty: number } {
+  useSyncExternalStore(ledgerClock.subscribe, () => ledgerClock.version, () => 0);
+  return { now: ledgerClock.now(), uncertainty: ledgerClock.uncertainty() };
+}
diff --git a/lib/stellar/quote.ts b/lib/stellar/quote.ts
new file mode 100644
index 0000000..0f339ba
--- /dev/null
+++ b/lib/stellar/quote.ts
@@ -0,0 +1,68 @@
+import type { Market } from "./generated/market-core";
+import { BPS, calcBuy, MAX_SETS, MathError } from "./generated/fpmm";
+import type { OutcomeTag } from "./clients";
+
+export type ExactBuy =
+  | { ok: true; collateralIn: bigint; sharesOut: bigint; overshoot: bigint; fee: bigint; net: bigint }
+  | { ok: false; reason: "invalid-target" | "market-too-large" | "overflow" };
+
+/**
+ * calcBuy's output is monotone: fee and net never decrease as collateralIn
+ * grows; newReserveOther grows with net, so the ceiling-rounded new bought
+ * reserve cannot increase. Thus net + reserveBought - newReserveBought cannot
+ * decrease.
+ */
+export function minCollateralForShares(
+  market: Pick<Market, "reserve_yes" | "reserve_no" | "fee_bps" | "sets_minted">,
+  outcome: OutcomeTag,
+  targetShares: bigint,
+): ExactBuy {
+  if (targetShares <= 0n) return { ok: false, reason: "invalid-target" };
+  if (targetShares > MAX_SETS) return { ok: false, reason: "market-too-large" };
+
+  const [rBought, rOther] =
+    outcome === "Yes" ? [market.reserve_yes, market.reserve_no] : [market.reserve_no, market.reserve_yes];
+  const feeBps = BigInt(market.fee_bps);
+  const headroom = MAX_SETS - market.sets_minted;
+  if (rBought <= 0n || rOther <= 0n || feeBps < 0n || feeBps >= BPS || headroom <= 0n) {
+    return { ok: false, reason: "market-too-large" };
+  }
+
+  const maxCollateralIn = (headroom * BPS) / (BPS - feeBps);
+  if (maxCollateralIn <= 0n) return { ok: false, reason: "market-too-large" };
+
+  const sharesAt = (amount: bigint) => {
+    try {
+      return calcBuy(rBought, rOther, amount, feeBps).sharesOut;
+    } catch (error) {
+      if (error instanceof MathError) return 0n;
+      throw error;
+    }
+  };
+
+  if (sharesAt(maxCollateralIn) < targetShares) return { ok: false, reason: "market-too-large" };
+
+  let low = 0n;
+  let high = maxCollateralIn;
+  while (high - low > 1n) {
+    const mid = (low + high) / 2n;
+    if (sharesAt(mid) >= targetShares) high = mid;
+    else low = mid;
+  }
+
+  try {
+    const quote = calcBuy(rBought, rOther, high, feeBps);
+    if (market.sets_minted + quote.net > MAX_SETS) return { ok: false, reason: "market-too-large" };
+    return {
+      ok: true,
+      collateralIn: high,
+      sharesOut: quote.sharesOut,
+      overshoot: quote.sharesOut - targetShares,
+      fee: quote.fee,
+      net: quote.net,
+    };
+  } catch (error) {
+    if (error instanceof MathError) return { ok: false, reason: "overflow" };
+    throw error;
+  }
+}
diff --git a/lib/stellar/sell-solver.ts b/lib/stellar/sell-solver.ts
new file mode 100644
index 0000000..4562c37
--- /dev/null
+++ b/lib/stellar/sell-solver.ts
@@ -0,0 +1,68 @@
+import { BPS, calcSell, MathError } from "./generated/fpmm";
+
+export interface SellSolution {
+  collateralOut: bigint;
+  sharesIn: bigint;
+  dust: bigint;
+  iterations: number;
+}
+
+export type SellSolveError = { error: "insufficient-liquidity" | "too-small" };
+
+/**
+ * calcSell's sharesIn is monotone: gross is non-decreasing in collateralOut;
+ * as gross grows, rOther - gross shrinks and ceil(rSold*rOther/(rOther-gross))
+ * cannot decrease. Their sum with gross therefore cannot decrease.
+ */
+export function solveSellForShares(
+  rSold: bigint,
+  rOther: bigint,
+  shareBudget: bigint,
+  feeBps: bigint,
+): SellSolution | SellSolveError {
+  if (rSold <= 0n || rOther <= 0n || feeBps < 0n || feeBps >= BPS) {
+    return { error: "insufficient-liquidity" };
+  }
+  if (shareBudget <= 0n) return { error: "too-small" };
+
+  // For calcSell to remain liquid, gross must be at most rOther - 1.
+  const maxCollateralOut = ((rOther - 1n) * (BPS - feeBps)) / BPS;
+  if (maxCollateralOut <= 0n) return { error: "insufficient-liquidity" };
+
+  let low = 0n;
+  let high = maxCollateralOut + 1n;
+  let iterations = 0;
+
+  while (high - low > 1n) {
+    const mid = (low + high) / 2n;
+    iterations++;
+    try {
+      if (calcSell(rSold, rOther, mid, feeBps).sharesIn <= shareBudget) low = mid;
+      else high = mid;
+    } catch (error) {
+      if (!(error instanceof MathError)) throw error;
+      high = mid;
+    }
+  }
+
+  if (low === 0n) return { error: "too-small" };
+  const sharesIn = calcSell(rSold, rOther, low, feeBps).sharesIn;
+  return { collateralOut: low, sharesIn, dust: shareBudget - sharesIn, iterations };
+}
+
+/**
+ * Confirm the local math against quote_sell. A caller can refetch reserves
+ * and re-solve when the quoted share count differs.
+ */
+export async function reconcileWithQuote(
+  local: SellSolution,
+  quote: (collateralOut: bigint) => Promise<bigint>,
+): Promise<SellSolution> {
+  const sharesIn = await quote(local.collateralOut);
+  if (sharesIn === local.sharesIn) return local;
+  return {
+    ...local,
+    sharesIn,
+    dust: local.dust + local.sharesIn - sharesIn,
+  };
+}
diff --git a/lib/stellar/trustline.ts b/lib/stellar/trustline.ts
new file mode 100644
index 0000000..27c78dd
--- /dev/null
+++ b/lib/stellar/trustline.ts
@@ -0,0 +1,165 @@
+import {
+  Address,
+  Asset,
+  BASE_FEE,
+  Operation,
+  TransactionBuilder,
+  xdr,
+} from "@stellar/stellar-sdk";
+import { rpcServer, token } from "./clients";
+import { CONTRACTS, NETWORK_PASSPHRASE } from "./config";
+import type { Signer } from "./clients";
+import { describeError, UserFacingError } from "./errors";
+
+export type TrustlineState =
+  | { kind: "native" }
+  | { kind: "present"; authorized: boolean; balance: bigint; limit: bigint }
+  | { kind: "missing" }
+  | { kind: "account-missing" };
+
+const assetNameCache = new Map<string, Promise<Asset>>();
+
+export function usdcClassicAsset(): Promise<Asset> {
+  let pending = assetNameCache.get(CONTRACTS.usdc);
+  if (!pending) {
+    pending = (async () => {
+      const transaction = await token.name(CONTRACTS.usdc);
+      const result: unknown = transaction.result;
+      const name =
+        result && typeof result === "object" && "isOk" in result &&
+        typeof (result as { isOk: unknown }).isOk === "function"
+          ? (result as { isOk(): boolean; unwrap(): string }).unwrap()
+          : (result as string);
+      if (name === "native") return Asset.native();
+      const separator = name.lastIndexOf(":");
+      if (separator <= 0 || separator === name.length - 1) {
+        throw new Error(`Unexpected SAC asset name: ${name}`);
+      }
+      const asset = new Asset(name.slice(0, separator), name.slice(separator + 1));
+      if (asset.contractId(NETWORK_PASSPHRASE) !== CONTRACTS.usdc) {
+        throw new Error("The configured USDC contract does not match the asset it wraps.");
+      }
+      return asset;
+    })();
+    assetNameCache.set(CONTRACTS.usdc, pending);
+  }
+  return pending;
+}
+
+export async function getTrustlineState(account: string, asset: Asset): Promise<TrustlineState> {
+  if (asset.isNative()) return { kind: "native" };
+
+  const address = new Address(account).toScAddress();
+  const keys = [
+    xdr.LedgerKey.account(new xdr.LedgerKeyAccount({ accountId: address })),
+    xdr.LedgerKey.trustLine(
+      new xdr.LedgerKeyTrustLine({ accountId: address, asset: asset.toTrustLineXDRObject() }),
+    ),
+  ];
+  const { entries } = await rpcServer.getLedgerEntries(...keys);
+  const accountEntry = entries.find((entry) => entry.key.switch().name === "account");
+  if (!accountEntry) return { kind: "account-missing" };
+  const trustlineEntry = entries.find((entry) => entry.key.switch().name === "trustline");
+  if (!trustlineEntry) return { kind: "missing" };
+
+  const trustline = trustlineEntry.val.trustLine();
+  const authorized = (trustline.flags() & xdr.TrustLineFlags.authorizedFlag().value) !== 0;
+  return {
+    kind: "present",
+    authorized,
+    balance: BigInt(trustline.balance().toString()),
+    limit: BigInt(trustline.limit().toString()),
+  };
+}
+
+function accountExtensionV1(account: xdr.AccountEntry) {
+  const ext = account.ext();
+  return ext.switch() === 1 ? ext.v1() : null;
+}
+
+export async function reserveCheck(
+  address: string,
+): Promise<{ ok: boolean; spendable: bigint; required: bigint }> {
+  const account = await rpcServer.getAccountEntry(address);
+  const v1 = accountExtensionV1(account);
+  const v2 = v1?.ext().switch() === 2 ? v1.ext().v2() : null;
+  const numSponsoring = BigInt(v2?.numSponsoring() ?? 0);
+  const numSponsored = BigInt(v2?.numSponsored() ?? 0);
+  let baseReserve = 5_000_000n;
+  try {
+    const latest = await rpcServer.getLatestLedger();
+    baseReserve = BigInt(latest.headerXdr.baseReserve());
+  } catch {
+    // Older RPC endpoints may not return ledger headers; Stellar's base reserve is 0.5 XLM.
+  }
+  const minimumBalance =
+    (2n + BigInt(account.numSubEntries()) + numSponsoring - numSponsored) * baseReserve;
+  const sellingLiabilities = BigInt(v1?.liabilities().selling().toString() ?? "0");
+  const spendable = BigInt(account.balance().toString()) - minimumBalance - sellingLiabilities;
+  const required = baseReserve + BigInt(BASE_FEE);
+  return { ok: spendable >= required, spendable, required };
+}
+
+export async function buildChangeTrustXdr(address: string, asset: Asset): Promise<string> {
+  const [account, feeStats] = await Promise.all([rpcServer.getAccount(address), rpcServer.getFeeStats()]);
+  const recommended = BigInt(feeStats.inclusionFee.p70 || BASE_FEE);
+  const fee = recommended > 10_000n ? 10_000n : recommended > BigInt(BASE_FEE) ? recommended : BigInt(BASE_FEE);
+  return new TransactionBuilder(account, {
+    fee: fee.toString(),
+    networkPassphrase: NETWORK_PASSPHRASE,
+  })
+    .addOperation(Operation.changeTrust({ asset }))
+    .setTimeout(120)
+    .build()
+    .toXDR();
+}
+
+const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export async function submitAndPoll(
+  signedXdr: string,
+  opts: { timeoutMs?: number } = {},
+): Promise<{ hash: string }> {
+  const tx = TransactionBuilder.fromXDR(signedXdr, NETWORK_PASSPHRASE);
+  let response = await rpcServer.sendTransaction(tx);
+  if (response.status === "TRY_AGAIN_LATER") {
+    await wait(2_000);
+    response = await rpcServer.sendTransaction(tx);
+  }
+  if (response.status === "ERROR") {
+    const described = describeError(response.errorResultXdr ?? "Transaction submission failed");
+    throw new UserFacingError(described, response.errorResultXdr);
+  }
+  if (response.status !== "PENDING" && response.status !== "DUPLICATE") {
+    throw new Error(`Unexpected transaction submission status: ${response.status}`);
+  }
+
+  const deadline = Date.now() + (opts.timeoutMs ?? 60_000);
+  let delay = 500;
+  while (Date.now() < deadline) {
+    await wait(delay);
+    const result = await rpcServer.getTransaction(response.hash);
+    if (result.status === "SUCCESS") return { hash: response.hash };
+    if (result.status === "FAILED") {
+      throw new UserFacingError(describeError(result.resultXdr.toXDR("base64")), result.resultXdr);
+    }
+    delay = Math.min(delay * 2, 4_000);
+  }
+  throw new Error("The trustline transaction is still pending. Check your wallet before retrying.");
+}
+
+export async function enableUsdcTrustline(address: string, asset: Asset, signer: Signer): Promise<{ hash: string }> {
+  const reserve = await reserveCheck(address);
+  if (!reserve.ok) {
+    const neededXlm = reserve.required - reserve.spendable;
+    throw new UserFacingError({
+      kind: "low-reserve",
+      message: `Add at least ${(Number(neededXlm) / 10_000_000).toFixed(2)} XLM to cover the USDC trustline reserve and fee.`,
+    });
+  }
+
+  const unsignedXdr = await buildChangeTrustXdr(address, asset);
+  const signed = await signer.signTransaction(unsignedXdr, { networkPassphrase: NETWORK_PASSPHRASE });
+  if (signed.error) throw new UserFacingError(describeError(signed.error), signed.error);
+  return submitAndPoll(signed.signedTxXdr);
+}