@octanejs/wagmi 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# @octanejs/wagmi
+
+Wagmi v3 bindings for Octane. The package reuses `@wagmi/core`, Viem, and the
+official connectors, while replacing the React provider and hooks with Octane
+bindings backed by `@octanejs/tanstack-query`.
+
+```bash
+pnpm add @octanejs/wagmi @octanejs/tanstack-query viem
+```
+
+```tsrx
+import { QueryClient, QueryClientProvider } from '@octanejs/tanstack-query';
+import { WagmiProvider, createConfig, http, useConnect, useConnection } from '@octanejs/wagmi';
+import { injected } from '@octanejs/wagmi/connectors';
+import { mainnet } from '@octanejs/wagmi/chains';
+
+const config = createConfig({
+	chains: [mainnet],
+	connectors: [injected()],
+	transports: { [mainnet.id]: http() },
+});
+const queryClient = new QueryClient();
+
+function Wallet() @{
+	const connection = useConnection();
+	const connect = useConnect();
+	<button onClick={() => connect.connect({ connector: connect.connectors[0] })}>
+		{connection.address ?? 'Connect wallet'}
+	</button>
+}
+
+function App() @{
+	<WagmiProvider config={config}>
+		<QueryClientProvider client={queryClient}>
+			<Wallet />
+		</QueryClientProvider>
+	</WagmiProvider>
+}
+```
+
+## Supported surface
+
+The first compatibility slice includes config/provider access; connection,
+connect, disconnect, switch-connection, and switch-chain; connector, connection,
+and chain lists; balance; contract read, simulate, and write; transaction send
+and receipt waiting; and message signing.
+
+Wagmi v3 names are authoritative. Deprecated v2 aliases and all remaining hooks
+are intentionally absent until they have behavioral evidence.
+
+## Wallet-action safety
+
+Signing, writing, sending, and wallet-switch prompts set `retry: false` even if a
+shared QueryClient has a mutation retry default. They require a live connected
+connector at dispatch. The binding snapshots the displayed address, chain, and
+connector: replacement before dispatch yields `ActionContextChangedError` and
+does not prompt; replacement after dispatch quarantines the late result in the
+same typed error instead of publishing normal success.
+
+Hydrated state is only an initial UI/cache hint. Use `parseHydratedState` for
+untrusted cookie/SSR input: it is versioned, capped at 16 KiB, schema checked,
+and rejects connector/provider/signature/token material. Privileged actions
+always consult current live connector state.
+
+EIP-1193 event validation, duplicate coalescing, and stale connector-generation
+discarding remain `@wagmi/core` responsibilities. The Octane binding subscribes
+to the core's normalized store; it does not intercept raw provider events or
+claim a second normalization implementation.
+
+## SSR
+
+Set `ssr: true` on the Wagmi config and pass the validated state as
+`initialState`. `WagmiProvider` follows Wagmi's split hydration contract:
+non-SSR configs mount immediately, while SSR configs reconnect after hydration.
+
+## RainbowKit compatibility gate
+
+RainbowKit 2.2.x declares Wagmi v2 peers, but its defining
+`RainbowKitProvider`, `ConnectButton.Custom`, and `useConnectModal` state can be
+derived honestly from this v3 surface. The test suite proves the critical
+disconnected → connecting → connected sequence with a deterministic connector.
+The actual UI/modal implementation belongs to the stacked RainbowKit package.
+
+No test needs a wallet secret, production RPC, or funded account.

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@octanejs/wagmi",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "octane": {
+    "hookSlots": {
+      "manual": [
+        "src"
+      ]
+    }
+  },
+  "description": "Wagmi v3 bindings for Octane over @wagmi/core and @octanejs/tanstack-query.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/wagmi"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md",
+    "status.json"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./connectors": "./src/connectors.ts",
+    "./chains": "./src/chains.ts"
+  },
+  "dependencies": {
+    "@wagmi/connectors": "8.0.25",
+    "@wagmi/core": "3.6.4",
+    "viem": "2.55.10",
+    "@octanejs/tanstack-query": "0.1.20"
+  },
+  "peerDependencies": {
+    "octane": "0.1.21"
+  },
+  "devDependencies": {
+    "@tsrx/react": "^0.2.56",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "vitest": "^4.1.10",
+    "wagmi": "3.7.4",
+    "octane": "0.1.21"
+  },
+  "scripts": {
+    "test": "vitest run --root ../.. --project wagmi"
+  }
+}

package/src/chains.ts

@@ -0,0 +1 @@
+export * from 'viem/chains';

package/src/connectors.ts

@@ -0,0 +1,2 @@
+export { injected, type InjectedParameters } from '@wagmi/connectors/injected';
+export { mock, type MockParameters } from '@wagmi/connectors/mock';

package/src/context.tsrx

@@ -0,0 +1,42 @@
+import { useEffect, useRef } from 'octane';
+import { hydrate, type ResolvedRegister, type State } from '@wagmi/core';
+import type { OctaneNode } from 'octane';
+import { WagmiContext } from './internal';
+
+export type WagmiProviderProps = {
+	config: ResolvedRegister['config'];
+	initialState?: State;
+	reconnectOnMount?: boolean;
+	children?: OctaneNode;
+};
+
+type HydrationLifecycle = {
+	config: ResolvedRegister['config'];
+	onMount: () => Promise<void>;
+};
+
+export function WagmiProvider(props: WagmiProviderProps) @{
+	const reconnectOnMount = props.reconnectOnMount ?? true;
+	const lifecycleRef = useRef<HydrationLifecycle | null>(null);
+	let lifecycle = lifecycleRef.current;
+
+	if (!lifecycle || lifecycle.config !== props.config) {
+		const { onMount } = hydrate(props.config, {
+			initialState: props.initialState,
+			reconnectOnMount,
+		});
+		lifecycle = {
+			config: props.config,
+			onMount,
+		};
+		lifecycleRef.current = lifecycle;
+		if (!props.config._internal.ssr) onMount();
+	}
+
+	useEffect(() => {
+		if (!lifecycle.config._internal.ssr) return;
+		lifecycle.onMount();
+	}, [lifecycle]);
+
+	<WagmiContext.Provider value={props.config}>{props.children}</WagmiContext.Provider>
+}

