@sodax/dapp-kit 2.0.0-rc.11 → 2.0.0-rc.13

package/src/hooks/leverageYield/useLeverageYieldDeposit.ts

@@ -0,0 +1,40 @@
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import type { LeverageYieldSwapPayload, LeverageYieldSwapDepositParams } from '@sodax/sdk';
+import type { MutationHookParams } from '../shared/types.js';
+import { useSafeMutation, type SafeUseMutationResult } from '../shared/useSafeMutation.js';
+import { unwrapResult } from '../shared/unwrapResult.js';
+
+/** Mutation variables for {@link useLeverageYieldDeposit} — the swap-style deposit inputs. */
+export type UseLeverageYieldDepositVars = LeverageYieldSwapDepositParams;
+
+/**
+ * Builds the `LeverageYieldSwapPayload` for a leverage-yield deposit (any token → `lsoda*` shares,
+ * delivered to the user's hub wallet). Spread the returned payload into
+ * {@link useLeverageYieldVaultSwap}.
+ *
+ * This is a builder, not an executor — it derives the hub wallet and assembles the intent; the
+ * actual swap is relayed by `useLeverageYieldVaultSwap`. Throws on SDK failure so React Query's
+ * error model engages; returns the unwrapped `LeverageYieldSwapPayload` on success.
+ *
+ * @example
+ * ```typescript
+ * const { mutateAsyncSafe: buildDeposit } = useLeverageYieldDeposit();
+ * const built = await buildDeposit({ vault, srcChainKey, srcAddress, inputToken, inputAmount, minOutputAmount });
+ * if (built.ok) vaultSwap({ ...built.value, walletProvider });
+ * ```
+ */
+export function useLeverageYieldDeposit({
+  mutationOptions,
+}: MutationHookParams<LeverageYieldSwapPayload, UseLeverageYieldDepositVars> = {}): SafeUseMutationResult<
+  LeverageYieldSwapPayload,
+  Error,
+  UseLeverageYieldDepositVars
+> {
+  const { sodax } = useSodaxContext();
+
+  return useSafeMutation<LeverageYieldSwapPayload, Error, UseLeverageYieldDepositVars>({
+    mutationKey: ['leverageYield', 'deposit'],
+    ...mutationOptions,
+    mutationFn: async vars => unwrapResult(await sodax.leverageYield.deposit(vars)),
+  });
+}

package/src/hooks/leverageYield/useLeverageYieldEffectiveApr.ts

@@ -0,0 +1,42 @@
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import type { Address, LeverageYieldEffectiveApr } from '@sodax/sdk';
+import type { ReadHookParams } from '../shared/types.js';
+
+export type UseLeverageYieldEffectiveAprParams = ReadHookParams<
+  LeverageYieldEffectiveApr,
+  { vault: Address | undefined }
+>;
+
+/**
+ * Reads a leverage-yield vault's effective APR — AAVE supply/borrow rates plus the LSD
+ * staking yield, with the vault's leverage formula re-applied on the boosted supply side.
+ *
+ * The underlying SDK call does the on-chain reads (AAVE rates + `targetLTV`) and the
+ * off-chain LSD fetch in parallel. Rates drift slowly, so the default refresh is 60s.
+ *
+ * @example
+ * ```typescript
+ * const { data: apr } = useLeverageYieldEffectiveApr({ params: { vault: vault.vault } });
+ * ```
+ */
+export function useLeverageYieldEffectiveApr({
+  params,
+  queryOptions,
+}: UseLeverageYieldEffectiveAprParams = {}): UseQueryResult<LeverageYieldEffectiveApr, Error> {
+  const { sodax } = useSodaxContext();
+  const vault = params?.vault;
+
+  return useQuery<LeverageYieldEffectiveApr, Error>({
+    queryKey: ['leverageYield', 'effectiveApr', vault],
+    queryFn: async () => {
+      if (!vault) throw new Error('vault is required');
+      const result = await sodax.leverageYield.getEffectiveApr(vault);
+      if (!result.ok) throw result.error;
+      return result.value;
+    },
+    enabled: !!vault,
+    refetchInterval: 60_000,
+    ...queryOptions,
+  });
+}

