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

package/package.json

@@ -1,16 +1,32 @@
 {
   "name": "@sodax/dapp-kit",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
   "license": "MIT",
-  "version": "2.0.0-rc.2",
-  "description": "dapp-kit of New World",
+  "version": "2.0.0-rc.20",
+  "description": "React hooks for building dApps on the SODAX cross-chain DeFi platform",
+  "keywords": [
+    "sodax",
+    "dapp-kit",
+    "react",
+    "react-query",
+    "hooks",
+    "defi"
+  ],
+  "homepage": "https://github.com/icon-project/sodax-sdks/tree/main/packages/dapp-kit",
+  "bugs": {
+    "url": "https://github.com/icon-project/sodax-sdks/issues"
+  },
   "type": "module",
-  "main": "dist/index.cjs",
+  "main": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "module": "dist/index.mjs",
   "files": [
     "dist",
-    "src",
-    "ai-exported"
+    "!dist/**/*.map",
+    "src"
   ],
   "repository": {
     "type": "git",
@@ -18,29 +34,31 @@
   },
   "dependencies": {
     "viem": "2.29.2",
-    "@sodax/sdk": "2.0.0-rc.2"
+    "@sodax/sdk": "2.0.0-rc.20"
   },
   "devDependencies": {
+    "@arethetypeswrong/cli": "0.17.4",
     "@tanstack/react-query": "5.87.4",
     "@types/react": "19.0.8",
     "knip": "5.30.5",
+    "tslib": "2.8.1",
     "tsup": "8.5.0",
     "typescript": "5.5.4",
-    "vitest": "2.1.9"
+    "vitest": "3.2.6"
   },
   "peerDependencies": {
     "@tanstack/react-query": "5.x",
     "react": ">=18"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=20.12.0"
   },
+  "sideEffects": false,
   "exports": {
     "./package.json": "./package.json",
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.cjs"
+      "import": "./dist/index.mjs"
     }
   },
   "scripts": {
@@ -50,14 +68,8 @@
     "clean": "rm -rf dist && rm -rf node_modules && rm -rf .turbo",
     "pretty": "biome format . --write",
     "checkTs": "tsc --noEmit",
-    "knip": "knip",
-    "lint": "biome lint . --write",
-    "check:ai-exported": "bash ./scripts/check-ai-exported.sh",
-    "check:ai-scope": "bash ./scripts/check-ai-scope.sh",
-    "check:ai-links": "bash ./scripts/check-ai-links.sh",
-    "check:ai-imports": "bash ./scripts/check-ai-imports.sh",
-    "check:ai-snippets": "bash ./scripts/check-ai-snippets.sh",
-    "check:ai-keys": "bash ./scripts/check-ai-keys.sh",
-    "check:ai-consistency": "bash ./scripts/check-ai-consistency.sh"
+    "check-exports": "attw --pack --profile esm-only",
+    "check:knip": "knip",
+    "lint": "biome lint . --write"
   }
 }

package/src/hooks/_mutationContract.test.ts

