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

package/README.md

@@ -10,10 +10,10 @@ High-level React hooks library for dApp developers. Wraps `@sodax/sdk` with Reac
 - **Staking** — `useStake`, `useUnstake`, `useInstantUnstake`, `useClaim`, `useCancelUnstake`, approval hooks, info/config/ratio queries
 - **DEX** — `useDexDeposit`, `useDexWithdraw`, `useSupplyLiquidity`, `useDecreaseLiquidity`, `useClaimRewards`, pool/position queries, param builders
 - **Migration** — `useMigrateIcxToSoda`, `useRevertMigrateSodaToIcx`, `useMigratebnUSD`, `useMigrateBaln`, `useMigrationApprove`, `useMigrationAllowance`
-- **Bitcoin (Radfi)** — `useRadfiAuth`, `useRadfiSession`, `useTradingWallet`, `useTradingWalletBalance`, `useBitcoinBalance`, `useFundTradingWallet`, `useRadfiWithdraw`, `useExpiredUtxos`, `useRenewUtxos`
+- **Bitcoin (Bound Exchange)** — `useRadfiAuth`, `useRadfiSession`, `useTradingWallet`, `useTradingWalletBalance`, `useBitcoinBalance`, `useFundTradingWallet`, `useRadfiWithdraw`, `useExpiredUtxos`, `useRenewUtxos`
 - **Partner** — `useFetchAssetsBalances`, `useGetAutoSwapPreferences`, `useIsTokenApproved`, `useApproveToken`, `useSetSwapPreference`, `useFeeClaimSwap`
 - **Recovery** — `useHubAssetBalances`, `useWithdrawHubAsset`
-- **Backend Queries** — Intent tracking, orderbook, money market position queries
+- **Backend Queries** — Intent tracking, swap-tx submission + status, orderbook, money market position queries
 - **Shared** — `useXBalances`, `useDeriveUserWalletAddress`, `useGetUserHubWalletAddress`, `useStellarTrustlineCheck`, `useRequestTrustline`, `useEstimateGas`
 
 ## Installation
@@ -35,11 +35,11 @@ RPC URLs are injected through `config.chains`. `SodaxProvider` is the outermost
 import { QueryClientProvider } from '@tanstack/react-query';
 import { SodaxProvider, createSodaxQueryClient } from '@sodax/dapp-kit';
 import { SodaxWalletProvider, type SodaxWalletConfig } from '@sodax/wallet-sdk-react';
-import { ChainKeys, type DeepPartial, type SodaxConfig } from '@sodax/sdk';
+import { ChainKeys, type SodaxOptions } from '@sodax/sdk';
 
 const queryClient = createSodaxQueryClient();
 
