feat: adapter architecture phase 3 — escape hatches, read-only surface, hardening

CLAUDE.md

@@ -100,6 +100,7 @@ The `/issue` skill applies these labels automatically when creating issues via C
 - Path aliases: `@/src/*` and `@packageJSON`
 - All env vars prefixed with `PUBLIC_` and validated in `src/env.ts`
 - JSDoc comments on exported functions/components (follow existing patterns)
+- Use `@precondition` in JSDoc ONLY for conditions enforced at runtime with a throw/guard. Use `@expects` for documented assumptions the caller is responsible for (TypeScript-enforced, gracefully handled, or downstream-validated). If you write `@precondition`, the function MUST validate and throw on violation.
 
 ## Styling
 

docs/architecture/adapter-architecture-spec.md

@@ -1804,6 +1804,115 @@ const bridge = useTransactionFlow([
 
 ---
 
+## Consumer Error Handling Guide
+
+This section maps every user-facing action to the exact SDK errors it can produce, documents whether the hook handles those errors internally or propagates them, and clarifies the two distinct error handling patterns consumers encounter.
+
+### Per-action error table
+
+Each row lists a user action, the SDK error classes that can be thrown, and how the hook layer handles them. "Propagates" means the consumer must `try/catch`. "Catches + re-throws" means the hook sets its `error` state AND re-throws — the consumer can read `error` reactively or `try/catch` the async call.
+
+| User Action | Possible Errors | Hook Behavior |
+|---|---|---|
+| Connect wallet | `WalletNotInstalledError`, `WalletConnectionRejectedError`, `ChainNotSupportedError` | `useWallet().connect()` propagates — consumer must try/catch |
+| Disconnect wallet | _(none — no-op if already disconnected)_ | `useWallet().disconnect()` propagates (but does not throw in practice) |
+| Sign message | `WalletNotConnectedError`, `SigningRejectedError` | `useWallet().signMessage()` propagates — consumer must try/catch |
+| Sign typed data | `WalletNotConnectedError`, `SigningRejectedError`, `CapabilityNotSupportedError` | `useWallet().signTypedData()` propagates — consumer must try/catch. `CapabilityNotSupportedError` is thrown synchronously if the adapter does not support the capability. |
+| Switch chain | `WalletNotConnectedError`, `ChainNotSupportedError` | `useWallet().switchChain()` propagates — consumer must try/catch |
+| Execute transaction | `AdapterNotFoundError`, `WalletNotConnectedError`, `TransactionNotReadyError`, `PreStepsNotExecutedError`, `InsufficientFundsError`, `InvalidSignerError`, `ChainNotSupportedError` | `useTransaction().execute()` catches all, sets `error` state, fires `lifecycle.onError`, AND re-throws |
+| Prepare transaction | `AdapterNotFoundError`, `TransactionNotReadyError`, `InsufficientFundsError` | `useTransaction().prepare()` catches all, sets `error` state AND re-throws |
+| Execute single pre-step | `Error` (prepare not called), `RangeError` (index out of bounds), `AdapterNotFoundError`, `WalletNotConnectedError` | `useTransaction().executePreStep()` — precondition errors (`Error`, `RangeError`, `AdapterNotFoundError`, `WalletNotConnectedError`) propagate directly without setting `error` state. Execution errors (from adapter `execute`/`confirm`) are caught, set `error` state, and re-thrown. |
+| Execute all pre-steps | Same as single pre-step (delegates to `executePreStep`) | `useTransaction().executeAllPreSteps()` — errors propagate from `executePreStep` |
+| Resolve wallet adapter | `AdapterNotFoundError`, `AmbiguousAdapterError` | `useWallet()` throws synchronously during render — React error boundary catches |
+| Provider initialization | `ChainRegistryConflictError`, `Error` (chainType mismatch) | `DAppBoosterProvider` throws synchronously during render — React error boundary catches |
+
+### Error semantics: `ChainNotSupportedError` vs `AdapterNotFoundError`
+
+Both errors mean "this chain doesn't work" to a consumer, but they occur at different levels:
+
+- **`AdapterNotFoundError`** — thrown by the hook resolution layer. No registered adapter's `supportedChains` includes the requested `chainId`. This means the SDK has no adapter at all for this chain.
+  - **Throw sites:** `useWallet()` (via `resolveAdapter()`), `useTransaction().execute()`, `useTransaction().prepare()`, `useTransaction().executePreStep()`
+
+- **`ChainNotSupportedError`** — thrown by the adapter itself. An adapter was found but its own validation rejects the `chainId`. This occurs inside adapter methods like `connect()`, `switchChain()`, and `execute()`.
+  - **Throw sites:** `WalletAdapter.connect()` (when `options.chainId` is not in `supportedChains`), `WalletAdapter.switchChain()`, `TransactionAdapter.execute()`
+
+In practice, `AdapterNotFoundError` fires first (during resolution) if no adapter matches. `ChainNotSupportedError` fires later (during execution) if the adapter was resolved via a different chain but the target chain is not supported.
+
+### Error semantics: `InvalidSignerError`
+
+`InvalidSignerError` is an internal safety check at the adapter boundary. The `TransactionAdapter.execute()` method validates that the signer it receives is the correct type (e.g., a viem `WalletClient` for EVM). This guards against passing an SVM signer to an EVM adapter. Consumers should not normally encounter this error — it indicates a misconfigured adapter stack, not a user action failure.
+
+### Hook error handling patterns
+
+The SDK uses two distinct patterns for error handling at the hook layer:
+
+#### Pattern 1: `useWallet` methods — raw passthrough
+
+All `useWallet()` methods (`connect`, `disconnect`, `signMessage`, `signTypedData`, `switchChain`, `getSigner`) delegate directly to the adapter. Errors propagate unmodified to the consumer. There is no `error` state on the return object.
+
+```ts
+const { connect, signMessage } = useWallet({ chainType: 'evm' })
+
+try {
+  await connect()
+} catch (err) {
+  if (err instanceof WalletConnectionRejectedError) {
+    // User cancelled — show a dismissable message
+  }
+  if (err instanceof WalletNotInstalledError) {
+    // Wallet not found — show install instructions
+  }
+}
+
+try {
+  const result = await signMessage({ message: 'Hello' })
+} catch (err) {
+  if (err instanceof SigningRejectedError) {
+    // User cancelled signing
+  }
+}
+```
+
+The `signMessage` and `signTypedData` wrappers fire `walletLifecycle.onSignError` before re-throwing, but the error still propagates to the consumer.
+
+#### Pattern 2: `useTransaction` methods — catch, set state, re-throw
+
+All `useTransaction()` async methods (`execute`, `prepare`, `executePreStep`, `executeAllPreSteps`) catch errors, set the `error` property on the hook return, and re-throw. Consumers can handle errors in two ways:
+
+**Reactive (read `error` state):**
+
+```ts
+const { execute, error, phase } = useTransaction()
+
+// In a click handler:
+execute(params).catch(() => {})  // swallow — read error reactively
+
+// In JSX:
+{error && <ErrorBanner message={error.message} />}
+```
+
+**Imperative (try/catch):**
+
+```ts
+const { execute } = useTransaction()
+
+try {
+  const result = await execute(params)
+  // success
+} catch (err) {
+  if (err instanceof TransactionNotReadyError) {
+    // preparation failed
+  }
+  if (err instanceof PreStepsNotExecutedError) {
+    // manual pre-steps not completed
+  }
+}
+```
+
+**Important nuance for `executePreStep`:** Precondition checks (prepare not called, index out of bounds, adapter not found, wallet not connected) throw directly without setting `error` state. Only errors during the actual on-chain execution (adapter `execute`/`confirm` calls) go through the catch-set-rethrow pattern. This means the reactive `error` state only captures execution failures, not programmer errors.
+
+---
+
 ## 12. Migration Path
 
 ### From current codebase to adapter architecture

src/chakra/ConnectWalletButton.tsx

@@ -0,0 +1,29 @@
+import type { FC } from 'react'
+import { ConnectWalletButton as HeadlessConnectWalletButton } from '@/src/sdk/react/components/ConnectWalletButton'
+import type { UseWalletOptions } from '@/src/sdk/react/hooks/useWallet'
+import ConnectButton from '@/src/wallet/components/ConnectButton'
+
+/**
+ * Chakra-styled connect/account button.
+ *
+ * Composes the headless ConnectWalletButton with the Chakra ConnectButton
+ * for styled rendering.
+ */
+export const ConnectWalletButton: FC<UseWalletOptions & { label?: string }> = ({
+  label = 'Connect',
+  ...walletOptions
+}) => {
+  return (
+    <HeadlessConnectWalletButton
+      {...walletOptions}
+      render={({ status, truncatedAddress, onConnect, onManageAccount }) => (
+        <ConnectButton
+          isConnected={status.connected}
+          onClick={status.connected ? onManageAccount : onConnect}
+        >
+          {status.connected && truncatedAddress ? truncatedAddress : label}
+        </ConnectButton>
+      )}
+    />
+  )
+}

src/chakra/WalletGuard.tsx

@@ -0,0 +1,50 @@
+import type { FC, ReactNode } from 'react'
+import {
+  WalletGuard as HeadlessWalletGuard,
+  type WalletRequirement,
+} from '@/src/sdk/react/components/WalletGuard'
+import SwitchChainButton from '@/src/wallet/components/SwitchChainButton'
+import { ConnectWalletButton } from './ConnectWalletButton'
+
+interface ChakraWalletGuardProps {
+  chainId?: string | number
+  chainType?: string
+  children?: ReactNode
+  require?: WalletRequirement[]
+  switchChainLabel?: string
+}
+
+/**
+ * Chakra-styled WalletGuard.
+ *
+ * Composes the headless WalletGuard with Chakra-styled ConnectWalletButton
+ * and SwitchChainButton as default render props.
+ */
+export const WalletGuard: FC<ChakraWalletGuardProps> = ({
+  chainId,
+  chainType,
+  children,
+  require: requirements,
+  switchChainLabel = 'Switch to',
+}) => {
+  return (
+    <HeadlessWalletGuard
+      chainId={chainId}
+      chainType={chainType}
+      require={requirements}
+      renderConnect={() => (
+        <ConnectWalletButton
+          chainId={chainId}
+          chainType={chainType}
+        />
+      )}
+      renderSwitchChain={({ chainName, onSwitch }) => (
+        <SwitchChainButton onClick={onSwitch}>
+          {switchChainLabel} {chainName}
+        </SwitchChainButton>
+      )}
+    >
+      {children}
+    </HeadlessWalletGuard>
+  )
+}

src/chakra/index.ts

@@ -0,0 +1,2 @@
+export { ConnectWalletButton } from './ConnectWalletButton'
+export { WalletGuard } from './WalletGuard'

src/components/pageComponents/home/Examples/demos/EnsName/index.tsx

@@ -9,7 +9,7 @@ import { OptionsDropdown } from '@/src/components/pageComponents/home/Examples/d
 import { Spinner } from '@/src/core/components'
 
 const EnsNameSearch = ({ address }: { address?: Address }) => {
-  const { data, error, status } = useEnsName({
+  const { data, status } = useEnsName({
     address: address,
     chainId: mainnet.id,
   })
@@ -19,7 +19,7 @@ const EnsNameSearch = ({ address }: { address?: Address }) => {
       {status === 'pending' ? (
         <Spinner size="md" />
       ) : status === 'error' ? (
-        `Error fetching ENS name (${error.message})`
+        'ENS resolution unavailable'
       ) : data === undefined || data === null ? (
         'Not available'
       ) : (
@@ -39,10 +39,7 @@ const EnsName = () => {
   }, debounceTime)
 
   const onChange = (e: ChangeEvent<HTMLInputElement>) => {
-    const value = e.target.value as Address
-
-    setValue(value)
-    debouncedSearch(value)
+    setValue(e.target.value as Address)
   }
 
   const addresses = [

src/components/pageComponents/home/Examples/demos/HashHandling/Hash.tsx

@@ -44,7 +44,7 @@ const Hash: FC<Props> = ({ chain, hash, truncatedHashLength }) => {
       borderRadius="8px"
       color="var(--theme-hash-color)"
       cursor="default"
-      explorerURL={getExplorerLink({ chain, hashOrAddress: hash })}
+      explorerURL={getExplorerLink({ chain, hashOrAddress: hash }) ?? ''}
       fontSize="14px"
       hash={hash}
       minHeight="64px"

src/components/pageComponents/home/Examples/demos/HashHandling/index.test.tsx

@@ -5,10 +5,9 @@ import hashHandling from './index'
 
 const system = createSystem(defaultConfig)
 
-vi.mock('@/src/wallet/hooks/useWeb3Status', () => ({
-  useWeb3Status: vi.fn(() => ({
-    isWalletConnected: false,
-    walletChainId: undefined,
+vi.mock('@/src/sdk/react/hooks', () => ({
+  useWallet: vi.fn(() => ({
+    status: { connected: false, activeAccount: null, connectedChainIds: [], connecting: false },
   })),
 }))
 

src/components/pageComponents/home/Examples/demos/HashHandling/index.tsx

@@ -7,7 +7,7 @@ import Icon from '@/src/components/pageComponents/home/Examples/demos/HashHandli
 import Wrapper from '@/src/components/pageComponents/home/Examples/wrapper'
 import { HashInput, Spinner } from '@/src/core/components'
 import type { DetectedHash } from '@/src/core/utils'
-import { useWeb3Status } from '@/src/wallet/hooks'
+import { useWallet } from '@/src/sdk/react/hooks'
 
 const AlertIcon = () => (
   <chakra.svg
@@ -61,7 +61,9 @@ const HashHandling = ({ ...restProps }) => {
   const [loading, setLoading] = useState<boolean | undefined>()
   const notFound = searchResult && searchResult.type === null
   const found = searchResult && searchResult.type !== null
-  const { isWalletConnected, walletChainId } = useWeb3Status()
+  const { status } = useWallet()
+  const isWalletConnected = status.connected
+  const walletChainId = status.connectedChainIds[0] as number | undefined
 
   const onLoading = (isLoading: boolean) => {
     setLoading(isLoading)
@@ -185,7 +187,14 @@ const HashHandling = ({ ...restProps }) => {
           )}
           <Hash
             chain={currentChain}
-            hash={searchResult?.data as Address}
+            hash={
+              searchResult?.type === 'transaction' &&
+              searchResult.data &&
+              typeof searchResult.data === 'object' &&
+              'hash' in searchResult.data
+                ? (searchResult.data.hash as Address)
+                : (searchResult?.data as Address)
+            }
             truncatedHashLength="disabled"
           />
         </Box>