@sodax/skills 2.0.0-rc.11 → 2.0.0-rc.12

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "2.0.0-rc.11",
+  "version": "2.0.0-rc.12",
   "license": "MIT",
   "description": "AI-agent skills and knowledge for consumers of @sodax/* SDKs (Claude Code, Codex, Cursor, …)",
   "keywords": [

package/skills/sodax-dapp-kit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sodax-dapp-kit
-description: 'INTEGRATION (write NEW code) — @sodax/dapp-kit is React hooks wrapping @sodax/sdk with React Query across 11 feature domains (swap, money market, staking, bridge, dex, migration, partner, recovery, bitcoin/Radfi, backend queries, shared). React-only — Node and backend code uses `@sodax/sdk` directly. Use whenever a React dapp needs SODAX feature hooks. Triggers on "use @sodax/dapp-kit", "useSwap", "useMoneyMarket", "useStake", "useBridge", "useDex", "useMigrate", any `use<Feature>` hook name from dapp-kit, "Sodax React hooks", "dapp-kit query / mutation". v2 hook shape: mutation hooks return `SafeUseMutationResult` with `mutateAsyncSafe(vars): Promise<Result<TData>>`. mutationFn unwraps SDK Result<T> and throws on `!ok` so React Query''s native error model engages. Hook-owned invalidations — consumer onSuccess runs after. MIGRATION (port v1 → v2) — a deep canonicalization pass: single-object hook params, mandatory `mutateAsyncSafe`, hook-owned invalidations, throw-on-`Result.!ok` inside `mutationFn`, canonical queryKey/mutationKey conventions. Plus the SDK underneath was reshaped (chain-key-driven routing, `Result<T>` everywhere, `WalletProviderSlot<K, Raw>`). v1 dapp-kit code will not compile against v2. Triggers on "migrate @sodax/dapp-kit", "useSpokeProvider gone", "dapp-kit v1 → v2", "invalidateMmQueries broken", "dapp-kit hook signatures changed", v1 fingerprints (positional args, hook-init `spokeProvider`, `useSpokeProvider`, `invalidateMmQueries`, legacy `useMigrate`, `*_MAINNET_CHAIN_ID`). Load this skill if EITHER applies; the body gates by mode.'
+description: 'INTEGRATION (write NEW code) — @sodax/dapp-kit is React hooks wrapping @sodax/sdk with React Query across 11 feature domains (swap, money market, staking, bridge, dex, migration, partner, recovery, bitcoin/Bound Exchange, backend queries, shared). React-only — Node and backend code uses `@sodax/sdk` directly. Use whenever a React dapp needs SODAX feature hooks. Triggers on "use @sodax/dapp-kit", "useSwap", "useMoneyMarket", "useStake", "useBridge", "useDex", "useMigrate", any `use<Feature>` hook name from dapp-kit, "Sodax React hooks", "dapp-kit query / mutation". v2 hook shape: mutation hooks return `SafeUseMutationResult` with `mutateAsyncSafe(vars): Promise<Result<TData>>`. mutationFn unwraps SDK Result<T> and throws on `!ok` so React Query''s native error model engages. Hook-owned invalidations — consumer onSuccess runs after. MIGRATION (port v1 → v2) — a deep canonicalization pass: single-object hook params, mandatory `mutateAsyncSafe`, hook-owned invalidations, throw-on-`Result.!ok` inside `mutationFn`, canonical queryKey/mutationKey conventions. Plus the SDK underneath was reshaped (chain-key-driven routing, `Result<T>` everywhere, `WalletProviderSlot<K, Raw>`). v1 dapp-kit code will not compile against v2. Triggers on "migrate @sodax/dapp-kit", "useSpokeProvider gone", "dapp-kit v1 → v2", "invalidateMmQueries broken", "dapp-kit hook signatures changed", v1 fingerprints (positional args, hook-init `spokeProvider`, `useSpokeProvider`, `invalidateMmQueries`, legacy `useMigrate`, `*_MAINNET_CHAIN_ID`). Load this skill if EITHER applies; the body gates by mode.'
 ---
 
 # When to use this skill
@@ -32,7 +32,7 @@ Pick this mode when the consumer is a React dapp using `@sodax/dapp-kit` hooks.
 1. Read [`integration/knowledge/ai-rules.md`](./integration/knowledge/ai-rules.md) — DO / DO NOT / workflow / stop conditions.
 2. Read [`integration/knowledge/quickstart.md`](./integration/knowledge/quickstart.md) — install + wire providers + first feature.
 3. Read [`integration/knowledge/architecture.md`](./integration/knowledge/architecture.md) — hook shapes, queryKey conventions, `useSafeMutation`, `unwrapResult`, `Result<T>`.
-4. For each feature you use, read [`integration/knowledge/features/`](./integration/knowledge/features/) — `swap.md`, `money-market.md`, `staking.md`, `bridge.md`, `dex.md`, `migration.md`, `bitcoin.md` (Radfi, dapp-kit-unique), `auxiliary-services.md` (partner + recovery + backend + shared).
+4. For each feature you use, read [`integration/knowledge/features/`](./integration/knowledge/features/) — `swap.md`, `money-market.md`, `staking.md`, `bridge.md`, `dex.md`, `migration.md`, `bitcoin.md` (Bound Exchange, dapp-kit-unique), `auxiliary-services.md` (partner + recovery + backend + shared).
 5. Recipes → [`integration/knowledge/recipes/`](./integration/knowledge/recipes/) — `setup.md`, `wallet-connectivity.md`, per-feature, `mutation-error-handling.md`, `observability.md`, `invalidations.md`.
 6. Lookups → [`integration/knowledge/reference/`](./integration/knowledge/reference/) — `hooks-index.md`, `querykey-conventions.md`, `public-api.md`, `glossary.md`.
 

package/skills/sodax-dapp-kit/integration/knowledge/README.md

@@ -15,7 +15,7 @@ This tree documents v2 of the dapp-kit React hooks for **new consumers** buildin
 | [`features/bridge.md`](features/bridge.md) | Bridge hooks: `useBridge`, allowance/approve, bridgeable amount/tokens. |
 | [`features/dex.md`](features/dex.md) | DEX hooks: deposit/withdraw, supply/decrease liquidity, claim rewards, position info, pools. |
 | [`features/migration.md`](features/migration.md) | Migration hooks: ICX/bnUSD/BALN forward + reverse, allowance/approve. |
-| [`features/bitcoin.md`](features/bitcoin.md) | Radfi hooks (dapp-kit-unique): session, trading wallet, fund/withdraw, UTXOs. |
+| [`features/bitcoin.md`](features/bitcoin.md) | Bound Exchange hooks (dapp-kit-unique): session, trading wallet, fund/withdraw, UTXOs. |
 | [`features/auxiliary-services.md`](features/auxiliary-services.md) | Partner, recovery, backend queries, shared (xBalances, gas estimation, trustlines). |
 | [`recipes/`](recipes/) | Copy-paste patterns: setup, wallet connectivity, per-feature flows, mutation error handling, observability, invalidations. |
 | [`reference/`](reference/) | Lookup tables: full hook index, queryKey conventions, public API surface, glossary. |

package/skills/sodax-dapp-kit/integration/knowledge/features/README.md

@@ -10,7 +10,7 @@ Per-feature reference docs. Each file documents the hooks, params types, return
 | [`bridge.md`](bridge.md) | Cross-chain token bridging: `useBridge`, allowance/approve, bridgeable amount/tokens. |
 | [`dex.md`](dex.md) | Concentrated liquidity DEX: assets in/out, liquidity supply/decrease, claim rewards, position info, pool reads, param builders. |
 | [`migration.md`](migration.md) | Token migration: `useMigrateIcxToSoda`, `useRevertMigrateSodaToIcx`, `useMigratebnUSD`, `useMigrateBaln`, allowance/approve. |
-| [`bitcoin.md`](bitcoin.md) | Radfi (dapp-kit-unique): session, trading wallet, fund/withdraw, UTXOs. |
+| [`bitcoin.md`](bitcoin.md) | Bound Exchange (dapp-kit-unique): session, trading wallet, fund/withdraw, UTXOs. |
 | [`auxiliary-services.md`](auxiliary-services.md) | Partner fee claiming, recovery, backend queries (intent tracking, orderbook, MM data), shared utilities (xBalances, gas, trustlines). |
 
 ## Reference vs recipes

package/skills/sodax-dapp-kit/integration/knowledge/features/auxiliary-services.md

@@ -94,6 +94,10 @@ useGetUserHubWalletAddress({ params, queryOptions }); // Hub wallet via wallet r
 useEstimateGas({ mutationOptions });                // Gas estimation for raw tx
 useStellarTrustlineCheck({ params, queryOptions });
 useRequestTrustline({ mutationOptions });
+useNearStorageCheck({ params, queryOptions });      // NEP-141 storage registration check (NEAR)
+useRegisterNearStorage({ mutationOptions });        // NEP-141 storage_deposit (NEAR)
+useNearStorageGate({ dstChainKey, token, accountId, walletProvider }); // composite NEAR receive-side gate
+resolveNearStorageGate(chainKey, check);            // unwrapped util: gate-state from a useNearStorageCheck result
 ```
 
 ### `useXBalances` shape
@@ -144,6 +148,46 @@ if (hasTrustline === false) {
 }
 ```
 
+### NEAR storage registration
+
+NEP-141 accounts must pay a one-time storage bond before they can receive a token — delivering to an unregistered account fails. The receive-side analogue of Stellar trustlines: gate any flow that delivers a token to the user on NEAR (swap output on NEAR, bridge into NEAR, money-market borrow/withdraw to NEAR). Use `useNearStorageGate` for app UI; use the lower-level `useNearStorageCheck` + `useRegisterNearStorage` pair when you need custom wiring.
+
+```ts
+// @ai-snippets-skip — illustrative only; real types pulled into agents below.
+// useNearStorageCheck is a canonical read hook: { params: { token, accountId, chainId }, queryOptions }.
+// `chainId` is a SpokeChainKey typed loosely — the hook returns `true` for non-NEAR chains (safe to
+// gate conditionally) and `true` for native NEAR (not a NEP-141 token). data is a boolean;
+// queryKey: ['shared', 'nearStorageCheck', chainId, token, accountId].
+const { data: isRegistered, isLoading } = useNearStorageCheck({
+  params: { token, accountId, chainId: ChainKeys.NEAR_MAINNET },
+});
+
+// useRegisterNearStorage IS a canonical mutation hook: { mutationOptions }, returns
+// SafeUseMutationResult. Domain inputs flow through mutate / mutateAsync / mutateAsyncSafe.
+// Vars: { token, accountId, walletProvider, deposit? } — deposit defaults to the NEP-141
+// storage bond (0.00125 NEAR). mutationKey: ['shared', 'registerNearStorage'].
+const { mutateAsyncSafe: registerStorage } = useRegisterNearStorage();
+if (isRegistered === false) {
+  await registerStorage({ token, accountId, walletProvider });
+}
+```
+
+For the common UI path, `useNearStorageGate` returns `{ isNear, needsRegistration, blocksAction, isChecking, isRegistering, registerStorage }`.
+
+Derive UI gate flags with the unwrapped `resolveNearStorageGate` util (no hook) when you need custom check/register composition:
+
+```ts
+// @ai-snippets-skip — illustrative only.
+// resolveNearStorageGate(chainKey, check) reads `isLoading` + `data` off the useNearStorageCheck
+// result and returns { isNear, needsRegistration, blocksAction }:
+//   needsRegistration — show the register action (check resolved AND not registered)
+//   blocksAction      — keep the downstream action disabled (still checking OR needs registration)
+const check = useNearStorageCheck({ params: { token, accountId, chainId: dstChainKey } });
+const { needsRegistration, blocksAction } = resolveNearStorageGate(dstChainKey, check);
+```
+
+The underlying SDK methods (`isStorageRegistered` / `registerStorage` on the NEAR spoke service, and the `NEAR_STORAGE_DEPOSIT` constant) are documented in the `sodax-sdk` skill (integration mode).
+
 ## Default polling intervals
 
 | Hook | Polling | Notes |

package/skills/sodax-dapp-kit/integration/knowledge/features/bitcoin.md

@@ -1,6 +1,6 @@
-# Bitcoin (Radfi) — `@sodax/dapp-kit`
+# Bitcoin (Bound Exchange) — `@sodax/dapp-kit`
 
-Bitcoin trading via the Radfi protocol — authenticate, fund a trading wallet, withdraw, manage UTXOs. **Dapp-kit-unique surface** (no SDK equivalent — these flows are React-shaped).
+Bitcoin trading via the Bound Exchange protocol — authenticate, fund a trading wallet, withdraw, manage UTXOs. **Dapp-kit-unique surface** (no SDK equivalent — these flows are React-shaped).
 
 Pair: [`features/bitcoin.md`](../../../migration-v1-to-v2/knowledge/features/bitcoin.md).
 
@@ -15,7 +15,7 @@ useTradingWallet(walletAddress);                 // Synchronous: read persisted
 
 // Balances
 useBitcoinBalance({ params: { address, rpcUrl? }, queryOptions });             // Personal wallet (default mempool.space)
-useTradingWalletBalance({ params: { walletProvider, tradingAddress }, queryOptions }); // Radfi API
+useTradingWalletBalance({ params: { walletProvider, tradingAddress }, queryOptions }); // Bound Exchange API
 
 // Operations
 useFundTradingWallet({ mutationOptions });
@@ -26,7 +26,7 @@ useRenewUtxos({ mutationOptions });
 
 ## Session flow
 
-Radfi requires authentication before trading operations. `useRadfiSession` handles the full lifecycle:
+Bound Exchange requires authentication before trading operations. `useRadfiSession` handles the full lifecycle:
 
 ```ts
 // @ai-snippets-skip
@@ -76,8 +76,8 @@ type RenewUtxosVars = { txIdVouts: string[]; walletProvider: IBitcoinWalletProvi
 
 1. **Authentication required before any trading operation.** `useRadfiSession` manages this automatically — gate buttons on `isAuthed`.
 2. **Trading wallet is created during first authentication** — not a separate step.
-3. **`useTradingWallet(walletAddress)` is synchronous** (no network call). It reads persisted Radfi session from localStorage. Use it when you don't have a `walletProvider` available yet but need the trading address.
-4. **PSBT signing flow for withdrawals.** Radfi server builds an unsigned PSBT, the user signs locally via the wallet provider, then submits back for co-signing and broadcast. The dapp-kit hook orchestrates this — consumers don't see PSBTs directly.
+3. **`useTradingWallet(walletAddress)` is synchronous** (no network call). It reads persisted Bound Exchange session from localStorage. Use it when you don't have a `walletProvider` available yet but need the trading address.
+4. **PSBT signing flow for withdrawals.** Bound Exchange server builds an unsigned PSBT, the user signs locally via the wallet provider, then submits back for co-signing and broadcast. The dapp-kit hook orchestrates this — consumers don't see PSBTs directly.
 5. **Session tokens are for API rate-limiting, not asset access.** Stored in localStorage keyed by wallet address. Compromise of localStorage data doesn't affect funds.
 6. **`useExpiredUtxos` polls every 60s** — set `queryOptions.refetchInterval: false` to disable while UI is hidden.
 

package/skills/sodax-dapp-kit/integration/knowledge/features/money-market.md

@@ -43,6 +43,8 @@ type UseUserFormattedSummaryParams = ReadHookParams<FormatUserSummaryResponse, {
   userAddress: string | undefined;
 }>;
 // Same shape on useUserReservesData. The hook derives the hub wallet from (spokeChainKey, userAddress) internally.
+// Bitcoin: always pass the personal address as userAddress — the hook transparently resolves to the
+// Bound Exchange trading-wallet-derived hub wallet when a session is active (local lookup, no network).
 
 // useAToken — single aToken metadata; FLAT (no chain/user fields)
 type UseATokenParams = ReadHookParams<ATokenData, {
@@ -57,10 +59,13 @@ type UseATokensBalancesParams = ReadHookParams<Map<Address, bigint>, {
   userAddress: string | undefined;
 }>;
 // Returns a Map keyed by aToken address. The hook resolves the hub wallet from (spokeChainKey, userAddress).
+// Bitcoin: always pass the personal address — trading-wallet resolution is automatic when a session exists.
 ```
 
 > **Read-side chain key is `spokeChainKey`, not `srcChainKey`.** Mutation hooks (`useSupply`/`useBorrow`/etc.) use `srcChainKey` because the request crosses chains and needs a source. Read hooks describe a user's position on a single spoke chain — the field is `spokeChainKey`. Applies to `useATokensBalances`, `useUserFormattedSummary`, and `useUserReservesData` (`useAToken` is metadata-only and takes neither). Don't grep-replace one for the other.
 
+> **Bitcoin `userAddress`**: always pass the **personal** address (the user's wallet address), not the Bound Exchange trading address. The read hooks (`useATokensBalances`, `useUserReservesData`, `useUserFormattedSummary`, `useGetUserHubWalletAddress`) automatically resolve to the trading-wallet-derived hub wallet when a Bound Exchange session is active — this is a local lookup with no network call and no throw on an unauthenticated session. See [`features/bitcoin.md`](bitcoin.md) for Bound Exchange session setup.
+
 ## Mutation params
 
 All four user mutations share the same TVars shape (only the `action` literal differs):

package/skills/sodax-dapp-kit/integration/knowledge/recipes/bitcoin.md

@@ -1,6 +1,6 @@
-# Recipe: Bitcoin (Radfi)
+# Recipe: Bitcoin (Bound Exchange)
 
-Bitcoin trading via the Radfi protocol. Authenticate, fund a trading wallet, trade, withdraw, and manage UTXOs.
+Bitcoin trading via the Bound Exchange protocol. Authenticate, fund a trading wallet, trade, withdraw, and manage UTXOs.
 
 **Depends on:** [setup.md](setup.md), [wallet-connectivity.md](wallet-connectivity.md)
 
@@ -10,7 +10,7 @@ Bitcoin trading via the Radfi protocol. Authenticate, fund a trading wallet, tra
 
 | Hook | Type | Purpose |
 |------|------|---------|
-| `useRadfiAuth` | Mutation | Authenticate with Radfi via BIP322 signing |
+| `useRadfiAuth` | Mutation | Authenticate with Bound Exchange via BIP322 signing |
 | `useRadfiSession` | Utility | Manage full session lifecycle (login, refresh, auto-refresh) |
 | `useTradingWallet` | Utility | Get trading wallet address from persisted session (synchronous) |
 
@@ -19,7 +19,7 @@ Bitcoin trading via the Radfi protocol. Authenticate, fund a trading wallet, tra
 | Hook | Type | Purpose |
 |------|------|---------|
 | `useBitcoinBalance` | Query | BTC balance for any address (sums UTXOs from mempool.space) |
-| `useTradingWalletBalance` | Query | Trading wallet balance from Radfi API (confirmed + pending) |
+| `useTradingWalletBalance` | Query | Trading wallet balance from Bound Exchange API (confirmed + pending) |
 
 ### Operations
 
@@ -32,7 +32,7 @@ Bitcoin trading via the Radfi protocol. Authenticate, fund a trading wallet, tra
 
 ## Session Flow
 
-Radfi requires authentication before any trading operation. The typical flow:
+Bound Exchange requires authentication before any trading operation. The typical flow:
 
 ```tsx
 import { useRadfiSession } from '@sodax/dapp-kit';
@@ -49,7 +49,7 @@ function BitcoinAuth() {
 
   return (
     <button onClick={login} disabled={isLoginPending}>
-      {isLoginPending ? 'Signing...' : 'Login to Radfi'}
+      {isLoginPending ? 'Signing...' : 'Login to Bound Exchange'}
     </button>
   );
 }
@@ -77,7 +77,7 @@ function BitcoinBalances({ walletAddress }: { walletAddress: string }) {
     params: { address: walletAddress },
   });
 
-  // Trading wallet balance (from Radfi API). `RadfiWalletBalance` fields:
+  // Trading wallet balance (from Bound Exchange API). `RadfiWalletBalance` fields:
   // `btcSatoshi`, `pendingSatoshi`, `externalPendingSatoshi`, `totalUtxos`.
   const { data: tradingBalance } = useTradingWalletBalance({
     params: { walletProvider, tradingAddress },
@@ -188,6 +188,6 @@ function UtxoManager({ tradingAddress }: { tradingAddress: string }) {
 
 - **Authentication required** before any trading operation. `useRadfiSession` manages this automatically.
 - **Trading wallet** is created during first authentication — not a separate step.
-- **`useTradingWallet(walletAddress)`** is a synchronous utility (no network call) — it reads the persisted Radfi session from localStorage.
+- **`useTradingWallet(walletAddress)`** is a synchronous utility (no network call) — it reads the persisted Bound Exchange session from localStorage.
 - **PSBT signing flow**: withdraw and renew operations build an unsigned PSBT server-side, user signs it locally, then submits back for co-signing and broadcast.
 - **Session tokens** are stored in localStorage keyed by wallet address. They're for API rate-limiting, not for accessing user assets.

package/skills/sodax-dapp-kit/integration/knowledge/recipes/wallet-connectivity.md

@@ -16,6 +16,9 @@ Connect wallets and pass wallet providers to feature hooks.
 | `useEstimateGas` | `@sodax/dapp-kit` | Mutation | Estimate gas for raw transactions |
 | `useStellarTrustlineCheck` | `@sodax/dapp-kit` | Query | Check if Stellar account has sufficient trustline |
 | `useRequestTrustline` | `@sodax/dapp-kit` | Mutation | Request a Stellar trustline for a token |
+| `useNearStorageCheck` | `@sodax/dapp-kit` | Query | Check if a NEAR account is NEP-141 storage-registered for a token |
+| `useRegisterNearStorage` | `@sodax/dapp-kit` | Mutation | Submit a NEP-141 `storage_deposit` so a NEAR account can receive a token |
+| `useNearStorageGate` | `@sodax/dapp-kit` | Hook | Combine the NEAR storage check, registration mutation, and UI gate flags |
 
 ## Connect a Wallet
 

package/skills/sodax-dapp-kit/integration/knowledge/reference/glossary.md

@@ -130,7 +130,7 @@ App-level React component. Provides:
 - RPC config for all chains
 - Hub provider access (via `useHubProvider()`)
 
-Optional config: `<SodaxProvider config={DeepPartial<SodaxConfig>}>`. Without config, SDK uses packaged defaults.
+Optional config: `<SodaxProvider config={SodaxOptions}>` (`SodaxOptions = DeepPartial<SodaxConfig> & { logger? }`). Without config, SDK uses packaged defaults.
 
 Config is tracked by **reference** - see [`recipes/setup.md § Config reactivity`](../recipes/setup.md#config-reactivity) for module-const vs `useMemo` patterns.
 

package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md

@@ -108,7 +108,7 @@ Comprehensive hook table across 11 feature domains. Use this when you know the f
 | `useMigrationApprove` | Mutation | Approve before migration (action-discriminated) |
 | `useMigrationAllowance` | Query | Approval check (action-discriminated) |
 
-## Bitcoin / Radfi
+## Bitcoin / Bound Exchange
 
 | Hook | Type | Purpose |
 |---|---|---|
@@ -116,7 +116,7 @@ Comprehensive hook table across 11 feature domains. Use this when you know the f
 | `useRadfiSession` | Utility | Manage full session lifecycle |
 | `useTradingWallet` | Utility | Synchronously read trading wallet from localStorage |
 | `useBitcoinBalance` | Query | BTC balance for any address |
-| `useTradingWalletBalance` | Query | Trading wallet balance from Radfi API |
+| `useTradingWalletBalance` | Query | Trading wallet balance from Bound Exchange API |
 | `useFundTradingWallet` | Mutation | Fund trading wallet from personal wallet |
 | `useRadfiWithdraw` | Mutation | Withdraw from trading wallet |
 | `useExpiredUtxos` | Query | Expired UTXOs (polls 60s) |
@@ -179,6 +179,10 @@ Comprehensive hook table across 11 feature domains. Use this when you know the f
 | `useEstimateGas` | Mutation | Estimate gas for raw tx |
 | `useStellarTrustlineCheck` | Query | Check Stellar trustline |
 | `useRequestTrustline` | Mutation | Request a Stellar trustline |
+| `useNearStorageCheck` | Query | Check NEP-141 storage registration (NEAR) |
+| `useRegisterNearStorage` | Mutation | Submit NEP-141 `storage_deposit` (NEAR) |
+| `useNearStorageGate` | Hook | Composite NEAR receive-side storage gate |
+| `resolveNearStorageGate` | Utility | Derive gate flags from a `useNearStorageCheck` result (unwrapped) |
 | `useSafeMutation` | Internal | The wrapper every mutation hook calls |
 | `unwrapResult` | Internal | `Result<T>` → throw / return |
 | `toResult` | Internal | `Promise<T>` → `Result<T>` |

package/skills/sodax-dapp-kit/integration/knowledge/reference/querykey-conventions.md

@@ -77,6 +77,7 @@ queryKey: ['staking', 'allowance', srcChainKey, action, srcAddress, amount.toStr
 queryKey: ['mm', 'userReservesData', spokeChainKey, userAddress]
 queryKey: ['staking', 'info', srcChainKey, srcAddress]              // useStakingInfo — second segment is 'info', not 'stakingInfo'
 queryKey: ['shared', 'xBalances', xChainId, tokens, address]
+queryKey: ['shared', 'nearStorageCheck', chainId, token, accountId] // useNearStorageCheck
 
 // Mutation default keys
 mutationKey: ['swap']                                                // useSwap
@@ -90,6 +91,7 @@ mutationKey: ['staking', 'approve', 'stake']                         // useStake
 mutationKey: ['bridge']                                              // useBridge — single segment (no 'execute' suffix)
 mutationKey: ['migrate', 'icxToSoda']
 mutationKey: ['dex', 'supplyLiquidity']
+mutationKey: ['shared', 'registerNearStorage']                       // useRegisterNearStorage
 ```
 
 ## Per-feature key tables

package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md

@@ -27,7 +27,7 @@ The structural shape of every dapp-kit hook changed in v2. Five categories of br
 + }}>
 ```
 
-The `config` prop is `DeepPartial<SodaxConfig>` from `@sodax/sdk`. Other fields available: `api`, `solver`, `swaps`, `bridge`, `dex`, `moneyMarket`, `hub`, `relay`, `fee`. See `sodax-sdk`: `migration-v1-to-v2/knowledge/breaking-changes/architecture.md` for the SDK-side reshape.
+The `config` prop is `SodaxOptions` from `@sodax/sdk` (`= DeepPartial<SodaxConfig> & { logger? }`). Data override fields: `api`, `solver`, `swaps`, `bridge`, `dex`, `moneyMarket`, `hub`, `relay`, `fee`, plus the client-side `logger` sink. See `sodax-sdk`: `migration-v1-to-v2/knowledge/breaking-changes/architecture.md` for the SDK-side reshape.
 
 **Recommended pairing**: replace `new QueryClient()` with `createSodaxQueryClient()` for global mutation observability.
 

package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md

@@ -81,7 +81,7 @@ Full SDK-level detail: `sodax-sdk`: `migration-v1-to-v2/knowledge/breaking-chang
 
 ## `SodaxConfig` reshape — `rpcConfig` → `chains`
 