package/src/context.tsrx.d.ts

@@ -0,0 +1,11 @@
+import type { ResolvedRegister, State } from '@wagmi/core';
+import type { OctaneNode } from 'octane';
+
+export type WagmiProviderProps = {
+	config: ResolvedRegister['config'];
+	initialState?: State;
+	reconnectOnMount?: boolean;
+	children?: OctaneNode;
+};
+
+export declare function WagmiProvider(props: WagmiProviderProps): OctaneNode;

package/src/hooks.ts

@@ -0,0 +1,762 @@
+import { useCallback, useContext, useEffect, useRef, useSyncExternalStore } from 'octane';
+import {
+	getChainId,
+	getChains,
+	getConnection,
+	getConnections,
+	getConnectors,
+	watchChainId,
+	watchConnection,
+	watchConnections,
+	watchConnectors,
+	type Config,
+	type ConnectErrorType,
+	type DisconnectErrorType,
+	type GetBalanceErrorType,
+	type ReadContractErrorType,
+	type SendTransactionErrorType,
+	type ResolvedRegister,
+	type SignMessageErrorType,
+	type SimulateContractErrorType,
+	type SwitchChainErrorType,
+	type SwitchConnectionErrorType,
+	type WaitForTransactionReceiptErrorType,
+	type WriteContractErrorType,
+} from '@wagmi/core';
+import { deepEqual, watchChains } from '@wagmi/core/internal';
+import {
+	connectMutationOptions,
+	disconnectMutationOptions,
+	getBalanceQueryOptions,
+	readContractQueryOptions,
+	sendTransactionMutationOptions,
+	signMessageMutationOptions,
+	simulateContractQueryOptions,
+	switchChainMutationOptions,
+	switchConnectionMutationOptions,
+	waitForTransactionReceiptQueryOptions,
+	writeContractMutationOptions,
+	type ConnectData,
+	type ConnectMutate,
+	type ConnectMutateAsync,
+	type ConnectOptions,
+	type ConnectVariables,
+	type DisconnectData,
+	type DisconnectMutate,
+	type DisconnectMutateAsync,
+	type DisconnectOptions,
+	type DisconnectVariables,
+	type GetBalanceData,
+	type GetBalanceOptions,
+	type ReadContractData,
+	type ReadContractOptions,
+	type SendTransactionData,
+	type SendTransactionMutate,
+	type SendTransactionMutateAsync,
+	type SendTransactionOptions,
+	type SendTransactionVariables,
+	type SignMessageData,
+	type SignMessageMutate,
+	type SignMessageMutateAsync,
+	type SignMessageOptions,
+	type SignMessageVariables,
+	type SimulateContractData,
+	type SimulateContractOptions,
+	type SwitchChainData,
+	type SwitchChainMutate,
+	type SwitchChainMutateAsync,
+	type SwitchChainOptions,
+	type SwitchChainVariables,
+	type SwitchConnectionData,
+	type SwitchConnectionMutate,
+	type SwitchConnectionMutateAsync,
+	type SwitchConnectionOptions,
+	type SwitchConnectionVariables,
+	type WaitForTransactionReceiptData,
+	type WaitForTransactionReceiptOptions,
+	type WriteContractData,
+	type WriteContractMutate,
+	type WriteContractMutateAsync,
+	type WriteContractOptions,
+	type WriteContractVariables,
+} from '@wagmi/core/query';
+import type { Abi, ContractFunctionArgs, ContractFunctionName } from 'viem';
+import {
+	useMutation,
+	useQuery,
+	type UseMutationOptions,
+	type UseMutationResult,
+	type UseQueryOptions,
+	type UseQueryResult,
+} from '@octanejs/tanstack-query';
+import { WagmiContext, subSlot } from './internal';
+import { secureMutationOptions } from './security';
+
+type ParametersWithConfig<config extends Config = Config> = {
+	config?: config;
+	[key: string]: unknown;
+};
+
+const useMutationWithSlot = useMutation as unknown as <data, error, variables, context>(
+	options: UseMutationOptions<data, error, variables, context>,
+	queryClient: undefined,
+	slot: symbol | undefined,
+) => UseMutationResult<data, error, variables, context>;
+
+const useQueryWithSlot = useQuery as unknown as <queryData, error, data>(
+	options: UseQueryOptions<queryData, error, data>,
+	queryClient: undefined,
+	slot: symbol | undefined,
+) => UseQueryResult<data, error>;
+
+function useOctaneMutation<data, error, variables, context>(
+	options: UseMutationOptions<data, error, variables, context>,
+	slot: symbol | undefined,
+): UseMutationResult<data, error, variables, context> {
+	return useMutationWithSlot(options, undefined, slot);
+}
+
+function useOctaneQuery<queryData, error, data>(
+	options: UseQueryOptions<queryData, error, data>,
+	slot: symbol | undefined,
+): UseQueryResult<data, error> {
+	return useQueryWithSlot(options, undefined, slot);
+}
+
+function argumentsAndSlot(
+	parameters: ParametersWithConfig | symbol | undefined,
+	rest: unknown[],
+): [ParametersWithConfig, symbol | undefined] {
+	if (typeof parameters === 'symbol') return [{}, parameters];
+	const tail = rest.at(-1);
+	return [parameters ?? {}, typeof tail === 'symbol' ? tail : undefined];
+}
+
+export class WagmiProviderNotFoundError extends Error {
+	override name = 'WagmiProviderNotFoundError';
+	constructor() {
+		super('`useConfig` must be used within `WagmiProvider` or receive a `config` option.');
+	}
+}
+
+export function useConfig<config extends Config = ResolvedRegister['config']>(
+	parameters: { config?: config } | symbol = {},
+): config {
+	const direct = typeof parameters === 'symbol' ? undefined : parameters.config;
+	const context = useContext(WagmiContext);
+	const config = direct ?? context;
+	if (!config) throw new WagmiProviderNotFoundError();
+	return config as config;
+}
+
+function useSnapshot<T>(
+	subscribe: (onChange: () => void) => () => void,
+	getSnapshot: () => T,
+	slot: symbol | undefined,
+): T {
+	const cached = useRef<T | undefined>(undefined, subSlot(slot, 'cache'));
+	const stableSnapshot = () => {
+		const next = getSnapshot();
+		if (cached.current !== undefined && deepEqual(cached.current, next)) return cached.current;
+		cached.current = next;
+		return next;
+	};
+	return useSyncExternalStore(
+		subscribe,
+		stableSnapshot,
+		stableSnapshot,
+		subSlot(slot, 'external-store'),
+	);
+}
+
+export function useConnection<config extends Config = ResolvedRegister['config']>(
+	parameters: ParametersWithConfig<config> | symbol = {},
+	...rest: unknown[]
+) {
+	const [options, slot] = argumentsAndSlot(parameters, rest);
+	const config = useConfig(options);
+	const subscribe = useCallback(
+		(onChange: () => void) => watchConnection(config, { onChange }),
+		[config],
+		subSlot(slot, 'subscribe'),
+	);
+	return useSnapshot(subscribe, () => getConnection(config), slot);
+}
+
+export function useChainId<config extends Config = ResolvedRegister['config']>(
+	parameters: ParametersWithConfig<config> | symbol = {},
+	...rest: unknown[]
+) {
+	const [options, slot] = argumentsAndSlot(parameters, rest);
+	const config = useConfig(options);
+	const subscribe = useCallback(
+		(onChange: () => void) => watchChainId(config, { onChange }),
+		[config],
+		subSlot(slot, 'subscribe'),
+	);
+	return useSnapshot(subscribe, () => getChainId(config), slot);
+}
+
+export function useChains<config extends Config = ResolvedRegister['config']>(
+	parameters: ParametersWithConfig<config> | symbol = {},
+	...rest: unknown[]
+) {
+	const [options, slot] = argumentsAndSlot(parameters, rest);
+	const config = useConfig(options);
+	const subscribe = useCallback(
+		(onChange: () => void) => watchChains(config, { onChange }),
+		[config],
+		subSlot(slot, 'subscribe'),
+	);
+	return useSnapshot(subscribe, () => getChains(config), slot);
+}
+
+export function useConnectors<config extends Config = ResolvedRegister['config']>(
+	parameters: ParametersWithConfig<config> | symbol = {},
+	...rest: unknown[]
+) {
+	const [options, slot] = argumentsAndSlot(parameters, rest);
+	const config = useConfig(options);
+	const subscribe = useCallback(
+		(onChange: () => void) => watchConnectors(config, { onChange }),
+		[config],
+		subSlot(slot, 'subscribe'),
+	);
+	return useSnapshot(subscribe, () => getConnectors(config), slot);
+}
+
+export function useConnections(parameters: ParametersWithConfig | symbol = {}, ...rest: unknown[]) {
+	const [options, slot] = argumentsAndSlot(parameters, rest);
+	const config = useConfig(options);
+	const subscribe = useCallback(
+		(onChange: () => void) => watchConnections(config, { onChange }),
+		[config],
+		subSlot(slot, 'subscribe'),
+	);
+	return useSnapshot(subscribe, () => getConnections(config), slot);
+}
+
+function useFactoryMutation<data, error, variables, context>(
+	factory: (
+		config: Config,
+		parameters: ParametersWithConfig,
+	) => UseMutationOptions<data, error, variables, context>,
+	parameters: ParametersWithConfig | symbol | undefined,
+	rest: unknown[],
+	privileged = false,
+	securityAction: 'privileged' | 'switchChain' | 'switchConnection' = 'privileged',
+): UseMutationResult<data, error, variables, context> {
+	const [options, slot] = argumentsAndSlot(parameters, rest);
+	const config = useConfig(options);
+	const mutationOptions = factory(config, options);
+	return useOctaneMutation(
+		privileged
+			? secureMutationOptions(config, mutationOptions, undefined, securityAction)
+			: mutationOptions,
+		subSlot(slot, 'mutation'),
+	);
+}
+
+export type UseConnectParameters<
+	config extends Config = Config,
+	context = unknown,
+> = ConnectOptions<config, context> & { config?: config };
+
+export type UseConnectReturnType<config extends Config = Config, context = unknown> = Omit<
+	UseMutationResult<
+		ConnectData<config, config['connectors'][number], boolean>,
+		ConnectErrorType,
+		ConnectVariables<config, config['connectors'][number], boolean>,
+		context
+	>,
+	'mutate' | 'mutateAsync'
+> & {
+	mutate: ConnectMutate<config, context>;
+	mutateAsync: ConnectMutateAsync<config, context>;
+	connect: ConnectMutate<config, context>;
+	connectAsync: ConnectMutateAsync<config, context>;
+	connectors: config['connectors'];
+};
+
+export function useConnect<config extends Config = ResolvedRegister['config'], context = unknown>(
+	parameters?: UseConnectParameters<config, context> | symbol,
+	...rest: unknown[]
+): UseConnectReturnType<config, context>;
+export function useConnect(parameters: ParametersWithConfig | symbol = {}, ...rest: unknown[]) {
+	const [options, slot] = argumentsAndSlot(parameters, rest);
+	const config = useConfig(options);
+	const mutationOptions = connectMutationOptions(
+		config,
+		options as UseConnectParameters<typeof config>,
+	);
+	const mutation = useOctaneMutation(
+		{ ...mutationOptions, retry: false },
+		subSlot(slot, 'mutation'),
+	);
+	useEffect(
+		() =>
+			config.subscribe(
+				({ status }) => status,
+				(status, previous) => {
+					if (previous === 'connected' && status === 'disconnected') mutation.reset();
+				},
+			),
+		[config, mutation.reset],
+		subSlot(slot, 'reset'),
+	);
+	return {
+		...mutation,
+		connect: mutation.mutate,
+		connectAsync: mutation.mutateAsync,
+		connectors: useConnectors({ config }, subSlot(slot, 'connectors')),
+	} as UseConnectReturnType<typeof config>;
+}
+
+type AliasedMutationResult<data, error, variables, context, mutate, mutateAsync> = Omit<
+	UseMutationResult<data, error, variables, context>,
+	'mutate' | 'mutateAsync'
+> & {
+	mutate: mutate;
+	mutateAsync: mutateAsync;
+};
+
+export type UseDisconnectParameters<context = unknown> = DisconnectOptions<context> & {
+	config?: Config;
+};
+export type UseDisconnectReturnType<context = unknown> = AliasedMutationResult<
+	DisconnectData,
+	DisconnectErrorType,
+	DisconnectVariables,
+	context,
+	DisconnectMutate<context>,
+	DisconnectMutateAsync<context>
+> & {
+	disconnect: DisconnectMutate<context>;
+	disconnectAsync: DisconnectMutateAsync<context>;
+	connectors: ReturnType<typeof useConnections>[number]['connector'][];
+};
+
+export function useDisconnect<context = unknown>(
+	parameters?: UseDisconnectParameters<context> | symbol,
+	...rest: unknown[]
+): UseDisconnectReturnType<context>;
+export function useDisconnect(parameters: ParametersWithConfig | symbol = {}, ...rest: unknown[]) {
+	const mutation = useFactoryMutation<
+		DisconnectData,
+		DisconnectErrorType,
+		DisconnectVariables,
+		unknown
+	>(
+		(config, options) => disconnectMutationOptions(config, options as DisconnectOptions<unknown>),
+		parameters,
+		rest,
+	);
+	const [options, slot] = argumentsAndSlot(parameters, rest);
+	const config = useConfig(options);
+	return {
+		...mutation,
+		disconnect: mutation.mutate,
+		disconnectAsync: mutation.mutateAsync,
+		connectors: useConnections({ config }, subSlot(slot, 'connections')).map(
+			(connection) => connection.connector,
+		),
+	} as UseDisconnectReturnType;
+}
+
+export type UseSwitchConnectionParameters<
+	config extends Config = Config,
+	context = unknown,
+> = SwitchConnectionOptions<config, context> & { config?: config };
+export type UseSwitchConnectionReturnType<
+	config extends Config = Config,
+	context = unknown,
+> = AliasedMutationResult<
+	SwitchConnectionData<config>,
+	SwitchConnectionErrorType,
+	SwitchConnectionVariables,
+	context,
+	SwitchConnectionMutate<config, context>,
+	SwitchConnectionMutateAsync<config, context>
+> & {
+	switchConnection: SwitchConnectionMutate<config, context>;
+	switchConnectionAsync: SwitchConnectionMutateAsync<config, context>;
+	connectors: ReturnType<typeof useConnections>[number]['connector'][];
+};
+
+export function useSwitchConnection<
+	config extends Config = ResolvedRegister['config'],
+	context = unknown,
+>(
+	parameters?: UseSwitchConnectionParameters<config, context> | symbol,
+	...rest: unknown[]
+): UseSwitchConnectionReturnType<config, context>;
+export function useSwitchConnection(
+	parameters: ParametersWithConfig | symbol = {},
+	...rest: unknown[]
+) {
+	const mutation = useFactoryMutation<
+		SwitchConnectionData<Config>,
+		SwitchConnectionErrorType,
+		SwitchConnectionVariables,
+		unknown
+	>(
+		(config, options) =>
+			switchConnectionMutationOptions(config, options as SwitchConnectionOptions<Config, unknown>),
+		parameters,
+		rest,
+		true,
+		'switchConnection',
+	);
+	const [options, slot] = argumentsAndSlot(parameters, rest);
+	const config = useConfig(options);
+	return {
+		...mutation,
+		switchConnection: mutation.mutate,
+		switchConnectionAsync: mutation.mutateAsync,
+		connectors: useConnections({ config }, subSlot(slot, 'connections')).map(
+			(connection) => connection.connector,
+		),
+	} as UseSwitchConnectionReturnType;
+}
+
+export type UseSwitchChainParameters<
+	config extends Config = Config,
+	context = unknown,
+> = SwitchChainOptions<config, context> & { config?: config };
+export type UseSwitchChainReturnType<
+	config extends Config = Config,
+	context = unknown,
+> = AliasedMutationResult<
+	SwitchChainData<config, config['chains'][number]['id']>,
+	SwitchChainErrorType,
+	SwitchChainVariables<config, config['chains'][number]['id']>,
+	context,
+	SwitchChainMutate<config, context>,
+	SwitchChainMutateAsync<config, context>
+> & {
+	switchChain: SwitchChainMutate<config, context>;
+	switchChainAsync: SwitchChainMutateAsync<config, context>;
+	chains: config['chains'];
+};
+
+export function useSwitchChain<
+	config extends Config = ResolvedRegister['config'],
+	context = unknown,
+>(
+	parameters?: UseSwitchChainParameters<config, context> | symbol,
+	...rest: unknown[]
+): UseSwitchChainReturnType<config, context>;
+export function useSwitchChain(parameters: ParametersWithConfig | symbol = {}, ...rest: unknown[]) {
+	const mutation = useFactoryMutation<
+		SwitchChainData<Config, Config['chains'][number]['id']>,
+		SwitchChainErrorType,
+		SwitchChainVariables<Config, Config['chains'][number]['id']>,
+		unknown
+	>(
+		(config, options) =>
+			switchChainMutationOptions(config, options as SwitchChainOptions<Config, unknown>),
+		parameters,
+		rest,
+		true,
+		'switchChain',
+	);
+	const [options, slot] = argumentsAndSlot(parameters, rest);
+	const config = useConfig(options);
+	return {
+		...mutation,
+		switchChain: mutation.mutate,
+		switchChainAsync: mutation.mutateAsync,
+		chains: useChains({ config }, subSlot(slot, 'chains')),
+	} as UseSwitchChainReturnType;
+}
+
+function useCoreQuery(
+	factory: unknown,
+	parameters: ParametersWithConfig | symbol | undefined,
+	rest: unknown[],
+	options: { account?: boolean; chain?: boolean } = {},
+) {
+	const [input, slot] = argumentsAndSlot(parameters, rest);
+	const config = useConfig(input);
+	const chainId = useChainId({ config }, subSlot(slot, 'chain'));
+	const connection = options.account
+		? useConnection({ config }, subSlot(slot, 'connection'))
+		: undefined;
+	const queryOptions = (
+		factory as (
+			config: Config,
+			parameters: ParametersWithConfig,
+		) => UseQueryOptions<unknown, unknown, unknown>
+	)(config, {
+		...input,
+		...(options.account
+			? {
+					account: input.account ?? connection?.address,
+					connector: input.connector ?? connection?.connector,
+				}
+			: {}),
+		...(options.chain ? { chainId: input.chainId ?? chainId } : {}),
+	});
+	return useOctaneQuery(queryOptions, subSlot(slot, 'query'));
+}
+
+export type UseBalanceParameters<
+	config extends Config = Config,
+	selectData = GetBalanceData,
+> = GetBalanceOptions<config, selectData> & { config?: config };
+export type UseBalanceReturnType<selectData = GetBalanceData> = UseQueryResult<
+	selectData,
+	GetBalanceErrorType
+>;
+
+export function useBalance<
+	config extends Config = ResolvedRegister['config'],
+	selectData = GetBalanceData,
+>(
+	parameters?: UseBalanceParameters<config, selectData> | symbol,
+	...rest: unknown[]
+): UseBalanceReturnType<selectData>;
+export function useBalance(parameters: ParametersWithConfig | symbol = {}, ...rest: unknown[]) {
+	return useCoreQuery(getBalanceQueryOptions, parameters, rest, { chain: true });
+}
+
+export type UseReadContractParameters<
+	abi extends Abi | readonly unknown[] = Abi,
+	functionName extends ContractFunctionName<abi, 'pure' | 'view'> = ContractFunctionName<
+		abi,
+		'pure' | 'view'
+	>,
+	args extends ContractFunctionArgs<abi, 'pure' | 'view', functionName> = ContractFunctionArgs<
+		abi,
+		'pure' | 'view',
+		functionName
+	>,
+	config extends Config = Config,
+	selectData = ReadContractData<abi, functionName, args>,
+> = ReadContractOptions<abi, functionName, args, config, selectData> & { config?: config };
+export type UseReadContractReturnType<
+	abi extends Abi | readonly unknown[],
+	functionName extends ContractFunctionName<abi, 'pure' | 'view'>,
+	args extends ContractFunctionArgs<abi, 'pure' | 'view', functionName>,
+	selectData = ReadContractData<abi, functionName, args>,
+> = UseQueryResult<selectData, ReadContractErrorType>;
+
+export function useReadContract<
+	const abi extends Abi | readonly unknown[],
+	functionName extends ContractFunctionName<abi, 'pure' | 'view'>,
+	const args extends ContractFunctionArgs<abi, 'pure' | 'view', functionName>,
+	config extends Config = ResolvedRegister['config'],
+	selectData = ReadContractData<abi, functionName, args>,
+>(
+	parameters?: UseReadContractParameters<abi, functionName, args, config, selectData> | symbol,
+	...rest: unknown[]
+): UseReadContractReturnType<abi, functionName, args, selectData>;
+export function useReadContract(
+	parameters: ParametersWithConfig | symbol = {},
+	...rest: unknown[]
+) {
+	return useCoreQuery(readContractQueryOptions, parameters, rest, { chain: true });
+}
+
+export type UseSimulateContractParameters<
+	abi extends Abi | readonly unknown[] = Abi,
+	functionName extends ContractFunctionName<abi, 'nonpayable' | 'payable'> = ContractFunctionName<
+		abi,
+		'nonpayable' | 'payable'
+	>,
+	args extends ContractFunctionArgs<abi, 'nonpayable' | 'payable', functionName> =
+		ContractFunctionArgs<abi, 'nonpayable' | 'payable', functionName>,
+	config extends Config = Config,
+	chainId extends config['chains'][number]['id'] | undefined = config['chains'][number]['id'],
+	selectData = SimulateContractData<abi, functionName, args, config, chainId>,
+> = SimulateContractOptions<abi, functionName, args, config, chainId, selectData> & {
+	config?: config;
+};
+export type UseSimulateContractReturnType<
+	abi extends Abi | readonly unknown[],
+	functionName extends ContractFunctionName<abi, 'nonpayable' | 'payable'>,
+	args extends ContractFunctionArgs<abi, 'nonpayable' | 'payable', functionName>,
+	config extends Config,
+	chainId extends config['chains'][number]['id'] | undefined,
+	selectData = SimulateContractData<abi, functionName, args, config, chainId>,
+> = UseQueryResult<selectData, SimulateContractErrorType>;
+
+export function useSimulateContract<
+	const abi extends Abi | readonly unknown[],
+	functionName extends ContractFunctionName<abi, 'nonpayable' | 'payable'>,
+	const args extends ContractFunctionArgs<abi, 'nonpayable' | 'payable', functionName>,
+	config extends Config = ResolvedRegister['config'],
+	chainId extends config['chains'][number]['id'] | undefined = config['chains'][number]['id'],
+	selectData = SimulateContractData<abi, functionName, args, config, chainId>,
+>(
+	parameters?:
+		UseSimulateContractParameters<abi, functionName, args, config, chainId, selectData> | symbol,
+	...rest: unknown[]
+): UseSimulateContractReturnType<abi, functionName, args, config, chainId, selectData>;
+export function useSimulateContract(
+	parameters: ParametersWithConfig | symbol = {},
+	...rest: unknown[]
+) {
+	return useCoreQuery(simulateContractQueryOptions, parameters, rest, {
+		account: true,
+		chain: true,
+	});
+}
+
+export type UseWaitForTransactionReceiptParameters<
+	config extends Config = Config,
+	chainId extends config['chains'][number]['id'] = config['chains'][number]['id'],
+	selectData = WaitForTransactionReceiptData<config, chainId>,
+> = WaitForTransactionReceiptOptions<config, chainId, selectData> & { config?: config };
+export type UseWaitForTransactionReceiptReturnType<selectData> = UseQueryResult<
+	selectData,
+	WaitForTransactionReceiptErrorType
+>;
+
+export function useWaitForTransactionReceipt<
+	config extends Config = ResolvedRegister['config'],
+	chainId extends config['chains'][number]['id'] = config['chains'][number]['id'],
+	selectData = WaitForTransactionReceiptData<config, chainId>,
+>(
+	parameters?: UseWaitForTransactionReceiptParameters<config, chainId, selectData> | symbol,
+	...rest: unknown[]
+): UseWaitForTransactionReceiptReturnType<selectData>;
+export function useWaitForTransactionReceipt(
+	parameters: ParametersWithConfig | symbol = {},
+	...rest: unknown[]
+) {
+	return useCoreQuery(waitForTransactionReceiptQueryOptions, parameters, rest, { chain: true });
+}
+
+export type UseWriteContractParameters<
+	config extends Config = Config,
+	context = unknown,
+> = WriteContractOptions<config, context> & { config?: config };
+export type UseWriteContractReturnType<
+	config extends Config = Config,
+	context = unknown,
+> = AliasedMutationResult<
+	WriteContractData,
+	WriteContractErrorType,
+	WriteContractVariables<Abi, string, readonly unknown[], config, config['chains'][number]['id']>,
+	context,
+	WriteContractMutate<config, context>,
+	WriteContractMutateAsync<config, context>
+> & {
+	writeContract: WriteContractMutate<config, context>;
+	writeContractAsync: WriteContractMutateAsync<config, context>;
+};
+
+export function useWriteContract<
+	config extends Config = ResolvedRegister['config'],
+	context = unknown,
+>(
+	parameters?: UseWriteContractParameters<config, context> | symbol,
+	...rest: unknown[]
+): UseWriteContractReturnType<config, context>;
+export function useWriteContract(
+	parameters: ParametersWithConfig | symbol = {},
+	...rest: unknown[]
+) {
+	const mutation = useFactoryMutation<
+		WriteContractData,
+		WriteContractErrorType,
+		WriteContractVariables<Abi, string, readonly unknown[], Config, Config['chains'][number]['id']>,
+		unknown
+	>(
+		(config, options) =>
+			writeContractMutationOptions(config, options as WriteContractOptions<Config, unknown>),
+		parameters,
+		rest,
+		true,
+	);
+	return {
+		...mutation,
+		writeContract: mutation.mutate,
+		writeContractAsync: mutation.mutateAsync,
+	} as UseWriteContractReturnType;
+}
+
+export type UseSendTransactionParameters<
+	config extends Config = Config,
+	context = unknown,
+> = SendTransactionOptions<config, context> & { config?: config };
+export type UseSendTransactionReturnType<
+	config extends Config = Config,
+	context = unknown,
+> = AliasedMutationResult<
+	SendTransactionData,
+	SendTransactionErrorType,
+	SendTransactionVariables<config, config['chains'][number]['id']>,
+	context,
+	SendTransactionMutate<config, context>,
+	SendTransactionMutateAsync<config, context>
+> & {
+	sendTransaction: SendTransactionMutate<config, context>;
+	sendTransactionAsync: SendTransactionMutateAsync<config, context>;
+};
+
+export function useSendTransaction<
+	config extends Config = ResolvedRegister['config'],
+	context = unknown,
+>(
+	parameters?: UseSendTransactionParameters<config, context> | symbol,
+	...rest: unknown[]
+): UseSendTransactionReturnType<config, context>;
+export function useSendTransaction(
+	parameters: ParametersWithConfig | symbol = {},
+	...rest: unknown[]
+) {
+	const mutation = useFactoryMutation<
+		SendTransactionData,
+		SendTransactionErrorType,
+		SendTransactionVariables<Config, Config['chains'][number]['id']>,
+		unknown
+	>(
+		(config, options) =>
+			sendTransactionMutationOptions(config, options as SendTransactionOptions<Config, unknown>),
+		parameters,
+		rest,
+		true,
+	);
+	return {
+		...mutation,
+		sendTransaction: mutation.mutate,
+		sendTransactionAsync: mutation.mutateAsync,
+	} as UseSendTransactionReturnType;
+}
+
+export type UseSignMessageParameters<context = unknown> = SignMessageOptions<context> & {
+	config?: Config;
+};
+export type UseSignMessageReturnType<context = unknown> = Omit<
+	UseMutationResult<SignMessageData, SignMessageErrorType, SignMessageVariables, context>,
+	'mutate' | 'mutateAsync'
+> & {
+	mutate: SignMessageMutate<context>;
+	mutateAsync: SignMessageMutateAsync<context>;
+	signMessage: SignMessageMutate<context>;
+	signMessageAsync: SignMessageMutateAsync<context>;
+};
+
+export function useSignMessage<context = unknown>(
+	parameters: UseSignMessageParameters<context> | symbol = {},
+	...rest: unknown[]
+): UseSignMessageReturnType<context> {
+	const mutation = useFactoryMutation<
+		SignMessageData,
+		SignMessageErrorType,
+		SignMessageVariables,
+		unknown
+	>(
+		(config, options) => signMessageMutationOptions(config, options as SignMessageOptions<context>),
+		parameters as ParametersWithConfig | symbol,
+		rest,
+		true,
+	);
+	return {
+		...mutation,
+		signMessage: mutation.mutate,
+		signMessageAsync: mutation.mutateAsync,
+	} as UseSignMessageReturnType<context>;
+}