package/src/hooks/leverageYield/useLeverageYieldNotifySolver.ts

@@ -0,0 +1,34 @@
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import type { SolverExecutionRequest, SolverExecutionResponse } from '@sodax/sdk';
+import type { MutationHookParams } from '../shared/types.js';
+import { useSafeMutation, type SafeUseMutationResult } from '../shared/useSafeMutation.js';
+import { unwrapResult } from '../shared/unwrapResult.js';
+
+/** Mutation variables for {@link useLeverageYieldNotifySolver} — the hub-side intent tx hash. */
+export type UseLeverageYieldNotifySolverVars = SolverExecutionRequest;
+
+/**
+ * Notifies the solver that a leverage-yield vault intent landed on the hub, triggering the fill.
+ * The standalone notify step for the manual create → relay → notify flow: build the intent with
+ * `sodax.leverageYield.createVaultIntent`, relay it yourself, then call this with the hub-side
+ * intent tx hash. The end-to-end {@link useLeverageYieldVaultSwap} already calls notifySolver
+ * internally — only reach for this hook when driving the relay manually.
+ *
+ * Throws on SDK failure so React Query's error model engages; returns the unwrapped
+ * `SolverExecutionResponse` (`{ answer: 'OK', intent_hash }`) on success.
+ */
+export function useLeverageYieldNotifySolver({
+  mutationOptions,
+}: MutationHookParams<SolverExecutionResponse, UseLeverageYieldNotifySolverVars> = {}): SafeUseMutationResult<
+  SolverExecutionResponse,
+  Error,
+  UseLeverageYieldNotifySolverVars
+> {
+  const { sodax } = useSodaxContext();
+
+  return useSafeMutation<SolverExecutionResponse, Error, UseLeverageYieldNotifySolverVars>({
+    mutationKey: ['leverageYield', 'notifySolver'],
+    ...mutationOptions,
+    mutationFn: async vars => unwrapResult(await sodax.leverageYield.notifySolver(vars)),
+  });
+}

package/src/hooks/leverageYield/useLeverageYieldPosition.ts

@@ -0,0 +1,40 @@
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import type { Address, LeverageYieldPosition } from '@sodax/sdk';
+import type { ReadHookParams } from '../shared/types.js';
+
+export type UseLeverageYieldPositionParams = ReadHookParams<LeverageYieldPosition, { vault: Address | undefined }>;
+
+/**
+ * Reads a leverage-yield vault's live position snapshot via the vault's `getPositionDetails`:
+ * collateral, debt, current LTV (drift vs `targetLTV`), health factor (∞ when no debt), and
+ * idle (not-yet-deployed) asset.
+ *
+ * LTV shifts with each rebalance/rate tick, so the default refresh (30s) is faster than the
+ * APR/stats reads.
+ *
+ * @example
+ * ```typescript
+ * const { data: position } = useLeverageYieldPosition({ params: { vault: vault.vault } });
+ * ```
+ */
+export function useLeverageYieldPosition({
+  params,
+  queryOptions,
+}: UseLeverageYieldPositionParams = {}): UseQueryResult<LeverageYieldPosition, Error> {
+  const { sodax } = useSodaxContext();
+  const vault = params?.vault;
+
+  return useQuery<LeverageYieldPosition, Error>({
+    queryKey: ['leverageYield', 'position', vault],
+    queryFn: async () => {
+      if (!vault) throw new Error('vault is required');
+      const result = await sodax.leverageYield.getPosition(vault);
+      if (!result.ok) throw result.error;
+      return result.value;
+    },
+    enabled: !!vault,
+    refetchInterval: 30_000,
+    ...queryOptions,
+  });
+}

package/src/hooks/leverageYield/useLeverageYieldPreviewRedeem.ts