-`SodaxProvider`'s config prop is `DeepPartial<SodaxConfig>`. The SDK renamed/restructured the config:
+`SodaxProvider`'s config prop is `SodaxOptions` (`= DeepPartial<SodaxConfig> & { logger? }`). The SDK renamed/restructured the config:
 
 ```diff
 - <SodaxProvider rpcConfig={{

package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/checklist.md

@@ -33,7 +33,7 @@ For each feature your app uses, walk the matching `migration/features/<feature>.
 - [ ] [`features/bridge.md`](features/bridge.md) — bridge.
 - [ ] [`features/dex.md`](features/dex.md) — deposit / supply liquidity / etc.
 - [ ] [`features/migration.md`](features/migration.md) — ICX / bnUSD / BALN. **Note:** v1's `useMigrate(spokeProvider)` is gone; v2 has 6 per-action hooks.
-- [ ] [`features/bitcoin.md`](features/bitcoin.md) — Radfi.
+- [ ] [`features/bitcoin.md`](features/bitcoin.md) — Bound Exchange.
 - [ ] [`features/auxiliary-services.md`](features/auxiliary-services.md) — partner, recovery, backend queries, shared utilities.
 
 The cross-cutting pattern at every call site:

package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/README.md

@@ -10,7 +10,7 @@ Per-feature porting playbooks. Each file shows the v1 → v2 delta for one featu
 | [`bridge.md`](bridge.md) | Field renames in `useBridge` params (`srcChainId` → `srcChainKey`, `recipient` → `dstAddress`). `useGetBridgeableAmount` shape change. |
 | [`dex.md`](dex.md) | Two-step flow stayed the same; field renames + `srcChainKey` requirement. `useSupplyLiquidity` mint/increase routing. |
 | [`migration.md`](migration.md) | **Biggest change**: v1's `useMigrate(spokeProvider)` → 6 per-action hooks. |
