@solana/react-hooks 1.0.0-rc.1 → 1.0.0-rc.3

package/README.md

@@ -1,432 +1,316 @@
 # @solana/react-hooks
 
-React hooks for `@solana/client`. Drop in the provider and call hooks instead of juggling RPC
-clients, wallets, and stores yourself.
-
-> **Status:** Experimental – breaking changes may land often.
+React hooks for `@solana/client`. Wrap your app once and reach for hooks instead of wiring RPC, wallets, and stores by hand.
 
 ## Install
 
 ```bash
-pnpm add @solana/react-hooks
+npm install @solana/client @solana/react-hooks
 ```
 
-## Minimal example
+## Quickstart
 
-Build connectors first, create a client, and hand it to the combined provider.
+1. Choose wallet connectors (auto-discovery is the fastest way to start).
+2. Create a Solana client.
+3. Wrap your tree with `SolanaProvider` and use the hooks.
 
 ```tsx
-import { autoDiscover, backpack, createClient, phantom, solflare } from '@solana/client';
-import { SolanaProvider, useBalance, useConnectWallet, useWallet } from '@solana/react-hooks';
+import { autoDiscover, createClient } from "@solana/client";
+import {
+  SolanaProvider,
+  useBalance,
+  useWalletConnection,
+} from "@solana/react-hooks";
 
-const walletConnectors = [...phantom(), ...solflare(), ...backpack(), ...autoDiscover()];
 const client = createClient({
-    endpoint: 'https://api.devnet.solana.com',
-    websocketEndpoint: 'wss://api.devnet.solana.com',
-    walletConnectors,
+  endpoint: "https://api.devnet.solana.com",
+  walletConnectors: autoDiscover(),
 });
 
-function WalletButton() {
-    const connectWallet = useConnectWallet();
-    return <button onClick={() => connectWallet('phantom')}>Connect Phantom</button>;
-}
-
-function WalletBalance() {
-    const wallet = useWallet();
-    const balance = useBalance(wallet.status === 'connected' ? wallet.session.account.address : undefined);
-
-    if (wallet.status !== 'connected') return <p>Connect a wallet</p>;
-    if (balance.fetching) return <p>Loading…</p>;
-
-    return <p>Lamports: {balance.lamports?.toString() ?? '0'}</p>;
-}
-
 export function App() {
-    return (
-        <SolanaProvider client={client} query={{ suspense: true }}>
-            <WalletButton />
-            <WalletBalance />
-        </SolanaProvider>
-    );
+  return (
+    <SolanaProvider client={client}>
+      {/* your components that call hooks go here */}
+    </SolanaProvider>
+  );
 }
 ```
 
-`SolanaProvider` composes `SolanaClientProvider` and `SolanaQueryProvider` with SWR v2-aligned defaults
-(`revalidateOnFocus`/`revalidateOnReconnect`/`revalidateIfStale` are `true`, `dedupingInterval` is `2000`,
-`focusThrottleInterval` is `5000`). Override them via the `query.config` prop or per-hook `swr` options.
-Prefer passing a `client`; `config`-based setup on `SolanaClientProvider` is still available for bespoke
-composition.
-
-Every hook exposes `UseHookNameParameters` / `UseHookNameReturnType` aliases so wrapper components stay in
-sync with the public API.
-
-## Hooks at a glance
+> **Next.js / RSC:** Components that call these hooks must be marked with `'use client'`.
 
-- `useWallet`, `useConnectWallet`, `useDisconnectWallet` – read or update the current wallet session.
-- `useBalance` / `useAccount` – fetch lamports once or keep account data in sync.
-- `useSolTransfer`, `useSplToken`, `useTransactionPool` – helper-driven flows for SOL, SPL, and
-  general transactions.
-- `useSendTransaction` – prepare and submit arbitrary instructions with shared mutation state.
-- `useSignatureStatus`, `useWaitForSignature` – declarative helpers for tracking confirmations.
-- `useClientStore` – access the underlying Zustand store if you need low-level state.
+## Common Solana flows (copy/paste)
 