@@ -0,0 +1,43 @@
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import type { Address } from '@sodax/sdk';
+import type { ReadHookParams } from '../shared/types.js';
+
+export type UseLeverageYieldPreviewRedeemParams = ReadHookParams<
+  bigint,
+  { vault: Address | undefined; shares: bigint | undefined }
+>;
+
+/**
+ * Reads the assets received for redeeming `shares` of a leverage-yield vault (ERC-4626
+ * `previewRedeem`). Passing `10n ** 18n` (one share) yields the per-share price that creeps
+ * up as the vault accrues interest. Moves slowly, so the default refresh is 60s.
+ *
+ * @example
+ * ```typescript
+ * const { data: sharePrice } = useLeverageYieldPreviewRedeem({
+ *   params: { vault: vault.vault, shares: 10n ** 18n },
+ * });
+ * ```
+ */
+export function useLeverageYieldPreviewRedeem({
+  params,
+  queryOptions,
+}: UseLeverageYieldPreviewRedeemParams = {}): UseQueryResult<bigint, Error> {
+  const { sodax } = useSodaxContext();
+  const vault = params?.vault;
+  const shares = params?.shares;
+
+  return useQuery<bigint, Error>({
+    queryKey: ['leverageYield', 'previewRedeem', vault, shares?.toString()],
+    queryFn: async () => {
+      if (!vault || shares === undefined) throw new Error('vault and shares are required');
+      const result = await sodax.leverageYield.previewRedeem(vault, shares);
+      if (!result.ok) throw result.error;
+      return result.value;
+    },
+    enabled: !!vault && shares !== undefined,
+    refetchInterval: 60_000,
+    ...queryOptions,
+  });
+}

package/src/hooks/leverageYield/useLeverageYieldShareBalances.ts

@@ -0,0 +1,74 @@
+import { useQueries, type UseQueryResult } from '@tanstack/react-query';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import type { Address, SpokeChainKey } from '@sodax/sdk';
+import type { ReadHookParams } from '../shared/types.js';
+
+/** A single `(chain, hub-wallet holder, share balance)` row produced by {@link useLeverageYieldShareBalances}. */
+export type LeverageYieldShareHolding = {
+  chainKey: SpokeChainKey;
+  holder: Address;
+  shares: bigint;
+};
+
+/** A `(chainKey, EOA address)` pair the user controls — one per spoke chain they may hold shares under. */
+export type LeverageYieldShareHolder = {
+  chainKey: SpokeChainKey;
+  address: string;
+};
+
+export type UseLeverageYieldShareBalancesParams = ReadHookParams<
+  LeverageYieldShareHolding,
+  { vault: Address | undefined; holders: readonly LeverageYieldShareHolder[] | undefined }
+>;
+
+/**
+ * Reads a user's leverage-vault share (`lsoda*`) balances across every chain they may hold a
+ * position under — one query per holder, fanned out via `useQueries`.
+ *
+ * For each `(chainKey, address)` the holder is resolved to the address that actually owns the
+ * shares: the user's **derived hub wallet** on every chain, including the hub itself. Leverage
+ * deposits always deliver `lsoda*` to `getUserHubWalletAddress(srcAddress, srcChainKey)` (the
+ * CREATE3 user-router on Sonic for a hub-sourced deposit, the per-spoke hub wallet otherwise) —
+ * never the bare EOA — so a hub-chain deposit's shares live in the router, not the signing EOA.
+ * Resolving the holder the same way the deposit does is what makes a Sonic-sourced position show
+ * up here instead of reading a stale zero off the EOA.
+ *
+ * Returns the raw `useQueries` result array (15s refresh per query); callers aggregate as needed
+ * (e.g. sum `shares` for a headline total, or pick the row for the active chain).
+ *
+ * `useQueries` has no top-level options slot, so `queryOptions` is spread into every individual
+ * query config (and applies uniformly to each holder's query).
+ *
+ * @example
+ * ```typescript
+ * const balances = useLeverageYieldShareBalances({ params: { vault: vault.vault, holders } });
+ * const total = balances.reduce((acc, q) => acc + (q.data?.shares ?? 0n), 0n);
+ * ```
+ */
+export function useLeverageYieldShareBalances({
+  params,
+  queryOptions,
+}: UseLeverageYieldShareBalancesParams = {}): UseQueryResult<LeverageYieldShareHolding, Error>[] {
+  const { sodax } = useSodaxContext();
+  const vault = params?.vault;
+  const holders = params?.holders;
+
+  return useQueries({
+    queries: (holders ?? []).map(({ chainKey, address }) => ({
+      queryKey: ['leverageYield', 'shareBalance', vault, chainKey, address] as const,
+      refetchInterval: 15_000,
+      ...queryOptions,
+      enabled: !!vault,
+      queryFn: async (): Promise<LeverageYieldShareHolding> => {
+        if (!vault) throw new Error('vault is required');
+        // Always the derived hub wallet — on the hub chain too. A leverage deposit delivers
+        // shares to getUserHubWalletAddress(...), the CREATE3 router on Sonic, never the EOA,
+        // so reading balanceOf(EOA) for the hub chain would always come back zero.
+        const holder = await sodax.hubProvider.getUserHubWalletAddress(address, chainKey);
+        const result = await sodax.leverageYield.getShareBalance(vault, holder);
+        if (!result.ok) throw result.error;
+        return { chainKey, holder, shares: result.value };
+      },
+    })),
+  });
+}