-| [`bitcoin.md`](bitcoin.md) | Radfi flow shapes are mostly unchanged; provider/session lifecycle hooks tightened. |
+| [`bitcoin.md`](bitcoin.md) | Bound Exchange flow shapes are mostly unchanged; provider/session lifecycle hooks tightened. |
 | [`auxiliary-services.md`](auxiliary-services.md) | Partner / recovery / backend queries / shared utilities — small per-hook changes. |
 
 ## Pair-completeness

package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/bitcoin.md

@@ -1,8 +1,8 @@
-# Bitcoin (Radfi) migration — v1 → v2 (dapp-kit)
+# Bitcoin (Bound Exchange) migration — v1 → v2 (dapp-kit)
 
 Pair: [`features/bitcoin.md`](../../../integration/knowledge/features/bitcoin.md).
 
-Bitcoin / Radfi hook surface was new in v1 with limited adoption; v2 standardizes its shapes against the canonical hook conventions. Treat the v2 forms below as the canonical reference — if your v1 code used a different shape, swap to v2's directly.
+Bitcoin / Bound Exchange hook surface was new in v1 with limited adoption; v2 standardizes its shapes against the canonical hook conventions. Treat the v2 forms below as the canonical reference — if your v1 code used a different shape, swap to v2's directly.
 
 ## TL;DR
 

