@sodax/dapp-kit 2.0.0-rc.2 → 2.0.0-rc.20

package/src/hooks/swapsApi/useSwapsApiIntentHash.ts

@@ -0,0 +1,40 @@
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import type { IntentHashResponseV2, IntentRequestV2, RequestOverrideConfig } from '@sodax/sdk';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import { unwrapResult } from '../shared/unwrapResult.js';
+import type { ReadHookParams } from '../shared/types.js';
+
+export type UseSwapsApiIntentHashParams = ReadHookParams<
+  IntentHashResponseV2 | undefined,
+  {
+    intent: IntentRequestV2 | undefined;
+    apiConfig?: RequestOverrideConfig;
+  }
+>;
+
+/**
+ * React hook to compute the keccak256 hash of an Intent struct via the swaps API —
+ * `sodax.api.swaps.getIntentHash`. The `intent` carries `bigint` numerics. Returns `{ hash }`.
+ *
+ * @example
+ * const { data } = useSwapsApiIntentHash({ params: { intent } });
+ */
+export const useSwapsApiIntentHash = ({
+  params,
+  queryOptions,
+}: UseSwapsApiIntentHashParams = {}): UseQueryResult<IntentHashResponseV2 | undefined, Error> => {
+  const { sodax } = useSodaxContext();
+  const intent = params?.intent;
+  const apiConfig = params?.apiConfig;
+
+  return useQuery({
+    queryKey: ['swapsApi', 'intentHash', intent?.intentId?.toString()],
+    queryFn: async (): Promise<IntentHashResponseV2 | undefined> => {
+      if (!intent) return undefined;
+      return unwrapResult(await sodax.api.swaps.getIntentHash({ intent }, apiConfig));
+    },
+    enabled: !!intent,
+    retry: 3,
+    ...queryOptions,
+  });
+};

package/src/hooks/swapsApi/useSwapsApiIntentPacket.ts

@@ -0,0 +1,43 @@
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import type { IntentPacketRequestV2, IntentPacketResponseV2, RequestOverrideConfig } from '@sodax/sdk';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import { unwrapResult } from '../shared/unwrapResult.js';
+import type { ReadHookParams } from '../shared/types.js';
+
+export type UseSwapsApiIntentPacketParams = ReadHookParams<
+  IntentPacketResponseV2 | undefined,
+  {
+    body: IntentPacketRequestV2 | undefined;
+    apiConfig?: RequestOverrideConfig;
+  }
+>;
+
+/**
+ * React hook to long-poll the relayer until the fill packet lands on the destination chain via the
+ * swaps API — `sodax.api.swaps.getSolvedIntentPacket`. The request is held open server-side until
+ * the packet arrives (or `body.timeout` ms elapses), so no client-side `refetchInterval` is set.
+ *
+ * @example
+ * const { data: packet } = useSwapsApiIntentPacket({
+ *   params: { body: { chainId: '146', fillTxHash: '0x123...' } },
+ * });
+ */
+export const useSwapsApiIntentPacket = ({
+  params,
+  queryOptions,
+}: UseSwapsApiIntentPacketParams = {}): UseQueryResult<IntentPacketResponseV2 | undefined, Error> => {
+  const { sodax } = useSodaxContext();
+  const body = params?.body;
+  const apiConfig = params?.apiConfig;
+
+  return useQuery({
+    queryKey: ['swapsApi', 'intentPacket', body?.chainId, body?.fillTxHash],
+    queryFn: async (): Promise<IntentPacketResponseV2 | undefined> => {
+      if (!body) return undefined;
+      return unwrapResult(await sodax.api.swaps.getSolvedIntentPacket(body, apiConfig));
+    },
+    enabled: !!body,
+    retry: 3,
+    ...queryOptions,
+  });
+};

package/src/hooks/swapsApi/useSwapsApiPartnerFee.ts