-### Wallet helpers
+These snippets assume a parent already handled wallet connection and can pass an address where needed.
 
-Read the current wallet session and expose connect/disconnect buttons.
+### Connect, disconnect, and show balance
 
 ```tsx
-const WalletActions = () => {
-    const wallet = useWallet();
-    const connect = useConnectWallet();
-    const disconnect = useDisconnectWallet();
-
-    if (wallet.status === 'connected') {
-        return (
-            <div>
-                <p>{wallet.session.account.address.toString()}</p>
-                <button onClick={() => disconnect()}>Disconnect</button>
-            </div>
-        );
-    }
-
-    return <button onClick={() => connect('phantom')}>Connect Phantom</button>;
-};
-```
-
-### Balance watcher
-
-Read lamports (cached plus live updates) for any address.
-
-```tsx
-import { useBalance } from '@solana/react-hooks';
+function WalletPanel() {
+  const { connectors, connect, disconnect, wallet, status } =
+    useWalletConnection();
+  const address = wallet?.account.address;
+  const balance = useBalance(address);
 
-function BalanceCard({ address }) {
-    const { lamports, fetching, slot } = useBalance(address);
-    if (fetching) return <p>Loading…</p>;
+  if (status === "connected") {
     return (
-        <div>
-            <p>Lamports: {lamports?.toString() ?? '0'}</p>
-            <small>Last slot: {slot?.toString() ?? 'unknown'}</small>
-        </div>
+      <div>
+        <p>{address?.toString()}</p>
+        <p>Lamports: {balance.lamports?.toString() ?? "loading…"}</p>
+        <button onClick={disconnect}>Disconnect</button>
+      </div>
     );
+  }
+
+  return connectors.map((c) => (
+    <button key={c.id} onClick={() => connect(c.id)}>
+      Connect {c.name}
+    </button>
+  ));
 }
 ```
 
-### Account cache
-
-Fetch account data and optionally keep it in sync via subscriptions.
+### Read lamport balance (auto fetch + watch)
 
 ```tsx
-import { useAccount } from '@solana/react-hooks';
-
-function AccountInspector({ address }) {
-    const account = useAccount(address, { watch: true });
-
-    if (!account) return <p>Loading…</p>;
-    if (account.error) return <p>Error loading account</p>;
-
-    return <pre>{JSON.stringify(account.data, null, 2)}</pre>;
+import { useBalance } from "@solana/react-hooks";
+
+function BalanceCard({ address }: { address: string }) {
+  const { lamports, fetching, slot } = useBalance(address);
+  if (fetching) return <p>Loading…</p>;
+  return (
+    <p>
+      Lamports: {lamports?.toString() ?? "0"} (slot {slot?.toString() ?? "—"})
+    </p>
+  );
 }
 ```
 
-### SOL transfers
-
-Trigger SOL transfers with built-in status tracking.
+### Send SOL
 
 ```tsx
-import { useSolTransfer } from '@solana/react-hooks';
-
-const SendSolButton = ({ destination, amount }) => {
-    const { send, isSending } = useSolTransfer();
-
-    return (
-        <button
-            disabled={isSending}
-            onClick={() =>
-                send({
-                    destination,
-                    lamports: amount,
-                })
-            }
-        >
-            {isSending ? 'Sending…' : 'Send SOL'}
-        </button>
-    );
-};
+import { useSolTransfer } from "@solana/react-hooks";
+
+function SendSol({ destination }: { destination: string }) {
+  const { send, isSending, status, signature, error } = useSolTransfer(); // expects a connected wallet
+  return (
+    <div>
+      <button
+        disabled={isSending}
+        onClick={() =>
+          send({ destination, lamports: 100_000_000n /* 0.1 SOL */ })
+        }
+      >
+        {isSending ? "Sending…" : "Send 0.1 SOL"}
+      </button>
+      <p>Status: {status}</p>
+      {signature ? <p>Signature: {signature}</p> : null}
+      {error ? <p role="alert">Error: {String(error)}</p> : null}
+    </div>
+  );
+}
 ```
 