package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/reference/renamed-hooks.md

@@ -59,7 +59,7 @@ These keep their name but their TypeScript signature is different. Usually requi
 | `useTradingWalletBalance` | Return is `RadfiWalletBalance = { btcSatoshi, pendingSatoshi, externalPendingSatoshi, totalUtxos }` — NOT `{ confirmed, pending }`. |
 | `useExpiredUtxos` | Return is `RadfiUtxo[]` (with `_id`, `txid`, `vout`, `txidVout`, `satoshi`, `amount`, `address`, `isSpent`, `status`, `source`, optional `runes`). Both this and `useTradingWalletBalance` take `{ params: { walletProvider, tradingAddress } }`. |
 | `useRadfiAuth` | TData is `RadfiAuthResult = { accessToken, refreshToken, tradingAddress }` (3 fields — `publicKey` is persisted to localStorage but NOT returned). |
-| All Bitcoin/Radfi mutations | Standard pattern — drop hook-init args; pass through `mutate(vars)`. |
+| All Bitcoin/Bound Exchange mutations | Standard pattern — drop hook-init args; pass through `mutate(vars)`. |
 
 ## Cross-references
 

package/skills/sodax-sdk/SKILL.md

@@ -72,7 +72,7 @@ Follow in order. Skipping `ai-rules.md` is the most common cause of agents rever
 1. Read [`integration/knowledge/ai-rules.md`](./integration/knowledge/ai-rules.md) — DO / DO NOT / workflow / stop conditions.
 2. Read [`integration/knowledge/quickstart.md`](./integration/knowledge/quickstart.md) — install, initialize, first-run troubleshooting.
 3. For your feature, read [`integration/knowledge/features/`](./integration/knowledge/features/) — `swap.md`, `money-market.md`, `staking.md`, `bridge.md`, `dex.md`, `migration.md`, `partner.md`, `recovery.md`, `backend-api.md`.