-const sodaxConfig: DeepPartial<SodaxConfig> = {
+const sodaxConfig: SodaxOptions = {
   chains: {
     [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://sonic-rpc.publicnode.com' },
     [ChainKeys.BSC_MAINNET]: { rpcUrl: 'https://bsc-dataseed.binance.org' },
@@ -117,7 +117,7 @@ function SwapButton({ intentParams }: { intentParams: CreateIntentParams }) {
 
 ## Requirements
 
-- Node.js >= 18.0.0
+- Node.js >= 20.12.0
 - React >= 18
 - TypeScript
 
@@ -125,7 +125,7 @@ function SwapButton({ intentParams }: { intentParams: CreateIntentParams }) {
 
 ### Provider
 
-- [`SodaxProvider`](src/providers/SodaxProvider.tsx) — Wraps your app, creates the `Sodax` SDK instance. Accepts `config?: DeepPartial<SodaxConfig>`.
+- [`SodaxProvider`](src/providers/SodaxProvider.tsx) — Wraps your app, creates the `Sodax` SDK instance. Accepts `config?: SodaxOptions`.
 - [`createSodaxQueryClient()`](src/providers/createSodaxQueryClient.ts) — Factory for a `QueryClient` with global mutation observability (`onMutationError` hook, `meta.silent` opt-out).
 
 ### Swap Hooks
@@ -213,13 +213,13 @@ function SwapButton({ intentParams }: { intentParams: CreateIntentParams }) {
 - [`useMigrationApprove()`](src/hooks/migrate/useMigrationApprove.ts) — Approve token spending before migration
 - [`useMigrationAllowance()`](src/hooks/migrate/useMigrationAllowance.ts) — Check if approval is needed
 
-### Bitcoin (Radfi) Hooks
+### Bitcoin (Bound Exchange) Hooks
 
-- [`useRadfiSession()`](src/hooks/bitcoin/useRadfiSession.ts) — Manage Radfi session (login, auto-refresh)
-- [`useRadfiAuth()`](src/hooks/bitcoin/useRadfiAuth.ts) — Authenticate with Radfi via BIP322 signing
+- [`useRadfiSession()`](src/hooks/bitcoin/useRadfiSession.ts) — Manage Bound Exchange session (login, auto-refresh)
+- [`useRadfiAuth()`](src/hooks/bitcoin/useRadfiAuth.ts) — Authenticate with Bound Exchange via BIP322 signing
 - [`useTradingWallet()`](src/hooks/bitcoin/useTradingWallet.ts) — Get trading wallet address from persisted session
 - [`useBitcoinBalance()`](src/hooks/bitcoin/useBitcoinBalance.ts) — BTC balance for any address
-- [`useTradingWalletBalance()`](src/hooks/bitcoin/useTradingWalletBalance.ts) — Trading wallet balance from Radfi API
+- [`useTradingWalletBalance()`](src/hooks/bitcoin/useTradingWalletBalance.ts) — Trading wallet balance from Bound Exchange API
 - [`useFundTradingWallet()`](src/hooks/bitcoin/useFundTradingWallet.ts) — Fund trading wallet from personal wallet
 - [`useRadfiWithdraw()`](src/hooks/bitcoin/useRadfiWithdraw.ts) — Withdraw from trading wallet
 - [`useExpiredUtxos()`](src/hooks/bitcoin/useExpiredUtxos.ts) — Fetch expired UTXOs (polls every 60s)
@@ -262,8 +262,17 @@ function SwapButton({ intentParams }: { intentParams: CreateIntentParams }) {
 - [`useBackendMoneyMarketAssetBorrowers()`](src/hooks/backend/useBackendMoneyMarketAssetBorrowers.ts) — Asset borrowers
 - [`useBackendMoneyMarketAssetSuppliers()`](src/hooks/backend/useBackendMoneyMarketAssetSuppliers.ts) — Asset suppliers
 - [`useBackendAllMoneyMarketBorrowers()`](src/hooks/backend/useBackendAllMoneyMarketBorrowers.ts) — All borrowers
-- [`useBackendSubmitSwapTx()`](src/hooks/backend/useBackendSubmitSwapTx.ts) — Submit swap tx to backend
-- [`useBackendSubmitSwapTxStatus()`](src/hooks/backend/useBackendSubmitSwapTxStatus.ts) — Check submitted swap status
+
+### Swaps API Hooks (`sodax.api.swaps`)
+
+Typed wrappers over the backend Swaps API v2 — one `useSwapsApi*` hook per endpoint (21 total). Highlights:
+
+- [`useSwapsApiQuote()`](src/hooks/swapsApi/useSwapsApiQuote.ts) — Solver quote for a cross-chain swap
+- [`useSwapsApiCreateIntent()`](src/hooks/swapsApi/useSwapsApiCreateIntent.ts) — Build an unsigned create-intent tx
+- [`useSwapsApiSubmitTx()`](src/hooks/swapsApi/useSwapsApiSubmitTx.ts) — Submit swap tx to backend
+- [`useSwapsApiSubmitTxStatus()`](src/hooks/swapsApi/useSwapsApiSubmitTxStatus.ts) — Check submitted swap status
+
+See [`src/hooks/swapsApi/`](src/hooks/swapsApi/) for the full set (tokens, deadline, allowance, approve, submit/cancel intent, status, hash, packet, extra-data, intent lookups, limit orders, gas, fees).
 
 ### DEX Utils
 
@@ -286,75 +295,21 @@ pnpm lint        # Lint code
 
 ## AI agent docs
 
-`@sodax/dapp-kit` ships an AI-ready documentation tree at `node_modules/@sodax/dapp-kit/ai-exported/`. It's tool-neutral: any agent that can read files (Claude Code, Cursor, Aider, Copilot Chat, ChatGPT with file context, etc.) can use it without further setup.
-
-### Get started
+AI-readable docs for `@sodax/dapp-kit` (and the other `@sodax/*` packages) are shipped via [`@sodax/skills`](https://github.com/icon-project/sodax-sdks/tree/main/packages/skills) — a separate npm package bundling Claude-Code SKILL.md files and a long-form knowledge tree.
 
-Point your agent at `node_modules/@sodax/dapp-kit/ai-exported/AGENTS.md` — it routes to the rest. Three sample prompts covering the typical entry points:
+**Recommended: [`skills` CLI](https://github.com/vercel-labs/skills)** — from your project root:
 
-```
-> Read node_modules/@sodax/dapp-kit/ai-exported/AGENTS.md and integrate
-> SODAX cross-chain swaps into my React app.
-
-> Read node_modules/@sodax/dapp-kit/ai-exported/AGENTS.md. My app uses
-> v1 dapp-kit (useSpokeProvider, custom approve return shapes) — port to v2.
-
-> Look up the canonical mutation hook shape in
-> node_modules/@sodax/dapp-kit/ai-exported/integration/architecture.md.
+```bash
+npx skills@latest add icon-project/sodax-sdks/packages/skills
 ```
 
-### What's inside
+**npm + `AGENTS.md` pointer** (fallback for web chats, or when you prefer a devDependency over the CLI):
 
+```bash
+pnpm add -D @sodax/skills
 ```
-ai-exported/
-├── AGENTS.md                          # Tool-neutral entry point — start here
-├── integration/                       # Building NEW v2 dapp-kit code
-│   ├── README.md, ai-rules.md         # Index + DO / DO NOT / workflow for agents
-│   ├── quickstart.md                  # Install + wire providers + first feature
-│   ├── architecture.md                # Hook shapes, queryKey conventions, useSafeMutation, mutateAsyncSafe
-│   ├── features/                      # 8 feature pages: swap, money-market, staking, bridge,
-│   │                                  #   dex, migration, bitcoin (Radfi), auxiliary-services
-│   ├── recipes/                       # 13 patterns: setup, wallet-connectivity, per-feature flows,
-│   │                                  #   mutation error handling, observability, invalidations
-│   └── reference/                     # 4 lookup tables: full hook index, queryKey conventions,
-│                                      #   public API surface, glossary
-└── migration/                         # Porting EXISTING v1 dapp-kit code to v2
-    ├── README.md, ai-rules.md         # Index + workflow for porting agents
-    ├── checklist.md                   # Top-down cross-cutting checklist
-    ├── breaking-changes/              # 4 cross-cutting changes: hook-signatures, result-handling,
-    │                                  #   querykey-conventions, sdk-leakage
-    ├── features/                      # 8 per-feature porting playbooks
-    ├── recipes.md                     # Codemods + adapters
-    └── reference/                     # 3 reference tables: deleted hooks, renamed hooks,
-                                       #   error-shape crosswalk
-```
-
-### Scope
-
-This tree documents `@sodax/dapp-kit` (a React hooks library) only. It assumes:
-
-- **TypeScript + React** (>=18). Examples use TSX.
-- **Framework-agnostic**: works in any React app (Vite, Next.js client components, CRA, Remix, etc.). **No Next.js Server Components content** — dapp-kit is client-side React.
-- **Sibling packages used in examples**: `@sodax/sdk` (peer; types and config; re-exported transparently from dapp-kit), `@sodax/wallet-sdk-react` (sibling; `useWalletProvider` is in every signed-flow example), `@tanstack/react-query` (peer).
-- **`@sodax/types` is re-exported** through `@sodax/sdk` (which dapp-kit re-exports); consumers don't add it as a separate dependency.
-
-The underlying Core SDK has its own ai-exported tree at `node_modules/@sodax/sdk/ai-exported/` (resolves correctly in node_modules). The dapp-kit migration tree links to it for SDK-leakage topics (chain-key terminology, `Result<T>` semantics, `SodaxError<C>`).
-
-### Integrity guarantees
-
-Every release passes seven CI checks against `ai-exported/`:
-
-| Guard | What it catches |
-|---|---|
-| `check:ai-exported` | Each `useFoo` hook reference in markdown matches a real exported hook from `@sodax/dapp-kit` (or an upstream allowlist: React, React Query, wallet-sdk-react). |
-| `check:ai-scope` | No accidental imports from forbidden packages (e.g. `@sodax/wallet-sdk-core` for Node-only flows; `@sodax/types` directly). |
-| `check:ai-links` | Every relative link between markdown files resolves (including cross-package links into `../../../sdk/ai-exported/`). |
-| `check:ai-imports` | Every `import … from '@sodax/dapp-kit'` example in the docs typechecks against the package source. |
-| `check:ai-snippets` | Every fenced `​```ts`/`​```tsx` block is typechecked AS-IS against source (opt-out via `// @ai-snippets-skip` for genuinely illustrative blocks). Catches call-shape drift like wrong `useQuote({ params: <Request> })` vs canonical `useQuote({ params: { payload: <Request> } })`. |
-| `check:ai-keys` | Every `queryKey:` / `mutationKey:` literal in docs (both `kind: [...]` declarations and backticked-array table cells) matches a real source key prefix. Catches drift like `['staking', 'stakingInfo']` in docs when source uses `['staking', 'info']`. |
-| `check:ai-consistency` | Polling-interval claims in docs (e.g. "polls 3s", "auto-refresh every 2s") match the actual `refetchInterval` value in source. Catches drift like docs claiming 1s when source is 3000ms. |
 
-If you're contributing to this repo, run them with `pnpm -C packages/dapp-kit run check:ai-exported` (or `:scope`, `:links`, `:imports`, `:snippets`, `:keys`, `:consistency`).
+Then point your agent at `node_modules/@sodax/skills/AGENTS.md`. See [docs/ai-integration-guide.md](https://github.com/icon-project/sodax-sdks/blob/main/docs/ai-integration-guide.md) for all install modes and per-tool wiring.
 
 ## License