@@ -7,13 +7,13 @@ const HOOKS_DIR = resolve(fileURLToPath(import.meta.url), '..');
 
 /**
  * Manifest of every mutation hook. `nativeThrow: true` marks hooks whose underlying SDK methods
- * throw natively (Radfi APIs) and so don't need `unwrapResult`.
+ * throw natively (Bound Exchange APIs) and so don't need `unwrapResult`.
  *
  * To add a new mutation hook, add its path here. The friction is intentional — it forces explicit
  * registration so the contract is enforced from day one.
  */
 const HOOKS: Array<{ path: string; nativeThrow?: true }> = [
-  { path: 'backend/useBackendSubmitSwapTx.ts' },
+  { path: 'bitcoin/useEnsureRadfiAccessToken.ts', nativeThrow: true },
   { path: 'bitcoin/useFundTradingWallet.ts', nativeThrow: true },
   { path: 'bitcoin/useRadfiAuth.ts', nativeThrow: true },
   { path: 'bitcoin/useRadfiWithdraw.ts', nativeThrow: true },
@@ -26,6 +26,10 @@ const HOOKS: Array<{ path: string; nativeThrow?: true }> = [
   { path: 'dex/useDexDeposit.ts' },
   { path: 'dex/useDexWithdraw.ts' },
   { path: 'dex/useSupplyLiquidity.ts' },
+  { path: 'leverageYield/useLeverageYieldDeposit.ts' },
+  { path: 'leverageYield/useLeverageYieldNotifySolver.ts' },
+  { path: 'leverageYield/useLeverageYieldVaultSwap.ts' },
+  { path: 'leverageYield/useLeverageYieldWithdraw.ts' },
   { path: 'migrate/useMigrateBaln.ts' },
   { path: 'migrate/useMigrateIcxToSoda.ts' },
   { path: 'migrate/useMigratebnUSD.ts' },
@@ -38,9 +42,12 @@ const HOOKS: Array<{ path: string; nativeThrow?: true }> = [
   { path: 'mm/useWithdraw.ts' },
   { path: 'partner/useApproveToken.ts' },
   { path: 'partner/useFeeClaimSwap.ts' },
+  { path: 'partner/useFeeClaimWithdraw.ts' },
+  { path: 'partner/usePartnerCancelIntent.ts' },
   { path: 'partner/useSetSwapPreference.ts' },
   { path: 'recovery/useWithdrawHubAsset.ts' },
   { path: 'shared/useEstimateGas.ts' },
+  { path: 'shared/useRegisterNearStorage.ts', nativeThrow: true },
   { path: 'staking/useCancelUnstake.ts' },
   { path: 'staking/useClaim.ts' },
   { path: 'staking/useInstantUnstake.ts' },
@@ -54,6 +61,12 @@ const HOOKS: Array<{ path: string; nativeThrow?: true }> = [
   { path: 'swap/useCreateLimitOrder.ts' },
   { path: 'swap/useSwap.ts' },
   { path: 'swap/useSwapApprove.ts' },
+  { path: 'swapsApi/useSwapsApiApprove.ts' },
+  { path: 'swapsApi/useSwapsApiCancelIntent.ts' },
+  { path: 'swapsApi/useSwapsApiCreateIntent.ts' },
+  { path: 'swapsApi/useSwapsApiCreateLimitOrder.ts' },
+  { path: 'swapsApi/useSwapsApiSubmitIntent.ts' },
+  { path: 'swapsApi/useSwapsApiSubmitTx.ts' },
 ];
 
 describe.each(HOOKS)('mutation hook contract: $path', ({ path, nativeThrow }) => {

package/src/hooks/backend/index.ts

@@ -12,10 +12,6 @@ export { useBackendIntentByTxHash } from './useBackendIntentByTxHash.js';
 export { useBackendIntentByHash } from './useBackendIntentByHash.js';
 export { useBackendUserIntents } from './useBackendUserIntents.js';
 
-// Swap submit-tx hooks
-export { useBackendSubmitSwapTx } from './useBackendSubmitSwapTx.js';
-export { useBackendSubmitSwapTxStatus } from './useBackendSubmitSwapTxStatus.js';
-
 // Solver hooks
 export { useBackendOrderbook } from './useBackendOrderbook.js';
 
@@ -26,4 +22,4 @@ export { useBackendMoneyMarketAsset } from './useBackendMoneyMarketAsset.js';
 export { useBackendMoneyMarketAssetBorrowers } from './useBackendMoneyMarketAssetBorrowers.js';
 export { useBackendMoneyMarketAssetSuppliers } from './useBackendMoneyMarketAssetSuppliers.js';
 export { useBackendAllMoneyMarketBorrowers } from './useBackendAllMoneyMarketBorrowers.js';
-export * from './types.js';
+export * from './types.js';

package/src/hooks/bitcoin/index.ts

@@ -1,9 +1,11 @@
 export * from './useRadfiAuth.js';
+export * from './useEnsureRadfiAccessToken.js';
 export * from './useRadfiSession.js';
 export * from './useFundTradingWallet.js';
 export * from './useBitcoinBalance.js';
 export * from './useTradingWallet.js';
 export * from './useTradingWalletBalance.js';
+export * from './useBitcoinTradingSetup.js';
 export * from './useExpiredUtxos.js';
 export * from './useRenewUtxos.js';
 export * from './useRadfiWithdraw.js';

package/src/hooks/bitcoin/resolveBtcReadAddress.test.ts

@@ -0,0 +1,54 @@
+import { ChainKeys } from '@sodax/sdk';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { RadfiSession } from './useRadfiAuth.js';
+import { loadRadfiSession } from './useRadfiAuth.js';
+import { resolveBtcReadAddress } from './resolveBtcReadAddress.js';
+
+// resolveBtcReadAddress reads the Bound Exchange session via loadRadfiSession (localStorage-backed).
+// The dapp-kit test env is `node` (no localStorage), so mock the session lookup to drive each branch.
+vi.mock('./useRadfiAuth.js', () => ({
+  loadRadfiSession: vi.fn(),
+}));
+
+const mockLoadRadfiSession = vi.mocked(loadRadfiSession);
+
+const PERSONAL_ADDRESS = 'bc1qpersonal00000000000000000000000000000';
+const TRADING_ADDRESS = 'bc1qtrading000000000000000000000000000000';
+
+const session = (tradingAddress: string): RadfiSession => ({
+  accessToken: 'access',
+  refreshToken: 'refresh',
+  tradingAddress,
+  publicKey: 'pub',
+});
+
+describe('resolveBtcReadAddress', () => {
+  beforeEach(() => {
+    mockLoadRadfiSession.mockReset();
+  });
+
+  it('passes the address through unchanged for non-Bitcoin chains (no session lookup)', () => {
+    const result = resolveBtcReadAddress(ChainKeys.ARBITRUM_MAINNET, PERSONAL_ADDRESS);
+
+    expect(result).toBe(PERSONAL_ADDRESS);
+    expect(mockLoadRadfiSession).not.toHaveBeenCalled();
+  });
+
+  it('returns the trading address from the local session for Bitcoin', () => {
+    mockLoadRadfiSession.mockReturnValue(session(TRADING_ADDRESS));
+
+    const result = resolveBtcReadAddress(ChainKeys.BITCOIN_MAINNET, PERSONAL_ADDRESS);
+
+    expect(result).toBe(TRADING_ADDRESS);
+    // The session is keyed by the personal address.
+    expect(mockLoadRadfiSession).toHaveBeenCalledWith(PERSONAL_ADDRESS);
+  });
+
+  it('falls back to the personal address for Bitcoin when there is no session', () => {
+    mockLoadRadfiSession.mockReturnValue(null);
+
+    const result = resolveBtcReadAddress(ChainKeys.BITCOIN_MAINNET, PERSONAL_ADDRESS);
+
+    expect(result).toBe(PERSONAL_ADDRESS);
+  });
+});

package/src/hooks/bitcoin/resolveBtcReadAddress.ts

@@ -0,0 +1,21 @@
+import { ChainKeys, type SpokeChainKey } from '@sodax/sdk';
+import { loadRadfiSession } from './useRadfiAuth.js';
+
+/**
+ * Resolve a spoke address for READ queries (positions, balances, hub-wallet display).
+ *
+ * Bitcoin positions live under the Bound Exchange trading-wallet-derived hub wallet, so for Bitcoin we
+ * resolve to the trading address from the locally-persisted Bound Exchange session. This is intentionally
+ * a LOCAL lookup (no network call): a transient Bound Exchange API outage can never make a real position
+ * read as empty, and reads never throw "Trading wallet not found". When there is no session, the
+ * user has no Bitcoin position to show, so the original (personal) address is returned — deriving
+ * an empty hub wallet, which is correct. Non-Bitcoin chains pass through unchanged.
+ *
+ * The WRITE path resolves the trading address authoritatively in the SDK
+ * (`getEffectiveWalletAddress`, called from the money-market create*Intent flows); reads
+ * deliberately use this lighter, fail-safe path.
+ */
+export function resolveBtcReadAddress(chainKey: SpokeChainKey, address: string): string {
+  if (chainKey !== ChainKeys.BITCOIN_MAINNET) return address;
+  return loadRadfiSession(address)?.tradingAddress ?? address;
+}

package/src/hooks/bitcoin/useBitcoinTradingSetup.ts

@@ -0,0 +1,45 @@
+import {
+  ChainKeys,
+  type IBitcoinWalletProvider,
+  type IWalletProvider,
+  type RadfiWalletBalance,
+  type SpokeChainKey,
+} from '@sodax/sdk';
+import { useTradingWallet } from './useTradingWallet.js';
+import { useTradingWalletBalance } from './useTradingWalletBalance.js';
+
+export interface UseBitcoinTradingSetupParams {
+  chainKey: SpokeChainKey;
+  /** This side's wallet provider + account, e.g. `useWalletProvider` / `useXAccount`. */
+  walletProvider: IWalletProvider | undefined;
+  address: string | undefined;
+}
+
+export interface BitcoinTradingSetup {
+  wallet: IBitcoinWalletProvider | undefined;
+  tradingBalance: RadfiWalletBalance | undefined;
+}
+
+const INERT: BitcoinTradingSetup = { wallet: undefined, tradingBalance: undefined };
+
+/**
+ * Bitcoin trading-wallet setup for one side of a cross-chain flow: Bitcoin funds move through a
+ * Bound Exchange (Radfi) trading wallet, not the personal wallet. Inert (no work) unless `chainKey`
+ * is Bitcoin. Wallet-layer inputs are passed in — this package doesn't depend on wallet-sdk-react.
+ */
+export function useBitcoinTradingSetup({
+  chainKey,
+  walletProvider,
+  address,
+}: UseBitcoinTradingSetupParams): BitcoinTradingSetup {
+  const isBitcoin = chainKey === ChainKeys.BITCOIN_MAINNET;
+  // Safe: when this side is Bitcoin its provider IS the Bitcoin one (TS can't relate chainKey to provider type).
+  const wallet = isBitcoin ? (walletProvider as IBitcoinWalletProvider | undefined) : undefined;
+
+  // Hooks run every render; undefined inputs keep the Bound balance query disabled when not Bitcoin.
+  const { tradingAddress } = useTradingWallet(isBitcoin ? address : undefined);
+  const { data: tradingBalance } = useTradingWalletBalance({ params: { walletProvider: wallet, tradingAddress } });
+
+  if (!isBitcoin) return INERT;
+  return { wallet, tradingBalance };
+}

package/src/hooks/bitcoin/useEnsureRadfiAccessToken.ts

@@ -0,0 +1,57 @@
+import type { IBitcoinWalletProvider } from '@sodax/sdk';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import type { MutationHookParams } from '../shared/types.js';
+import { useSafeMutation, type SafeUseMutationResult } from '../shared/useSafeMutation.js';
+import { loadRadfiSession, saveRadfiSession } from './useRadfiAuth.js';
+
+export type UseEnsureRadfiAccessTokenVars = {
+  walletProvider: IBitcoinWalletProvider;
+};
+
+/**
+ * Ensure a valid Bound Exchange access token and return it. Refreshes the existing token (no
+ * signature prompt) when a refresh token is available, falling back to a full BIP322 re-auth only if
+ * refresh fails. Bound tokens are short-lived, so call this right before a Bitcoin-source
+ * createIntent — forward the returned token via the typed `extras.bound.accessToken` slot (SDK in-process)
+ * or the `accessToken` body field on the backend DTO — or before the client-side sign + co-sign step.
+ *
+ * @example
+ * const { mutateAsync: ensureToken } = useEnsureRadfiAccessToken();
+ * const accessToken = await ensureToken({ walletProvider });
+ * // SDK in-process (Bitcoin-gated extras):
+ * await sodax.swaps.createIntent({ params, extras: { bound: { accessToken } }, raw: true });
+ * // or backend createIntent — token in the body, not an x-bound-access-token header:
+ * await createIntent({ body: { ...body, accessToken } });
+ */
+export function useEnsureRadfiAccessToken({
+  mutationOptions,
+}: MutationHookParams<string, UseEnsureRadfiAccessTokenVars> = {}): SafeUseMutationResult<
+  string,
+  Error,
+  UseEnsureRadfiAccessTokenVars
+> {
+  const { sodax } = useSodaxContext();
+  return useSafeMutation<string, Error, UseEnsureRadfiAccessTokenVars>({
+    mutationKey: ['bitcoin', 'ensureAccessToken'],
+    ...mutationOptions,
+    mutationFn: async ({ walletProvider }) => {
+      const radfi = sodax.spoke.bitcoin.radfi;
+      const walletAddress = await walletProvider.getWalletAddress();
+      // Seed in-memory tokens from the saved session so a refresh can run without a re-sign popup.
+      const session = loadRadfiSession(walletAddress);
+      if (session?.refreshToken && !radfi.refreshToken) {
+        radfi.setRadfiAccessToken(session.accessToken, session.refreshToken);
+      }
+      await radfi.ensureRadfiAccessToken(walletProvider);
+      const accessToken = radfi.accessToken;
+      if (!accessToken) {
+        throw new Error('Failed to obtain a Bound Exchange access token');
+      }
+      // Persist refreshed tokens so a later reload can refresh again without re-signing.
+      if (session) {
+        saveRadfiSession(walletAddress, { ...session, accessToken, refreshToken: radfi.refreshToken });
+      }
+      return accessToken;
+    },
+  });
+}

package/src/hooks/bitcoin/useFundTradingWallet.ts

@@ -11,7 +11,7 @@ export type UseFundTradingWalletVars = {
 };
 
 /**
- * React hook for funding the user's Radfi trading wallet from their personal Bitcoin wallet.
+ * React hook for funding the user's Bound Exchange trading wallet from their personal Bitcoin wallet.
  * Pure mutation: pass `{ amount, walletProvider }` to `mutate({...})`. Returns the broadcast tx
  * id on success.
  */

package/src/hooks/bitcoin/useRadfiAuth.ts

@@ -45,7 +45,7 @@ export function clearRadfiSession(address: string): void {
 }
 
 /**
- * React hook for authenticating with Radfi via BIP322-signed message. Pure mutation: pass
+ * React hook for authenticating with Bound Exchange via BIP322-signed message. Pure mutation: pass
  * `{ walletProvider }` to `mutate({...})`. The hook itself takes no arguments other than the
  * structural `mutationOptions` slot.
  */
@@ -95,7 +95,7 @@ export function useRadfiAuth({
           }
 
           throw new Error(
-            'This wallet is already registered with Radfi from another session. ' +
+            'This wallet is already registered with Bound Exchange from another session. ' +
               'Please clear your browser storage for this site and try again, ' +
               'or wait for the previous session to expire.',
           );

package/src/hooks/bitcoin/useRadfiWithdraw.ts

@@ -19,7 +19,7 @@ type WithdrawResult = {
 };
 
 /**
- * React hook for withdrawing BTC from the user's Radfi trading wallet back to their personal
+ * React hook for withdrawing BTC from the user's Bound Exchange trading wallet back to their personal
  * Bitcoin wallet. Pure mutation: pass all inputs (including the wallet provider) to
  * `mutate({...})`.
  */
@@ -44,7 +44,7 @@ export function useRadfiWithdraw({
       const accessToken = session?.accessToken || radfi.accessToken;
 
       if (!accessToken) {
-        throw new Error('Radfi authentication required. Please login first.');
+        throw new Error('Bound Exchange authentication required. Please login first.');
       }
 
       const buildResult = await radfi.withdrawToUser({ userAddress, amount, tokenId, withdrawTo }, accessToken);

package/src/hooks/bitcoin/useRenewUtxos.ts

@@ -12,7 +12,7 @@ export type UseRenewUtxosVars = {
 };
 
 /**
- * React hook for renewing expired UTXOs in the user's Radfi trading wallet. Pure mutation: pass
+ * React hook for renewing expired UTXOs in the user's Bound Exchange trading wallet. Pure mutation: pass
  * `{ txIdVouts, walletProvider }` to `mutate({...})`.
  */
 export function useRenewUtxos({
@@ -32,7 +32,7 @@ export function useRenewUtxos({
       const accessToken = session?.accessToken || radfi.accessToken;
 
       if (!accessToken) {
-        throw new Error('Radfi authentication required. Please login first.');
+        throw new Error('Bound Exchange authentication required. Please login first.');
       }
 
       const buildResult = await radfi.buildRenewUtxoTransaction({ userAddress, txIdVouts }, accessToken);

package/src/hooks/bitcoin/useTradingWallet.ts

@@ -5,7 +5,7 @@ type UseTradingWalletReturn = {
 };
 
 /**
- * Returns the Radfi trading wallet address from the persisted session.
+ * Returns the Bound Exchange trading wallet address from the persisted session.
  * Trading wallet is created automatically during authentication — no API call needed.
  */
 export function useTradingWallet(walletAddress: string | undefined): UseTradingWalletReturn {

package/src/hooks/index.ts

@@ -4,9 +4,11 @@ export * from './bitcoin/index.js';
 export * from './mm/index.js';
 export * from './swap/index.js';
 export * from './backend/index.js';
+export * from './swapsApi/index.js';
 export * from './bridge/index.js';
 export * from './staking/index.js';
 export * from './partner/index.js';
 export * from './recovery/index.js';
 export * from './migrate/index.js';
 export * from './dex/index.js';
+export * from './leverageYield/index.js';

package/src/hooks/leverageYield/index.ts

@@ -0,0 +1,9 @@
+export * from './useLeverageYieldEffectiveApr.js';
+export * from './useLeverageYieldPosition.js';
+export * from './useLeverageYieldTotalAssets.js';
+export * from './useLeverageYieldPreviewRedeem.js';
+export * from './useLeverageYieldShareBalances.js';
+export * from './useLeverageYieldDeposit.js';
+export * from './useLeverageYieldNotifySolver.js';
+export * from './useLeverageYieldVaultSwap.js';
+export * from './useLeverageYieldWithdraw.js';

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,
+  });
+}