Wrap-ratio UX (chip, explainer, ratio history, denom toggle) + wtSGOV

.planning/codebase/INTEGRATIONS.md

@@ -33,10 +33,10 @@
 - Base URL: env `ST0X_API_URL`
 - Auth: HTTP Basic via `ST0X_API_KEY` + `ST0X_API_SECRET` (`btoa('key:secret')`, server-only)
 - Allowlist of proxied routes (with per-route Vercel edge cache):
-  - `GET v1/orders/token/:address` — `private, no-store` (browser + Vercel CDN; upstream API caches ~15s)
-  - `GET v1/trades/token/:address` — same as orders/token
+  - `GET v1/orders/token/:address` — `s-maxage=5, stale-while-revalidate=120`
+  - `GET v1/trades/token/:address` — `s-maxage=5, stale-while-revalidate=120`
   - `GET v1/orders/owner/:address`, `GET v1/trades/:address`, `GET v1/trades/taker/:address` — no shared cache
-  - `POST v1/trades/batch` — no cache
+  - `POST v1/trades/query` — no cache
   - `GET health`
 - Client wrapper: `src/lib/api/st0xApi.ts` (typed `apiGet*` functions; all gated to browser context)
 

src/lib/api/st0xApi.ts

@@ -145,7 +145,7 @@ export async function apiGetOrdersByToken(
 		pageSize: options?.pageSize,
 		side: options?.side
 	});