-### SPL tokens
-
-Scope SPL helpers by mint and reuse the same API for balances and transfers.
+### SPL token balance + transfer
 
 ```tsx
-const SplBalance = ({ mint }) => {
-    const { balance, send, isSending } = useSplToken(mint);
-
-    return (
-        <div>
-            <p>Amount: {balance?.uiAmount ?? '0'}</p>
-            <button
-                disabled={isSending}
-                onClick={() =>
-                    send({
-                        amount: 1n,
-                        destinationOwner: 'Destination111111111111111111111111',
-                    })
-                }
-            >
-                Send 1 token
-            </button>
-        </div>
-    );
-};
+import { useSplToken } from "@solana/react-hooks";
+
+function TokenPanel({
+  mint,
+  destinationOwner,
+}: {
+  mint: string;
+  destinationOwner: string;
+}) {
+  const { balance, send, isSending, owner } = useSplToken(mint);
+  return (
+    <div>
+      <p>Owner: {owner ?? "Connect wallet"}</p>
+      <p>Balance: {balance?.uiAmount ?? "0"}</p>
+      <button
+        disabled={isSending || !owner}
+        onClick={() => send({ amount: 1n, destinationOwner })}
+      >
+        {isSending ? "Sending…" : "Send 1 token"}
+      </button>
+    </div>
+  );
+}
 ```
 
-### Transaction pool
-
-Compose instructions, refresh blockhashes automatically, and send transactions from one hook.
+### Build and send arbitrary transactions
 
 ```tsx
-import type { TransactionInstructionInput } from '@solana/client';
-
-const useMemoizedInstruction = (): TransactionInstructionInput => ({
-    accounts: [],
-    data: new Uint8Array(),
-    programAddress: 'Example1111111111111111111111111111111111',
-});
-
-const TransactionFlow = () => {
-    const instruction = useMemoizedInstruction();
-    const {
-        addInstruction,
-        prepareAndSend,
-        sendStatus,
-        latestBlockhash,
-    } = useTransactionPool();
-
-    return (
-        <div>
-            <button onClick={() => addInstruction(instruction)}>Add instruction</button>
-            <button disabled={sendStatus === 'loading'} onClick={() => prepareAndSend()}>
-                {sendStatus === 'loading' ? 'Sending…' : 'Prepare & Send'}
-            </button>
-            <p>Recent blockhash: {latestBlockhash.blockhash ?? 'loading…'}</p>
-        </div>
-    );
-};
+import type { TransactionInstructionInput } from "@solana/client";
+import { useTransactionPool } from "@solana/react-hooks";
+
+function TransactionFlow({ ix }: { ix: TransactionInstructionInput }) {
+  const pool = useTransactionPool();
+  return (
+    <div>
+      <button onClick={() => pool.addInstruction(ix)}>Add instruction</button>
+      <button disabled={pool.isSending} onClick={() => pool.prepareAndSend()}>
+        {pool.isSending ? "Sending…" : "Prepare & Send"}
+      </button>
+      <p>Blockhash: {pool.latestBlockhash.blockhash ?? "loading…"}</p>
+    </div>
+  );
+}
 ```
 
-### Client store access
-
-Drop down to the underlying Zustand store when you need bespoke selectors.
+### Simple mutation helper (when you already have instructions)
 
 ```tsx
-import { useClientStore } from '@solana/react-hooks';
-
-function ClusterStatus() {
-    const cluster = useClientStore((state) => state.cluster);
-    return <p>Cluster: {cluster.status.status}</p>;
+import { useSendTransaction } from "@solana/react-hooks";
+
+function SendPrepared({ instructions }) {
+  const { send, isSending, signature, error } = useSendTransaction();
+  return (
+    <div>
+      <button disabled={isSending} onClick={() => send({ instructions })}>
+        {isSending ? "Submitting…" : "Send transaction"}
+      </button>
+      {signature ? <p>Signature: {signature}</p> : null}
+      {error ? <p role="alert">{String(error)}</p> : null}
+    </div>
+  );
 }
 ```
 