@@ -0,0 +1,40 @@
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import type { FeeResponseV2, RequestOverrideConfig } from '@sodax/sdk';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import { unwrapResult } from '../shared/unwrapResult.js';
+import type { ReadHookParams } from '../shared/types.js';
+
+export type UseSwapsApiPartnerFeeParams = ReadHookParams<
+  FeeResponseV2 | undefined,
+  {
+    amount: string | undefined;
+    apiConfig?: RequestOverrideConfig;
+  }
+>;
+
+/**
+ * React hook to compute the partner fee for a given input amount via the swaps API —
+ * `sodax.api.swaps.getPartnerFee`. Returns `{ fee }` (decimal string).
+ *
+ * @example
+ * const { data } = useSwapsApiPartnerFee({ params: { amount: '1000000' } });
+ */
+export const useSwapsApiPartnerFee = ({
+  params,
+  queryOptions,
+}: UseSwapsApiPartnerFeeParams = {}): UseQueryResult<FeeResponseV2 | undefined, Error> => {
+  const { sodax } = useSodaxContext();
+  const amount = params?.amount;
+  const apiConfig = params?.apiConfig;
+
+  return useQuery({
+    queryKey: ['swapsApi', 'partnerFee', amount],
+    queryFn: async (): Promise<FeeResponseV2 | undefined> => {
+      if (!amount) return undefined;
+      return unwrapResult(await sodax.api.swaps.getPartnerFee({ amount }, apiConfig));
+    },
+    enabled: !!amount && amount.length > 0,
+    retry: 3,
+    ...queryOptions,
+  });
+};

package/src/hooks/swapsApi/useSwapsApiQuote.ts

@@ -0,0 +1,55 @@
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import type { QuoteQueryV2, QuoteRequestV2, QuoteResponseV2, RequestOverrideConfig } from '@sodax/sdk';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import { unwrapResult } from '../shared/unwrapResult.js';
+import type { ReadHookParams } from '../shared/types.js';
+
+export type UseSwapsApiQuoteParams = ReadHookParams<
+  QuoteResponseV2 | undefined,
+  {
+    body: QuoteRequestV2 | undefined;
+    query?: QuoteQueryV2;
+    apiConfig?: RequestOverrideConfig;
+  }
+>;
+
+/**
+ * React hook to get a solver quote for a cross-chain swap via the swaps API —
+ * `sodax.api.swaps.getQuote`. Pass `query.includeTxData = true` to also build an unsigned
+ * create-intent transaction (`txData`); `srcAddress`/`dstAddress` are then required in the body.
+ *
+ * @example
+ * const { data: quote } = useSwapsApiQuote({
+ *   params: {
+ *     body: {
+ *       tokenSrc: '0x...', tokenSrcChainKey: '0xa4b1.arbitrum',
+ *       tokenDst: '0x...', tokenDstChainKey: 'sonic',
+ *       amount: '1000000', quoteType: 'exact_input',
+ *     },
+ *   },
+ * });
+ */
+export const useSwapsApiQuote = ({
+  params,
+  queryOptions,
+}: UseSwapsApiQuoteParams = {}): UseQueryResult<QuoteResponseV2 | undefined, Error> => {
+  const { sodax } = useSodaxContext();
+  const body = params?.body;
+  const query = params?.query;
+  const apiConfig = params?.apiConfig;
+
+  return useQuery({
+    // Hash the whole request body so every quote input — including partnerFee and the other
+    // SwapExtrasV2 fields — is a cache dimension; a partnerFee change alters the quote and must
+    // miss the cache. QuoteRequestV2 is bigint-free (compile-time guaranteed), so React Query's
+    // default key hashing handles the object directly.
+    queryKey: ['swapsApi', 'quote', body, query?.includeTxData ?? false],
+    queryFn: async (): Promise<QuoteResponseV2 | undefined> => {
+      if (!body) return undefined;
+      return unwrapResult(await sodax.api.swaps.getQuote(body, query, apiConfig));
+    },
+    enabled: !!body,
+    retry: 3,
+    ...queryOptions,
+  });
+};

package/src/hooks/swapsApi/useSwapsApiSolverFee.ts