-	return fetchJson<ApiOrdersListResponse>(url, { cache: 'no-store' });
+	return fetchJson<ApiOrdersListResponse>(url);
 }
 
 /**
@@ -226,7 +226,6 @@ export async function apiGetTradesByToken(
 	if (startTime !== undefined) params.set('startTime', String(startTime));
 	if (endTime !== undefined) params.set('endTime', String(endTime));
 	return fetchJson<ApiTradesByAddressResponse>(
-		`/api/st0x/v1/trades/token/${tokenAddress}?${params}`,
-		{ cache: 'no-store' }
+		`/api/st0x/v1/trades/token/${tokenAddress}?${params}`
 	);
 }

src/lib/components/TradeAmountInput.svelte

@@ -24,6 +24,20 @@
 	export let compact: boolean = false;
 	export let noBorder: boolean = false;
 
+	// Optional label override — when set, this string is shown as the input's
+	// trailing unit instead of `amountToken.symbol`. Used by the trade panel
+	// to flip wtX ↔ tX when the user toggles share-denominated display on.
+	export let unitOverride: string | undefined = undefined;
+
+	// Display-only scale factor. When > 0 and !== 1, the user types values
+	// in the SCALED denomination (e.g. tSGOV shares) while `amount` remains
+	// in the token's native denomination (wtSGOV wei). Math is:
+	//   amount  = parseUnits(inputString / displayScale, decimals)
+	//   display = formatUnits(amount * displayScale, decimals)
+	// `displayScale` is a float — the wrap ratio is bounded (1.0–~2.0) and
+	// only has ~4 significant digits in practice, so float precision is fine.
+	export let displayScale: number = 1;
+
 	// Expose balance to parent component
 	export let balance: bigint = 0n;
 	export let balanceDecimals: number | null = null;
@@ -69,21 +83,60 @@
 		amount = undefined;
 	};
 
+	function activeScale(): number {
+		return Number.isFinite(displayScale) && displayScale > 0 ? displayScale : 1;
+	}
+
+	// Convert a user-typed string (in the displayed denomination) into a wt-
+	// denominated BigInt at `amountDecimals` precision. When `displayScale`
+	// is 1 (the default) this is just `parseUnits`. When >1, we divide by
+	// the ratio first so the stored BigInt is the on-chain (wt) amount.
+	function parseDisplayInput(input: string, decimals: number): bigint {
+		const scale = activeScale();
+		if (scale === 1) return parseUnits(input, decimals);
+		// `parseFloat` is OK here: the wrap ratio's significant digits (~4) and
+		// typical user inputs (≤ 10^10) stay well within float64 precision.
+		const tValue = parseFloat(input);
+		if (!Number.isFinite(tValue)) throw new Error('invalid input');
+		const wtValue = tValue / scale;
+		// Clamp to the token's decimals so we never exceed parseUnits' digit
+		// budget. toFixed(decimals) gives a fixed-point string with up to
+		// `decimals` fractional digits — safe input for parseUnits.
+		return parseUnits(wtValue.toFixed(decimals), decimals);
+	}
+
+	function formatWtAsDisplay(wt: bigint, decimals: number): string {
+		const scale = activeScale();
+		const native = formatUnits(wt, decimals);
+		if (scale === 1) return native;
+		const tValue = parseFloat(native) * scale;
+		return tValue.toFixed(decimals);
+	}
+
+	// Reference `displayScale` here so Svelte's reactive tracker re-runs this
+	// block when the parent flips the share-denominated toggle after the user
+	// has already typed. Without this the bound `amount` BigInt stays in
+	// whichever denom was active at type-time and the user thinks the
+	// conversion isn't working.
 	$: if (inputAmount && canParseDecimals(amountDecimals)) {
+		// eslint-disable-next-line @typescript-eslint/no-unused-expressions -- justification: bare reference registers displayScale as a Svelte reactive dependency; it is consumed transitively via activeScale() inside parseDisplayInput, which the compiler cannot see.
+		displayScale; // explicit dep — see comment above
 		try {
-			amount = parseUnits(inputAmount, amountDecimals);
+			amount = parseDisplayInput(inputAmount, amountDecimals);
 		} catch {
 			amount = undefined;
 		}
 	} else if (!inputAmount) {
 		amount = undefined;
 	}
 
-	// Expose function to set amount from parent (for percentage buttons)
+	// Expose function to set amount from parent (for percentage buttons).
+	// Parent always speaks wt-denominated BigInts; we render the display
+	// string in whichever denomination is active.
 	export function setAmountValue(newAmount: bigint) {
 		if (!canParseDecimals(amountDecimals)) return;
 		amount = newAmount;
-		inputAmount = formatUnits(newAmount, amountDecimals);
+		inputAmount = formatWtAsDisplay(newAmount, amountDecimals);
 	}
 
 	$: balancePromise = (async () => {
@@ -139,7 +192,7 @@
 		if (!canParseDecimals(amountDecimals)) {
 			return;
 		}
-		inputAmount = formatUnits(balance, amountDecimals);
+		inputAmount = formatWtAsDisplay(balance, amountDecimals);
 		amount = balance;
 	};
 </script>
@@ -149,7 +202,7 @@
 		{...$$restProps}
 		bind:amount={inputAmount}
 		type="number"
-		unit={showUnit ? amountToken.symbol : ''}
+		unit={showUnit ? unitOverride ?? amountToken.symbol : ''}
 		maxButton={showMaxButton}
 		on:setValueToMax={setValueToMax}
 		{dataTestId}
@@ -165,10 +218,11 @@
 				</span>
 			{:then data}
 				{#if data}
-					{@const balanceFormatted = parseFloat(formatUnits(data.balance, data.decimals))}
+					{@const balanceFormatted =
+						parseFloat(formatUnits(data.balance, data.decimals)) * activeScale()}
 					{@const balanceRounded = Math.round(balanceFormatted * 1000) / 1000}
 					Balance: {balanceRounded.toFixed(3)}
-					{(balanceToken ?? amountToken)?.symbol}
+					{unitOverride ?? (balanceToken ?? amountToken)?.symbol}
 				{:else}
 					Balance: —
 				{/if}

src/lib/components/orders/DcaOrder.svelte

@@ -38,6 +38,15 @@
 			: 'bg-red-500 hover:bg-red-600 text-white';
 
 	export let assetToken: PythToken | undefined; // The token we're accumulating
+	/** Share-denominated display toggle — see MarketOrder for the contract. */
+	export let displayDenom: 'wrapped' | 'unwrapped' = 'wrapped';
+	export let wrapRatio: number = 1;
+	$: displayedAssetSymbol =
+		displayDenom === 'unwrapped' && assetToken
+			? assetToken.symbol.replace(/^wt/, 't')
+			: assetToken?.symbol ?? '';
+	$: displayScale =
+		displayDenom === 'unwrapped' && Number.isFinite(wrapRatio) && wrapRatio > 0 ? wrapRatio : 1;
 
 	// Filter tokens based on current network
 	$: ALL_TOKENS = $currentNetwork ? getAllTokensByNetwork($currentNetwork.chainId) : [];