-4. For specific patterns (init, raw vs signed, chain narrowing, gas, testing, errors), read [`integration/knowledge/recipes/`](./integration/knowledge/recipes/).
+4. For specific patterns (init, raw vs signed, chain narrowing, gas, testing, errors, logging), read [`integration/knowledge/recipes/`](./integration/knowledge/recipes/).
 5. Lookups (chain keys, error codes, public API surface, wallet provider types, glossary) → [`integration/knowledge/reference/`](./integration/knowledge/reference/).
 6. Non-EVM quirks (Stellar trustline, BTC PSBT, Solana PDA, ICON, NEAR) → [`integration/knowledge/chain-specifics.md`](./integration/knowledge/chain-specifics.md).
 

package/skills/sodax-sdk/integration/knowledge/README.md

@@ -19,7 +19,7 @@ This tree documents v2 of the SDK for **new consumers** building against it. If
 | [`features/backend-api.md`](features/backend-api.md) | `BackendApiService` — HTTP client for backend reads + swap-tx submission. |
 | [`recipes/`](recipes/) | Copy-pasteable patterns: SDK initialization, `Result` + error discrimination, raw-tx flow, signed-tx flow, chain-key narrowing + cast-at-boundary, testing (mocks/stubs), gas estimation, backend-server init. |
 | [`reference/`](reference/) | Lookup tables: 20-chain `ChainKeys` table with family + relay id, `I*WalletProvider` interfaces, 13 `SodaxErrorCode` meanings + per-feature narrow unions, public API surface (incl. `@sodax/types` re-export rule), glossary. |