@@ -0,0 +1,40 @@
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import type { FeeResponseV2, RequestOverrideConfig } from '@sodax/sdk';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import { unwrapResult } from '../shared/unwrapResult.js';
+import type { ReadHookParams } from '../shared/types.js';
+
+export type UseSwapsApiSolverFeeParams = ReadHookParams<
+  FeeResponseV2 | undefined,
+  {
+    amount: string | undefined;
+    apiConfig?: RequestOverrideConfig;
+  }
+>;
+
+/**
+ * React hook to compute the protocol (solver) fee for a given input amount via the swaps API —
+ * `sodax.api.swaps.getSolverFee`. Returns `{ fee }` (decimal string).
+ *
+ * @example
+ * const { data } = useSwapsApiSolverFee({ params: { amount: '1000000' } });
+ */
+export const useSwapsApiSolverFee = ({
+  params,
+  queryOptions,
+}: UseSwapsApiSolverFeeParams = {}): UseQueryResult<FeeResponseV2 | undefined, Error> => {
+  const { sodax } = useSodaxContext();
+  const amount = params?.amount;
+  const apiConfig = params?.apiConfig;
+
+  return useQuery({
+    queryKey: ['swapsApi', 'solverFee', amount],
+    queryFn: async (): Promise<FeeResponseV2 | undefined> => {
+      if (!amount) return undefined;
+      return unwrapResult(await sodax.api.swaps.getSolverFee({ amount }, apiConfig));
+    },
+    enabled: !!amount && amount.length > 0,
+    retry: 3,
+    ...queryOptions,
+  });
+};

package/src/hooks/swapsApi/useSwapsApiStatus.ts

@@ -0,0 +1,45 @@
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import type { RequestOverrideConfig, StatusResponseV2 } from '@sodax/sdk';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import { unwrapResult } from '../shared/unwrapResult.js';
+import type { ReadHookParams } from '../shared/types.js';
+import { isTerminalSwapIntentStatus } from './isTerminalSwapIntentStatus.js';
+
+export type UseSwapsApiStatusParams = ReadHookParams<
+  StatusResponseV2 | undefined,
+  {
+    intentTxHash: string | undefined;
+    apiConfig?: RequestOverrideConfig;
+  }
+>;
+
+/**
+ * React hook for polling the solver intent status by hub-chain intent tx hash via the swaps API —
+ * `sodax.api.swaps.getStatus`. Returns `{ status, fillTxHash? }` (`fillTxHash` set when `status === 3`).
+ *
+ * @example
+ * const { data } = useSwapsApiStatus({ params: { intentTxHash: '0x123...' } });
+ *
+ * @remarks
+ * - Default refetch interval is 1 second; stops once `status` is `3` (SOLVED) or `4` (FAILED).
+ */
+export const useSwapsApiStatus = ({
+  params,
+  queryOptions,
+}: UseSwapsApiStatusParams = {}): UseQueryResult<StatusResponseV2 | undefined, Error> => {
+  const { sodax } = useSodaxContext();
+  const intentTxHash = params?.intentTxHash;
+  const apiConfig = params?.apiConfig;
+
+  return useQuery({
+    queryKey: ['swapsApi', 'status', intentTxHash],
+    queryFn: async (): Promise<StatusResponseV2 | undefined> => {
+      if (!intentTxHash) return undefined;
+      return unwrapResult(await sodax.api.swaps.getStatus({ intentTxHash }, apiConfig));
+    },
+    enabled: !!intentTxHash && intentTxHash.length > 0,
+    retry: 3,
+    refetchInterval: query => (isTerminalSwapIntentStatus(query.state.data?.status) ? false : 1000),
+    ...queryOptions,
+  });
+};

package/src/hooks/swapsApi/useSwapsApiSubmitIntent.ts

@@ -0,0 +1,43 @@
+import type { RequestOverrideConfig, SubmitIntentRequestV2, SubmitIntentResponseV2 } from '@sodax/sdk';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import { unwrapResult } from '../shared/unwrapResult.js';
+import type { MutationHookParams } from '../shared/types.js';
+import { useSafeMutation, type SafeUseMutationResult } from '../shared/useSafeMutation.js';
+
+/**
+ * Mutation variables for {@link useSwapsApiSubmitIntent}. The per-request `apiConfig` override
+ * belongs here rather than at the hook level.
+ */
+export type UseSwapsApiSubmitIntentVars = {
+  body: SubmitIntentRequestV2;
+  apiConfig?: RequestOverrideConfig;
+};
+
+/**
+ * React hook to submit the broadcast intent tx to the relay via the swaps API —
+ * `sodax.api.swaps.submitIntent`. Returns `{ result }` (opaque relay response).
+ *
+ * No auto-retry (`retry: false`): submitting is non-idempotent — a retry after a lost response
+ * could double-submit to the relay. Override via `mutationOptions.retry` if your relay dedupes.
+ *
+ * @example
+ * const { mutateAsync: submitIntent } = useSwapsApiSubmitIntent();
+ * const { result } = await submitIntent({ body: { chainId: '146', txHash: '0x123...' } });
+ */
+export const useSwapsApiSubmitIntent = ({
+  mutationOptions,
+}: MutationHookParams<SubmitIntentResponseV2, UseSwapsApiSubmitIntentVars> = {}): SafeUseMutationResult<
+  SubmitIntentResponseV2,
+  Error,
+  UseSwapsApiSubmitIntentVars
+> => {
+  const { sodax } = useSodaxContext();
+
+  return useSafeMutation<SubmitIntentResponseV2, Error, UseSwapsApiSubmitIntentVars>({
+    mutationKey: ['swapsApi', 'submitIntent'],
+    retry: false,
+    ...mutationOptions,
+    mutationFn: async ({ body, apiConfig }): Promise<SubmitIntentResponseV2> =>
+      unwrapResult(await sodax.api.swaps.submitIntent(body, apiConfig)),
+  });
+};

