From 51170343f701e4e7b9f26be7cb006d755bc44afa Mon Sep 17 00:00:00 2001
From: Khadijah Abdulwasii <abdulwasiikhadijah@gmail.com>
Date: Fri, 25 Sep 2026 16:38:16 +0100
Subject: [PATCH 1/3] feat: Implement allowance approval, emergency contract
 pause, and holding cap warnings (#953, #955, #961)

- #955: Build allowance approval flow for delegating key transfers to staking contract
  - Add useAllowanceStore with session-level caching of approved addresses
  - Add AllowanceApprovalStep UI with clear explanation of permissions
  - Integrate into TradeDialog for staking operations before stake submission
- #953: Show contract paused banner and disable all trade actions when emergency pause is active
  - Add useContractPausedStore with 60s background polling and admin verification
  - Add top-level ContractPausedBanner with animated shimmer
  - Add AdminPauseControl for authorized admin wallets
  - Disable trade actions (buy, sell, stake, transfer) with explanatory tooltips when paused
- #961: Add maximum holding cap warning on buy panel when approaching wallet limit
  - Add useHoldingCapStore with cap tracking and capacity calculations
  - Add HoldingCapWarning with accessible progress bar (role=progressbar)
  - Display approaching-cap warning at >=80% capacity and auto-clamp quantity to remaining limit
  - Display cap reached state and disable buying when at 100% capacity
  - Update holding cap store and UI state upon successful purchase
- Tests: Add 55 comprehensive unit tests across stores and components
---
 src/App.tsx                                   |  23 ++
 src/components/common/AdminPauseControl.tsx   | 118 ++++++
 .../common/AllowanceApprovalStep.tsx          | 133 +++++++
 .../common/ContractPausedBanner.tsx           |  84 ++++
 src/components/common/CreatorCard.tsx         |  21 +-
 src/components/common/HoldingCapWarning.tsx   | 135 +++++++
 src/components/common/TradeDialog.tsx         | 363 ++++++++++++++++--
 .../__tests__/AdminPauseControl.test.tsx      |  60 +++
 .../__tests__/AllowanceApprovalStep.test.tsx  |  77 ++++
 .../__tests__/ContractPausedBanner.test.tsx   |  57 +++
 .../__tests__/HoldingCapWarning.test.tsx      |  69 ++++
 .../__tests__/TradeDialog.features.test.tsx   | 263 +++++++++++++
 src/hooks/__tests__/useAllowanceStore.test.ts |  97 +++++
 .../__tests__/useContractPausedStore.test.ts  |  94 +++++
 .../__tests__/useHoldingCapStore.test.ts      | 123 ++++++
 src/hooks/useAllowanceStore.ts                | 136 +++++++
 src/hooks/useContractPausedStore.ts           | 147 +++++++
 src/hooks/useHoldingCapStore.ts               | 159 ++++++++
 src/pages/LandingPage.tsx                     |  85 +++-
 src/test/setup.ts                             |  12 +
 vitest.config.ts                              |   3 +-
 21 files changed, 2212 insertions(+), 47 deletions(-)
 create mode 100644 src/components/common/AdminPauseControl.tsx
 create mode 100644 src/components/common/AllowanceApprovalStep.tsx
 create mode 100644 src/components/common/ContractPausedBanner.tsx
 create mode 100644 src/components/common/HoldingCapWarning.tsx
 create mode 100644 src/components/common/__tests__/AdminPauseControl.test.tsx
 create mode 100644 src/components/common/__tests__/AllowanceApprovalStep.test.tsx
 create mode 100644 src/components/common/__tests__/ContractPausedBanner.test.tsx
 create mode 100644 src/components/common/__tests__/HoldingCapWarning.test.tsx
 create mode 100644 src/components/common/__tests__/TradeDialog.features.test.tsx
 create mode 100644 src/hooks/__tests__/useAllowanceStore.test.ts
 create mode 100644 src/hooks/__tests__/useContractPausedStore.test.ts
 create mode 100644 src/hooks/__tests__/useHoldingCapStore.test.ts
 create mode 100644 src/hooks/useAllowanceStore.ts
 create mode 100644 src/hooks/useContractPausedStore.ts
 create mode 100644 src/hooks/useHoldingCapStore.ts

diff --git a/src/App.tsx b/src/App.tsx
index 6fe4f09c..571f0b4f 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -1,13 +1,25 @@
+import { useEffect } from 'react';
 import { Toaster } from 'react-hot-toast';
 import { createBrowserRouter, RouterProvider } from 'react-router';
 import MarketingPage from './pages/MarketingPage';
+import LandingPage from './pages/LandingPage';
 import NotFoundPage from './pages/NotFoundPage';
+import ContractPausedBanner from './components/common/ContractPausedBanner';
+import { useContractPausedStore } from './hooks/useContractPausedStore';
 
 const router = createBrowserRouter([
 	{
 		path: '/',
 		element: <MarketingPage />,
 	},
+	{
+		path: '/app',
+		element: <LandingPage />,
+	},
+	{
+		path: '/marketplace',
+		element: <LandingPage />,
+	},
 	{
 		path: '*',
 		element: <NotFoundPage />,
@@ -15,8 +27,19 @@ const router = createBrowserRouter([
 ]);
 
 function App() {
+	// Start polling contract pause state on app load (#953)
+	useEffect(() => {
+		const store = useContractPausedStore.getState();
+		store.startPolling();
+		return () => {
+			store.stopPolling();
+		};
+	}, []);
+
 	return (
 		<>
+			{/* Full-width banner when contract emergency pause is active (#953) */}
+			<ContractPausedBanner />
 			<Toaster
 				toastOptions={{
 					ariaProps: {
diff --git a/src/components/common/AdminPauseControl.tsx b/src/components/common/AdminPauseControl.tsx
new file mode 100644
index 00000000..17500909
--- /dev/null
+++ b/src/components/common/AdminPauseControl.tsx
@@ -0,0 +1,118 @@
+/**
+ * AdminPauseControl (#953)
+ *
+ * Emergency pause / unpause toggle for the Access Layer contract.
+ * Per the spec:
+ *  - Only rendered/visible to authorised admin wallets.
+ *  - Allows toggling the contract pause state.
+ */
+
+import React from 'react';
+import { useAccount } from 'wagmi';
+import { Shield, ShieldAlert, ShieldCheck } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+import { cn } from '@/lib/utils';
+import {
+	useContractPausedStore,
+	selectIsPaused,
+	isAuthorizedAdminWallet,
+} from '@/hooks/useContractPausedStore';
+import toast from 'react-hot-toast';
+
+export interface AdminPauseControlProps {
+	/** Optional wallet address override (otherwise uses wagmi's useAccount). */
+	walletAddress?: string;
+	className?: string;
+}
+
+const AdminPauseControl: React.FC<AdminPauseControlProps> = ({
+	walletAddress,
+	className,
+}) => {
+	const { address } = useAccount();
+	const activeAddress = walletAddress ?? address;
+
+	const isPaused = useContractPausedStore(selectIsPaused);
+	const togglePause = useContractPausedStore(state => state.togglePause);
+
+	// Only visible to authorised admin wallets
+	if (!isAuthorizedAdminWallet(activeAddress)) {
+		return null;
+	}
+
+	const handleToggle = () => {
+		const nextState = !isPaused;
+		togglePause();
+		if (nextState) {
+			toast.error('Emergency pause activated. All trading disabled.');
+		} else {
+			toast.success('Contract unpaused. Trading resumed.');
+		}
+	};
+
+	return (
+		<div
+			data-testid="admin-pause-panel"
+			className={cn(
+				'flex flex-col sm:flex-row items-start sm:items-center justify-between gap-3',
+				'rounded-xl border border-amber-500/30 bg-amber-500/10 p-3 sm:px-4',
+				className
+			)}
+		>
+			<div className="flex items-center gap-2.5">
+				<div className="flex size-7 items-center justify-center rounded-lg bg-amber-500/20 text-amber-300">
+					{isPaused ? (
+						<ShieldAlert className="size-4 text-red-400" aria-hidden="true" />
+					) : (
+						<Shield className="size-4 text-amber-400" aria-hidden="true" />
+					)}
+				</div>
+				<div>
+					<p className="text-xs font-bold tracking-wide uppercase text-amber-300">
+						Admin Controls
+					</p>
+					<p className="text-xs text-white/70">
+						Contract status:{' '}
+						<span
+							className={cn(
+								'font-semibold',
+								isPaused ? 'text-red-400' : 'text-emerald-400'
+							)}
+						>
+							{isPaused ? 'Paused (Trading Suspended)' : 'Active (Trading Open)'}
+						</span>
+					</p>
+				</div>
+			</div>
+
+			<Button
+				type="button"
+				size="sm"
+				variant={isPaused ? 'default' : 'destructive'}
+				onClick={handleToggle}
+				data-testid="admin-pause-toggle"
+				aria-label={isPaused ? 'Unpause contract' : 'Emergency pause contract'}
+				className={cn(
+					'rounded-lg font-bold text-xs',
+					isPaused
+						? 'bg-emerald-600 hover:bg-emerald-500 text-white'
+						: 'bg-red-600 hover:bg-red-500 text-white'
+				)}
+			>
+				{isPaused ? (
+					<>
+						<ShieldCheck className="mr-1.5 size-3.5" aria-hidden="true" />
+						Resume Contract
+					</>
+				) : (
+					<>
+						<ShieldAlert className="mr-1.5 size-3.5" aria-hidden="true" />
+						Emergency Pause
+					</>
+				)}
+			</Button>
+		</div>
+	);
+};
+
+export default AdminPauseControl;
diff --git a/src/components/common/AllowanceApprovalStep.tsx b/src/components/common/AllowanceApprovalStep.tsx
new file mode 100644
index 00000000..aa67f989
--- /dev/null
+++ b/src/components/common/AllowanceApprovalStep.tsx
@@ -0,0 +1,133 @@
+/**
+ * AllowanceApprovalStep (#955)
+ *
+ * Inline approval step rendered inside the buy/staking flow when the
+ * staking contract does not yet have sufficient allowance to transfer
+ * the user's keys.
+ *
+ * Flow:
+ *  1. Parent checks `needsApproval` (from useAllowanceStore).
+ *  2. If true, renders this component instead of the normal confirm button.
+ *  3. User reads the explanation and clicks "Approve transfer".
+ *  4. On success, `onApproved` is called so the parent can proceed.
+ *  5. On error, an inline error message is shown with a retry option.
+ *
+ * The component is purely presentational with respect to layout — it takes
+ * no wallet addresses; the parent passes the pre-checked status and the
+ * submit handler.
+ */
+
+import { ShieldCheck, AlertCircle, Loader2, Info } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+import { StableButtonContent } from '@/components/ui/stable-button-content';
+import { cn } from '@/lib/utils';
+
+export interface AllowanceApprovalStepProps {
+	/** Whether the approval transaction is currently in-flight. */
+	isApproving: boolean;
+	/** Non-null when the approval transaction failed. */
+	errorMessage: string | null;
+	/** Called when the user clicks "Approve transfer". */
+	onApprove: () => void;
+	className?: string;
+}
+
+const AllowanceApprovalStep: React.FC<AllowanceApprovalStepProps> = ({
+	isApproving,
+	errorMessage,
+	onApprove,
+	className,
+}) => {
+	return (
+		<div
+			className={cn(
+				'rounded-xl border border-amber-500/25 bg-amber-500/8 px-4 py-4 space-y-3',
+				className
+			)}
+		>
+			{/* Header */}
+			<div className="flex items-start gap-3">
+				<div className="mt-0.5 flex size-7 shrink-0 items-center justify-center rounded-full bg-amber-500/15">
+					<ShieldCheck
+						className="size-3.5 text-amber-400"
+						aria-hidden="true"
+					/>
+				</div>
+				<div className="min-w-0 flex-1">
+					<p className="text-sm font-bold text-amber-100">
+						Approval required
+					</p>
+					<p className="mt-1 text-xs leading-relaxed text-amber-200/70">
+						Before staking your keys, you must grant the staking contract
+						permission to transfer them on your behalf. This is a one-time
+						on-chain approval per wallet.
+					</p>
+				</div>
+			</div>
+
+			{/* What the approval grants */}
+			<div className="rounded-lg border border-white/8 bg-white/[0.03] px-3 py-2.5 space-y-1.5">
+				<p className="flex items-center gap-1.5 text-[0.7rem] font-semibold uppercase tracking-wider text-white/40">
+					<Info className="size-3" aria-hidden="true" />
+					What this approval grants
+				</p>
+				<ul className="space-y-1 text-xs text-white/60">
+					<li className="flex items-start gap-1.5">
+						<span className="mt-1 size-1 shrink-0 rounded-full bg-amber-400/60" />
+						The staking contract may transfer your approved creator keys.
+					</li>
+					<li className="flex items-start gap-1.5">
+						<span className="mt-1 size-1 shrink-0 rounded-full bg-amber-400/60" />
+						Your wallet retains full custody until a stake action is
+						confirmed.
+					</li>
+					<li className="flex items-start gap-1.5">
+						<span className="mt-1 size-1 shrink-0 rounded-full bg-amber-400/60" />
+						You can revoke this approval at any time from your wallet
+						settings.
+					</li>
+				</ul>
+			</div>
+
+			{/* Error state */}
+			{errorMessage && (
+				<div
+					role="alert"
+					className="flex items-start gap-2 rounded-lg border border-red-500/25 bg-red-500/10 px-3 py-2.5"
+				>
+					<AlertCircle
+						className="mt-0.5 size-3.5 shrink-0 text-red-400"
+						aria-hidden="true"
+					/>
+					<p className="text-xs text-red-300">{errorMessage}</p>
+				</div>
+			)}
+
+			{/* Approve button */}
+			<Button
+				type="button"
+				onClick={onApprove}
+				disabled={isApproving}
+				aria-busy={isApproving || undefined}
+				className="w-full rounded-xl font-bold"
+				data-testid="allowance-approve-btn"
+			>
+				<StableButtonContent
+					isLoading={isApproving}
+					loadingLabel="Approving…"
+					spinner={
+						<Loader2
+							className="size-4 animate-spin"
+							aria-hidden="true"
+						/>
+					}
+				>
+					<ShieldCheck className="size-4" aria-hidden="true" />
+					Approve transfer
+				</StableButtonContent>
+			</Button>
+		</div>
+	);
+};
+
+export default AllowanceApprovalStep;
diff --git a/src/components/common/ContractPausedBanner.tsx b/src/components/common/ContractPausedBanner.tsx
new file mode 100644
index 00000000..8cf91021
--- /dev/null
+++ b/src/components/common/ContractPausedBanner.tsx
@@ -0,0 +1,84 @@
+/**
+ * ContractPausedBanner (#953)
+ *
+ * Full-width banner shown at the top of the app when the contract emergency
+ * pause is active. Dismissed automatically when the contract is unpaused
+ * (the store polling handles this).
+ *
+ * When paused:
+ *  - Renders a prominent red/amber banner with an explanation.
+ *  - All trade action buttons elsewhere are disabled (enforced by callers
+ *    reading `selectIsPaused` from the store).
+ *
+ * When not paused (or still checking): renders nothing.
+ */
+
+import { AnimatePresence, motion } from 'framer-motion';
+import { ShieldAlert } from 'lucide-react';
+import { cn } from '@/lib/utils';
+import {
+	useContractPausedStore,
+	selectIsPaused,
+} from '@/hooks/useContractPausedStore';
+
+interface ContractPausedBannerProps {
+	className?: string;
+}
+
+const ContractPausedBanner: React.FC<ContractPausedBannerProps> = ({
+	className,
+}) => {
+	const isPaused = useContractPausedStore(selectIsPaused);
+
+	return (
+		<AnimatePresence>
+			{isPaused && (
+				<motion.div
+					key="contract-paused-banner"
+					role="alert"
+					aria-live="assertive"
+					aria-atomic="true"
+					initial={{ opacity: 0, y: -12 }}
+					animate={{ opacity: 1, y: 0 }}
+					exit={{ opacity: 0, y: -12 }}
+					transition={{ duration: 0.25 }}
+					className={cn(
+						'relative z-50 w-full overflow-hidden',
+						'border-b border-red-500/40 bg-gradient-to-r from-red-900/80 via-red-800/70 to-orange-900/60',
+						'backdrop-blur-md',
+						className
+					)}
+				>
+					{/* Subtle animated shimmer to draw attention */}
+					<div
+						aria-hidden="true"
+						className="pointer-events-none absolute inset-0 bg-[linear-gradient(90deg,transparent_0%,rgba(255,255,255,0.04)_50%,transparent_100%)] animate-[shimmer_2s_linear_infinite]"
+					/>
+
+					<div className="mx-auto flex max-w-7xl items-center gap-3 px-4 py-3 sm:px-6">
+						<div className="flex size-8 shrink-0 items-center justify-center rounded-full bg-red-500/20">
+							<ShieldAlert
+								className="size-4 text-red-300"
+								aria-hidden="true"
+							/>
+						</div>
+
+						<div className="min-w-0 flex-1">
+							<p className="text-sm font-bold text-red-100">
+								Trading suspended — contract paused
+							</p>
+							<p className="mt-0.5 text-xs leading-relaxed text-red-200/75">
+								The Access Layer contract has been temporarily paused by
+								the admin. All buy, sell, stake, and transfer actions are
+								disabled until it is unpaused. Read-only browsing
+								continues normally.
+							</p>
+						</div>
+					</div>
+				</motion.div>
+			)}
+		</AnimatePresence>
+	);
+};
+
+export default ContractPausedBanner;
diff --git a/src/components/common/CreatorCard.tsx b/src/components/common/CreatorCard.tsx
index cc9edae0..f177f24d 100644
--- a/src/components/common/CreatorCard.tsx
+++ b/src/components/common/CreatorCard.tsx
@@ -43,6 +43,10 @@ import WalletConnectCalloutBanner from '@/components/common/WalletConnectCallout
 import NetworkMismatchBanner from '@/components/common/NetworkMismatchBanner';
 import CreatorSocialLinksList from '@/components/common/CreatorSocialLinksList';
 import TransactionStatusIcon from '@/components/common/TransactionStatusIcon';
+import {
+	useContractPausedStore,
+	selectIsPaused,
+} from '@/hooks/useContractPausedStore';
 import MiniStatChip from '@/components/common/MiniStatChip';
 import Change24hBadge from '@/components/common/Change24hBadge';
 import KeySupplyBadge from '@/components/common/KeySupplyBadge';
@@ -90,6 +94,7 @@ const CreatorCard: React.FC<CreatorCardProps> = ({
 	const { isConnected } = useAccount();
 	const { isMismatch: isNetworkMismatch, expectedChainName } =
 		useNetworkMismatch();
+	const isPaused = useContractPausedStore(selectIsPaused);
 	const [transactionState, setTransactionState] = useState<
 		'idle' | 'submitting' | 'failed' | 'success'
 	>('idle');
@@ -174,6 +179,11 @@ const CreatorCard: React.FC<CreatorCardProps> = ({
 	};
 
 	const handleBuy = () => {
+		if (isPaused) {
+			toast.error('Trading is suspended: contract is paused');
+			return;
+		}
+
 		if (!isConnected) {
 			toast.error('Please connect your wallet to purchase keys', {
 				duration: 4000,
@@ -483,7 +493,8 @@ const CreatorCard: React.FC<CreatorCardProps> = ({
 					size="sm"
 					isPending={transactionState === 'submitting'}
 					pendingText="Processing..."
-					disabled={isNetworkMismatch}
+					disabled={isNetworkMismatch || isPaused}
+					title={isPaused ? 'Trading suspended: contract is paused' : undefined}
 					className={cn(
 						'rounded-xl font-bold',
 						!isConnected && 'border-white/10  hover:bg-white/5'
@@ -513,9 +524,11 @@ const CreatorCard: React.FC<CreatorCardProps> = ({
 				state={transactionState}
 				className="mt-4"
 				disabledReason={
-					isNetworkMismatch
-						? `Switch to ${expectedChainName} to enable purchases.`
-						: undefined
+					isPaused
+						? 'Trading is currently suspended because the contract is paused.'
+						: isNetworkMismatch
+							? `Switch to ${expectedChainName} to enable purchases.`
+							: undefined
 				}
 			/>
 
diff --git a/src/components/common/HoldingCapWarning.tsx b/src/components/common/HoldingCapWarning.tsx
new file mode 100644
index 00000000..cb311bd5
--- /dev/null
+++ b/src/components/common/HoldingCapWarning.tsx
@@ -0,0 +1,135 @@
+/**
+ * HoldingCapWarning (#961)
+ *
+ * Displays the connected wallet's current key holding as a percentage of the
+ * contract-defined maximum cap for a given creator. Shows:
+ *
+ *  - A progress bar (current / max).
+ *  - A warning banner when holding ≥ 80% of cap.
+ *  - A "cap reached" state that surfaces via `isAtCap` for callers to
+ *    disable the buy button.
+ *
+ * This component is purely presentational — it receives pre-fetched data
+ * from the parent (which calls `useHoldingCapStore.fetchCap`).
+ */
+
+import { AlertTriangle, Lock } from 'lucide-react';
+import { cn } from '@/lib/utils';
+import {
+	type HoldingCapData,
+	capUsedFraction,
+	isApproachingCap,
+	isAtHoldingCap,
+	remainingCapacity,
+} from '@/hooks/useHoldingCapStore';
+
+export interface HoldingCapWarningProps {
+	data: HoldingCapData;
+	className?: string;
+}
+
+const HoldingCapWarning: React.FC<HoldingCapWarningProps> = ({
+	data,
+	className,
+}) => {
+	const fraction = capUsedFraction(data);
+	const pct = Math.round(fraction * 100);
+	const atCap = isAtHoldingCap(data);
+	const approaching = isApproachingCap(data);
+	const remaining = remainingCapacity(data);
+
+	// Show nothing while loading or when there's no cap data.
+	if (data.isLoading || data.maxCap === 0) return null;
+
+	return (
+		<div className={cn('space-y-2', className)}>
+			{/* Progress bar row */}
+			<div className="space-y-1">
+				<div className="flex items-center justify-between text-xs text-white/50">
+					<span>
+						Holding:{' '}
+						<span className="font-semibold text-white/70">
+							{data.currentHolding}
+						</span>{' '}
+						/ {data.maxCap} keys
+					</span>
+					<span
+						className={cn(
+							'font-semibold tabular-nums',
+							atCap
+								? 'text-red-400'
+								: approaching
+									? 'text-amber-400'
+									: 'text-white/50'
+						)}
+						aria-label={`${pct}% of maximum holding cap used`}
+					>
+						{pct}%
+					</span>
+				</div>
+
+				{/* Track + fill */}
+				<div
+					role="progressbar"
+					aria-valuenow={pct}
+					aria-valuemin={0}
+					aria-valuemax={100}
+					aria-label={`Key holding: ${pct}% of maximum cap`}
+					className="h-1.5 w-full overflow-hidden rounded-full bg-white/10"
+				>
+					<div
+						className={cn(
+							'h-full rounded-full transition-all duration-500',
+							atCap
+								? 'bg-red-500'
+								: approaching
+									? 'bg-amber-400'
+									: 'bg-emerald-500/70'
+						)}
+						style={{ width: `${pct}%` }}
+					/>
+				</div>
+			</div>
+
+			{/* Warning banner — approaching cap */}
+			{approaching && !atCap && (
+				<div
+					role="status"
+					aria-live="polite"
+					className="flex items-start gap-2 rounded-lg border border-amber-500/25 bg-amber-500/10 px-3 py-2"
+				>
+					<AlertTriangle
+						className="mt-0.5 size-3.5 shrink-0 text-amber-400"
+						aria-hidden="true"
+					/>
+					<p className="text-xs leading-relaxed text-amber-200/80">
+						You hold {pct}% of the maximum cap. You can buy up to{' '}
+						<span className="font-semibold text-amber-300">
+							{remaining} more key{remaining !== 1 ? 's' : ''}
+						</span>
+						.
+					</p>
+				</div>
+			)}
+
+			{/* Cap-reached state */}
+			{atCap && (
+				<div
+					role="alert"
+					className="flex items-start gap-2 rounded-lg border border-red-500/25 bg-red-500/10 px-3 py-2"
+				>
+					<Lock
+						className="mt-0.5 size-3.5 shrink-0 text-red-400"
+						aria-hidden="true"
+					/>
+					<p className="text-xs leading-relaxed text-red-200/80">
+						Maximum holding cap reached ({data.maxCap} keys). You cannot
+						purchase more keys for this creator from this wallet.
+					</p>
+				</div>
+			)}
+		</div>
+	);
+};
+
+export default HoldingCapWarning;
diff --git a/src/components/common/TradeDialog.tsx b/src/components/common/TradeDialog.tsx
index 728850b8..a6c5b1b1 100644
--- a/src/components/common/TradeDialog.tsx
+++ b/src/components/common/TradeDialog.tsx
@@ -1,4 +1,6 @@
 import { useEffect, useMemo, useRef, useState } from 'react';
+import { useAccount } from 'wagmi';
+import { ShieldAlert } from 'lucide-react';
 import { Button } from '@/components/ui/button';
 import { StableButtonContent } from '@/components/ui/stable-button-content';
 import {
@@ -14,43 +16,157 @@ import { formatNumber } from '@/utils/numberFormat.utils';
 import { formatDisplayKeyPrice } from '@/utils/keyPriceDisplay.utils';
 import PercentageBadge from '@/components/common/PercentageBadge';
 import NetworkFeeHint from '@/components/common/NetworkFeeHint';
-import { TRADE_FEE_ESTIMATE } from '@/constants/fees';
-import { formatTransactionFeeDisplay } from '@/utils/transactionFee.utils';
+import AllowanceApprovalStep from '@/components/common/AllowanceApprovalStep';
+import HoldingCapWarning from '@/components/common/HoldingCapWarning';
+import { TRADE_FEE_ESTIMATE, BUY_QUANTITY_BOUNDS } from '@/constants/fees';
+import { clampBuyQuantity } from '@/utils/buyQuantity';
+import {
+	fetchTradeNetworkFeeEstimate,
+	formatTransactionFeeDisplay,
+	type NetworkFeeDataProvider,
+} from '@/utils/transactionFee.utils';
+import { normalizeCreatorDisplayName } from '@/utils/creatorDisplayName.utils';
+import {
+	useAllowanceStore,
+	selectNeedsApproval,
+} from '@/hooks/useAllowanceStore';
+import {
+	useHoldingCapStore,
+	isAtHoldingCap,
+	remainingCapacity,
+} from '@/hooks/useHoldingCapStore';
+import {
+	useContractPausedStore,
+	selectIsPaused,
+} from '@/hooks/useContractPausedStore';
+import { useShallow } from 'zustand/react/shallow';
 
-export type TradeSide = 'buy' | 'sell';
+export type TradeSide = 'buy' | 'sell' | 'stake' | 'transfer';
 
 export interface TradeDialogProps {
 	open: boolean;
 	side: TradeSide;
 	creatorName: string;
+	/** Creator / course ID — used to look up the holding cap. */
+	creatorId?: string;
 	availableHoldings: number;
 	/** Per-key price in stroops, shown on the buy confirmation step. */
 	keyPriceStroops?: number | null;
 	onOpenChange: (open: boolean) => void;
 	onConfirm: (amount: number) => Promise<void> | void;
 	isSubmitting?: boolean;
+	networkFeeEstimateProvider?: NetworkFeeDataProvider;
+	/** Optional wallet address override (otherwise uses wagmi account). */
+	walletAddress?: string;
 }
 
+type NetworkFeeEstimateState =
+	| { status: 'idle' | 'loading' | 'error'; fee: null }
+	| { status: 'success'; fee: number };
+
 const TradeDialog: React.FC<TradeDialogProps> = ({
 	open,
 	side,
 	creatorName,
+	creatorId,
 	availableHoldings,
 	keyPriceStroops,
 	onOpenChange,
 	onConfirm,
 	isSubmitting = false,
+	networkFeeEstimateProvider,
+	walletAddress,
 }) => {
+	const { address } = useAccount();
+	const activeAddress = walletAddress ?? address;
+
+	// ── Contract pause state (#953) ───────────────────────────────────────
+	const isPaused = useContractPausedStore(selectIsPaused);
+
+	// ── Allowance (#955) ──────────────────────────────────────────────────
+	const {
+		status: allowanceStatus,
+		checkAllowance,
+		submitApproval,
+	} = useAllowanceStore(
+		useShallow(s => ({
+			status: s.status,
+			checkAllowance: s.checkAllowance,
+			submitApproval: s.submitApproval,
+		}))
+	);
+	const needsApproval = useAllowanceStore(selectNeedsApproval);
+	const isApproving = allowanceStatus === 'approving';
+	const approvalError =
+		allowanceStatus === 'error'
+			? (useAllowanceStore.getState().errorMessage ?? null)
+			: null;
+
+	// ── Holding cap (#961) ────────────────────────────────────────────────
+	const { caps, fetchCap, incrementHolding } = useHoldingCapStore(
+		useShallow(s => ({
+			caps: s.caps,
+			fetchCap: s.fetchCap,
+			incrementHolding: s.incrementHolding,
+		}))
+	);
+	const capData = creatorId ? caps[creatorId] : undefined;
+	const atCap = capData ? isAtHoldingCap(capData) : false;
+	const maxBuyable = capData ? remainingCapacity(capData) : null;
+
+	// ── Local state ───────────────────────────────────────────────────────
 	const [amountText, setAmountText] = useState('1');
 	const [touched, setTouched] = useState(false);
+	const [adjustmentNote, setAdjustmentNote] = useState<string | null>(null);
+	const [networkFeeEstimate, setNetworkFeeEstimate] =
+		useState<NetworkFeeEstimateState>({ status: 'idle', fee: null });
 	const amountInputRef = useRef<HTMLInputElement | null>(null);
 
+	// On open: reset amount + kick off allowance check + cap fetch.
 	useEffect(() => {
-		if (open) {
-			setAmountText('1');
-			setTouched(false);
+		if (!open) return;
+		setAmountText('1');
+		setTouched(false);
+		setAdjustmentNote(null);
+		if (side === 'stake' && activeAddress) {
+			checkAllowance(activeAddress);
+		}
+		if (side === 'buy' && creatorId && activeAddress) {
+			fetchCap(creatorId, activeAddress);
+		}
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [open, side, activeAddress, creatorId]);
+
+	const handleBlur = () => {
+		setTouched(true);
+		if (side !== 'buy') return;
+
+		const trimmed = amountText.trim();
+		// Effective max clamp considering holding cap if present
+		const maxClamp =
+			maxBuyable !== null
+				? Math.min(BUY_QUANTITY_BOUNDS.MAX_QTY, maxBuyable)
+				: BUY_QUANTITY_BOUNDS.MAX_QTY;
+
+		const res = clampBuyQuantity(trimmed, BUY_QUANTITY_BOUNDS.MIN_QTY, maxClamp);
+
+		if (res.adjusted) {
+			setAmountText(res.value.toString());
+			if (res.reason === 'below_min') {
+				setAdjustmentNote(
+					`Quantity adjusted to the minimum of ${res.value}.`
+				);
+			} else if (res.reason === 'above_max') {
+				setAdjustmentNote(
+					`Quantity adjusted to the maximum of ${res.value}.`
+				);
+			} else {
+				setAdjustmentNote(`Quantity rounded to ${res.value}.`);
+			}
+		} else {
+			setAdjustmentNote(null);
 		}
-	}, [open]);
+	};
 
 	const parsedAmount = useMemo(() => {
 		const normalized = amountText.trim();
@@ -63,50 +179,185 @@ const TradeDialog: React.FC<TradeDialogProps> = ({
 		if (!normalized) return 'Please enter an amount.';
 		if (!Number.isFinite(parsedAmount)) return 'Amount must be a valid number.';
 		if (parsedAmount <= 0) return 'Amount must be greater than zero.';
-		if (side === 'sell' && parsedAmount > availableHoldings)
-			return `You can't sell more than your holdings (${formatNumber(availableHoldings)} keys).`;
+		if (isPaused) return 'Trading is currently suspended because the contract is paused.';
+		if (side === 'buy' && atCap)
+			return 'You have reached the maximum holding cap for this creator.';
+		if (
+			side === 'buy' &&
+			maxBuyable !== null &&
+			parsedAmount > maxBuyable
+		)
+			return `You can only buy up to ${formatNumber(maxBuyable)} more key${maxBuyable !== 1 ? 's' : ''} (holding cap).`;
+		if (
+			(side === 'sell' || side === 'stake' || side === 'transfer') &&
+			parsedAmount > availableHoldings
+		)
+			return `You can't ${side} more than your holdings (${formatNumber(availableHoldings)} keys).`;
 		return null;
-	}, [amountText, parsedAmount, side, availableHoldings]);
+	}, [amountText, parsedAmount, side, availableHoldings, atCap, maxBuyable, isPaused]);
 
 	const amountValid = validationError === null;
 	const showError = touched && validationError !== null;
 
-	const title = side === 'buy' ? 'Buy keys' : 'Sell keys';
-	const confirmLabel = side === 'buy' ? 'Confirm buy' : 'Confirm sell';
+	const isAllowanceChecking =
+		side === 'stake' && allowanceStatus === 'checking';
+	const requiresAllowanceApproval =
+		side === 'stake' && needsApproval;
+	const confirmDisabled =
+		!amountValid ||
+		isSubmitting ||
+		isApproving ||
+		isAllowanceChecking ||
+		atCap ||
+		isPaused ||
+		requiresAllowanceApproval;
+
+	const displayCreatorName =
+		normalizeCreatorDisplayName(creatorName) || 'Unnamed creator';
+
+	const title =
+		side === 'buy'
+			? 'Buy keys'
+			: side === 'sell'
+				? 'Sell keys'
+				: side === 'stake'
+					? 'Stake keys'
+					: 'Transfer keys';
+
+	const confirmLabel =
+		side === 'buy'
+			? atCap
+				? 'Cap reached'
+				: isPaused
+					? 'Contract paused'
+					: 'Confirm buy'
+			: isPaused
+				? 'Contract paused'
+				: side === 'sell'
+					? 'Confirm sell'
+					: side === 'stake'
+						? 'Confirm stake'
+						: 'Confirm transfer';
+
 	const estimatedNetworkFee = formatTransactionFeeDisplay(
-		TRADE_FEE_ESTIMATE.DEFAULT_NETWORK_FEE,
+		networkFeeEstimate.status === 'success'
+			? networkFeeEstimate.fee
+			: TRADE_FEE_ESTIMATE.DEFAULT_NETWORK_FEE,
 		{ unit: TRADE_FEE_ESTIMATE.UNIT }
 	);
 
+	const networkFeeCopy =
+		networkFeeEstimate.status === 'loading'
+			? 'Estimating...'
+			: networkFeeEstimate.status === 'error'
+				? 'Cannot estimate network fee'
+				: estimatedNetworkFee;
+
+	const isBusy = isSubmitting || isApproving;
+
+	useEffect(() => {
+		if (!open) {
+			setNetworkFeeEstimate({ status: 'idle', fee: null });
+			return;
+		}
+
+		if (!amountValid || !networkFeeEstimateProvider) {
+			setNetworkFeeEstimate({ status: 'error', fee: null });
+			return;
+		}
+
+		let cancelled = false;
+		setNetworkFeeEstimate({ status: 'loading', fee: null });
+
+		const feeSide = side === 'buy' || side === 'sell' ? side : 'buy';
+		fetchTradeNetworkFeeEstimate(networkFeeEstimateProvider, {
+			side: feeSide,
+			amount: parsedAmount,
+		})
+			.then(fee => {
+				if (cancelled) return;
+				setNetworkFeeEstimate(
+					fee == null
+						? { status: 'error', fee: null }
+						: { status: 'success', fee }
+				);
+			})
+			.catch(() => {
+				if (!cancelled) {
+					setNetworkFeeEstimate({ status: 'error', fee: null });
+				}
+			});
+
+		return () => {
+			cancelled = true;
+		};
+	}, [amountValid, networkFeeEstimateProvider, open, parsedAmount, side]);
+
+	const handleConfirm = async () => {
+		if (confirmDisabled) return;
+		await onConfirm(parsedAmount);
+		// Update holding cap store on successful buy (#961)
+		if (side === 'buy' && creatorId) {
+			incrementHolding(creatorId, parsedAmount);
+		}
+	};
+
 	return (
 		<Dialog
 			open={open}
-			onOpenChange={next => !isSubmitting && onOpenChange(next)}
+			onOpenChange={next => !isBusy && onOpenChange(next)}
 		>
 			<DialogContent
 				className="max-w-md"
-				showCloseButton={!isSubmitting}
-				showEscapeHint={!isSubmitting}
+				showCloseButton={!isBusy}
+				showEscapeHint={!isBusy}
 				onOpenAutoFocus={event => {
 					event.preventDefault();
 					amountInputRef.current?.focus();
 				}}
 				onEscapeKeyDown={event => {
-					if (isSubmitting) event.preventDefault();
+					if (isBusy) event.preventDefault();
 				}}
 				onInteractOutside={event => {
-					if (isSubmitting) event.preventDefault();
+					if (isBusy) event.preventDefault();
 				}}
 			>
 				<DialogHeader>
 					<DialogTitle>{title}</DialogTitle>
 					<DialogDescription>
 						{side === 'buy'
-							? `Purchase creator keys for ${creatorName}.`
-							: `Sell creator keys for ${creatorName}.`}
+							? `Purchase creator keys for ${displayCreatorName}.`
+							: side === 'sell'
+								? `Sell creator keys for ${displayCreatorName}.`
+								: side === 'stake'
+									? `Stake creator keys for ${displayCreatorName}.`
+									: `Transfer creator keys for ${displayCreatorName}.`}
 					</DialogDescription>
 				</DialogHeader>
 
+				{/* Contract paused alert (#953) */}
+				{isPaused && (
+					<div
+						role="alert"
+						data-testid="trade-dialog-paused-alert"
+						className="flex items-start gap-2.5 rounded-xl border border-red-500/30 bg-red-500/10 p-3 text-xs text-red-200"
+					>
+						<ShieldAlert
+							className="mt-0.5 size-4 shrink-0 text-red-400"
+							aria-hidden="true"
+						/>
+						<div>
+							<p className="font-semibold text-red-300">
+								Trading suspended — contract paused
+							</p>
+							<p className="mt-0.5 text-red-200/80">
+								Actions are disabled until the emergency pause is lifted by
+								the admin.
+							</p>
+						</div>
+					</div>
+				)}
+
 				{side === 'buy' && keyPriceStroops != null && (
 					<p className="text-sm text-white/60">
 						Unit price:{' '}
@@ -116,6 +367,11 @@ const TradeDialog: React.FC<TradeDialogProps> = ({
 					</p>
 				)}
 
+				{/* Holding cap warning (#961) — buy side only */}
+				{side === 'buy' && capData && (
+					<HoldingCapWarning data={capData} />
+				)}
+
 				<div className="space-y-2">
 					<div className="text-sm text-white/70">Amount</div>
 					<input
@@ -125,13 +381,17 @@ const TradeDialog: React.FC<TradeDialogProps> = ({
 						onChange={event => {
 							setAmountText(event.target.value);
 							setTouched(true);
+							setAdjustmentNote(null);
 						}}
-						onBlur={() => setTouched(true)}
-						disabled={isSubmitting}
+						onBlur={handleBlur}
+						disabled={isSubmitting || atCap || isPaused}
 						className={cn(
 							'w-full rounded-xl border bg-white/[0.04] px-3 py-2 text-white outline-none transition-colors',
 							'border-white/10 focus:border-amber-500/50 focus:ring-2 focus:ring-amber-500/15',
-							showError ? 'border-red-500/60' : ''
+							showError || (!amountValid && amountText.trim())
+								? 'border-red-500/60'
+								: '',
+							atCap || isPaused ? 'opacity-40 cursor-not-allowed' : ''
 						)}
 						aria-label="Trade amount"
 						aria-describedby={showError ? 'trade-amount-error' : undefined}
@@ -139,6 +399,17 @@ const TradeDialog: React.FC<TradeDialogProps> = ({
 						data-focus-order="1"
 						data-testid="trade-dialog-amount"
 					/>
+
+					{/* Adjustment note on blur */}
+					{side === 'buy' && adjustmentNote && (
+						<div
+							className="text-xs text-amber-400 font-medium animate-in fade-in duration-200"
+							data-testid="buy-qty-adjustment-note"
+						>
+							{adjustmentNote}
+						</div>
+					)}
+
 					{showError && (
 						<p
 							id="trade-amount-error"
@@ -149,13 +420,23 @@ const TradeDialog: React.FC<TradeDialogProps> = ({
 							{validationError}
 						</p>
 					)}
+
+					{side === 'buy' && maxBuyable !== null && !atCap && (
+						<p className="text-xs text-white/40">
+							Max you can buy:{' '}
+							<span className="font-semibold text-white/60">
+								{formatNumber(maxBuyable)} key{maxBuyable !== 1 ? 's' : ''}
+							</span>
+						</p>
+					)}
+
 					<div className="flex flex-wrap items-center gap-2 text-xs text-white/45">
 						<span
 							aria-label={`Current wallet holdings: ${formatNumber(availableHoldings)} keys`}
 						>
 							Holdings: {formatNumber(availableHoldings)} keys
 						</span>
-						{side === 'sell' &&
+						{(side === 'sell' || side === 'stake' || side === 'transfer') &&
 							availableHoldings > 0 &&
 							Number.isFinite(parsedAmount) &&
 							parsedAmount > 0 && (
@@ -170,15 +451,24 @@ const TradeDialog: React.FC<TradeDialogProps> = ({
 								/>
 							)}
 					</div>
-					{side === 'buy' && (
-						<NetworkFeeHint
-							variant="text"
-							fee={estimatedNetworkFee}
-							className="text-white/45"
-						/>
-					)}
+
+					<NetworkFeeHint
+						variant="text"
+						label="Approx. network fee"
+						fee={networkFeeCopy}
+						className="text-white/45"
+					/>
 				</div>
 
+				{/* Allowance approval step (#955) — shown when approval is needed */}
+				{requiresAllowanceApproval && (
+					<AllowanceApprovalStep
+						isApproving={isApproving}
+						errorMessage={approvalError}
+						onApprove={() => activeAddress && submitApproval(activeAddress)}
+					/>
+				)}
+
 				{/*
 				 * Focus order is intentional: amount input → Cancel → Confirm.
 				 * That matches the visual left-to-right reading order in the
@@ -193,7 +483,7 @@ const TradeDialog: React.FC<TradeDialogProps> = ({
 						type="button"
 						variant="ghost"
 						onClick={() => onOpenChange(false)}
-						disabled={isSubmitting}
+						disabled={isBusy}
 						data-focus-order="2"
 						data-testid="trade-dialog-cancel"
 					>
@@ -201,9 +491,14 @@ const TradeDialog: React.FC<TradeDialogProps> = ({
 					</Button>
 					<Button
 						type="button"
-						onClick={() => onConfirm(parsedAmount)}
-						disabled={!amountValid || isSubmitting}
+						onClick={handleConfirm}
+						disabled={confirmDisabled}
 						aria-busy={isSubmitting || undefined}
+						title={
+							isPaused
+								? 'Trading suspended: contract is paused'
+								: undefined
+						}
 						data-focus-order="3"
 						data-testid="trade-dialog-confirm"
 					>
diff --git a/src/components/common/__tests__/AdminPauseControl.test.tsx b/src/components/common/__tests__/AdminPauseControl.test.tsx
new file mode 100644
index 00000000..c2cb3811
--- /dev/null
+++ b/src/components/common/__tests__/AdminPauseControl.test.tsx
@@ -0,0 +1,60 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import AdminPauseControl from '../AdminPauseControl';
+import { useContractPausedStore } from '@/hooks/useContractPausedStore';
+
+describe('AdminPauseControl (#953)', () => {
+	const ADMIN_WALLET = '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266';
+	const NON_ADMIN_WALLET = '0x1234567890123456789012345678901234567890';
+
+	beforeEach(() => {
+		useContractPausedStore.setState({
+			status: 'inactive',
+			lastCheckedAt: null,
+			isChecking: false,
+			_intervalId: null,
+		});
+	});
+
+	it('renders nothing when walletAddress is not an authorized admin', () => {
+		const { container } = render(
+			<AdminPauseControl walletAddress={NON_ADMIN_WALLET} />
+		);
+		expect(container.firstChild).toBeNull();
+		expect(screen.queryByTestId('admin-pause-panel')).not.toBeInTheDocument();
+	});
+
+	it('renders nothing when no wallet address is provided and wagmi is disconnected', () => {
+		const { container } = render(<AdminPauseControl />);
+		expect(container.firstChild).toBeNull();
+	});
+
+	it('renders admin controls when connected wallet is an authorized admin', () => {
+		render(<AdminPauseControl walletAddress={ADMIN_WALLET} />);
+
+		expect(screen.getByTestId('admin-pause-panel')).toBeInTheDocument();
+		expect(screen.getByText('Admin Controls')).toBeInTheDocument();
+		expect(screen.getByText(/Active \(Trading Open\)/i)).toBeInTheDocument();
+
+		const toggleBtn = screen.getByTestId('admin-pause-toggle');
+		expect(toggleBtn).toBeInTheDocument();
+		expect(toggleBtn).toHaveTextContent(/Emergency Pause/i);
+	});
+
+	it('toggles pause state when admin clicks emergency pause button', () => {
+		render(<AdminPauseControl walletAddress={ADMIN_WALLET} />);
+
+		const toggleBtn = screen.getByTestId('admin-pause-toggle');
+		fireEvent.click(toggleBtn);
+
+		expect(useContractPausedStore.getState().status).toBe('active');
+		expect(screen.getByText(/Paused \(Trading Suspended\)/i)).toBeInTheDocument();
+		expect(toggleBtn).toHaveTextContent(/Resume Contract/i);
+
+		// Click to unpause
+		fireEvent.click(toggleBtn);
+		expect(useContractPausedStore.getState().status).toBe('inactive');
+		expect(screen.getByText(/Active \(Trading Open\)/i)).toBeInTheDocument();
+		expect(toggleBtn).toHaveTextContent(/Emergency Pause/i);
+	});
+});
diff --git a/src/components/common/__tests__/AllowanceApprovalStep.test.tsx b/src/components/common/__tests__/AllowanceApprovalStep.test.tsx
new file mode 100644
index 00000000..f851b046
--- /dev/null
+++ b/src/components/common/__tests__/AllowanceApprovalStep.test.tsx
@@ -0,0 +1,77 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import AllowanceApprovalStep from '../AllowanceApprovalStep';
+
+describe('AllowanceApprovalStep (#955)', () => {
+	it('renders approval required explanation and grants list', () => {
+		render(
+			<AllowanceApprovalStep
+				isApproving={false}
+				errorMessage={null}
+				onApprove={vi.fn()}
+			/>
+		);
+
+		expect(screen.getByText('Approval required')).toBeInTheDocument();
+		expect(
+			screen.getByText(/Before staking your keys, you must grant the staking contract permission/i)
+		).toBeInTheDocument();
+		expect(screen.getByText(/What this approval grants/i)).toBeInTheDocument();
+		expect(
+			screen.getByText(/The staking contract may transfer your approved creator keys/i)
+		).toBeInTheDocument();
+		expect(
+			screen.getByText(/Your wallet retains full custody until a stake action is confirmed/i)
+		).toBeInTheDocument();
+		expect(
+			screen.getByText(/You can revoke this approval at any time from your wallet settings/i)
+		).toBeInTheDocument();
+	});
+
+	it('calls onApprove when approve button is clicked', () => {
+		const handleApprove = vi.fn();
+		render(
+			<AllowanceApprovalStep
+				isApproving={false}
+				errorMessage={null}
+				onApprove={handleApprove}
+			/>
+		);
+
+		const button = screen.getByTestId('allowance-approve-btn');
+		expect(button).toBeInTheDocument();
+		expect(button).toHaveTextContent(/Approve transfer/i);
+
+		fireEvent.click(button);
+		expect(handleApprove).toHaveBeenCalledTimes(1);
+	});
+
+	it('displays loading state and disables button when isApproving is true', () => {
+		render(
+			<AllowanceApprovalStep
+				isApproving={true}
+				errorMessage={null}
+				onApprove={vi.fn()}
+			/>
+		);
+
+		const button = screen.getByTestId('allowance-approve-btn');
+		expect(button).toBeDisabled();
+		expect(button).toHaveAttribute('aria-busy', 'true');
+		expect(screen.getByText('Approving…')).toBeInTheDocument();
+	});
+
+	it('displays error alert when errorMessage is provided', () => {
+		render(
+			<AllowanceApprovalStep
+				isApproving={false}
+				errorMessage="Transaction was rejected by user."
+				onApprove={vi.fn()}
+			/>
+		);
+
+		const alert = screen.getByRole('alert');
+		expect(alert).toBeInTheDocument();
+		expect(alert).toHaveTextContent('Transaction was rejected by user.');
+	});
+});
diff --git a/src/components/common/__tests__/ContractPausedBanner.test.tsx b/src/components/common/__tests__/ContractPausedBanner.test.tsx
new file mode 100644
index 00000000..33aacf9b
--- /dev/null
+++ b/src/components/common/__tests__/ContractPausedBanner.test.tsx
@@ -0,0 +1,57 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { render, screen, waitFor, act } from '@testing-library/react';
+import ContractPausedBanner from '../ContractPausedBanner';
+import { useContractPausedStore } from '@/hooks/useContractPausedStore';
+
+describe('ContractPausedBanner (#953)', () => {
+	beforeEach(() => {
+		useContractPausedStore.setState({
+			status: 'inactive',
+			lastCheckedAt: null,
+			isChecking: false,
+			_intervalId: null,
+		});
+	});
+
+	it('renders nothing when contract pause state is inactive', () => {
+		const { container } = render(<ContractPausedBanner />);
+		expect(container.firstChild).toBeNull();
+		expect(screen.queryByRole('alert')).not.toBeInTheDocument();
+	});
+
+	it('renders nothing when contract pause state is unknown', () => {
+		useContractPausedStore.setState({ status: 'unknown' });
+		const { container } = render(<ContractPausedBanner />);
+		expect(container.firstChild).toBeNull();
+	});
+
+	it('renders full-width banner when contract pause state is active', () => {
+		useContractPausedStore.setState({ status: 'active' });
+		render(<ContractPausedBanner />);
+
+		const banner = screen.getByRole('alert');
+		expect(banner).toBeInTheDocument();
+		expect(
+			screen.getByText('Trading suspended — contract paused')
+		).toBeInTheDocument();
+		expect(
+			screen.getByText(/All buy, sell, stake, and transfer actions are disabled/i)
+		).toBeInTheDocument();
+	});
+
+	it('dismisses banner automatically when contract is unpaused', async () => {
+		useContractPausedStore.setState({ status: 'active' });
+		render(<ContractPausedBanner />);
+
+		expect(screen.getByRole('alert')).toBeInTheDocument();
+
+		// Simulate contract unpause
+		act(() => {
+			useContractPausedStore.setState({ status: 'inactive' });
+		});
+
+		await waitFor(() => {
+			expect(screen.queryByRole('alert')).not.toBeInTheDocument();
+		});
+	});
+});
diff --git a/src/components/common/__tests__/HoldingCapWarning.test.tsx b/src/components/common/__tests__/HoldingCapWarning.test.tsx
new file mode 100644
index 00000000..98589c8d
--- /dev/null
+++ b/src/components/common/__tests__/HoldingCapWarning.test.tsx
@@ -0,0 +1,69 @@
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import HoldingCapWarning from '../HoldingCapWarning';
+import type { HoldingCapData } from '@/hooks/useHoldingCapStore';
+
+describe('HoldingCapWarning (#961)', () => {
+	const baseData: HoldingCapData = {
+		creatorId: 'creator-test',
+		currentHolding: 10,
+		maxCap: 50,
+		isLoading: false,
+		error: null,
+	};
+
+	it('renders nothing when data is loading or maxCap is 0', () => {
+		const { container: loadingContainer } = render(
+			<HoldingCapWarning data={{ ...baseData, isLoading: true }} />
+		);
+		expect(loadingContainer.firstChild).toBeNull();
+
+		const { container: zeroCapContainer } = render(
+			<HoldingCapWarning data={{ ...baseData, maxCap: 0 }} />
+		);
+		expect(zeroCapContainer.firstChild).toBeNull();
+	});
+
+	it('renders progress indicator with correct percentage and aria attributes', () => {
+		render(<HoldingCapWarning data={{ ...baseData, currentHolding: 25, maxCap: 50 }} />);
+
+		expect(screen.getByText(/Holding:/i)).toHaveTextContent('Holding: 25 / 50 keys');
+		expect(screen.getByText('50%')).toBeInTheDocument();
+
+		const progressbar = screen.getByRole('progressbar');
+		expect(progressbar).toBeInTheDocument();
+		expect(progressbar).toHaveAttribute('aria-valuenow', '50');
+		expect(progressbar).toHaveAttribute('aria-valuemin', '0');
+		expect(progressbar).toHaveAttribute('aria-valuemax', '100');
+
+		// Below 80%: no warning banner
+		expect(screen.queryByRole('status')).not.toBeInTheDocument();
+		expect(screen.queryByRole('alert')).not.toBeInTheDocument();
+	});
+
+	it('displays warning banner when holding exceeds 80% of cap', () => {
+		// 42 / 50 = 84% -> approaching cap
+		render(<HoldingCapWarning data={{ ...baseData, currentHolding: 42, maxCap: 50 }} />);
+
+		expect(screen.getByText('84%')).toBeInTheDocument();
+
+		const warning = screen.getByRole('status');
+		expect(warning).toBeInTheDocument();
+		expect(warning).toHaveTextContent(/You hold 84% of the maximum cap/i);
+		expect(warning).toHaveTextContent(/You can buy up to 8 more keys/i);
+	});
+
+	it('displays cap reached alert when holding is at 100% of cap', () => {
+		render(<HoldingCapWarning data={{ ...baseData, currentHolding: 50, maxCap: 50 }} />);
+
+		expect(screen.getByText('100%')).toBeInTheDocument();
+
+		const alert = screen.getByRole('alert');
+		expect(alert).toBeInTheDocument();
+		expect(alert).toHaveTextContent(/Maximum holding cap reached \(50 keys\)/i);
+		expect(alert).toHaveTextContent(/You cannot purchase more keys for this creator/i);
+
+		// Approaching banner should not be present
+		expect(screen.queryByRole('status')).not.toBeInTheDocument();
+	});
+});
diff --git a/src/components/common/__tests__/TradeDialog.features.test.tsx b/src/components/common/__tests__/TradeDialog.features.test.tsx
new file mode 100644
index 00000000..e1a65154
--- /dev/null
+++ b/src/components/common/__tests__/TradeDialog.features.test.tsx
@@ -0,0 +1,263 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import TradeDialog from '../TradeDialog';
+import { useAllowanceStore } from '@/hooks/useAllowanceStore';
+import { useContractPausedStore } from '@/hooks/useContractPausedStore';
+import { useHoldingCapStore } from '@/hooks/useHoldingCapStore';
+
+describe('TradeDialog Features Integration (#955, #953, #961)', () => {
+	const defaultWallet = '0x1234567890123456789012345678901234567890';
+	const creatorId = 'creator-test-id';
+
+	beforeEach(() => {
+		useAllowanceStore.setState({
+			status: 'idle',
+			approvedAddresses: new Set<string>(),
+			errorMessage: null,
+		});
+
+		useContractPausedStore.setState({
+			status: 'inactive',
+			lastCheckedAt: null,
+			isChecking: false,
+			_intervalId: null,
+		});
+
+		useHoldingCapStore.setState({
+			caps: {},
+		});
+	});
+
+	// ── #955: Allowance Approval Flow ─────────────────────────────────────
+	describe('#955 Allowance Approval Flow', () => {
+		it('shows approval step when staking and allowance is insufficient', async () => {
+			useAllowanceStore.setState({ status: 'insufficient' });
+
+			render(
+				<TradeDialog
+					open={true}
+					side="stake"
+					creatorName="Alice"
+					availableHoldings={10}
+					walletAddress={defaultWallet}
+					onOpenChange={vi.fn()}
+					onConfirm={vi.fn()}
+				/>
+			);
+
+			await waitFor(() => {
+				expect(screen.getByText('Approval required')).toBeInTheDocument();
+				expect(screen.getByTestId('allowance-approve-btn')).toBeInTheDocument();
+			});
+
+			const confirmBtn = screen.getByTestId('trade-dialog-confirm');
+			expect(confirmBtn).toBeDisabled();
+		});
+
+		it('bypasses approval step when allowance is already sufficient', () => {
+			useAllowanceStore.setState({
+				status: 'sufficient',
+				approvedAddresses: new Set([defaultWallet.toLowerCase()]),
+			});
+
+			render(
+				<TradeDialog
+					open={true}
+					side="stake"
+					creatorName="Alice"
+					availableHoldings={10}
+					walletAddress={defaultWallet}
+					onOpenChange={vi.fn()}
+					onConfirm={vi.fn()}
+				/>
+			);
+
+			expect(screen.queryByText('Approval required')).not.toBeInTheDocument();
+			expect(screen.queryByTestId('allowance-approve-btn')).not.toBeInTheDocument();
+
+			const confirmBtn = screen.getByTestId('trade-dialog-confirm');
+			expect(confirmBtn).not.toBeDisabled();
+		});
+
+		it('enables confirm button after successful approval submission', async () => {
+			useAllowanceStore.setState({ status: 'insufficient' });
+
+			render(
+				<TradeDialog
+					open={true}
+					side="stake"
+					creatorName="Alice"
+					availableHoldings={10}
+					walletAddress={defaultWallet}
+					onOpenChange={vi.fn()}
+					onConfirm={vi.fn()}
+				/>
+			);
+
+			const approveBtn = await screen.findByTestId('allowance-approve-btn');
+			fireEvent.click(approveBtn);
+
+			await waitFor(() => {
+				expect(useAllowanceStore.getState().status).toBe('approved');
+			});
+
+			const confirmBtn = screen.getByTestId('trade-dialog-confirm');
+			expect(confirmBtn).not.toBeDisabled();
+		});
+	});
+
+	// ── #953: Contract Paused Behavior ────────────────────────────────────
+	describe('#953 Contract Paused Behavior', () => {
+		it('displays paused alert and disables confirm button when contract is paused', () => {
+			useContractPausedStore.setState({ status: 'active' });
+
+			render(
+				<TradeDialog
+					open={true}
+					side="buy"
+					creatorName="Alice"
+					availableHoldings={10}
+					walletAddress={defaultWallet}
+					onOpenChange={vi.fn()}
+					onConfirm={vi.fn()}
+				/>
+			);
+
+			expect(screen.getByTestId('trade-dialog-paused-alert')).toBeInTheDocument();
+			expect(
+				screen.getByText(/Trading suspended — contract paused/i)
+			).toBeInTheDocument();
+
+			const confirmBtn = screen.getByTestId('trade-dialog-confirm');
+			expect(confirmBtn).toBeDisabled();
+			expect(confirmBtn).toHaveAttribute(
+				'title',
+				'Trading suspended: contract is paused'
+			);
+			expect(confirmBtn).toHaveTextContent('Contract paused');
+		});
+	});
+
+	// ── #961: Maximum Holding Cap Warning & Limiting ──────────────────────
+	describe('#961 Maximum Holding Cap Warning and Limiting', () => {
+		it('disables buy input and confirm button when wallet is at 100% cap', () => {
+			useHoldingCapStore.setState({
+				caps: {
+					[creatorId]: {
+						creatorId,
+						currentHolding: 50,
+						maxCap: 50,
+						isLoading: false,
+						error: null,
+					},
+				},
+			});
+
+			render(
+				<TradeDialog
+					open={true}
+					side="buy"
+					creatorName="Alice"
+					creatorId={creatorId}
+					availableHoldings={10}
+					walletAddress={defaultWallet}
+					onOpenChange={vi.fn()}
+					onConfirm={vi.fn()}
+				/>
+			);
+
+			expect(
+				screen.getByText(/Maximum holding cap reached \(50 keys\)/i)
+			).toBeInTheDocument();
+
+			const amountInput = screen.getByTestId('trade-dialog-amount');
+			expect(amountInput).toBeDisabled();
+
+			const confirmBtn = screen.getByTestId('trade-dialog-confirm');
+			expect(confirmBtn).toBeDisabled();
+			expect(confirmBtn).toHaveTextContent('Cap reached');
+		});
+
+		it('shows remaining capacity and automatically limits buy quantity to remaining capacity', () => {
+			// Holds 45 of 50 -> remaining capacity is 5
+			useHoldingCapStore.setState({
+				caps: {
+					[creatorId]: {
+						creatorId,
+						currentHolding: 45,
+						maxCap: 50,
+						isLoading: false,
+						error: null,
+					},
+				},
+			});
+
+			render(
+				<TradeDialog
+					open={true}
+					side="buy"
+					creatorName="Alice"
+					creatorId={creatorId}
+					availableHoldings={10}
+					walletAddress={defaultWallet}
+					onOpenChange={vi.fn()}
+					onConfirm={vi.fn()}
+				/>
+			);
+
+			expect(screen.getByText(/Max you can buy:/i)).toBeInTheDocument();
+			expect(screen.getByText('5 keys')).toBeInTheDocument();
+
+			const amountInput = screen.getByTestId('trade-dialog-amount') as HTMLInputElement;
+			fireEvent.change(amountInput, { target: { value: '6' } });
+			fireEvent.blur(amountInput);
+
+			expect(amountInput.value).toBe('5');
+			expect(screen.getByTestId('buy-qty-adjustment-note')).toHaveTextContent(
+				'Quantity adjusted to the maximum of 5.'
+			);
+		});
+
+		it('updates holding cap display after successful buy', async () => {
+			useHoldingCapStore.setState({
+				caps: {
+					[creatorId]: {
+						creatorId,
+						currentHolding: 10,
+						maxCap: 50,
+						isLoading: false,
+						error: null,
+					},
+				},
+			});
+
+			const onConfirm = vi.fn().mockResolvedValue(undefined);
+
+			render(
+				<TradeDialog
+					open={true}
+					side="buy"
+					creatorName="Alice"
+					creatorId={creatorId}
+					availableHoldings={10}
+					walletAddress={defaultWallet}
+					onOpenChange={vi.fn()}
+					onConfirm={onConfirm}
+				/>
+			);
+
+			const amountInput = screen.getByTestId('trade-dialog-amount');
+			fireEvent.change(amountInput, { target: { value: '5' } });
+
+			const confirmBtn = screen.getByTestId('trade-dialog-confirm');
+			fireEvent.click(confirmBtn);
+
+			await waitFor(() => {
+				expect(onConfirm).toHaveBeenCalledWith(5);
+			});
+
+			// incrementHolding should have updated the store from 10 to 15
+			expect(useHoldingCapStore.getState().caps[creatorId].currentHolding).toBe(15);
+		});
+	});
+});
diff --git a/src/hooks/__tests__/useAllowanceStore.test.ts b/src/hooks/__tests__/useAllowanceStore.test.ts
new file mode 100644
index 00000000..d214cd77
--- /dev/null
+++ b/src/hooks/__tests__/useAllowanceStore.test.ts
@@ -0,0 +1,97 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+	useAllowanceStore,
+	selectNeedsApproval,
+	selectApprovalComplete,
+} from '../useAllowanceStore';
+
+describe('useAllowanceStore (#955)', () => {
+	beforeEach(() => {
+		useAllowanceStore.setState({
+			status: 'idle',
+			approvedAddresses: new Set<string>(),
+			errorMessage: null,
+		});
+	});
+
+	it('initializes with idle status and empty approved set', () => {
+		const state = useAllowanceStore.getState();
+		expect(state.status).toBe('idle');
+		expect(state.approvedAddresses.size).toBe(0);
+		expect(selectNeedsApproval(state)).toBe(false);
+		expect(selectApprovalComplete(state)).toBe(false);
+	});
+
+	it('checks allowance and detects insufficient allowance for a new wallet', async () => {
+		const store = useAllowanceStore.getState();
+		const checkPromise = store.checkAllowance('0x1234567890123456789012345678901234567890');
+
+		expect(useAllowanceStore.getState().status).toBe('checking');
+		await checkPromise;
+
+		const state = useAllowanceStore.getState();
+		expect(state.status).toBe('insufficient');
+		expect(selectNeedsApproval(state)).toBe(true);
+		expect(selectApprovalComplete(state)).toBe(false);
+	});
+
+	it('submits approval and caches approved address for the session', async () => {
+		const wallet = '0x1234567890123456789012345678901234567890';
+		const store = useAllowanceStore.getState();
+
+		const approvalPromise = store.submitApproval(wallet);
+		expect(useAllowanceStore.getState().status).toBe('approving');
+
+		await approvalPromise;
+
+		const state = useAllowanceStore.getState();
+		expect(state.status).toBe('approved');
+		expect(state.approvedAddresses.has(wallet.toLowerCase())).toBe(true);
+		expect(selectNeedsApproval(state)).toBe(false);
+		expect(selectApprovalComplete(state)).toBe(true);
+	});
+
+	it('bypasses approval step on subsequent stakes for same session using cached approval', async () => {
+		const wallet = '0x1234567890123456789012345678901234567890';
+
+		// First stake: requires approval and gets approved
+		await useAllowanceStore.getState().submitApproval(wallet);
+		expect(useAllowanceStore.getState().approvedAddresses.has(wallet.toLowerCase())).toBe(true);
+
+		// Reset dialog state for next stake
+		useAllowanceStore.getState().reset();
+		expect(useAllowanceStore.getState().status).toBe('idle');
+
+		// Second stake: check allowance
+		await useAllowanceStore.getState().checkAllowance(wallet);
+
+		const state = useAllowanceStore.getState();
+		expect(state.status).toBe('sufficient');
+		expect(selectNeedsApproval(state)).toBe(false);
+		expect(selectApprovalComplete(state)).toBe(true);
+	});
+
+	it('supports case-insensitive address matching in cache', async () => {
+		const lowerWallet = '0xabcdef1234567890abcdef1234567890abcdef12';
+		const upperWallet = '0xABCDEF1234567890ABCDEF1234567890ABCDEF12';
+
+		useAllowanceStore.getState()._setApproved(lowerWallet);
+
+		await useAllowanceStore.getState().checkAllowance(upperWallet);
+
+		const state = useAllowanceStore.getState();
+		expect(state.status).toBe('sufficient');
+		expect(selectNeedsApproval(state)).toBe(false);
+	});
+
+	it('resets state to idle without clearing approved addresses cache', () => {
+		const wallet = '0x1234567890123456789012345678901234567890';
+		useAllowanceStore.getState()._setApproved(wallet);
+
+		useAllowanceStore.getState().reset();
+
+		const state = useAllowanceStore.getState();
+		expect(state.status).toBe('idle');
+		expect(state.approvedAddresses.has(wallet.toLowerCase())).toBe(true);
+	});
+});
diff --git a/src/hooks/__tests__/useContractPausedStore.test.ts b/src/hooks/__tests__/useContractPausedStore.test.ts
new file mode 100644
index 00000000..3f676bc8
--- /dev/null
+++ b/src/hooks/__tests__/useContractPausedStore.test.ts
@@ -0,0 +1,94 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import {
+	useContractPausedStore,
+	selectIsPaused,
+	selectPauseKnown,
+	isAuthorizedAdminWallet,
+	addAuthorizedAdminWallet,
+	POLL_INTERVAL_MS,
+} from '../useContractPausedStore';
+
+describe('useContractPausedStore (#953)', () => {
+	beforeEach(() => {
+		vi.useFakeTimers();
+		useContractPausedStore.getState().stopPolling();
+		useContractPausedStore.setState({
+			status: 'unknown',
+			lastCheckedAt: null,
+			isChecking: false,
+			_intervalId: null,
+		});
+	});
+
+	afterEach(() => {
+		useContractPausedStore.getState().stopPolling();
+		vi.restoreAllMocks();
+	});
+
+	it('initializes with unknown pause status', () => {
+		const state = useContractPausedStore.getState();
+		expect(state.status).toBe('unknown');
+		expect(selectIsPaused(state)).toBe(false);
+		expect(selectPauseKnown(state)).toBe(false);
+	});
+
+	it('updates status and lastCheckedAt when setPaused is called', () => {
+		useContractPausedStore.getState().setPaused(true);
+		expect(useContractPausedStore.getState().status).toBe('active');
+		expect(selectIsPaused(useContractPausedStore.getState())).toBe(true);
+		expect(useContractPausedStore.getState().lastCheckedAt).not.toBeNull();
+
+		useContractPausedStore.getState().setPaused(false);
+		expect(useContractPausedStore.getState().status).toBe('inactive');
+		expect(selectIsPaused(useContractPausedStore.getState())).toBe(false);
+	});
+
+	it('toggles pause state with togglePause', () => {
+		useContractPausedStore.getState().setPaused(false);
+		expect(selectIsPaused(useContractPausedStore.getState())).toBe(false);
+
+		useContractPausedStore.getState().togglePause();
+		expect(selectIsPaused(useContractPausedStore.getState())).toBe(true);
+
+		useContractPausedStore.getState().togglePause();
+		expect(selectIsPaused(useContractPausedStore.getState())).toBe(false);
+	});
+
+	it('starts polling on call and sets interval for 60 seconds', () => {
+		useContractPausedStore.getState().startPolling();
+		const intervalId = useContractPausedStore.getState()._intervalId;
+		expect(intervalId).not.toBeNull();
+
+		// Calling startPolling again is idempotent
+		useContractPausedStore.getState().startPolling();
+		expect(useContractPausedStore.getState()._intervalId).toBe(intervalId);
+
+		expect(POLL_INTERVAL_MS).toBe(60_000);
+	});
+
+	it('stops polling and clears interval', () => {
+		useContractPausedStore.getState().startPolling();
+		expect(useContractPausedStore.getState()._intervalId).not.toBeNull();
+
+		useContractPausedStore.getState().stopPolling();
+		expect(useContractPausedStore.getState()._intervalId).toBeNull();
+	});
+
+	it('identifies authorized admin wallets', () => {
+		// Anvil / default deployer wallet
+		const admin = '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266';
+		expect(isAuthorizedAdminWallet(admin)).toBe(true);
+		expect(isAuthorizedAdminWallet(admin.toLowerCase())).toBe(true);
+		expect(isAuthorizedAdminWallet(admin.toUpperCase())).toBe(true);
+
+		// Non-admin wallet
+		expect(isAuthorizedAdminWallet('0x1111111111111111111111111111111111111111')).toBe(false);
+		expect(isAuthorizedAdminWallet(undefined)).toBe(false);
+		expect(isAuthorizedAdminWallet(null)).toBe(false);
+
+		// Adding custom admin wallet
+		const customAdmin = '0x9999999999999999999999999999999999999999';
+		addAuthorizedAdminWallet(customAdmin);
+		expect(isAuthorizedAdminWallet(customAdmin)).toBe(true);
+	});
+});
diff --git a/src/hooks/__tests__/useHoldingCapStore.test.ts b/src/hooks/__tests__/useHoldingCapStore.test.ts
new file mode 100644
index 00000000..361f501e
--- /dev/null
+++ b/src/hooks/__tests__/useHoldingCapStore.test.ts
@@ -0,0 +1,123 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+	useHoldingCapStore,
+	capUsedFraction,
+	isApproachingCap,
+	isAtHoldingCap,
+	remainingCapacity,
+	type HoldingCapData,
+} from '../useHoldingCapStore';
+
+describe('useHoldingCapStore (#961)', () => {
+	beforeEach(() => {
+		useHoldingCapStore.setState({ caps: {} });
+	});
+
+	it('initializes with empty caps record', () => {
+		expect(useHoldingCapStore.getState().caps).toEqual({});
+	});
+
+	it('fetches holding cap data and populates store', async () => {
+		const creatorId = 'creator-alice';
+		const wallet = '0x1234567890123456789012345678901234567890';
+
+		const fetchPromise = useHoldingCapStore.getState().fetchCap(creatorId, wallet);
+		expect(useHoldingCapStore.getState().caps[creatorId]?.isLoading).toBe(true);
+
+		await fetchPromise;
+
+		const cap = useHoldingCapStore.getState().caps[creatorId];
+		expect(cap).toBeDefined();
+		expect(cap.isLoading).toBe(false);
+		expect(cap.maxCap).toBeGreaterThan(0);
+		expect(typeof cap.currentHolding).toBe('number');
+	});
+
+	it('increments holding after a successful buy', () => {
+		const creatorId = 'creator-test';
+		useHoldingCapStore.setState({
+			caps: {
+				[creatorId]: {
+					creatorId,
+					currentHolding: 10,
+					maxCap: 50,
+					isLoading: false,
+					error: null,
+				},
+			},
+		});
+
+		useHoldingCapStore.getState().incrementHolding(creatorId, 5);
+		expect(useHoldingCapStore.getState().caps[creatorId].currentHolding).toBe(15);
+
+		// Clamps at maxCap
+		useHoldingCapStore.getState().incrementHolding(creatorId, 100);
+		expect(useHoldingCapStore.getState().caps[creatorId].currentHolding).toBe(50);
+	});
+
+	describe('Holding cap helper selectors', () => {
+		it('calculates capUsedFraction accurately', () => {
+			const data: HoldingCapData = {
+				creatorId: 'c1',
+				currentHolding: 25,
+				maxCap: 50,
+				isLoading: false,
+				error: null,
+			};
+			expect(capUsedFraction(data)).toBe(0.5);
+
+			// Edge case: maxCap 0
+			expect(capUsedFraction({ ...data, maxCap: 0 })).toBe(0);
+
+			// Over cap clamp
+			expect(capUsedFraction({ ...data, currentHolding: 60 })).toBe(1);
+		});
+
+		it('detects approaching cap when >= 80% and < 100%', () => {
+			const data: HoldingCapData = {
+				creatorId: 'c1',
+				currentHolding: 39,
+				maxCap: 50,
+				isLoading: false,
+				error: null,
+			};
+			// 39 / 50 = 78% -> not approaching
+			expect(isApproachingCap(data)).toBe(false);
+
+			// 40 / 50 = 80% -> approaching
+			expect(isApproachingCap({ ...data, currentHolding: 40 })).toBe(true);
+
+			// 49 / 50 = 98% -> approaching
+			expect(isApproachingCap({ ...data, currentHolding: 49 })).toBe(true);
+
+			// 50 / 50 = 100% -> at cap, not approaching
+			expect(isApproachingCap({ ...data, currentHolding: 50 })).toBe(false);
+		});
+
+		it('detects at cap when currentHolding >= maxCap', () => {
+			const data: HoldingCapData = {
+				creatorId: 'c1',
+				currentHolding: 49,
+				maxCap: 50,
+				isLoading: false,
+				error: null,
+			};
+			expect(isAtHoldingCap(data)).toBe(false);
+			expect(isAtHoldingCap({ ...data, currentHolding: 50 })).toBe(true);
+			expect(isAtHoldingCap({ ...data, currentHolding: 55 })).toBe(true);
+		});
+
+		it('calculates remainingCapacity accurately', () => {
+			const data: HoldingCapData = {
+				creatorId: 'c1',
+				currentHolding: 35,
+				maxCap: 50,
+				isLoading: false,
+				error: null,
+			};
+			expect(remainingCapacity(data)).toBe(15);
+			expect(remainingCapacity({ ...data, currentHolding: 50 })).toBe(0);
+			expect(remainingCapacity({ ...data, currentHolding: 60 })).toBe(0);
+		});
+	});
+});
diff --git a/src/hooks/useAllowanceStore.ts b/src/hooks/useAllowanceStore.ts
new file mode 100644
index 00000000..e51d31f4
--- /dev/null
+++ b/src/hooks/useAllowanceStore.ts
@@ -0,0 +1,136 @@
+/**
+ * Allowance approval store (#955).
+ *
+ * Manages whether the staking contract has sufficient allowance to transfer
+ * a user's creator keys. The flow is:
+ *
+ *  1. Before the staking flow begins, call `checkAllowance(address)`.
+ *  2. If `needsApproval` is true, surface the approval step UI.
+ *  3. User submits the approve transaction → call `submitApproval(address)`.
+ *  4. On success the approval is cached for the session — subsequent staking
+ *     actions skip the approval step automatically.
+ *
+ * A real implementation would call `token.allowance(owner, spakingContract)`
+ * then `token.approve(stakingContract, amount)` via ethers. Here we simulate
+ * both operations so the UI is fully exercisable without on-chain infra.
+ *
+ * Cache scope: in-memory (store lifetime). Resets on page reload — the spec
+ * says "cached for the session", which aligns with Zustand's default
+ * (no persistence middleware).
+ */
+
+import { create } from 'zustand';
+
+export type AllowanceStatus =
+	| 'idle'
+	| 'checking'
+	| 'sufficient'
+	| 'insufficient'
+	| 'approving'
+	| 'approved'
+	| 'error';
+
+interface AllowanceState {
+	status: AllowanceStatus;
+	/** Wallet addresses that have been approved this session (cached). */
+	approvedAddresses: Set<string>;
+	/** Error message when status === 'error'. */
+	errorMessage: string | null;
+
+	// actions
+	checkAllowance: (walletAddress: string) => Promise<void>;
+	submitApproval: (walletAddress: string) => Promise<void>;
+	reset: () => void;
+	/** Testing helper to manually mark an address as approved */
+	_setApproved: (walletAddress: string) => void;
+}
+
+const isTestEnv =
+	typeof process !== 'undefined' &&
+	(process.env?.NODE_ENV === 'test' || process.env?.VITEST === 'true');
+
+/** Simulated allowance check — replace with real ethers call when ABI lands. */
+async function simulateAllowanceCheck(walletAddress: string): Promise<boolean> {
+	if (!isTestEnv) {
+		await new Promise<void>(r => window.setTimeout(r, 400));
+	}
+	void walletAddress;
+	return false; // insufficient by default until approved
+}
+
+/** Simulated approve tx — replace with real ethers call when ABI lands. */
+async function simulateApproveTransaction(
+	walletAddress: string
+): Promise<void> {
+	if (!isTestEnv) {
+		await new Promise<void>(r => window.setTimeout(r, 600));
+	}
+	void walletAddress;
+	// Succeeds silently; errors would throw.
+}
+
+export const useAllowanceStore = create<AllowanceState>((set, get) => ({
+	status: 'idle',
+	approvedAddresses: new Set<string>(),
+	errorMessage: null,
+
+	checkAllowance: async (walletAddress: string) => {
+		const normalized = walletAddress.toLowerCase();
+		// If already approved this session, skip the check.
+		if (get().approvedAddresses.has(normalized)) {
+			set({ status: 'sufficient', errorMessage: null });
+			return;
+		}
+
+		set({ status: 'checking', errorMessage: null });
+		try {
+			const sufficient = await simulateAllowanceCheck(normalized);
+			set({ status: sufficient ? 'sufficient' : 'insufficient' });
+		} catch (e) {
+			set({
+				status: 'error',
+				errorMessage:
+					e instanceof Error ? e.message : 'Failed to check allowance.',
+			});
+		}
+	},
+
+	submitApproval: async (walletAddress: string) => {
+		const normalized = walletAddress.toLowerCase();
+		set({ status: 'approving', errorMessage: null });
+		try {
+			await simulateApproveTransaction(normalized);
+			// Cache the approval for the rest of the session.
+			const next = new Set(get().approvedAddresses);
+			next.add(normalized);
+			set({ status: 'approved', approvedAddresses: next });
+		} catch (e) {
+			set({
+				status: 'error',
+				errorMessage:
+					e instanceof Error ? e.message : 'Approval transaction failed.',
+			});
+		}
+	},
+
+	_setApproved: (walletAddress: string) => {
+		const normalized = walletAddress.toLowerCase();
+		const next = new Set(get().approvedAddresses);
+		next.add(normalized);
+		set({ status: 'sufficient', approvedAddresses: next, errorMessage: null });
+	},
+
+	reset: () => set({ status: 'idle', errorMessage: null }),
+}));
+
+// ---------------------------------------------------------------------------
+// Selectors
+// ---------------------------------------------------------------------------
+
+export function selectNeedsApproval(state: AllowanceState): boolean {
+	return state.status === 'insufficient';
+}
+
+export function selectApprovalComplete(state: AllowanceState): boolean {
+	return state.status === 'sufficient' || state.status === 'approved';
+}
diff --git a/src/hooks/useContractPausedStore.ts b/src/hooks/useContractPausedStore.ts
new file mode 100644
index 00000000..f2ec93d8
--- /dev/null
+++ b/src/hooks/useContractPausedStore.ts
@@ -0,0 +1,147 @@
+/**
+ * Contract pause state store (#953).
+ *
+ * Polls whether the contract's emergency pause is active. A real
+ * implementation would call `contract.paused()` via ethers; here we
+ * simulate the check with a random-flip stub so the UI is fully testable
+ * without on-chain infrastructure.
+ *
+ * Polling cadence: every 60 seconds (per spec), and once on first mount via
+ * `startPolling()`. The store is a singleton — callers call `startPolling()`
+ * in a top-level effect; redundant calls are no-ops.
+ */
+
+import { create } from 'zustand';
+
+export type PauseStatus = 'unknown' | 'active' | 'inactive';
+
+interface ContractPausedState {
+	/** Current pause status. `unknown` until first poll resolves. */
+	status: PauseStatus;
+	/** ISO timestamp of the last successful poll. */
+	lastCheckedAt: string | null;
+	/** Whether a poll is currently in-flight. */
+	isChecking: boolean;
+	/** Interval handle — stored so `stopPolling` can clear it. */
+	_intervalId: ReturnType<typeof setInterval> | null;
+
+	// actions
+	/** Start polling (idempotent — safe to call multiple times). */
+	startPolling: () => void;
+	/** Stop polling and clean up the interval. */
+	stopPolling: () => void;
+	/** Set pause state (for admin panel or tests). */
+	setPaused: (paused: boolean) => void;
+	/** Toggle pause state. */
+	togglePause: () => void;
+	/** Manually override pause state (alias for setPaused). */
+	_setPaused: (paused: boolean) => void;
+}
+
+/** Simulated contract check — replace with real ethers call when ABI lands. */
+async function simulatePauseCheck(): Promise<boolean> {
+	// Simulate ~200ms network latency.
+	await new Promise<void>(r => window.setTimeout(r, 200));
+	// Contract starts unpaused; stays unpaused unless explicitly toggled via
+	// the admin panel. We return `false` so the UI looks normal by default.
+	return false;
+}
+
+export const POLL_INTERVAL_MS = 60_000;
+
+export const useContractPausedStore = create<ContractPausedState>(
+	(set, get) => ({
+		status: 'unknown',
+		lastCheckedAt: null,
+		isChecking: false,
+		_intervalId: null,
+
+		startPolling: () => {
+			// Idempotent — don't create a second interval.
+			if (get()._intervalId !== null) return;
+
+			const poll = async () => {
+				if (get().isChecking) return;
+				set({ isChecking: true });
+				try {
+					const paused = await simulatePauseCheck();
+					set({
+						status: paused ? 'active' : 'inactive',
+						lastCheckedAt: new Date().toISOString(),
+					});
+				} catch {
+					// Network error — keep last known status, don't crash.
+				} finally {
+					set({ isChecking: false });
+				}
+			};
+
+			// Fire immediately, then on interval.
+			poll();
+			const id = setInterval(poll, POLL_INTERVAL_MS);
+			set({ _intervalId: id });
+		},
+
+		stopPolling: () => {
+			const id = get()._intervalId;
+			if (id !== null) clearInterval(id);
+			set({ _intervalId: null });
+		},
+
+		setPaused: (paused: boolean) => {
+			set({
+				status: paused ? 'active' : 'inactive',
+				lastCheckedAt: new Date().toISOString(),
+			});
+		},
+
+		togglePause: () => {
+			const isPaused = get().status === 'active';
+			set({
+				status: isPaused ? 'inactive' : 'active',
+				lastCheckedAt: new Date().toISOString(),
+			});
+		},
+
+		_setPaused: (paused: boolean) => {
+			set({
+				status: paused ? 'active' : 'inactive',
+				lastCheckedAt: new Date().toISOString(),
+			});
+		},
+	})
+);
+
+// ---------------------------------------------------------------------------
+// Admin Authorization (#953)
+// ---------------------------------------------------------------------------
+
+export const AUTHORIZED_ADMIN_WALLETS = new Set<string>([
+	// Well-known default admin / deployer / anvil address
+	'0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
+	'0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
+]);
+
+export function isAuthorizedAdminWallet(address?: string | null): boolean {
+	if (!address) return false;
+	const normalized = address.toLowerCase();
+	const envAdmin = (import.meta.env?.VITE_ADMIN_WALLET as string | undefined)?.toLowerCase();
+	if (envAdmin && normalized === envAdmin) return true;
+	return AUTHORIZED_ADMIN_WALLETS.has(normalized);
+}
+
+export function addAuthorizedAdminWallet(address: string): void {
+	AUTHORIZED_ADMIN_WALLETS.add(address.toLowerCase());
+}
+
+// ---------------------------------------------------------------------------
+// Selectors
+// ---------------------------------------------------------------------------
+
+export function selectIsPaused(state: ContractPausedState): boolean {
+	return state.status === 'active';
+}
+
+export function selectPauseKnown(state: ContractPausedState): boolean {
+	return state.status !== 'unknown';
+}
diff --git a/src/hooks/useHoldingCapStore.ts b/src/hooks/useHoldingCapStore.ts
new file mode 100644
index 00000000..7e13f7d4
--- /dev/null
+++ b/src/hooks/useHoldingCapStore.ts
@@ -0,0 +1,159 @@
+/**
+ * Holding cap store (#961).
+ *
+ * Tracks the connected wallet's current key holdings and the contract-defined
+ * maximum holding cap for a given creator. Exposes helpers for:
+ *  - Showing a progress indicator (% of cap used).
+ *  - Displaying a warning banner at ≥80% cap utilisation.
+ *  - Capping the buy input to the remaining allowable quantity.
+ *  - Disabling the buy button when the cap is reached (100%).
+ *
+ * A real implementation would read `contract.balanceOf(wallet, creatorId)`
+ * and `contract.maxHoldingCap(creatorId)` on-chain; here we simulate both
+ * so the UI is fully exercisable without contract infrastructure.
+ */
+
+import { create } from 'zustand';
+
+export interface HoldingCapData {
+	creatorId: string;
+	/** How many keys the wallet currently holds for this creator. */
+	currentHolding: number;
+	/** Contract-defined maximum a single wallet may hold. */
+	maxCap: number;
+	/** True while the data is being fetched. */
+	isLoading: boolean;
+	/** Error message from a failed fetch. */
+	error: string | null;
+}
+
+interface HoldingCapState {
+	/** Keyed by creatorId. */
+	caps: Record<string, HoldingCapData>;
+
+	// actions
+	fetchCap: (creatorId: string, walletAddress: string) => Promise<void>;
+	/** Update holding after a successful buy (avoids a full re-fetch). */
+	incrementHolding: (creatorId: string, qty: number) => void;
+}
+
+/** Simulated on-chain fetch — replace with real ethers calls when ABI lands. */
+async function simulateFetchHoldingCap(
+	creatorId: string,
+	walletAddress: string
+): Promise<{ currentHolding: number; maxCap: number }> {
+	await new Promise<void>(r => window.setTimeout(r, 350));
+	void walletAddress;
+	// Deterministic demo values keyed by last char of creatorId so different
+	// creator cards show different cap utilisation states in the UI.
+	const seed = creatorId.charCodeAt(creatorId.length - 1) % 5;
+	const maxCap = 50;
+	const holdings = [0, 10, 38, 45, 50][seed] ?? 0;
+	return { currentHolding: holdings, maxCap };
+}
+
+export const useHoldingCapStore = create<HoldingCapState>((set, get) => ({
+	caps: {},
+
+	fetchCap: async (creatorId, walletAddress, force = false) => {
+		const existing = get().caps[creatorId];
+		if (existing && !existing.isLoading && !force && existing.maxCap > 0) {
+			return;
+		}
+
+		// Mark as loading.
+		set(state => ({
+			caps: {
+				...state.caps,
+				[creatorId]: {
+					...(state.caps[creatorId] ?? {
+						creatorId,
+						currentHolding: 0,
+						maxCap: 0,
+						error: null,
+					}),
+					isLoading: true,
+				},
+			},
+		}));
+
+		try {
+			const { currentHolding, maxCap } = await simulateFetchHoldingCap(
+				creatorId,
+				walletAddress
+			);
+			set(state => ({
+				caps: {
+					...state.caps,
+					[creatorId]: {
+						creatorId,
+						currentHolding,
+						maxCap,
+						isLoading: false,
+						error: null,
+					},
+				},
+			}));
+		} catch (e) {
+			set(state => ({
+				caps: {
+					...state.caps,
+					[creatorId]: {
+						...(state.caps[creatorId] ?? {
+							creatorId,
+							currentHolding: 0,
+							maxCap: 0,
+						}),
+						isLoading: false,
+						error:
+							e instanceof Error
+								? e.message
+								: 'Failed to fetch holding cap.',
+					},
+				},
+			}));
+		}
+	},
+
+	incrementHolding: (creatorId, qty) => {
+		const existing = get().caps[creatorId];
+		if (!existing) return;
+		set(state => ({
+			caps: {
+				...state.caps,
+				[creatorId]: {
+					...existing,
+					currentHolding: Math.min(
+						existing.currentHolding + qty,
+						existing.maxCap
+					),
+				},
+			},
+		}));
+	},
+}));
+
+// ---------------------------------------------------------------------------
+// Selectors
+// ---------------------------------------------------------------------------
+
+/** Fraction of the cap consumed (0–1). */
+export function capUsedFraction(data: HoldingCapData): number {
+	if (data.maxCap === 0) return 0;
+	return Math.min(data.currentHolding / data.maxCap, 1);
+}
+
+/** True when ≥80% of the cap is consumed. */
+export function isApproachingCap(data: HoldingCapData): boolean {
+	return capUsedFraction(data) >= 0.8 && data.currentHolding < data.maxCap;
+}
+
+/** True when the wallet is at 100% of the cap. */
+export function isAtHoldingCap(data: HoldingCapData): boolean {
+	return data.currentHolding >= data.maxCap && data.maxCap > 0;
+}
+
+/** How many more keys the wallet may buy. */
+export function remainingCapacity(data: HoldingCapData): number {
+	return Math.max(0, data.maxCap - data.currentHolding);
+}
diff --git a/src/pages/LandingPage.tsx b/src/pages/LandingPage.tsx
index 339cc803..beff9cf5 100644
--- a/src/pages/LandingPage.tsx
+++ b/src/pages/LandingPage.tsx
@@ -31,6 +31,11 @@ import EmptyTransactionTimelineState from '@/components/common/EmptyTransactionT
 import TradeDialog, { type TradeSide } from '@/components/common/TradeDialog';
 import NetworkMismatchBanner from '@/components/common/NetworkMismatchBanner';
 import StellarConnectionQualityBadge from '@/components/common/StellarConnectionQualityBadge';
+import AdminPauseControl from '@/components/common/AdminPauseControl';
+import {
+	useContractPausedStore,
+	selectIsPaused,
+} from '@/hooks/useContractPausedStore';
 import { useNetworkMismatch } from '@/hooks/useNetworkMismatch';
 import showToast from '@/utils/toast.util';
 import { getSignatureErrorMessage } from '@/utils/errorHandling.utils';
@@ -613,20 +618,36 @@ function LandingPage() {
 		displayedPortfolioValue
 	);
 
+	const isPaused = useContractPausedStore(selectIsPaused);
+
 	const openTradeDialog = (side: TradeSide) => {
+		if (isPaused) {
+			showToast.error('Trading is suspended: contract is paused');
+			return;
+		}
 		setTradeSide(side);
 		setTradeDialogOpen(true);
 	};
 
 	const handleConfirmTrade = async (amount: number) => {
+		if (isPaused) {
+			showToast.error('Trading is suspended: contract is paused');
+			return;
+		}
 		const previousHoldings = featuredHoldings;
 		setTradeSubmitting(true);
 
 		try {
-			showToast.loading(
+			const actionVerb =
 				tradeSide === 'buy'
-					? `Submitting buy for ${amount} key${amount === 1 ? '' : 's'}...`
-					: `Submitting sell for ${amount} key${amount === 1 ? '' : 's'}...`
+					? 'buy'
+					: tradeSide === 'sell'
+						? 'sell'
+						: tradeSide === 'stake'
+							? 'stake'
+							: 'transfer';
+			showToast.loading(
+				`Submitting ${actionVerb} for ${amount} key${amount === 1 ? '' : 's'}...`
 			);
 
 			await new Promise<void>(resolve => window.setTimeout(resolve, 900));
@@ -693,8 +714,9 @@ function LandingPage() {
 							<Button>Buy Access</Button>
 						</UnavailableAction>
 					</div>
-					<div className="mt-4 flex justify-center">
+					<div className="mt-4 flex flex-col items-center gap-3">
 						<StellarConnectionQualityBadge />
+						<AdminPauseControl className="w-full max-w-md mx-auto" />
 					</div>
 				</MarketplaceSection>
 
@@ -1192,8 +1214,9 @@ function LandingPage() {
 												className="rounded-xl"
 												onClick={() => openTradeDialog('buy')}
 												disabled={
-													isNetworkMismatch || tradeSubmitting
+													isNetworkMismatch || tradeSubmitting || isPaused
 												}
+												title={isPaused ? 'Trading suspended: contract is paused' : undefined}
 											>
 												Buy
 											</Button>
@@ -1202,11 +1225,34 @@ function LandingPage() {
 												variant="outline"
 												onClick={() => openTradeDialog('sell')}
 												disabled={
-													isNetworkMismatch || tradeSubmitting
+													isNetworkMismatch || tradeSubmitting || isPaused
 												}
+												title={isPaused ? 'Trading suspended: contract is paused' : undefined}
 											>
 												Sell
 											</Button>
+											<Button
+												className="rounded-xl"
+												variant="outline"
+												onClick={() => openTradeDialog('stake')}
+												disabled={
+													isNetworkMismatch || tradeSubmitting || isPaused
+												}
+												title={isPaused ? 'Trading suspended: contract is paused' : undefined}
+											>
+												Stake
+											</Button>
+											<Button
+												className="rounded-xl"
+												variant="outline"
+												onClick={() => openTradeDialog('transfer')}
+												disabled={
+													isNetworkMismatch || tradeSubmitting || isPaused
+												}
+												title={isPaused ? 'Trading suspended: contract is paused' : undefined}
+											>
+												Transfer
+											</Button>
 										</div>
 										{tradeSubmitting && (
 											<div className="absolute inset-0 hidden items-center justify-center rounded-[1.25rem] border border-white/10 bg-slate-950/65 backdrop-blur-sm md:flex">
@@ -1271,7 +1317,8 @@ function LandingPage() {
 											className="rounded-xl"
 											size="sm"
 											onClick={() => openTradeDialog('buy')}
-											disabled={isNetworkMismatch || tradeSubmitting}
+											disabled={isNetworkMismatch || tradeSubmitting || isPaused}
+											title={isPaused ? 'Trading suspended: contract is paused' : undefined}
 										>
 											Buy
 										</Button>
@@ -1280,10 +1327,31 @@ function LandingPage() {
 											size="sm"
 											variant="outline"
 											onClick={() => openTradeDialog('sell')}
-											disabled={isNetworkMismatch || tradeSubmitting}
+											disabled={isNetworkMismatch || tradeSubmitting || isPaused}
+											title={isPaused ? 'Trading suspended: contract is paused' : undefined}
 										>
 											Sell
 										</Button>
+										<Button
+											className="rounded-xl"
+											size="sm"
+											variant="outline"
+											onClick={() => openTradeDialog('stake')}
+											disabled={isNetworkMismatch || tradeSubmitting || isPaused}
+											title={isPaused ? 'Trading suspended: contract is paused' : undefined}
+										>
+											Stake
+										</Button>
+										<Button
+											className="rounded-xl"
+											size="sm"
+											variant="outline"
+											onClick={() => openTradeDialog('transfer')}
+											disabled={isNetworkMismatch || tradeSubmitting || isPaused}
+											title={isPaused ? 'Trading suspended: contract is paused' : undefined}
+										>
+											Transfer
+										</Button>
 									</div>
 									{tradeSubmitting && (
 										<div className="absolute inset-0 flex items-center justify-center rounded-xl border border-white/10 bg-slate-950/65 px-3 backdrop-blur-sm">
@@ -1313,6 +1381,7 @@ function LandingPage() {
 				open={tradeDialogOpen}
 				side={tradeSide}
 				creatorName="Alex Rivers"
+				creatorId={featuredCreator?.id ?? 'alex-rivers'}
 				availableHoldings={featuredHoldings}
 				keyPriceStroops={resolveCreatorKeyPriceStroops(featuredCreator)}
 				isSubmitting={tradeSubmitting}
diff --git a/src/test/setup.ts b/src/test/setup.ts
index bb02c60c..6a7dce22 100644
--- a/src/test/setup.ts
+++ b/src/test/setup.ts
@@ -1 +1,13 @@
 import '@testing-library/jest-dom/vitest';
+import { vi } from 'vitest';
+
+vi.mock('wagmi', async importOriginal => {
+	const actual = await importOriginal<typeof import('wagmi')>();
+	return {
+		...actual,
+		useAccount: vi.fn(() => ({
+			address: undefined,
+			isConnected: false,
+		})),
+	};
+});
diff --git a/vitest.config.ts b/vitest.config.ts
index 3ebbd9fc..22fdc010 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -1,6 +1,6 @@
 import path from 'path';
 import react from '@vitejs/plugin-react-swc';
-import { defineConfig } from 'vitest/config';
+import { defineConfig, configDefaults } from 'vitest/config';
 
 export default defineConfig({
 	plugins: [react()],
@@ -8,6 +8,7 @@ export default defineConfig({
 		globals: true,
 		environment: 'jsdom',
 		setupFiles: ['./src/test/setup.ts'],
+		exclude: [...configDefaults.exclude, '**/.kilo/**'],
 	},
 	resolve: {
 		alias: {

From bc6a6e7b353ba53393bc404bb61e32eb3cfed05b Mon Sep 17 00:00:00 2001
From: Khadijah Abdulwasii <abdulwasiikhadijah@gmail.com>
Date: Wed, 30 Sep 2026 10:03:57 +0100
Subject: [PATCH 2/3] fix: remove unused ContractPausedBanner import from
 LandingPage; fix duplicate disabled prop in CreatorCard

---
 src/components/common/CreatorCard.tsx | 3 +--
 src/pages/LandingPage.tsx             | 1 -
 2 files changed, 1 insertion(+), 3 deletions(-)

diff --git a/src/components/common/CreatorCard.tsx b/src/components/common/CreatorCard.tsx
index 0e5f9f20..97a9a0f1 100644
--- a/src/components/common/CreatorCard.tsx
+++ b/src/components/common/CreatorCard.tsx
@@ -617,9 +617,8 @@ const CreatorCard: React.FC<CreatorCardProps> = ({
 					size="sm"
 					isPending={transactionState === 'submitting'}
 					pendingText="Processing..."
-					disabled={isNetworkMismatch || isPaused}
+					disabled={isNetworkMismatch || isPaused || isKeyDeprecated(creator)}
 					title={isPaused ? 'Trading suspended: contract is paused' : undefined}
-					disabled={isNetworkMismatch || isKeyDeprecated(creator)}
 					className={cn(
 						'rounded-xl font-bold',
 						!isConnected && 'border-white/10  hover:bg-white/5'
diff --git a/src/pages/LandingPage.tsx b/src/pages/LandingPage.tsx
index 2f33684c..7ee2074b 100644
--- a/src/pages/LandingPage.tsx
+++ b/src/pages/LandingPage.tsx
@@ -46,7 +46,6 @@ import TradePanelErrorBoundary from '@/components/common/TradePanelErrorBoundary
 import NetworkMismatchBanner from '@/components/common/NetworkMismatchBanner';
 import StellarConnectionQualityBadge from '@/components/common/StellarConnectionQualityBadge';
 import AdminPauseControl from '@/components/common/AdminPauseControl';
-import ContractPausedBanner from '@/components/common/ContractPausedBanner';
 import {
 	useContractPausedStore,
 	selectIsPaused,

From f0a9f1887a1b25f0fc0484d228be004302ef44c3 Mon Sep 17 00:00:00 2001
From: Khadijah Abdulwasii <abdulwasiikhadijah@gmail.com>
Date: Wed, 30 Sep 2026 16:11:55 +0100
Subject: [PATCH 3/3] fix: resolve parse error in CreatorCard, clean
 TradeDialog and LandingPage conflicts

---
 src/components/common/CreatorCard.tsx |  10 ++-
 src/components/common/TradeDialog.tsx | 103 +++++++++++++++++++++-----
 src/pages/LandingPage.tsx             |   4 +-
 3 files changed, 97 insertions(+), 20 deletions(-)

diff --git a/src/components/common/CreatorCard.tsx b/src/components/common/CreatorCard.tsx
index 97a9a0f1..8185c53a 100644
--- a/src/components/common/CreatorCard.tsx
+++ b/src/components/common/CreatorCard.tsx
@@ -225,13 +225,17 @@ const CreatorCard: React.FC<CreatorCardProps> = ({
 		}
 	};
 
-	const handleBuy = () => {
+	const handleBuy = useCallback(() => {
 		if (isPaused) {
 			toast.error('Trading is suspended: contract is paused');
 			return;
 		}
 
-	const handleBuy = useCallback(() => {
+		if (isKeyDeprecated(creator)) {
+			toast.error('This key has been deprecated and can no longer be bought');
+			return;
+		}
+
 		if (!isConnected) {
 			toast.error('Please connect your wallet to purchase keys', {
 				duration: 4000,
@@ -252,6 +256,8 @@ const CreatorCard: React.FC<CreatorCardProps> = ({
 		// Implementation for contract interaction would go here
 		runPurchaseAttempt();
 	}, [
+		isPaused,
+		creator,
 		isConnected,
 		isNetworkMismatch,
 		expectedChainName,
diff --git a/src/components/common/TradeDialog.tsx b/src/components/common/TradeDialog.tsx
index 2f1da054..c9ce716e 100644
--- a/src/components/common/TradeDialog.tsx
+++ b/src/components/common/TradeDialog.tsx
@@ -57,10 +57,10 @@ import {
 	type ContractDynamicFeeRate,
 	type DynamicFeeBreakdown as DynamicFeeBreakdownData,
 } from '@/utils/dynamicFeeRate.utils';
-import { courseService } from '@/services/course.service';
-import PriceImpactWarning from '@/components/common/PriceImpactWarning';
-import PriceImpactOverrideCheckbox from '@/components/common/PriceImpactOverrideCheckbox';
-import TradeConfirmationModal from '@/components/common/TradeConfirmationModal';
+import { courseService, type KeyConfig } from '@/services/course.service';
+import SpreadIndicator from '@/components/common/SpreadIndicator';
+import CircuitBreakerStatusIndicator from '@/components/common/CircuitBreakerStatusIndicator';
+import { evaluateCircuitBreakerStatus } from '@/utils/circuitBreaker.utils';
 import {
 	calculateTradePriceImpact,
 	PRICE_IMPACT_THRESHOLD_PERCENT,
@@ -127,6 +127,14 @@ export interface TradeDialogProps {
 	launchPenaltyBps?: number | null;
 	/** Max buy quantity allowed per transaction; null means no limit. */
 	maxBuyQuantity?: number | null;
+	/** Live key trading config carrying the bid-ask spread (#951). */
+	keyConfig?: KeyConfig | null;
+	/** Whether the key config query is still loading. */
+	isKeyConfigLoading?: boolean;
+	/** Key-level circuit breaker threshold in percent (defaults to keyConfig or 15%) (#1034). */
+	circuitBreakerThresholdPercent?: number | null;
+	/** Key-level circuit breaker threshold in basis points (defaults to keyConfig or 1500) (#1034). */
+	circuitBreakerThresholdBps?: number | null;
 	/** Whether to display the confirmation modal step before submission (#919). Defaults to false. */
 	requireConfirmation?: boolean;
 	/** Optional XLM/USD spot rate for the confirmation fee USD equivalent (#994). */
@@ -161,6 +169,10 @@ const TradeDialog: React.FC<TradeDialogProps> = ({
 	currentLedger,
 	launchPenaltyBps,
 	maxBuyQuantity = null,
+	keyConfig,
+	isKeyConfigLoading = false,
+	circuitBreakerThresholdPercent,
+	circuitBreakerThresholdBps,
 	requireConfirmation = false,
 	xlmUsdRate = null,
 	onOpenChange,
@@ -344,6 +356,39 @@ const TradeDialog: React.FC<TradeDialogProps> = ({
 	const amountValid = validationError === null;
 	const showError = touched && validationError !== null;
 
+	const priceImpactPercent = useMemo(() => {
+		if (!amountValid || !Number.isFinite(parsedAmount) || (side !== 'buy' && side !== 'sell')) return 0;
+		return calculateTradePriceImpact({ side, quantity: parsedAmount, currentSupply: currentSupply ?? 0 });
+	}, [amountValid, parsedAmount, side, currentSupply]);
+
+	const effectiveCircuitBreakerThresholdPercent =
+		circuitBreakerThresholdPercent ??
+		keyConfig?.circuitBreakerThresholdPercent ??
+		null;
+	const effectiveCircuitBreakerThresholdBps =
+		circuitBreakerThresholdBps ??
+		keyConfig?.circuitBreakerThresholdBps ??
+		null;
+
+	const circuitBreakerStatus = useMemo(() => {
+		if (side !== 'buy' || !amountValid) return null;
+		return evaluateCircuitBreakerStatus({
+			impactPercent: priceImpactPercent,
+			thresholdPercent: effectiveCircuitBreakerThresholdPercent,
+			thresholdBps: effectiveCircuitBreakerThresholdBps,
+		});
+	}, [
+		side,
+		amountValid,
+		priceImpactPercent,
+		effectiveCircuitBreakerThresholdPercent,
+		effectiveCircuitBreakerThresholdBps,
+	]);
+
+	const isCircuitBreakerBreached = Boolean(
+		side === 'buy' && circuitBreakerStatus?.isBreached
+	);
+
 	const isAllowanceChecking = side === 'stake' && allowanceStatus === 'checking';
 	const requiresAllowanceApproval = side === 'stake' && needsApproval;
 	const confirmDisabled =
@@ -351,6 +396,7 @@ const TradeDialog: React.FC<TradeDialogProps> = ({
 		isSubmitting ||
 		isApproving ||
 		isAllowanceChecking ||
+		isCircuitBreakerBreached ||
 		atCap ||
 		isPaused ||
 		requiresAllowanceApproval;
@@ -365,11 +411,20 @@ const TradeDialog: React.FC<TradeDialogProps> = ({
 
 	const confirmLabel =
 		side === 'buy'
-			? atCap ? 'Cap reached' : isPaused ? 'Contract paused' : 'Confirm buy'
-			: isPaused ? 'Contract paused'
-			: side === 'sell' ? 'Confirm sell'
-			: side === 'stake' ? 'Confirm stake'
-			: 'Confirm transfer';
+			? isCircuitBreakerBreached
+				? 'Circuit Breaker Tripped'
+				: atCap
+					? 'Cap reached'
+					: isPaused
+						? 'Contract paused'
+						: 'Confirm buy'
+			: isPaused
+				? 'Contract paused'
+				: side === 'sell'
+					? 'Confirm sell'
+					: side === 'stake'
+						? 'Confirm stake'
+						: 'Confirm transfer';
 
 	const estimatedNetworkFee = formatTransactionFeeDisplay(
 		networkFeeEstimate.status === 'success'
@@ -425,15 +480,10 @@ const TradeDialog: React.FC<TradeDialogProps> = ({
 	}, [side, pricePreview, estimatedTotalStroops, estimatedProceedsStroops]);
 
 	const slippageBounds = useMemo<SlippageBounds | null>(() => {
-		if (slippageReferencePriceStroops == null) return null;
+		if (slippageReferencePriceStroops == null || (side !== 'buy' && side !== 'sell')) return null;
 		return computeSlippageBounds(side, slippageReferencePriceStroops, slippageTolerancePercent);
 	}, [side, slippageReferencePriceStroops, slippageTolerancePercent]);
 
-	const priceImpactPercent = useMemo(() => {
-		if (!amountValid || !Number.isFinite(parsedAmount)) return 0;
-		return calculateTradePriceImpact({ side, quantity: parsedAmount, currentSupply: currentSupply ?? 0 });
-	}, [amountValid, parsedAmount, side, currentSupply]);
-
 	const handleMaxClick = () => {
 		setTouched(true);
 		if (side === 'sell') {
@@ -657,6 +707,15 @@ const TradeDialog: React.FC<TradeDialogProps> = ({
 				</p>
 			)}
 
+			{/* Configurable bid-ask spread between buy and sell price (#951) */}
+			<SpreadIndicator
+				buyPriceStroops={keyConfig?.buyPriceStroops}
+				sellPriceStroops={keyConfig?.sellPriceStroops}
+				spreadStroops={keyConfig?.spreadStroops}
+				spreadBps={keyConfig?.spreadBps}
+				isLoading={isKeyConfigLoading}
+			/>
+
 			{side === 'sell' && (
 				<LaunchPenaltyWarning visible={launchPenalty.applies} penaltyBps={launchPenalty.penaltyBps} />
 			)}
@@ -738,6 +797,15 @@ const TradeDialog: React.FC<TradeDialogProps> = ({
 						)}
 				</div>
 
+				{side === 'buy' && (
+					<CircuitBreakerStatusIndicator
+						impactPercent={priceImpactPercent}
+						thresholdPercent={effectiveCircuitBreakerThresholdPercent}
+						thresholdBps={effectiveCircuitBreakerThresholdBps}
+						isValid={amountValid}
+					/>
+				)}
+
 				<NetworkFeeHint variant="text" label="Approx. network fee" fee={networkFeeCopy} className="text-white/45" />
 
 				{side === 'buy' && amountValid && (
@@ -822,7 +890,7 @@ const TradeDialog: React.FC<TradeDialogProps> = ({
 		</>
 	);
 
-	const confirmationModal = (
+	const confirmationModal = (side === 'buy' || side === 'sell') ? (
 		<TradeConfirmationModal
 			open={confirmationOpen}
 			onOpenChange={setConfirmationOpen}
@@ -840,6 +908,7 @@ const TradeDialog: React.FC<TradeDialogProps> = ({
 			minPriceStroops={slippageBounds?.minPriceStroops ?? null}
 			priceImpactPercent={priceImpactPercent}
 			onConfirm={async () => {
+				if (isCircuitBreakerBreached) return;
 				await onConfirm(parsedAmount, pricePreview, slippageBounds);
 				if (side === 'buy' && creatorId) incrementHolding(creatorId, parsedAmount);
 				setConfirmationOpen(false);
@@ -847,7 +916,7 @@ const TradeDialog: React.FC<TradeDialogProps> = ({
 			onCancel={() => setConfirmationOpen(false)}
 			isSubmitting={isSubmitting}
 		/>
-	);
+	) : null;
 
 	if (isMobile) {
 		return (
diff --git a/src/pages/LandingPage.tsx b/src/pages/LandingPage.tsx
index 7ee2074b..16eb024c 100644
--- a/src/pages/LandingPage.tsx
+++ b/src/pages/LandingPage.tsx
@@ -2091,7 +2091,9 @@ function LandingPage() {
 					onConfirm={handleConfirmTrade}
 				/>
 			</TradePanelErrorBoundary>
-			<TradeShortcutHints open={tradeDialogOpen} side={tradeSide} />
+			{(tradeSide === 'buy' || tradeSide === 'sell') && (
+				<TradeShortcutHints open={tradeDialogOpen} side={tradeSide} />
+			)}
 			<KeyboardShortcutsHelp
 				open={shortcutsHelpOpen}
 				onOpenChange={setShortcutsHelpOpen}