-### General transaction sender
-
-Use `useSendTransaction` when you already have instructions/messages and just need a mutation helper
-that exposes `{ send, sendPrepared, status, error, signature }`. When no authority is supplied, it
-will use the currently connected wallet session by default.
+### Track confirmations for a signature
 
 ```tsx
-import { useSendTransaction } from '@solana/react-hooks';
-
-function SendAnythingButton({ instructions }) {
-    const { send, isSending, signature, error } = useSendTransaction();
-
-    return (
-        <div>
-            <button disabled={isSending} onClick={() => send({ instructions })}>
-                {isSending ? 'Submitting…' : 'Send transaction'}
-            </button>
-            {signature ? <p>Signature: {signature}</p> : null}
-            {error ? <p role="alert">Failed to send: {String(error)}</p> : null}
-        </div>
-    );
+import { useWaitForSignature } from "@solana/react-hooks";
+
+function SignatureWatcher({ signature }: { signature: string }) {
+  const wait = useWaitForSignature(signature, { commitment: "finalized" });
+  if (wait.waitStatus === "error") return <p role="alert">Failed</p>;
+  if (wait.waitStatus === "success") return <p>Finalized ✅</p>;
+  if (wait.waitStatus === "waiting") return <p>Waiting…</p>;
+  return <p>Provide a signature</p>;
 }
 ```
 
-### Signature helpers
-
-Poll RPC for signature metadata or wait for a confirmation level without writing loops.
+### Query program accounts
 
 ```tsx
-import { useSignatureStatus, useWaitForSignature } from '@solana/react-hooks';
-
-function SignatureStatusCard({ signature }) {
-    const status = useSignatureStatus(signature);
-
-    if (status.isLoading) return <p>Loading…</p>;
-    if (status.isError) return <p>RPC error.</p>;
+import { SolanaQueryProvider, useProgramAccounts } from "@solana/react-hooks";
+
+function ProgramAccounts({ program }: { program: string }) {
+  const query = useProgramAccounts(program);
+  if (query.isLoading) return <p>Loading…</p>;
+  if (query.isError) return <p role="alert">RPC error</p>;
+  return (
+    <div>
+      <button onClick={() => query.refresh()}>Refresh</button>
+      <ul>
+        {query.accounts.map(({ pubkey }) => (
+          <li key={pubkey.toString()}>{pubkey.toString()}</li>
+        ))}
+      </ul>
+    </div>
+  );
+}
 
-    return (
-        <div>
-            <p>Confirmation: {status.confirmationStatus ?? 'pending'}</p>
-            <button onClick={() => status.refresh()}>Refresh</button>
-        </div>
-    );
+function ProgramAccountsSection({ program }: { program: string }) {
+  return (
+    <SolanaQueryProvider>
+      <ProgramAccounts program={program} />
+    </SolanaQueryProvider>
+  );
 }
+```
 