@@ -315,7 +324,7 @@
 				<div class="mb-2 block text-sm font-medium text-gray-300">
 					{orderSide === 'Buy' ? 'Purchase Budget' : 'Amount to Sell'}
 					<span class="ml-1 text-xs text-gray-500"
-						>({orderSide === 'Buy' ? settlementLabel : selectedInputToken.symbol})</span
+						>({orderSide === 'Buy' ? settlementLabel : displayedAssetSymbol})</span
 					>
 				</div>
 				<TradeAmountInput
@@ -329,6 +338,8 @@
 					validate={validateSelectedAmount}
 					bind:isError={selectedAmountError}
 					showMaxButton={false}
+					displayScale={orderSide === 'Buy' ? 1 : displayScale}
+					unitOverride={orderSide === 'Buy' ? settlementLabel : displayedAssetSymbol}
 				/>
 				<!-- Percentage buttons -->
 				<div class="mt-2 flex gap-2">

src/lib/components/orders/LimitOrder.svelte

@@ -65,6 +65,17 @@
 	export let orderSide: 'Buy' | 'Sell' = 'Buy';
 	export let buyPrice: number | null = null; // Best bid price (what you get when selling)
 	export let sellPrice: number | null = null; // Best ask price (what you pay when buying)
+	/** Share-denominated display toggle — see MarketOrder for the contract. */
+	export let displayDenom: 'wrapped' | 'unwrapped' = 'wrapped';
+	export let wrapRatio: number = 1;
+	$: displayedAssetSymbol =
+		displayDenom === 'unwrapped' && assetToken
+			? assetToken.symbol.replace(/^wt/, 't')
+			: assetToken?.symbol ?? '';
+	$: displayScale =
+		displayDenom === 'unwrapped' && Number.isFinite(wrapRatio) && wrapRatio > 0 ? wrapRatio : 1;
+	$: showShareEquivalent = displayDenom === 'unwrapped' && displayScale !== 1;
+	$: wtDecimalsForSummary = showShareEquivalent ? 5 : 3;
 
 	// Filter tokens based on current network
 	$: ALL_TOKENS = $currentNetwork ? getAllTokensByNetwork($currentNetwork.chainId) : [];
@@ -437,6 +448,8 @@
 						bind:isError={selectedAmountError}
 						showUnit={false}
 						showMaxButton={false}
+						{displayScale}
+						unitOverride={displayedAssetSymbol}
 					/>
 					<!-- Percentage buttons -->
 					<div class="mt-2 flex gap-2">
@@ -455,7 +468,7 @@
 					<div class="mb-2 block text-sm font-medium text-gray-300">
 						Limit Price
 						<span class="ml-1 text-xs text-gray-500"
-							>({settlementLabel} per {assetToken.symbol})</span
+							>({settlementLabel} per {displayedAssetSymbol})</span
 						>
 					</div>
 					<Input
@@ -475,14 +488,27 @@
 			<div class={containerStyles.cardBordered}>
 				<h4 class="mb-3 text-sm font-medium text-gray-300">Order Summary</h4>
 				<div class="space-y-2 text-sm">
-					<div class="flex justify-between">
+					<div class="flex items-start justify-between gap-3">
 						<span class="text-gray-400">{orderSide === 'Buy' ? 'Buying' : 'Selling'}</span>
-						<span class="font-medium">
-							{selectedAmount
-								? parseFloat(formatUnits(selectedAmount, assetToken.decimals)).toFixed(3)
-								: '0'}
-							{assetToken.symbol}
-						</span>
+						<div class="text-right">
+							<span class="font-medium">
+								{(selectedAmount
+									? parseFloat(formatUnits(selectedAmount, assetToken.decimals))
+									: 0
+								).toFixed(wtDecimalsForSummary)}
+								{assetToken.symbol}
+							</span>
+							{#if showShareEquivalent}
+								<div class="text-[11px] text-gray-500">
+									equivalent to {(
+										(selectedAmount
+											? parseFloat(formatUnits(selectedAmount, assetToken.decimals))
+											: 0) * displayScale
+									).toFixed(5)}
+									{displayedAssetSymbol}
+								</div>
+							{/if}
+						</div>
 					</div>
 					<div class="flex justify-between">
 						<span class="text-gray-400">At price</span>