package/src/index.ts

@@ -0,0 +1,54 @@
+export * from '@wagmi/core';
+export { WagmiContext } from './internal';
+export { WagmiProvider, type WagmiProviderProps } from './context.tsrx';
+export {
+	WagmiProviderNotFoundError,
+	type UseBalanceParameters,
+	type UseBalanceReturnType,
+	type UseConnectParameters,
+	type UseConnectReturnType,
+	type UseDisconnectParameters,
+	type UseDisconnectReturnType,
+	type UseReadContractParameters,
+	type UseReadContractReturnType,
+	type UseSendTransactionParameters,
+	type UseSendTransactionReturnType,
+	type UseSignMessageParameters,
+	type UseSignMessageReturnType,
+	type UseSimulateContractParameters,
+	type UseSimulateContractReturnType,
+	type UseSwitchChainParameters,
+	type UseSwitchChainReturnType,
+	type UseSwitchConnectionParameters,
+	type UseSwitchConnectionReturnType,
+	type UseWaitForTransactionReceiptParameters,
+	type UseWaitForTransactionReceiptReturnType,
+	type UseWriteContractParameters,
+	type UseWriteContractReturnType,
+	useBalance,
+	useChainId,
+	useChains,
+	useConfig,
+	useConnect,
+	useConnection,
+	useConnections,
+	useConnectors,
+	useDisconnect,
+	useReadContract,
+	useSendTransaction,
+	useSignMessage,
+	useSimulateContract,
+	useSwitchChain,
+	useSwitchConnection,
+	useWaitForTransactionReceipt,
+	useWriteContract,
+} from './hooks';
+export {
+	HYDRATION_VERSION,
+	MAX_HYDRATION_BYTES,
+	parseHydratedState,
+	secureMutationOptions,
+	serializeHydratedState,
+	ActionContextChangedError,
+	LiveConnectionRequiredError,
+} from './security';

