@solana/react 7.0.0 → 7.1.0-canary-20260812151931

package/README.md

@@ -19,7 +19,7 @@ The Kit client is a plugin-extensible value built outside the React tree (`creat
 
 ### `ClientProvider`
 
-Publishes a caller-owned Kit client to its subtree. Required for `useClient`, `useClientCapability`, and any plugin-specific hook that depends on a client capability. Generic primitives like `useAction` work against arbitrary async functions and don't need a provider.
+Publishes a caller-owned Kit client to its subtree. Required for `useClient` and any plugin-specific hook that reads a client capability. Generic primitives like `useAction` work against arbitrary async functions and don't need a provider.
 
 ```tsx
 import { createClient } from '@solana/kit';
@@ -59,38 +59,58 @@ function Root() {
 
 Reads the Kit client published by the nearest `ClientProvider`. Throws a `SolanaError` with code `SOLANA_ERROR__REACT__MISSING_PROVIDER` if no provider is mounted.
 
-Defaults to the base `Client` shape. Callers who know a specific plugin is installed may widen the type via the generic — this is a pure cast with no runtime check, so reach for `useClientCapability` when a missing plugin should fail loudly at mount instead of surfacing later as `undefined`.
+Pass your client's type through the generic to get the capabilities you installed typed at the call site. The ergonomic way is to **reuse the type of the client you already built** — export it from wherever you compose the client and hand that to `useClient`, so the hook's type stays in sync with your real plugin composition automatically:
 
 ```tsx
-import { ClientWithRpc, GetEpochInfoApi } from '@solana/kit';
+// client.ts — where you build the client
+import { createClient } from '@solana/kit';
+import { solanaDevnetRpc } from '@solana/kit-plugin-rpc';
+import { generatedSigner } from '@solana/kit-plugin-signer';
+
+export const client = createClient().use(generatedSigner()).use(solanaDevnetRpc());
+
+// `Awaited<…>` resolves the promise when any plugin is async (e.g. `generatedSigner()`);
+// for a fully-synchronous client it is simply `typeof client`.
+export type AppClient = Awaited<typeof client>;
+```
+
+```tsx
+// any component
 import { useClient } from '@solana/react';
+import type { AppClient } from './client';
 
 function ManualSend() {
-    const client = useClient<ClientWithRpc<GetEpochInfoApi>>();
+    const client = useClient<AppClient>(); // rpc, signers, … all typed
     return <button onClick={() => client.rpc.getEpochInfo().send()}>Fetch</button>;
 }
 ```
 
+`useClient` is a pure type assertion with no runtime check.
+
 ### `useClientCapability<TClient>(config)`
 
-Reads the client and asserts at mount that the requested capability is installed, narrowing the return type via the generic. Throws a `SolanaError` with code `SOLANA_ERROR__REACT__MISSING_CAPABILITY` when the capability is absent — including `hookName` and `providerHint` so users can fix the mistake without cross-referencing docs.
+A runtime escape hatch for the uncommon case where the client isn't precisely typed — a loosely-typed `Client` read from context, say — and you want a clear failure at mount rather than a downstream `undefined`. It reads the client, asserts at mount that the requested capability is installed, and narrows the return type via the generic, throwing a `SolanaError` with code `SOLANA_ERROR__REACT__MISSING_CAPABILITY` (with your `hookName` and `providerHint`) when the capability is absent.
 
-Use this from the implementation of plugin-specific hooks. Apps that need ad-hoc access can reach for `useClient` directly and supply their own narrowing.
+When you type your client with `useClient<AppClient>()`, the compiler already guarantees the capability is present, so you rarely need this.
 
 ```tsx
 import { ClientWithRpc, GetEpochInfoApi } from '@solana/kit';
 import { useClientCapability } from '@solana/react';
 
-function useRpc() {
-    return useClientCapability<ClientWithRpc<GetEpochInfoApi>>({
+// The provider holds a loosely-typed `Client` (built elsewhere, or by a
+// third party), so `useClient` can't prove `rpc` is installed. Assert it here
+// and get a clear mount-time error — with your hint — if it isn't.
+function EpochBadge() {
+    const client = useClientCapability<ClientWithRpc<GetEpochInfoApi>>({
         capability: 'rpc',
-        hookName: 'useRpc',
+        hookName: 'EpochBadge',
         providerHint: 'Install `solanaRpc()` on the client.',
     });
+    return <button onClick={() => client.rpc.getEpochInfo().send()}>Refresh epoch</button>;
 }
 ```
 
-Pass an array of capability names when a hook needs more than one (e.g. `['rpc', 'rpcSubscriptions']`) — the same `providerHint` is surfaced for whichever is missing.
+Pass an array of capability names when you need more than one (e.g. `['rpc', 'rpcSubscriptions']`) — the same `providerHint` is surfaced for whichever is missing.
 
 ### `useAction(fn)`
 
@@ -129,6 +149,73 @@ try {
 }
 ```
 
+### Transaction planning & sending
+
+Wrap a client's transaction-planning and -sending capabilities as tracked actions. Each hook takes the client and returns the same `ActionResult` as [`useAction`](#useactionfn) — `{ data, dispatch, dispatchAsync, error, isRunning, status, reset, ... }` — with `dispatch(input)` supplying the input and the hook injecting the `AbortSignal` for you.
+
+```tsx
+import { usePlanTransaction, useSendTransaction } from '@solana/react';
+
+function SendButton({ client, instructions }) {
+    const { dispatch, isRunning } = useSendTransaction(client);
+    return (
+        <button disabled={isRunning} onClick={() => dispatch(instructions)}>
+            {isRunning ? 'Sending…' : 'Send'}
+        </button>
+    );
+}
+```
+
+- **`usePlanTransaction(client)`** / **`usePlanTransactions(client)`** — plan a single, or multiple, transaction message(s) from an instruction input. Requires a client with transaction planning installed (`ClientWithTransactionPlanning`). `usePlanTransaction` resolves with a single transaction message; `usePlanTransactions` resolves with the full transaction plan.
+- **`useSendTransaction(client)`** / **`useSendTransactions(client)`** — sign, submit, and confirm a single, or multiple, transaction(s). Requires a client with transaction sending installed (`ClientWithTransactionSending`). Both accept flexible input (instructions, an instruction plan, or a transaction plan); `useSendTransaction` additionally accepts a single transaction message.
+
+### `useAirdrop(client)`
+
+Request an airdrop of SOL to an address as a tracked action. Requires a client with an airdrop plugin installed (`ClientWithAirdrop`) — typically available on devnet, testnet, and local validators. Returns the same `ActionResult` as [`useAction`](#useactionfn); `dispatch(address, amount)` supplies the recipient and lamport amount while the hook injects the `AbortSignal`. A natural fit for a devnet "fund this account" button.
+
+```tsx
+import { useAirdrop } from '@solana/react';
+import { lamports } from '@solana/kit';
+import type { Address } from '@solana/kit';
+
+function AirdropButton({ client, address }: { client: ClientWithAirdrop; address: Address }) {
+    const { dispatch, isRunning } = useAirdrop(client);
+    return (
+        <button disabled={isRunning} onClick={() => dispatch(address, lamports(1_000_000_000n))}>
+            {isRunning ? 'Airdropping…' : 'Airdrop 1 SOL'}
+        </button>
+    );
+}
+```
+
+`data` resolves to the transaction `Signature`, or `undefined` when the airdrop was applied without a transaction (some implementations, e.g. LiteSVM, adjust balances directly) — null-check it before use.
+
+### Payer & identity
+
+Read the signer a client uses to pay for transactions (`payer`), or the wallet whose on-chain assets the app acts upon (`identity`), and re-render whenever it changes. Both hooks return the current `TransactionSigner`, or `undefined` while none is available.
+
+```tsx
+import { useClient, useIdentity, usePayer } from '@solana/react';
+import type { AppClient } from './client';
+
+function AccountBar() {
+    const client = useClient<AppClient>();
+    const identity = useIdentity(client);
+    const payer = usePayer(client);
+    return (
+        <div>
+            <span>{identity ? `Signed in as ${identity.address}` : 'Signed out'}</span>
+            <span>{payer ? `Paying with ${payer.address}` : 'No payer'}</span>
+        </div>
+    );
+}
+```
+
+- **`usePayer(client)`** — reads `client.payer`. Requires a client with a payer plugin installed (`ClientWithPayer`).
+- **`useIdentity(client)`** — reads `client.identity`. Requires a client with an identity plugin installed (`ClientWithIdentity`).
+
+When the client also advertises `subscribeToPayer` / `subscribeToIdentity` (`ClientWithSubscribeToPayer` / `ClientWithSubscribeToIdentity`), each hook subscribes so the returned value always reflects the latest signer. For a client whose payer or identity is fixed for its lifetime, it falls back to a no-op subscription and reads the value once.
+
 ### `useRequest(source, options?)`
 
 Fires a one-shot request on mount and re-fires whenever `source` changes identity. Returns `{ data, error, status, refresh }` where `status` is one of `'fetching' | 'success' | 'error' | 'disabled'`. Use it for RPC reads, or for any other one-shot async work an app needs (a `fetch`, a third-party SDK call, etc.).
@@ -139,10 +226,10 @@ Fires a one-shot request on mount and re-fires whenever `source` changes identit
 
 ```tsx
 import { useClient, useRequest } from '@solana/react';
-import type { ClientWithRpc, GetLatestBlockhashApi } from '@solana/kit';
+import type { AppClient } from './client';
 
 function LatestBlockhash() {
-    const client = useClient<ClientWithRpc<GetLatestBlockhashApi>>();
+    const client = useClient<AppClient>();
     const source = useMemo(() => client.rpc.getLatestBlockhash(), [client]);
     const { data, error, refresh } = useRequest(source);
     if (error) return <button onClick={refresh}>Retry</button>;
@@ -154,7 +241,7 @@ function LatestBlockhash() {
 
 ```tsx
 function Balance({ address }: { address: Address | null }) {
-    const client = useClient<ClientWithRpc<GetBalanceApi>>();
+    const client = useClient<AppClient>();
     // Disabled until an address is selected.
     const source = useMemo(() => (address ? client.rpc.getBalance(address) : null), [client, address]);
     const { data, status } = useRequest(source);
@@ -209,10 +296,11 @@ Subscribe to a stream-store source and surface the latest notification as reacti
 
 ```tsx
 import { useClient, useSubscription } from '@solana/react';
-import type { Address, AccountNotificationsApi, ClientWithRpcSubscriptions } from '@solana/kit';
+import type { Address } from '@solana/kit';
+import type { AppClient } from './client';
 
 function AccountBalance({ address }: { address: Address }) {
-    const client = useClient<ClientWithRpcSubscriptions<AccountNotificationsApi>>();
+    const client = useClient<AppClient>();
     const source = useMemo(() => client.rpcSubscriptions.accountNotifications(address), [client, address]);
     const { data, error, reconnect } = useSubscription(source);
     if (error) return <button onClick={reconnect}>Reconnect</button>;
@@ -252,16 +340,11 @@ Render reactive state for an RPC subscription seeded by a one-shot RPC fetch, sl
 
 ```tsx
 import { useClient, useTrackedData } from '@solana/react';
-import type {
-    Address,
-    AccountNotificationsApi,
-    ClientWithRpc,
-    ClientWithRpcSubscriptions,
-    GetBalanceApi,
-} from '@solana/kit';
+import type { Address } from '@solana/kit';
+import type { AppClient } from './client';
 
 function AccountBalance({ address }: { address: Address }) {
-    const client = useClient<ClientWithRpc<GetBalanceApi> & ClientWithRpcSubscriptions<AccountNotificationsApi>>();
+    const client = useClient<AppClient>();
     const spec = useMemo(
         () => ({
             rpcRequest: client.rpc.getBalance(address),
@@ -312,10 +395,10 @@ SWR-backed counterpart to `useRequest`. Same `source` shape (a `ReactiveActionSo
 ```tsx
 import { useClient } from '@solana/react';
 import { useRequestSWR } from '@solana/react/swr';
-import type { ClientWithRpc, GetLatestBlockhashApi } from '@solana/kit';
+import type { AppClient } from './client';
 
 function LatestBlockhash() {
-    const client = useClient<ClientWithRpc<GetLatestBlockhashApi>>();
+    const client = useClient<AppClient>();
     const { data, error, isLoading, mutate } = useRequestSWR(['latestBlockhash'], client.rpc.getLatestBlockhash());
     if (error) return <button onClick={() => mutate()}>Retry</button>;
     if (isLoading) return <p>Loading…</p>;
@@ -360,7 +443,7 @@ SWR-backed counterpart to `useSubscription`. Routes a `ReactiveStreamSource<T>`
 
 ```tsx
 function AccountBalance({ address }: { address: Address }) {
-    const client = useClient<ClientWithRpcSubscriptions<AccountNotificationsApi>>();
+    const client = useClient<AppClient>();
     const { data, error } = useSubscriptionSWR(
         address ? ['account', address] : null,
         address ? client.rpcSubscriptions.accountNotifications(address) : null,
@@ -383,7 +466,7 @@ SWR-backed counterpart to `useTrackedData`. Takes the same `TrackedDataSpec` (RP
 
 ```tsx
 function AccountBalance({ address }: { address: Address }) {
-    const client = useClient<ClientWithRpc<GetBalanceApi> & ClientWithRpcSubscriptions<AccountNotificationsApi>>();
+    const client = useClient<AppClient>();
     const spec = useMemo(
         () =>
             address
@@ -418,10 +501,10 @@ TanStack Query-backed counterpart to `useRequest`. Same `source` shape (a `React
 ```tsx
 import { useClient } from '@solana/react';
 import { useRequestQuery } from '@solana/react/query';
-import type { ClientWithRpc, GetLatestBlockhashApi } from '@solana/kit';
+import type { AppClient } from './client';
 
 function LatestBlockhash() {
-    const client = useClient<ClientWithRpc<GetLatestBlockhashApi>>();
+    const client = useClient<AppClient>();
     const { data, error, isLoading, refetch } = useRequestQuery(['latestBlockhash'], client.rpc.getLatestBlockhash());
     if (error) return <button onClick={() => refetch()}>Retry</button>;
     if (isLoading) return <p>Loading…</p>;
@@ -463,10 +546,10 @@ Returns TanStack's native `UseQueryResult<T>`. `data` is the raw notification, e
 ```tsx
 import { useClient } from '@solana/react';
 import { useSubscriptionQuery } from '@solana/react/query';
-import type { ClientWithRpcSubscriptions, SlotNotificationsApi } from '@solana/kit';
+import type { AppClient } from './client';
 
 function SlotHeight() {
-    const client = useClient<ClientWithRpcSubscriptions<SlotNotificationsApi>>();
+    const client = useClient<AppClient>();
     const { data, error } = useSubscriptionQuery(['slot'], client.rpcSubscriptions.slotNotifications());
     if (error) return <p>Disconnected.</p>;
     if (!data) return <p>Connecting…</p>;
@@ -494,16 +577,11 @@ Returns TanStack's native `UseQueryResult`. `data` is the `SolanaRpcResponse<TIt
 ```tsx
 import { useClient } from '@solana/react';
 import { useTrackedDataQuery } from '@solana/react/query';
-import type {
-    Address,
-    AccountNotificationsApi,
-    ClientWithRpc,
-    ClientWithRpcSubscriptions,
-    GetBalanceApi,
-} from '@solana/kit';
+import type { Address } from '@solana/kit';
+import type { AppClient } from './client';
 
 function AccountBalance({ address }: { address: Address }) {
-    const client = useClient<ClientWithRpc<GetBalanceApi> & ClientWithRpcSubscriptions<AccountNotificationsApi>>();
+    const client = useClient<AppClient>();
     const spec = useMemo(
         () => ({
             initialValueSource: client.rpc.getBalance(address),

package/dist/index.browser.cjs

@@ -79,6 +79,11 @@ function useAction(fn) {
     [state, store]
   );
 }
+
+// src/useAirdrop.ts
+function useAirdrop(client) {
+  return useAction((abortSignal, address4, amount) => client.airdrop(address4, amount, abortSignal));
+}
 function useClient() {
   const client = React5__default.default.useContext(ClientContext);
   if (client == null) {
@@ -103,6 +108,48 @@ function useClientCapability({
   }
   return client;
 }
+var NOOP_UNSUBSCRIBE = () => {
+};
+function useIdentity(client) {
+  const subscribe = React5.useCallback(
+    (onStoreChange) => client.subscribeToIdentity ? client.subscribeToIdentity(onStoreChange) : NOOP_UNSUBSCRIBE,
+    [client]
+  );
+  const getSnapshot = React5.useCallback(() => {
+    try {
+      return client.identity;
+    } catch {
+      return void 0;
+    }
+  }, [client]);
+  return React5.useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+var NOOP_UNSUBSCRIBE2 = () => {
+};
+function usePayer(client) {
+  const subscribe = React5.useCallback(
+    (onStoreChange) => client.subscribeToPayer ? client.subscribeToPayer(onStoreChange) : NOOP_UNSUBSCRIBE2,
+    [client]
+  );
+  const getSnapshot = React5.useCallback(() => {
+    try {
+      return client.payer;
+    } catch {
+      return void 0;
+    }
+  }, [client]);
+  return React5.useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+
+// src/usePlanTransaction.ts
+function usePlanTransaction(client) {
+  return useAction((abortSignal, input) => client.planTransaction(input, { abortSignal }));
+}
+
+// src/usePlanTransactions.ts
+function usePlanTransactions(client) {
+  return useAction((abortSignal, input) => client.planTransactions(input, { abortSignal }));
+}
 
 // src/staticStores.ts
 var DISABLED_ACTION_STATE = Object.freeze({
@@ -211,6 +258,16 @@ function useRequest(source, options) {
   const refresh = useReactiveStoreLifecycle(store, fireAction, options?.getAbortSignal);
   return useRequestResult(store, refresh, source == null);
 }
+
+// src/useSendTransaction.ts
+function useSendTransaction(client) {
+  return useAction((abortSignal, input) => client.sendTransaction(input, { abortSignal }));
+}
+
+// src/useSendTransactions.ts
+function useSendTransactions(client) {
+  return useAction((abortSignal, input) => client.sendTransactions(input, { abortSignal }));
+}
 function useSignAndSendTransaction(uiWalletAccount, chain) {
   const signAndSendTransactions = useSignAndSendTransactions(uiWalletAccount, chain);
   return React5.useCallback(
@@ -663,10 +720,17 @@ exports.ClientProvider = ClientProvider;
 exports.SelectedWalletAccountContext = SelectedWalletAccountContext;
 exports.SelectedWalletAccountContextProvider = SelectedWalletAccountContextProvider;
 exports.useAction = useAction;
+exports.useAirdrop = useAirdrop;
 exports.useClient = useClient;
 exports.useClientCapability = useClientCapability;
+exports.useIdentity = useIdentity;
+exports.usePayer = usePayer;
+exports.usePlanTransaction = usePlanTransaction;
+exports.usePlanTransactions = usePlanTransactions;
 exports.useRequest = useRequest;
 exports.useSelectedWalletAccount = useSelectedWalletAccount;
+exports.useSendTransaction = useSendTransaction;
+exports.useSendTransactions = useSendTransactions;
 exports.useSignAndSendTransaction = useSignAndSendTransaction;
 exports.useSignAndSendTransactions = useSignAndSendTransactions;
 exports.useSignIn = useSignIn;