package/src/hooks/{backend/useBackendSubmitSwapTx.ts → swapsApi/useSwapsApiSubmitTx.ts}

@@ -1,49 +1,48 @@
-// packages/dapp-kit/src/hooks/backend/useBackendSubmitSwapTx.ts
-import type { RequestOverrideConfig, SubmitSwapTxRequest, SubmitSwapTxResponse } from '@sodax/sdk';
+import type { RequestOverrideConfig, SubmitTxRequestV2, SubmitTxResponseV2 } from '@sodax/sdk';
 import { useSodaxContext } from '../shared/useSodaxContext.js';
-import { unwrapResult } from './unwrapResult.js';
+import { unwrapResult } from '../shared/unwrapResult.js';
 import type { MutationHookParams } from '../shared/types.js';
 import { useSafeMutation, type SafeUseMutationResult } from '../shared/useSafeMutation.js';
 
 /**
- * Mutation variables for {@link useBackendSubmitSwapTx}. The per-request `apiConfig` override
+ * Mutation variables for {@link useSwapsApiSubmitTx}. The per-request `apiConfig` override
  * (e.g. base URL) belongs here rather than at the hook level — different submissions in the same
  * component can target different endpoints without re-rendering.
  */
-export type UseBackendSubmitSwapTxVars = {
-  request: SubmitSwapTxRequest;
+export type UseSwapsApiSubmitTxVars = {
+  request: SubmitTxRequestV2;
   apiConfig?: RequestOverrideConfig;
 };
 
 /**
- * React hook for submitting a swap transaction to be processed by the backend (relay, post
- * execution to solver, etc.).
+ * React hook for submitting a swap transaction to be processed (relay, post execution to the
+ * solver, etc.) via the swaps API — `sodax.api.swaps.submitTx`.
  *
  * Pure mutation: pass `{ request, apiConfig? }` to `mutate({...})`. Default `retry: 3` is applied
  * at the hook level — consumers can override via `mutationOptions.retry`.
  *
  * @example
- * const { mutateAsync: submitSwapTx, isPending, error } = useBackendSubmitSwapTx();
+ * const { mutateAsync: submitSwapTx, isPending, error } = useSwapsApiSubmitTx();
  *
  * const result = await submitSwapTx({
  *   request: { txHash: '0x123...', srcChainKey: 'sonic', walletAddress: '0xabc...', intent: { ... }, relayData: '0x...' },
  *   apiConfig: { baseURL: 'https://...' },
  * });
  */
-export const useBackendSubmitSwapTx = ({
+export const useSwapsApiSubmitTx = ({
   mutationOptions,
-}: MutationHookParams<SubmitSwapTxResponse, UseBackendSubmitSwapTxVars> = {}): SafeUseMutationResult<
-  SubmitSwapTxResponse,
+}: MutationHookParams<SubmitTxResponseV2, UseSwapsApiSubmitTxVars> = {}): SafeUseMutationResult<
+  SubmitTxResponseV2,
   Error,
-  UseBackendSubmitSwapTxVars
+  UseSwapsApiSubmitTxVars
 > => {
   const { sodax } = useSodaxContext();
 
-  return useSafeMutation<SubmitSwapTxResponse, Error, UseBackendSubmitSwapTxVars>({
-    mutationKey: ['backend', 'submitSwapTx'],
+  return useSafeMutation<SubmitTxResponseV2, Error, UseSwapsApiSubmitTxVars>({
+    mutationKey: ['swapsApi', 'submitTx'],
     retry: 3,
     ...mutationOptions,
-    mutationFn: async ({ request, apiConfig }): Promise<SubmitSwapTxResponse> =>
-      unwrapResult(await sodax.backendApi.submitSwapTx(request, apiConfig)),
+    mutationFn: async ({ request, apiConfig }): Promise<SubmitTxResponseV2> =>
+      unwrapResult(await sodax.api.swaps.submitTx(request, apiConfig)),
   });
 };

package/src/hooks/swapsApi/useSwapsApiSubmitTxStatus.ts

@@ -0,0 +1,55 @@
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import type { RequestOverrideConfig, SubmitTxStatusResponseV2 } from '@sodax/sdk';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import { unwrapResult } from '../shared/unwrapResult.js';
+import type { ReadHookParams } from '../shared/types.js';
+
+export type UseSwapsApiSubmitTxStatusParams = ReadHookParams<
+  SubmitTxStatusResponseV2 | undefined,
+  {
+    txHash: string | undefined;
+    srcChainKey?: string;
+    apiConfig?: RequestOverrideConfig;
+  }
+>;
+
+/**
+ * React hook for polling the processing status of a submitted swap transaction via the swaps API —
+ * `sodax.api.swaps.getSubmitTxStatus`. Both `txHash` and `srcChainKey` are required for the query
+ * to run (the swaps API v2 status query requires the source chain key).
+ *
+ * @example
+ * const { data: status } = useSwapsApiSubmitTxStatus({
+ *   params: { txHash: '0x123...', srcChainKey: 'sonic' },
+ * });
+ *
+ * @remarks
+ * - Default refetch interval is 1 second; stops on 'solved' or 'failed' status.
+ */
+export const useSwapsApiSubmitTxStatus = ({
+  params,
+  queryOptions,
+}: UseSwapsApiSubmitTxStatusParams = {}): UseQueryResult<SubmitTxStatusResponseV2 | undefined, Error> => {
+  const { sodax } = useSodaxContext();
+  const txHash = params?.txHash;
+  const srcChainKey = params?.srcChainKey;
+  const apiConfig = params?.apiConfig;
+
+  return useQuery({
+    queryKey: ['swapsApi', 'submitTx', 'status', txHash, srcChainKey],
+    queryFn: async (): Promise<SubmitTxStatusResponseV2 | undefined> => {
+      // `srcChainKey` is required by the swaps API v2 status query. The `enabled` gate below
+      // ensures both are present; this guard also narrows the types for the call.
+      if (!txHash || !srcChainKey) return undefined;
+      return unwrapResult(await sodax.api.swaps.getSubmitTxStatus({ txHash, srcChainKey }, apiConfig));
+    },
+    enabled: !!txHash && txHash.length > 0 && !!srcChainKey,
+    retry: 3,
+    refetchInterval: query => {
+      const status = query.state.data?.data?.status;
+      if (status === 'solved' || status === 'failed') return false;
+      return 1000;
+    },
+    ...queryOptions,
+  });
+};

package/src/hooks/swapsApi/useSwapsApiTokens.ts

@@ -0,0 +1,34 @@
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import type { GetSwapTokensResponseV2, RequestOverrideConfig } from '@sodax/sdk';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import { unwrapResult } from '../shared/unwrapResult.js';
+import type { ReadHookParams } from '../shared/types.js';
+
+export type UseSwapsApiTokensParams = ReadHookParams<
+  GetSwapTokensResponseV2,
+  {
+    apiConfig?: RequestOverrideConfig;
+  }
+>;
+
+/**
+ * React hook to fetch all supported swap tokens grouped by SpokeChainKey via the swaps API —
+ * `sodax.api.swaps.getTokens`.
+ *
+ * @example
+ * const { data: tokensByChain } = useSwapsApiTokens();
+ */
+export const useSwapsApiTokens = ({
+  params,
+  queryOptions,
+}: UseSwapsApiTokensParams = {}): UseQueryResult<GetSwapTokensResponseV2, Error> => {
+  const { sodax } = useSodaxContext();
+  const apiConfig = params?.apiConfig;
+
+  return useQuery<GetSwapTokensResponseV2, Error>({
+    queryKey: ['swapsApi', 'tokens'],
+    queryFn: async (): Promise<GetSwapTokensResponseV2> => unwrapResult(await sodax.api.swaps.getTokens(apiConfig)),
+    retry: 3,
+    ...queryOptions,
+  });
+};

package/src/hooks/swapsApi/useSwapsApiTokensByChain.ts

@@ -0,0 +1,40 @@
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import type { GetSwapTokensByChainResponseV2, RequestOverrideConfig } from '@sodax/sdk';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import { unwrapResult } from '../shared/unwrapResult.js';
+import type { ReadHookParams } from '../shared/types.js';
+
+export type UseSwapsApiTokensByChainParams = ReadHookParams<
+  GetSwapTokensByChainResponseV2 | undefined,
+  {
+    chainKey: string | undefined;
+    apiConfig?: RequestOverrideConfig;
+  }
+>;
+
+/**
+ * React hook to fetch supported swap tokens for a single SpokeChainKey via the swaps API —
+ * `sodax.api.swaps.getTokensByChain`.
+ *
+ * @example
+ * const { data: tokens } = useSwapsApiTokensByChain({ params: { chainKey: '0xa4b1.arbitrum' } });
+ */
+export const useSwapsApiTokensByChain = ({
+  params,
+  queryOptions,
+}: UseSwapsApiTokensByChainParams = {}): UseQueryResult<GetSwapTokensByChainResponseV2 | undefined, Error> => {
+  const { sodax } = useSodaxContext();
+  const chainKey = params?.chainKey;
+  const apiConfig = params?.apiConfig;
+
+  return useQuery({
+    queryKey: ['swapsApi', 'tokens', chainKey],
+    queryFn: async (): Promise<GetSwapTokensByChainResponseV2 | undefined> => {
+      if (!chainKey) return undefined;
+      return unwrapResult(await sodax.api.swaps.getTokensByChain(chainKey, apiConfig));
+    },
+    enabled: !!chainKey && chainKey.length > 0,
+    retry: 3,
+    ...queryOptions,
+  });
+};

package/src/providers/SodaxProvider.tsx

@@ -1,25 +1,28 @@
-import { useMemo, useRef, type ReactNode, type ReactElement } from 'react';
-import { Sodax, type SodaxConfig } from '@sodax/sdk';
+import { useMemo, type ReactNode, type ReactElement } from 'react';
+import { Sodax, type SodaxOptions } from '@sodax/sdk';
 import { SodaxContext } from '@/contexts/index.js';
-import type { DeepPartial } from '@sodax/sdk';
 
 interface SodaxProviderProps {
   children: ReactNode;
   /**
-   * Sodax config (overrides defaults including rpcUrls). **Read-once at mount** —
-   * changes after first render are ignored to prevent re-instantiating the SDK
-   * from unstable parent references. To switch config (e.g. testnet ↔ mainnet),
-   * unmount/remount the provider.
+   * Sodax SDK config. Tracked by **reference** - a new identity re-instantiates the
+   * SDK. Hoist to a module constant or wrap in `useMemo`; include any value the SDK
+   * should react to (e.g. solver env) in the deps. Inline `{...}` re-creates the SDK
+   * every parent render and resets every `useSodaxContext` consumer.
+   *
+   * @example
+   * ```tsx
+   * const config = useMemo(() => ({ solver: solverMap[env] }), [env]);
+   * <SodaxProvider config={config}>...</SodaxProvider>
+   * ```
    */
-  config?: DeepPartial<SodaxConfig>;
+  config?: SodaxOptions;
 }
 
+/** Root provider for `@sodax/dapp-kit`. Must be paired with `QueryClientProvider`. */
 export const SodaxProvider = ({ children, config }: SodaxProviderProps): ReactElement => {
-  // Freeze config on first render so the SDK instance and consumers share one
-  // snapshot (matches SodaxWalletProvider semantic).
-  const configRef = useRef<DeepPartial<SodaxConfig> | undefined>(config);
-  const frozen = configRef.current;
-  const sodax = useMemo(() => new Sodax(frozen), [frozen]);
+  const sodax = useMemo(() => new Sodax(config), [config]);
+  const contextValue = useMemo(() => ({ sodax }), [sodax]);
 
-  return <SodaxContext.Provider value={{ sodax }}>{children}</SodaxContext.Provider>;
+  return <SodaxContext.Provider value={contextValue}>{children}</SodaxContext.Provider>;
 };

package/src/utils/index.ts

@@ -1 +1,2 @@
 export * from './dex-utils.js';
+export * from './nearStorageGate.js';

package/src/utils/nearStorageGate.test.ts

@@ -0,0 +1,46 @@
+import { ChainKeys } from '@sodax/sdk';
+import { describe, expect, it } from 'vitest';
+import { resolveNearStorageGate } from './nearStorageGate.js';
+
+describe('resolveNearStorageGate', () => {
+  it('destination not NEAR → never gates', () => {
+    expect(resolveNearStorageGate(ChainKeys.POLYGON_MAINNET, { isLoading: false, data: false })).toEqual({
+      isNear: false,
+      needsRegistration: false,
+      blocksAction: false,
+    });
+  });
+
+  it('NEAR, check in flight → blocks action but does not yet prompt registration', () => {
+    expect(resolveNearStorageGate(ChainKeys.NEAR_MAINNET, { isLoading: true, data: undefined })).toEqual({
+      isNear: true,
+      needsRegistration: false,
+      blocksAction: true,
+    });
+  });
+
+  it('NEAR, check resolved, not registered → prompt registration and block action', () => {
+    expect(resolveNearStorageGate(ChainKeys.NEAR_MAINNET, { isLoading: false, data: false })).toEqual({
+      isNear: true,
+      needsRegistration: true,
+      blocksAction: true,
+    });
+  });
+
+  it('NEAR, check resolved, registered → no gate', () => {
+    expect(resolveNearStorageGate(ChainKeys.NEAR_MAINNET, { isLoading: false, data: true })).toEqual({
+      isNear: true,
+      needsRegistration: false,
+      blocksAction: false,
+    });
+  });
+
+  it('NEAR, query disabled (unresolved, not checking) → does not block', () => {
+    // isLoading is false for a disabled query; data stays undefined → action must not be blocked.
+    expect(resolveNearStorageGate(ChainKeys.NEAR_MAINNET, { isLoading: false, data: undefined })).toEqual({
+      isNear: true,
+      needsRegistration: false,
+      blocksAction: false,
+    });
+  });
+});

package/src/utils/nearStorageGate.ts

@@ -0,0 +1,39 @@
+import { ChainKeys, type SpokeChainKey } from '@sodax/sdk';
+import type { UseQueryResult } from '@tanstack/react-query';
+
+/** The subset of a `useNearStorageCheck` result the gate reads. A full `UseQueryResult<boolean>` satisfies it. */
+export type NearStorageCheckResult = Pick<UseQueryResult<boolean>, 'isLoading' | 'data'>;
+
+/** UI gate state for NEP-141 storage registration on NEAR. */
+export interface NearStorageGateState {
+  /** Destination is NEAR — the only chain with a NEP-141 storage-registration prerequisite. */
+  isNear: boolean;
+  /** Show the "register storage" action: the check resolved and the recipient is not registered. */
+  needsRegistration: boolean;
+  /**
+   * Keep the downstream action (swap/bridge/borrow/withdraw) disabled: the NEAR gate is unresolved
+   * (still checking) or unmet (needs registration).
+   */
+  blocksAction: boolean;
+}
+
+/**
+ * Derives the NEP-141 storage-registration UI gate state for a flow that delivers a token to a user
+ * on NEAR — NEAR's analogue of the Stellar trustline gate. Unwrapped (no hook): pass the destination
+ * `chainKey` and the `useNearStorageCheck` result; the util owns the `=== NEAR` test and reads
+ * `isLoading` (NOT `isPending`, which stays `true` for a disabled query and would block forever).
+ *
+ * `blocksAction` deliberately also covers the in-flight check window so the action can't be
+ * triggered before registration status is known; `needsRegistration` only flips once the check has
+ * resolved (so the "register" button isn't shown speculatively while still checking).
+ */
+export function resolveNearStorageGate(chainKey: SpokeChainKey, check: NearStorageCheckResult): NearStorageGateState {
+  const isNear = chainKey === ChainKeys.NEAR_MAINNET;
+  const isChecking = check.isLoading;
+  const isRegistered = check.data;
+  return {
+    isNear,
+    needsRegistration: isNear && !isChecking && isRegistered === false,
+    blocksAction: isNear && (isChecking || isRegistered === false),
+  };
+}