package/src/internal.ts

@@ -0,0 +1,21 @@
+import { createContext } from 'octane';
+import type { ResolvedRegister } from '@wagmi/core';
+
+export const WagmiContext = createContext<ResolvedRegister['config'] | undefined>(undefined);
+
+const slots = new Map<symbol, Map<string, symbol>>();
+
+export function subSlot(slot: symbol | undefined, tag: string): symbol | undefined {
+	if (!slot) return undefined;
+	let children = slots.get(slot);
+	if (!children) {
+		children = new Map();
+		slots.set(slot, children);
+	}
+	let child = children.get(tag);
+	if (!child) {
+		child = Symbol.for(`${slot.description ?? ''}:${tag}`);
+		children.set(tag, child);
+	}
+	return child;
+}

package/src/security.ts

@@ -0,0 +1,186 @@
+import type { State } from '@wagmi/core';
+import { getChainId, getConnection, type Config } from '@wagmi/core';
+
+export const HYDRATION_VERSION = 1;
+export const MAX_HYDRATION_BYTES = 16_384;
+
+export class LiveConnectionRequiredError extends Error {
+	override name = 'LiveConnectionRequiredError';
+	constructor() {
+		super('A current live connector is required for this privileged action.');
+	}
+}
+
+export class ActionContextChangedError extends Error {
+	override name = 'ActionContextChangedError';
+	readonly phase: 'before-dispatch' | 'after-dispatch';
+	constructor(phase: 'before-dispatch' | 'after-dispatch') {
+		super(
+			phase === 'before-dispatch'
+				? 'Wallet context changed before dispatch; the action was cancelled.'
+				: 'Wallet context changed after dispatch; the result is indeterminate and quarantined.',
+		);
+		this.phase = phase;
+	}
+}
+
+export type SecureMutationAction = 'privileged' | 'switchChain' | 'switchConnection';
+
+function actionContext(config: Config) {
+	const connection = getConnection(config);
+	return {
+		address: connection.address,
+		chainId: connection.status === 'connected' ? connection.chainId : getChainId(config),
+		connector: connection.connector?.uid,
+		status: connection.status,
+	};
+}
+
+function sameContext(a: ReturnType<typeof actionContext>, b: ReturnType<typeof actionContext>) {
+	return (
+		a.address === b.address &&
+		a.chainId === b.chainId &&
+		a.connector === b.connector &&
+		a.status === b.status
+	);
+}
+
+function sameIdentity(a: ReturnType<typeof actionContext>, b: ReturnType<typeof actionContext>) {
+	return a.address === b.address && a.connector === b.connector && a.status === b.status;
+}
+
+function variableRecord(value: unknown): Record<string, any> {
+	return isRecord(value) ? value : {};
+}
+
+function connectorUid(value: unknown): string | undefined {
+	return isRecord(value) && typeof value.uid === 'string' ? value.uid : undefined;
+}
+
+function accountAddress(value: unknown): string | undefined {
+	if (typeof value === 'string') return value;
+	return isRecord(value) && typeof value.address === 'string' ? value.address : undefined;
+}
+
+function sameAddress(a: string | undefined, b: string | undefined) {
+	return a?.toLowerCase() === b?.toLowerCase();
+}
+
+function variablesMatchLiveContext(
+	variables: unknown,
+	context: ReturnType<typeof actionContext>,
+	action: SecureMutationAction,
+) {
+	const input = variableRecord(variables);
+	if (action !== 'switchConnection' && 'connector' in input) {
+		if (connectorUid(input.connector) !== context.connector) return false;
+	}
+	if ('account' in input && !sameAddress(accountAddress(input.account), context.address))
+		return false;
+	return true;
+}
+
+function validPostDispatchContext(
+	action: SecureMutationAction,
+	before: ReturnType<typeof actionContext>,
+	after: ReturnType<typeof actionContext>,
+	variables: unknown,
+	result: unknown,
+) {
+	if (action === 'privileged') return sameContext(before, after);
+	if (action === 'switchChain') {
+		const chainId = variableRecord(variables).chainId;
+		return sameIdentity(before, after) && after.chainId === chainId;
+	}
+
+	const targetUid = connectorUid(variableRecord(variables).connector);
+	const returned = variableRecord(result);
+	const returnedAddress = Array.isArray(returned.accounts) ? returned.accounts[0] : undefined;
+	return (
+		after.status === 'connected' &&
+		after.connector === targetUid &&
+		(typeof returned.chainId !== 'number' || after.chainId === returned.chainId) &&
+		(typeof returnedAddress !== 'string' || sameAddress(after.address, returnedAddress))
+	);
+}
+
+/**
+ * Hardens a Wagmi mutation option object without retrying wallet prompts.
+ * Late success is deliberately converted to a typed quarantined error.
+ */
+export function secureMutationOptions(
+	config: Config,
+	options: Record<string, any>,
+	displayed = actionContext(config),
+	action: SecureMutationAction = 'privileged',
+) {
+	const mutationFn = options.mutationFn;
+	if (typeof mutationFn !== 'function') return { ...options, retry: false };
+	return {
+		...options,
+		retry: false,
+		async mutationFn(variables: unknown) {
+			const before = actionContext(config);
+			const disconnectedLocalSwitch =
+				action === 'switchChain' &&
+				before.status === 'disconnected' &&
+				!before.connector &&
+				!('connector' in variableRecord(variables));
+			if (!disconnectedLocalSwitch && (before.status !== 'connected' || !before.connector))
+				throw new LiveConnectionRequiredError();
+			if (!sameContext(displayed, before)) throw new ActionContextChangedError('before-dispatch');
+			if (!variablesMatchLiveContext(variables, before, action))
+				throw new ActionContextChangedError('before-dispatch');
+			const result = await mutationFn(variables);
+			if (!validPostDispatchContext(action, before, actionContext(config), variables, result))
+				throw new ActionContextChangedError('after-dispatch');
+			return result;
+		},
+	};
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isSafeState(value: unknown): value is State {
+	if (!isRecord(value)) return false;
+	if (!['connected', 'connecting', 'disconnected', 'reconnecting'].includes(String(value.status)))
+		return false;
+	if (!Array.isArray(value.connections) && !(value.connections instanceof Map)) return false;
+	if (typeof value.chainId !== 'number' || !Number.isSafeInteger(value.chainId)) return false;
+	return true;
+}
+
+/** Parse an untrusted SSR/cookie hint. Connector and provider objects are never accepted. */
+export function parseHydratedState(input: string): State | undefined {
+	if (new TextEncoder().encode(input).byteLength > MAX_HYDRATION_BYTES) return undefined;
+	try {
+		const envelope: unknown = JSON.parse(input);
+		if (!isRecord(envelope) || envelope.version !== HYDRATION_VERSION) return undefined;
+		if (!isSafeState(envelope.state)) return undefined;
+		const state = envelope.state as unknown as Record<string, unknown>;
+		if ('connector' in state || 'provider' in state || 'signature' in state || 'token' in state)
+			return undefined;
+		return {
+			...(envelope.state as State),
+			// Untrusted JSON cannot carry live connector instances. Connections are
+			// deliberately rebuilt by Wagmi reconnect rather than trusted here.
+			connections: new Map(),
+			current: null,
+			status: 'disconnected',
+		};
+	} catch {
+		return undefined;
+	}
+}
+
+export function serializeHydratedState(state: State): string | undefined {
+	const connections = state.connections instanceof Map ? [] : state.connections;
+	const safe = {
+		version: HYDRATION_VERSION,
+		state: { chainId: state.chainId, connections, current: state.current, status: state.status },
+	};
+	const value = JSON.stringify(safe);
+	return new TextEncoder().encode(value).byteLength <= MAX_HYDRATION_BYTES ? value : undefined;
+}

package/status.json

@@ -0,0 +1,46 @@
+{
+  "upstream": {
+    "package": "wagmi",
+    "version": "3.7.4"
+  },
+  "surface": "WagmiProvider and createConfig over @wagmi/core 3.6.4, with config, connection, connect, disconnect, switch-connection, switch-chain, connectors, connections, chains, balance, contract read/simulate/write, transaction send/wait, and message-signing hooks.",
+  "divergences": [
+    "The binding targets Wagmi v3 names. Deprecated v2 useAccount/useSwitchAccount aliases and hooks outside the documented representative inventory are not exported.",
+    "Privileged mutation hooks force retry:false, require a current live connector, cancel before dispatch when the displayed wallet context changed, and quarantine a late success as ActionContextChangedError when account, chain, or connector changed after dispatch.",
+    "RainbowKit 2.2.x declares Wagmi v2 peers. Its defining provider/custom-button/modal contracts can be implemented over this v3 surface, proven by the deterministic disconnected-to-connecting-to-connected gate, but the downstream binding must document that peer-range divergence.",
+    "The connectors subpath exposes the dependency-free injected and deterministic mock connectors. Vendor connectors and their optional SDKs remain direct application dependencies.",
+    "EIP-1193 event validation, duplicate coalescing, and connector-generation invalidation are delegated unchanged to @wagmi/core 3.6.4. This binding does not add a second provider-event layer or claim independent normalization behavior."
+  ],
+  "ssr": "WagmiProvider supports ssr:true and initialState through @wagmi/core hydrate. parseHydratedState accepts only a versioned, 16 KiB-bounded public-state hint and rejects malformed or privileged material; a hydrated connection is never authority for signing or submission.",
+  "verified": "2026-07-29",
+  "provenance": {
+    "source": "https://github.com/wevm/wagmi",
+    "license": "MIT"
+  },
+  "supportedExports": [
+    "createConfig",
+    "WagmiProvider",
+    "useConfig",
+    "useConnection",
+    "useConnect",
+    "useDisconnect",
+    "useSwitchConnection",
+    "useSwitchChain",
+    "useConnectors",
+    "useConnections",
+    "useChains",
+    "useBalance",
+    "useReadContract",
+    "useSimulateContract",
+    "useWriteContract",
+    "useSendTransaction",
+    "useWaitForTransactionReceipt",
+    "useSignMessage"
+  ],
+  "unsupported": [
+    "deprecated Wagmi v2 aliases",
+    "connector-specific React UI",
+    "all Wagmi hooks not named in supportedExports",
+    "automatic signing or submission retry"
+  ]
+}