-| [`chain-specifics.md`](chain-specifics.md) | Non-EVM quirks — Stellar trustline check/request, Bitcoin PSBT + Radfi auth/session, Solana PDA derivation, ICON Hana wallet + chain-key string, NEAR connector discovery. |
+| [`chain-specifics.md`](chain-specifics.md) | Non-EVM quirks — Stellar trustline check/request, Bitcoin PSBT + Bound Exchange auth/session, Solana PDA derivation, ICON Hana wallet + chain-key string, NEAR connector discovery. |
 
 ## Reading order for a new integrator
 

package/skills/sodax-sdk/integration/knowledge/architecture.md

@@ -95,7 +95,7 @@ The chain key is the bridge between the type system and runtime routing.
 The `Sodax` class is the public entry point. It constructs and wires every service once at construction time, then reuses them across calls:
 
 ```ts
-const sodax = new Sodax(/* optional DeepPartial<SodaxConfig> */);
+const sodax = new Sodax(/* optional SodaxOptions */);
 await sodax.config.initialize();   // fetch dynamic config; fall back to packaged defaults
 
 // All feature services accessed off the instance:
@@ -127,11 +127,13 @@ All feature services receive `{ hubProvider, config, spoke }` via constructor in
 ### Constructor
 
 ```ts
-import { Sodax, type SodaxConfig, type DeepPartial } from '@sodax/sdk';
+import { Sodax, type SodaxOptions } from '@sodax/sdk';
 
-new Sodax(config?: DeepPartial<SodaxConfig>): Sodax;
+new Sodax(config?: SodaxOptions): Sodax;
 ```
 
+`SodaxOptions` is `DeepPartial<SodaxConfig> & { logger?: SodaxLoggerOption }` — a deep-partial override of the `SodaxConfig` data contract, plus the client-side `logger` sink (kept off `SodaxConfig` itself; see [`recipes/logging.md`](recipes/logging.md)).
+
 `SodaxConfig` has exactly **10 fields** (all required at the type level, but `DeepPartial` makes every leaf optional):
 
 - `fee: PartnerFee | undefined` — global partner fee, applied unless a feature-level config overrides.

package/skills/sodax-sdk/integration/knowledge/chain-specifics.md

@@ -5,7 +5,7 @@ EVM chains (12 of them) work uniformly through `IEvmWalletProvider`. Non-EVM cha
 ## Section index
 
 1. [Stellar trustline](#1-stellar-trustline) — `STELLAR_MAINNET`. Required before receiving any non-XLM asset.
-2. [Bitcoin PSBT and Radfi](#2-bitcoin-psbt-and-radfi) — `BITCOIN_MAINNET`. PSBT signing; trading wallet; Radfi auth/session.
+2. [Bitcoin PSBT and Bound Exchange](#2-bitcoin-psbt-and-radfi) — `BITCOIN_MAINNET`. PSBT signing; trading wallet; Bound Exchange auth/session.
 3. [Solana PDA derivation](#3-solana-pda-derivation) — `SOLANA_MAINNET`. Deterministic addresses; one-time setup utilities.
 4. [ICON Hana wallet](#4-icon-hana-wallet) — `ICON_MAINNET`. Low-level Hana-extension helpers; chain key string vs numeric ID.
 5. [NEAR connector discovery](#5-near-connector-discovery) — `NEAR_MAINNET`. Account-id semantics; multiple wallet variants.
@@ -39,7 +39,7 @@ Stellar accounts that have never held the asset have **no** trustline — receiv
 
 ---
 
-## 2. Bitcoin PSBT and Radfi
+## 2. Bitcoin PSBT and Bound Exchange
 
 Bitcoin support uses Partially Signed Bitcoin Transactions (PSBT) — a different model than EVM tx signing. The wallet provider (`BTCWalletProvider`) handles PSBT construction and signing internally.
 
@@ -51,11 +51,11 @@ type BtcAddressType = 'P2PKH' | 'P2SH' | 'P2WPKH' | 'P2TR';
 
 `BTCWalletProvider` config takes an `addressType`. `'P2WPKH'` (native SegWit) is the modern default; `'P2TR'` (Taproot) is supported but may have lower compatibility with some on-chain logic.
 
-### Radfi (auth + trading wallet)
+### Bound Exchange (auth + trading wallet)
 
-SODAX uses the Radfi infrastructure for Bitcoin. Each user gets a derived "trading wallet" funded from their main BTC address. Operations consume UTXOs from the trading wallet rather than directly from the user's main address.
+SODAX uses the Bound Exchange infrastructure for Bitcoin. Each user gets a derived "trading wallet" funded from their main BTC address. Operations consume UTXOs from the trading wallet rather than directly from the user's main address.
 
-The Radfi provider is owned by `BitcoinSpokeService`. Reach it via the spoke router:
+The Bound Exchange provider is owned by `BitcoinSpokeService`. Reach it via the spoke router:
 
 ```ts
 import { ChainKeys, type BitcoinSpokeService } from '@sodax/sdk';
@@ -64,10 +64,10 @@ const btcSpoke = sodax.spoke.getSpokeService(ChainKeys.BITCOIN_MAINNET) as Bitco
 const radfi = btcSpoke.radfi;   // RadfiProvider instance
 ```
 
-Most consumer flows don't need to touch `radfi` directly — `sodax.bridge.bridge(...)`, `sodax.swaps.createIntent(...)`, etc. handle the Radfi auth + trading-wallet routing internally on the Bitcoin path. For explicit lifecycle management:
+Most consumer flows don't need to touch `radfi` directly — `sodax.bridge.bridge(...)`, `sodax.swaps.createIntent(...)`, etc. handle the Bound Exchange auth + trading-wallet routing internally on the Bitcoin path. For explicit lifecycle management:
 
 ```ts
-// Authenticate against Radfi (the wallet signs an auth message):
+// Authenticate against Bound Exchange (the wallet signs an auth message):
 await radfi.authenticateWithWallet(/* args per RadfiProvider source */);
 
 // Fetch the trading wallet for an address (creating it if needed):