package/src/hooks/leverageYield/useLeverageYieldTotalAssets.ts

@@ -0,0 +1,36 @@
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import type { Address } from '@sodax/sdk';
+import type { ReadHookParams } from '../shared/types.js';
+
+export type UseLeverageYieldTotalAssetsParams = ReadHookParams<bigint, { vault: Address | undefined }>;
+
+/**
+ * Reads a leverage-yield vault's total underlying assets (vault-asset units, 18 decimals) —
+ * i.e. its TVL. Moves slowly, so the default refresh is 60s.
+ *
+ * @example
+ * ```typescript
+ * const { data: tvl } = useLeverageYieldTotalAssets({ params: { vault: vault.vault } });
+ * ```
+ */
+export function useLeverageYieldTotalAssets({
+  params,
+  queryOptions,
+}: UseLeverageYieldTotalAssetsParams = {}): UseQueryResult<bigint, Error> {
+  const { sodax } = useSodaxContext();
+  const vault = params?.vault;
+
+  return useQuery<bigint, Error>({
+    queryKey: ['leverageYield', 'totalAssets', vault],
+    queryFn: async () => {
+      if (!vault) throw new Error('vault is required');
+      const result = await sodax.leverageYield.getTotalAssets(vault);
+      if (!result.ok) throw result.error;
+      return result.value;
+    },
+    enabled: !!vault,
+    refetchInterval: 60_000,
+    ...queryOptions,
+  });
+}

package/src/hooks/leverageYield/useLeverageYieldVaultSwap.ts