-function WaitForSignature({ signature }) {
-    const wait = useWaitForSignature(signature, { commitment: 'finalized' });
+### Simulate a transaction
 
-    if (wait.waitStatus === 'error') return <p role="alert">Failed: {JSON.stringify(wait.waitError)}</p>;
-    if (wait.waitStatus === 'success') return <p>Finalized!</p>;
-    if (wait.waitStatus === 'waiting') return <p>Waiting for confirmation…</p>;
-    return <p>Provide a signature</p>;
+```tsx
+import { useSimulateTransaction } from "@solana/react-hooks";
+
+function Simulation({ wire }: { wire: string }) {
+  const sim = useSimulateTransaction(wire);
+  if (sim.isLoading) return <p>Simulating…</p>;
+  if (sim.isError) return <p role="alert">Simulation failed</p>;
+  return (
+    <div>
+      <button onClick={() => sim.refresh()}>Re-run</button>
+      <pre>{JSON.stringify(sim.logs, null, 2)}</pre>
+    </div>
+  );
 }
 ```
 
-## Query hooks
-
-Wrap a subtree with `<SolanaQueryProvider>` and call hooks like `useLatestBlockhash`,
-`useProgramAccounts`, `useSignatureStatus`, or `useSimulateTransaction`. Every hook returns
-`{ data, status, refresh }` so you can read the current value and trigger a refetch. Want to lean on React
-Suspense later? Pass `suspense` to `SolanaQueryProvider` and wrap just the section that should pause in a
-local `<Suspense>` boundary—no hook changes required:
+## Using Suspense (opt-in)
 
-The query provider ships SWR v2-aligned defaults: `revalidateOnFocus`/`revalidateOnReconnect`/`revalidateIfStale`
-are `true`, `dedupingInterval` is `2000`, and `focusThrottleInterval` is `5000`. Override them per-provider via the
-`query.config` prop or per-hook via the `swr` option.
+Enable Suspense per subtree by setting `suspense` on `SolanaQueryProvider` and wrapping content in a React `<Suspense>` boundary. This keeps the rest of the UI non-blocking.
 
 ```tsx
-import { SolanaQueryProvider, useBalance } from '@solana/react-hooks';
-import { Suspense } from 'react';
+import { SolanaQueryProvider, useBalance } from "@solana/react-hooks";
+import { Suspense } from "react";
 
 function BalanceDetails({ address }: { address: string }) {
-    const balance = useBalance(address);
-    return <p>Lamports: {balance.lamports?.toString() ?? '0'}</p>;
+  const balance = useBalance(address);
+  return <p>Lamports: {balance.lamports?.toString() ?? "0"}</p>;
 }
 
 export function WalletPanel({ address }: { address: string }) {
-    return (
-        <SolanaQueryProvider suspense>
-            {/* Only this block suspends while balance loads */}
-            <Suspense fallback={<p>Loading balance…</p>}>
-                <BalanceDetails address={address} />
-            </Suspense>
-        </SolanaQueryProvider>
-    );
+  return (
+    <SolanaQueryProvider suspense>
+      <Suspense fallback={<p>Loading balance…</p>}>
+        <BalanceDetails address={address} />
+      </Suspense>
+    </SolanaQueryProvider>
+  );
 }
 ```
 
-### Latest blockhash
-
-Poll or refetch the cluster's latest blockhash.
+## Provider SWR config (optional)
 
 ```tsx
-import { SolanaQueryProvider, useLatestBlockhash } from '@solana/react-hooks';
-
-function BlockhashTicker() {
-    const latest = useLatestBlockhash({ swr: { refreshInterval: 20_000 } });
-    if (latest.status === 'loading') return <p>Fetching blockhash…</p>;
-    if (latest.status === 'error') return <p role="alert">Failed to fetch blockhash.</p>;
-
-    return (
-        <div>
-            <button onClick={() => latest.refresh()}>Refresh</button>
-            <p>Status: {latest.status}</p>
-            <p>Blockhash: {latest.blockhash ?? 'unknown'}</p>
-        </div>
-    );
-}
-
-export function BlockhashCard() {
-    return (
-        <SolanaQueryProvider>
-            <BlockhashTicker />
-        </SolanaQueryProvider>
-    );
+export function App() {
+  return (
+    <SolanaProvider
+      client={client}
+      query={{
+        config: {
+          revalidateOnFocus: false,
+          revalidateOnReconnect: false,
+          refreshInterval: 30_000,
+        },
+      }}
+    >
+      <WalletPanel />
+    </SolanaProvider>
+  );
 }
 ```
 
-### Program accounts
+Defaults when you omit `query.config`:
+- `revalidateOnFocus` / `revalidateOnReconnect` / `revalidateIfStale`: `true`
+- `dedupingInterval`: `2000ms`
+- `focusThrottleInterval`: `5000ms`
 
-```tsx
-import { autoDiscover, backpack, createClient, phantom, solflare } from '@solana/client';
-import { SolanaProvider, SolanaQueryProvider, useProgramAccounts } from '@solana/react-hooks';
+SWR background: stale-while-revalidate (RFC 5861): https://datatracker.ietf.org/doc/html/rfc5861
 
-const walletConnectors = [...phantom(), ...solflare(), ...backpack(), ...autoDiscover()];
-const client = createClient({
-    endpoint: 'https://api.devnet.solana.com',
-    websocketEndpoint: 'wss://api.devnet.solana.com',
-    walletConnectors,
-});
-
-function ProgramAccountsList({ programAddress }) {
-    const query = useProgramAccounts(programAddress);
-    if (query.status === 'loading') return <p>Loading accounts…</p>;
-    if (query.status === 'error') return <p role="alert">Retry later.</p>;
+### Work with the client store directly
 
-    return (
-        <div>
-            <button onClick={() => query.refresh()}>Refresh</button>
-            <p>Status: {query.status}</p>
-            <ul>
-                {query.accounts?.map(({ pubkey }) => (
-                    <li key={pubkey.toString()}>{pubkey.toString()}</li>
-                ))}
-            </ul>
-        </div>
-    );
-}
+```tsx
+import { useClientStore } from "@solana/react-hooks";
 
-export function QueryDemo({ programAddress }) {
-    return (
-        <SolanaProvider client={client}>
-            <SolanaQueryProvider>
-                <ProgramAccountsList programAddress={programAddress} />
-            </SolanaQueryProvider>
-        </SolanaProvider>
-    );
+function ClusterBadge() {
+  const cluster = useClientStore((s) => s.cluster);
+  return <p>Endpoint: {cluster.endpoint}</p>;
 }
 ```
 
-### Transaction simulation
-
-Simulate any transaction payload (wire string or object) and read RPC logs.
+## Notes and defaults
 
-```tsx
-import { useSimulateTransaction } from '@solana/react-hooks';
+- Wallet connectors: use `autoDiscover()` to pick up Wallet Standard injectables; or explicitly compose `phantom()`, `solflare()`, `backpack()`, etc.
+- Queries: all RPC query hooks accept `swr` options under `swr` and `disabled` flags. Suspense is opt-in via `SolanaQueryProvider`’s `suspense` prop.
+- Authorities: transaction helpers default to the connected wallet session when `authority` is omitted.
+- Types: every hook exports `UseHookNameParameters` / `UseHookNameReturnType` aliases.
 
-function SimulationLogs({ transaction }) {
-    const query = useSimulateTransaction(transaction);
-    if (query.status === 'loading') return <p>Simulating…</p>;
-    if (query.status === 'error') return <p role="alert">Simulation failed.</p>;
-    return (
-        <div>
-            <button onClick={() => query.refresh()}>Re-run</button>
-            <p>Status: {query.status}</p>
-            <pre>{JSON.stringify(query.logs, null, 2)}</pre>
-        </div>
-    );
-}
-```
+## More resources
 
-## Going further
-
-- Wallet connection UI: `useWalletConnection` gives you the current wallet, connect/disconnect
-  helpers, and the connector list from `client.connectors` (or an explicit override). Pair it with
-  your preferred UI, or `WalletConnectionManager` for a simple modal state helper.
-- Signing helpers: the wallet session returned by `useWallet` exposes `signMessage`,
-  `signTransaction`, and `sendTransaction` when supported by the connector. These connector methods
-  replace the deprecated Wallet Standard shims.
-- Query hooks keep SWR options under `swr` for consistency (for example,
-  `useProgramAccounts(address, { swr: { revalidateOnFocus: false } })`) and expose typed parameter
-  and return aliases across all hooks.
-- Type helpers: use `UseHookNameParameters` / `UseHookNameReturnType` for public hooks.
-- Looking for examples? See `examples/vite-react` for a ready-to-run, tabbed playground that wires
-  the provider, hooks, and mock UIs together across wallet/state, transaction, and query demos.
-
-## Scripts
-
-- `pnpm build` – run both JS compilation and type definition emit
-- `pnpm test:typecheck` – strict type-checking without emit
-- `pnpm lint` / `pnpm format` – Biome-powered linting and formatting
+- Playground: `examples/vite-react` (run with `pnpm install && pnpm dev`).
+- Next.js reference app: `examples/nextjs`.
+- Hook JSDoc lives in `src/hooks.ts`, `src/queryHooks.ts`, `src/ui.tsx`.