@@ -84,7 +84,7 @@ Other public methods on `RadfiProvider` you may need: `setRadfiAccessToken`, `re
 
 ### Pitfall
 
-`BitcoinSpokeService.radfi` is what feature services use under the hood. Bypassing the feature services and driving Radfi yourself works but is rarely needed — and you have to wire token balances + UTXO state manually. Prefer the standard feature flows unless you specifically need lifecycle control.
+`BitcoinSpokeService.radfi` is what feature services use under the hood. Bypassing the feature services and driving Bound Exchange yourself works but is rarely needed — and you have to wire token balances + UTXO state manually. Prefer the standard feature flows unless you specifically need lifecycle control.
 
 ---
 
@@ -168,6 +168,31 @@ Both are valid. `GetAddressType<typeof ChainKeys.NEAR_MAINNET>` accepts both via
 
 `NearWalletProvider` requires the `accountId` field at construction (alongside `privateKey`). Unlike EVM, NEAR can't derive an account from a key alone — keys are scoped to accounts.
 
+### Receiving tokens: NEP-141 storage registration
+
+Before a NEAR account can **receive** (hold a balance of) a NEP-141 token, it must pay a one-time storage bond on that token contract — delivering to an unregistered account fails. This gates any flow that delivers a token to a user on NEAR: swap output on NEAR, bridge into NEAR, money-market borrow/withdraw to NEAR. (Native NEAR is not a NEP-141 token and needs no registration.)
+
+The NEAR spoke service exposes two methods — reach it via `sodax.spoke.near` or `sodax.spoke.getSpokeService(ChainKeys.NEAR_MAINNET)`:
+
+- `isStorageRegistered(token, accountId): Promise<boolean>` — whether `accountId` can already receive `token`. Returns `true` for the native token (no NEP-141). Read-only; uses the configured NEAR RPC.
+- `registerStorage({ token, accountId, walletProvider, deposit?, raw? })` — submits a `storage_deposit` for `accountId`; returns the tx hash (or the unsigned tx when `raw: true`). `deposit` defaults to `NEAR_STORAGE_DEPOSIT` (0.00125 NEAR, exported from `@sodax/sdk`) — override per token if its `storage_balance_bounds.min` differs. Throws for the native token. The recipient's NEAR wallet signs it.
+
+Gate pattern, run before delivering to NEAR:
+
+```ts
+// @ai-snippets-skip — illustrative.
+const near = sodax.spoke.near;
+if (!(await near.isStorageRegistered(token, accountId))) {
+  await near.registerStorage({ token, accountId, walletProvider });
+}
+```
+
+The `sodax-dapp-kit` skill wraps these as the `useNearStorageCheck` / `useRegisterNearStorage` hooks plus a `resolveNearStorageGate` helper (integration mode).
+
+### `ft_transfer_call` attaches 1 yoctoNEAR
+
+Deposits **from** NEAR (`deposit()` / `fillIntent()` on the NEAR spoke service) call the token's `ft_transfer_call`, which per NEP-141 must carry **exactly 1 yoctoNEAR** — the spoke service attaches it automatically. The signer only needs a small NEAR balance to cover gas (the 1 yoctoNEAR is dust). Native-token deposits use a plain `transfer` and aren't subject to this.
+
 ---
 
 ## Other non-EVM chains

package/skills/sodax-sdk/integration/knowledge/features/bridge.md

@@ -169,4 +169,5 @@ if (result.ok) {
 
 - v1 → v2 bridge migration: [`features/bridge.md`](../../../migration-v1-to-v2/knowledge/features/bridge.md).
 - Stellar destinations need a trustline first: [`../chain-specifics.md`](../chain-specifics.md).
+- NEAR destinations need NEP-141 storage registration first: [`../chain-specifics.md`](../chain-specifics.md).
 - Hub-and-spoke vault architecture: [`../architecture.md`](../architecture.md) § 1.

package/skills/sodax-sdk/integration/knowledge/features/money-market.md

@@ -196,3 +196,4 @@ Aave's RAY precision (27 decimals) is used for interest calculations under the h
 - v1 → v2 money market migration: [`features/money-market.md`](../../../migration-v1-to-v2/knowledge/features/money-market.md).
 - Architecture (hub-side wallet abstraction, ConfigService): [`../architecture.md`](../architecture.md) §§ 3, 4.
 - Stellar destinations need a trustline: [`../chain-specifics.md`](../chain-specifics.md).
+- NEAR destinations (borrow/withdraw to NEAR) need NEP-141 storage registration: [`../chain-specifics.md`](../chain-specifics.md).

package/skills/sodax-sdk/integration/knowledge/features/swap.md

@@ -271,3 +271,4 @@ Solver-specific context on `EXTERNAL_API_ERROR`:
 - v1 → v2 swap migration: [`features/swap.md`](../../../migration-v1-to-v2/knowledge/features/swap.md).
 - Error model: [`../architecture.md`](../architecture.md) § 8 and [`../reference/`](../reference/) § 3.
 - Stellar destinations require a trustline first: [`../chain-specifics.md`](../chain-specifics.md) § "Stellar trustline".
+- NEAR destinations require NEP-141 storage registration first: [`../chain-specifics.md`](../chain-specifics.md) § "Receiving tokens: NEP-141 storage registration".

package/skills/sodax-sdk/integration/knowledge/recipes/README.md

@@ -6,6 +6,7 @@ Copy-pasteable patterns for the most common Core SDK consumer tasks. Each file i
 |---|---|
 | [`initialize-sodax.md`](initialize-sodax.md) | App startup. `new Sodax()` + `await sodax.config.initialize()`, with and without config override. |
 | [`result-and-errors.md`](result-and-errors.md) | Branching on `result.ok`, switching on `(error.feature, error.code)`, `isSodaxError` over `instanceof`, sub-Result propagation, logger integration. |
+| [`logging.md`](logging.md) | Select a `SodaxLogger` (`'console'` / `'silent'` / custom sink) at construction; forward SDK diagnostics to Sentry / Pino / Datadog. |
 | [`signed-tx-flow.md`](signed-tx-flow.md) | `raw: false` + chain-narrowed `walletProvider`. Returns tx hash (or `TxHashPair` for cross-chain mutations). |
 | [`raw-tx-flow.md`](raw-tx-flow.md) | `raw: true`. Builds an unsigned chain-specific payload; you sign elsewhere. |
 | [`chain-key-narrowing.md`](chain-key-narrowing.md) | Cast-at-boundary pattern; runtime `chainType` discriminant. |

package/skills/sodax-sdk/integration/knowledge/recipes/initialize-sodax.md

@@ -15,9 +15,10 @@ const result = sodax.config.isValidSpokeChainKey(ChainKeys.ARBITRUM_MAINNET);
 ### With config override
 
 ```ts
-import { Sodax, ChainKeys, type SodaxConfig, type DeepPartial } from '@sodax/sdk';
+import { Sodax, ChainKeys, type SodaxOptions } from '@sodax/sdk';
 