@@ -0,0 +1,50 @@
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import type { SpokeChainKey, VaultSwapActionParams, VaultSwapResponse } from '@sodax/sdk';
+import { useQueryClient } from '@tanstack/react-query';
+import type { MutationHookParams } from '../shared/types.js';
+import { useSafeMutation, type SafeUseMutationResult } from '../shared/useSafeMutation.js';
+import { unwrapResult } from '../shared/unwrapResult.js';
+
+/**
+ * Mutation variables for {@link useLeverageYieldVaultSwap}. Generic over `K extends SpokeChainKey`
+ * (defaults to the full union). Sophisticated callers can lock K at the hook call site to narrow
+ * the `walletProvider` and `params.srcChainKey` types.
+ */
+export type UseLeverageYieldVaultSwapVars<K extends SpokeChainKey = SpokeChainKey> = Omit<
+  VaultSwapActionParams<K, false>,
+  'raw'
+>;
+
+/**
+ * React hook for executing an end-to-end leverage-yield vault swap (deposit or withdraw).
+ *
+ * Spread a `LeverageYieldSwapPayload` built by {@link useLeverageYieldDeposit} /
+ * {@link useLeverageYieldWithdraw} into `mutate` alongside the wallet provider:
+ * `vaultSwap({ ...payload, walletProvider })`. Runs `sodax.leverageYield.vaultSwap` —
+ * create intent → verify → relay → notify solver — so vault flows never touch the
+ * generic swap surface.
+ *
+ * Throws on SDK failure so React Query's native error model engages (`isError`, `error`,
+ * `onError`, `retry`). Returns the unwrapped `VaultSwapResponse` on success.
+ */
+export function useLeverageYieldVaultSwap<K extends SpokeChainKey = SpokeChainKey>({
+  mutationOptions,
+}: MutationHookParams<VaultSwapResponse, UseLeverageYieldVaultSwapVars<K>> = {}): SafeUseMutationResult<
+  VaultSwapResponse,
+  Error,
+  UseLeverageYieldVaultSwapVars<K>
+> {
+  const { sodax } = useSodaxContext();
+  const queryClient = useQueryClient();
+
+  return useSafeMutation<VaultSwapResponse, Error, UseLeverageYieldVaultSwapVars<K>>({
+    mutationKey: ['leverageYield', 'vaultSwap'],
+    ...mutationOptions,
+    mutationFn: async vars => unwrapResult(await sodax.leverageYield.vaultSwap({ ...vars, raw: false })),
+    onSuccess: async (data, vars, ctx) => {
+      queryClient.invalidateQueries({ queryKey: ['shared', 'xBalances', vars.params.srcChainKey] });
+      queryClient.invalidateQueries({ queryKey: ['shared', 'xBalances', vars.params.dstChainKey] });
+      await mutationOptions?.onSuccess?.(data, vars, ctx);
+    },
+  });
+}

package/src/hooks/leverageYield/useLeverageYieldWithdraw.ts

@@ -0,0 +1,40 @@
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import type { LeverageYieldSwapPayload, LeverageYieldSwapWithdrawParams } from '@sodax/sdk';
+import type { MutationHookParams } from '../shared/types.js';
+import { useSafeMutation, type SafeUseMutationResult } from '../shared/useSafeMutation.js';
+import { unwrapResult } from '../shared/unwrapResult.js';
+
+/** Mutation variables for {@link useLeverageYieldWithdraw} — the swap-style withdraw inputs. */
+export type UseLeverageYieldWithdrawVars = LeverageYieldSwapWithdrawParams;
+
+/**
+ * Builds the `LeverageYieldSwapPayload` for a leverage-yield withdraw (`lsoda*` shares → any token).
+ * The returned payload carries `hubWalletSwap: true`; spread it into
+ * {@link useLeverageYieldVaultSwap}, which authorises the hub wallet to spend the shares via a
+ * `Connection.sendMessage`.
+ *
+ * This is a builder, not an executor. Throws on SDK failure so React Query's error model engages;
+ * returns the unwrapped `LeverageYieldSwapPayload` on success.
+ *
+ * @example
+ * ```typescript
+ * const { mutateAsyncSafe: buildWithdraw } = useLeverageYieldWithdraw();
+ * const built = await buildWithdraw({ vault, srcChainKey, srcAddress, dstChainKey, outputToken, inputAmount, minOutputAmount });
+ * if (built.ok) vaultSwap({ ...built.value, walletProvider });
+ * ```
+ */
+export function useLeverageYieldWithdraw({
+  mutationOptions,
+}: MutationHookParams<LeverageYieldSwapPayload, UseLeverageYieldWithdrawVars> = {}): SafeUseMutationResult<
+  LeverageYieldSwapPayload,
+  Error,
+  UseLeverageYieldWithdrawVars
+> {
+  const { sodax } = useSodaxContext();
+
+  return useSafeMutation<LeverageYieldSwapPayload, Error, UseLeverageYieldWithdrawVars>({
+    mutationKey: ['leverageYield', 'withdraw'],
+    ...mutationOptions,
+    mutationFn: async vars => unwrapResult(await sodax.leverageYield.withdraw(vars)),
+  });
+}

package/src/hooks/mm/useATokensBalances.ts

@@ -2,6 +2,7 @@ import type { SpokeChainKey } from '@sodax/sdk';
 import { useQuery, type UseQueryResult } from '@tanstack/react-query';
 import { type Address, isAddress } from 'viem';
 import { useSodaxContext } from '../shared/useSodaxContext.js';
+import { resolveBtcReadAddress } from '../bitcoin/resolveBtcReadAddress.js';
 import type { ReadHookParams } from '../shared/types.js';
 
 export type UseATokensBalancesParams = ReadHookParams<
@@ -42,7 +43,12 @@ export function useATokensBalances({
         }
       }
 
-      const hubWalletAddress = await sodax.hubProvider.getUserHubWalletAddress(userAddress, spokeChainKey);
+      // Bitcoin positions live under the trading-wallet-derived hub wallet; resolve it locally
+      // (no network) so a Bound Exchange outage never reads a real position as empty.
+      const hubWalletAddress = await sodax.hubProvider.getUserHubWalletAddress(
+        resolveBtcReadAddress(spokeChainKey, userAddress),
+        spokeChainKey,
+      );
       return sodax.moneyMarket.data.getATokensBalances(aTokens, hubWalletAddress);
     },
     enabled: aTokens.length > 0 && !!spokeChainKey && !!userAddress,

package/src/hooks/mm/useUserFormattedSummary.ts

@@ -2,6 +2,7 @@ import type { FormatReserveUSDResponse, FormatUserSummaryResponse } from '@sodax
 import type { SpokeChainKey } from '@sodax/sdk';
 import { useQuery, type UseQueryResult } from '@tanstack/react-query';
 import { useSodaxContext } from '../shared/useSodaxContext.js';
+import { resolveBtcReadAddress } from '../bitcoin/resolveBtcReadAddress.js';
 import type { ReadHookParams } from '../shared/types.js';
 
 export type UseUserFormattedSummaryParams = ReadHookParams<