-const config: DeepPartial<SodaxConfig> = {
+// `SodaxOptions` = `DeepPartial<SodaxConfig>` (the data override) plus the client-side `logger` option.
+const config: SodaxOptions = {
   // Per-chain overrides — merged with packaged defaults at the field level.
   chains: {
     [ChainKeys.SONIC_MAINNET]: { rpcUrl: process.env.SONIC_RPC_URL },
@@ -31,6 +32,8 @@ const config: DeepPartial<SodaxConfig> = {
   solver: {
     solverApiEndpoint: 'https://my-solver.example.com',
   },
+  // SDK log sink: 'console' (default) | 'silent' | a custom SodaxLogger. See logging.md.
+  logger: 'silent',
 };
 
 const sodax = new Sodax(config);
@@ -74,5 +77,6 @@ export const SUPPORTED_TOKENS_PER_CHAIN = sodaxConfig.swaps.supportedTokens;
 ## Cross-references
 
 - [`README.md`](README.md) — recipe index.
+- [`logging.md`](logging.md) — the `logger` constructor option in depth (presets + custom sinks).
 - [`../architecture.md`](../architecture.md) — concepts behind these patterns.
 - [`../reference/`](../reference/) — chain keys, error codes, public API surface.

package/skills/sodax-sdk/integration/knowledge/recipes/logging.md

@@ -0,0 +1,102 @@
+# Logging
+
+The SDK routes all of its internal diagnostics through a single `SodaxLogger` instead of calling
+`console.*` directly. Pick a preset or forward to a structured sink (Sentry, Pino, Datadog, …) without
+patching globals.
+
+## Select a logger at construction
+
+`logger` is a `Sodax` constructor option — a field on `SodaxOptions` (the constructor's parameter
+type), kept off the `SodaxConfig` data contract because it is a client-side sink, not backend-fetched
+config. It accepts a preset name or a custom implementation:
+
+```ts
+import { Sodax } from '@sodax/sdk';
+
+new Sodax();                       // default — same as { logger: 'console' }
+new Sodax({ logger: 'console' });  // mirror console.* output
+new Sodax({ logger: 'silent' });   // drop all SDK logs
+```
+
+The logger is resolved **once** at construction and held on `ConfigService` outside the swappable
+dynamic config (read it back as `sodax.config.logger`). `await sodax.config.initialize()` fetches fresh
+chain config from the backend but **never** replaces the logger — the backend cannot set or overwrite
+it.
+
+> Combine with the other constructor options freely — pass `logger` alongside `chains` / `api` /
+> `solver` overrides in the same object. The constructor splits `logger` off the data override before
+> merging, so it never lands in `sodax.instanceConfig`. See [`initialize-sodax.md`](initialize-sodax.md).
+
+## Custom sink
+
+Implement the `SodaxLogger` interface and pass the instance:
+
+```ts
+import { Sodax, type SodaxLogger } from '@sodax/sdk';
+
+const sentryLogger: SodaxLogger = {
+  debug: (message, data) => Sentry.addBreadcrumb({ level: 'debug', message, data }),
+  info: (message, data) => Sentry.addBreadcrumb({ level: 'info', message, data }),
+  warn: (message, data) => Sentry.captureMessage(message, { level: 'warning', extra: data }),
+  error: (message, error, data) =>
+    error !== undefined
+      ? Sentry.captureException(error, { extra: { message, ...data } })
+      : Sentry.captureMessage(message, { level: 'error', extra: data }),
+};
+
+const sodax = new Sodax({ logger: sentryLogger });
+```
+
+## Interface
+
+```ts
+import type { SodaxLogger, SodaxLoggerOption } from '@sodax/sdk';
+
+// SodaxLogger:
+//   debug(message: string, data?: Record<string, unknown>): void;
+//   info(message: string, data?: Record<string, unknown>): void;
+//   warn(message: string, data?: Record<string, unknown>): void;
+//   error(message: string, error?: unknown, data?: Record<string, unknown>): void;
+//
+// SodaxLoggerOption = SodaxLogger | 'console' | 'silent';
+```
+
+`error()` takes the thrown value as a separate second argument (before structured `data`) so adapters
+can attach it as the exception — `warn` / `info` / `debug` take only `(message, data?)`. SDK errors are
+`SodaxError` instances; their `toJSON()` is the canonical serialization surface (`JSON.stringify(error)`
+invokes it automatically). For routing a failed `Result<T>`'s `error` into a sink, see the **Logging**
+section of [`result-and-errors.md`](result-and-errors.md).
+
+## Built-in loggers and resolver
+
+`consoleLogger`, `silentLogger`, and `resolveLogger(option)` are exported from `@sodax/sdk` for
+composition — e.g. wrapping the console logger to add a prefix, or resolving a preset name yourself:
+
+```ts
+import { consoleLogger, resolveLogger, type SodaxLogger } from '@sodax/sdk';
+
+// Wrap the default to add a prefix
+const prefixed: SodaxLogger = {
+  debug: (m, d) => consoleLogger.debug(`[sodax] ${m}`, d),
+  info: (m, d) => consoleLogger.info(`[sodax] ${m}`, d),
+  warn: (m, d) => consoleLogger.warn(`[sodax] ${m}`, d),
+  error: (m, e, d) => consoleLogger.error(`[sodax] ${m}`, e, d),
+};
+
+// Resolve a preset name to a concrete logger
+const resolved = resolveLogger('silent'); // → silentLogger
+```
+
+## Coverage
+
+All instance feature services (swap, bridge, money market, DEX, staking, partner, recovery, the spoke
+services), `BackendApiService`, and the solver API client route through the configured logger. A small
+number of pure utility / static-helper functions still call `console.*` directly because they have no
+access to the instance logger.
+
+## Cross-references
+
+- [`README.md`](README.md) — recipe index.
+- [`initialize-sodax.md`](initialize-sodax.md) — the constructor options object `logger` lives in.
+- [`result-and-errors.md`](result-and-errors.md) — routing a failed `Result<T>` into a logging sink.
+- [`../reference/public-api.md`](../reference/public-api.md) — exported logger symbols.

package/skills/sodax-sdk/integration/knowledge/reference/public-api.md

@@ -8,9 +8,17 @@ Import everything from `@sodax/sdk`. The barrel re-exports the entire `@sodax/ty
 import {
   // Main entry
   Sodax,
+  type SodaxOptions, // constructor param: DeepPartial<SodaxConfig> & { logger? }
   type SodaxConfig,
   type DeepPartial,
 
+  // Logging (see recipes/logging.md)
+  type SodaxLogger,
+  type SodaxLoggerOption,
+  consoleLogger,
+  silentLogger,
+  resolveLogger,
+
   // Chain keys + narrowing
   ChainKeys,
   type ChainKey,