@@ -36,7 +37,10 @@ export function useUserFormattedSummary({
 
       const [reserves, userReserves] = await Promise.all([
         sodax.moneyMarket.data.getReservesHumanized(),
-        sodax.moneyMarket.data.getUserReservesHumanized(spokeChainKey, userAddress),
+        sodax.moneyMarket.data.getUserReservesHumanized(
+          spokeChainKey,
+          resolveBtcReadAddress(spokeChainKey, userAddress),
+        ),
       ]);
       const formattedReserves = sodax.moneyMarket.data.formatReservesUSD(
         sodax.moneyMarket.data.buildReserveDataWithPrice(reserves),

package/src/hooks/mm/useUserReservesData.ts

@@ -2,6 +2,7 @@ import type { UserReserveData } from '@sodax/sdk';
 import type { SpokeChainKey } from '@sodax/sdk';
 import { useQuery, type UseQueryResult } from '@tanstack/react-query';
 import { useSodaxContext } from '../shared/useSodaxContext.js';
+import { resolveBtcReadAddress } from '../bitcoin/resolveBtcReadAddress.js';
 import type { ReadHookParams } from '../shared/types.js';
 
 export type UseUserReservesDataParams = ReadHookParams<
@@ -30,7 +31,10 @@ export function useUserReservesData({
       if (!spokeChainKey || !userAddress) {
         throw new Error('spokeChainKey and userAddress are required');
       }
-      return sodax.moneyMarket.data.getUserReservesData(spokeChainKey, userAddress);
+      return sodax.moneyMarket.data.getUserReservesData(
+        spokeChainKey,
+        resolveBtcReadAddress(spokeChainKey, userAddress),
+      );
     },
     enabled: !!spokeChainKey && !!userAddress,
     refetchInterval: 5000,

package/src/hooks/shared/index.ts

@@ -6,5 +6,8 @@ export * from './useEstimateGas.js';
 export * from './useDeriveUserWalletAddress.js';
 export * from './useStellarTrustlineCheck.js';
 export * from './useRequestTrustline.js';
+export * from './useNearStorageCheck.js';
+export * from './useRegisterNearStorage.js';
+export * from './useNearStorageGate.js';
 export * from './useGetUserHubWalletAddress.js';
 export * from './useXBalances.js';

package/src/hooks/shared/useGetUserHubWalletAddress.ts

@@ -1,6 +1,7 @@
 import type { SpokeChainKey } from '@sodax/sdk';
 import { useQuery, type UseQueryResult } from '@tanstack/react-query';
 import { useSodaxContext } from './useSodaxContext.js';
+import { resolveBtcReadAddress } from '../bitcoin/resolveBtcReadAddress.js';
 import type { Address } from 'viem';
 import type { ReadHookParams } from './types.js';
 
@@ -44,7 +45,10 @@ export function useGetUserHubWalletAddress({
       if (!spokeChainId || !spokeAddress) {
         throw new Error('Spoke chain id and address are required');
       }
-      return await sodax.hubProvider.getUserHubWalletAddress(spokeAddress, spokeChainId);
+      return await sodax.hubProvider.getUserHubWalletAddress(
+        resolveBtcReadAddress(spokeChainId, spokeAddress),
+        spokeChainId,
+      );
     },
     enabled: !!spokeChainId && !!spokeAddress,
     refetchInterval: false,

package/src/hooks/shared/useNearStorageCheck.ts

@@ -0,0 +1,45 @@
+import { ChainKeys, type SpokeChainKey } from '@sodax/sdk';
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import { useSodaxContext } from './useSodaxContext.js';
+import type { ReadHookParams } from './types.js';
+
+export type UseNearStorageCheckParams = ReadHookParams<
+  boolean,
+  {
+    token: string | undefined;
+    accountId: string | undefined;
+    chainId: SpokeChainKey | undefined;
+  }
+>;
+
+/**
+ * Whether `accountId` is NEP-141 storage-registered for `token` on NEAR — the receive-side
+ * prerequisite for any leg that delivers a token to the user on NEAR (swap output on NEAR, bridge
+ * into NEAR, money-market borrow/withdraw to NEAR). NEAR's analogue of a Stellar trustline.
+ *
+ * Returns `true` (no gate) when `chainId` is not NEAR, mirroring how the Stellar trustline check
+ * short-circuits off-chain. Native NEAR is not a NEP-141 token, so the SDK reports it as registered.
+ *
+ * Pair with {@link useRegisterNearStorage} to perform the one-time `storage_deposit` when this
+ * resolves to `false`.
+ */
+export function useNearStorageCheck({
+  params,
+  queryOptions,
+}: UseNearStorageCheckParams = {}): UseQueryResult<boolean, Error> {
+  const { sodax } = useSodaxContext();
+  const token = params?.token;
+  const accountId = params?.accountId;
+  const chainId = params?.chainId;
+
+  return useQuery<boolean, Error>({
+    queryKey: ['shared', 'nearStorageCheck', chainId, token, accountId],
+    queryFn: async () => {
+      if (chainId !== ChainKeys.NEAR_MAINNET) return true;
+      if (!token || !accountId) return false;
+      return sodax.spoke.near.isStorageRegistered(token, accountId);
+    },
+    enabled: !!token && !!accountId,
+    ...queryOptions,
+  });
+}

package/src/hooks/shared/useNearStorageGate.ts

@@ -0,0 +1,60 @@
+import type { GetWalletProviderType, INearWalletProvider, Result, SpokeChainKey } from '@sodax/sdk';
+import { resolveNearStorageGate } from '../../utils/nearStorageGate.js';
+import { useNearStorageCheck } from './useNearStorageCheck.js';
+import { useRegisterNearStorage } from './useRegisterNearStorage.js';
+
+interface UseNearStorageGateParams {
+  /** Destination chain the token is delivered on. */
+  dstChainKey: SpokeChainKey;
+  /** Destination token address the recipient must be registered for. */
+  token: string | undefined;
+  /** Recipient NEAR account id. */
+  accountId: string | undefined;
+  /** Destination wallet provider; only consumed when it is the NEAR provider. */
+  walletProvider: GetWalletProviderType<SpokeChainKey> | undefined;
+}
+
+interface NearStorageGate {
+  /** Destination is NEAR. */
+  isNear: boolean;
+  /** Destination is NEAR and the recipient is not yet storage-registered for `token`. */
+  needsRegistration: boolean;
+  /** The downstream action must stay disabled while the gate is unresolved or unmet. */
+  blocksAction: boolean;
+  /** The registration-status query is actively fetching. */
+  isChecking: boolean;
+  /** A `storage_deposit` tx is in flight. */
+  isRegistering: boolean;
+  /** Submit the `storage_deposit`; resolves to the SDK `Result` or `undefined` if inputs are missing. */
+  registerStorage: () => Promise<Result<string> | undefined>;
+}
+
+/**
+ * NEP-141 storage-registration gate for flows that deliver a token to a user on NEAR.
+ */
+export function useNearStorageGate({
+  dstChainKey,
+  token,
+  accountId,
+  walletProvider,
+}: UseNearStorageGateParams): NearStorageGate {
+  const nearWalletProvider = walletProvider?.chainType === 'NEAR' ? (walletProvider as INearWalletProvider) : undefined;
+
+  const storageCheck = useNearStorageCheck({ params: { token, accountId, chainId: dstChainKey } });
+  const { mutateAsyncSafe: register, isPending: isRegistering } = useRegisterNearStorage();
+  const { isNear, needsRegistration, blocksAction } = resolveNearStorageGate(dstChainKey, storageCheck);
+
+  const registerStorage = async (): Promise<Result<string> | undefined> => {
+    if (!nearWalletProvider || !token || !accountId) return undefined;
+    return register({ token, accountId, walletProvider: nearWalletProvider });
+  };
+
+  return {
+    isNear,
+    needsRegistration,
+    blocksAction,
+    isChecking: storageCheck.isLoading,
+    isRegistering,
+    registerStorage,
+  };
+}

package/src/hooks/shared/useRegisterNearStorage.ts

@@ -0,0 +1,46 @@
+import { ChainKeys, type INearWalletProvider } from '@sodax/sdk';
+import { useQueryClient } from '@tanstack/react-query';
+import { useSodaxContext } from './useSodaxContext.js';
+import type { MutationHookParams } from './types.js';
+import { useSafeMutation, type SafeUseMutationResult } from './useSafeMutation.js';
+
+export type UseRegisterNearStorageVars = {
+  token: string;
+  accountId: string;
+  walletProvider: INearWalletProvider;
+  /** Storage bond override; defaults to the SDK's `NEAR_STORAGE_DEPOSIT` (0.00125 NEAR). */
+  deposit?: bigint;
+};
+
+/**
+ * Submit a NEP-141 `storage_deposit` so `accountId` can receive `token` on NEAR. NEAR's analogue of
+ * requesting a Stellar trustline; pair with {@link useNearStorageCheck} and call this when the check
+ * resolves to `false`. The recipient's NEAR wallet signs the registration tx.
+ *
+ * Pure mutation: pass `{ token, accountId, walletProvider }` to `mutate(...)`. The hook itself only
+ * takes the structural `mutationOptions` slot. `registerStorage` throws natively (no `Result<T>`),
+ * so this hook is registered as `nativeThrow` in the mutation contract. On success it invalidates
+ * the matching {@link useNearStorageCheck} query.
+ */
+export function useRegisterNearStorage({
+  mutationOptions,
+}: MutationHookParams<string, UseRegisterNearStorageVars> = {}): SafeUseMutationResult<
+  string,
+  Error,
+  UseRegisterNearStorageVars
+> {
+  const { sodax } = useSodaxContext();
+  const queryClient = useQueryClient();
+  return useSafeMutation<string, Error, UseRegisterNearStorageVars>({
+    mutationKey: ['shared', 'registerNearStorage'],
+    ...mutationOptions,
+    mutationFn: async ({ token, accountId, walletProvider, deposit }) =>
+      sodax.spoke.near.registerStorage({ token, accountId, walletProvider, deposit, raw: false }),
+    onSuccess: async (data, vars, ctx) => {
+      queryClient.invalidateQueries({
+        queryKey: ['shared', 'nearStorageCheck', ChainKeys.NEAR_MAINNET, vars.token, vars.accountId],
+      });
+      await mutationOptions?.onSuccess?.(data, vars, ctx);
+    },
+  });
+}