@sodax/skills 2.0.0-rc.8 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (168) hide show
  1. package/.claude-plugin/plugin.json +1 -0
  2. package/AGENTS.md +123 -13
  3. package/README.md +5 -2
  4. package/package.json +1 -1
  5. package/skills/sodax-build/SKILL.md +90 -0
  6. package/skills/sodax-build/knowledge/README.md +35 -0
  7. package/skills/sodax-build/knowledge/brief-template.md +41 -0
  8. package/skills/sodax-build/knowledge/chains-and-assets.md +26 -0
  9. package/skills/sodax-build/knowledge/example-sessions.md +84 -0
  10. package/skills/sodax-build/knowledge/feature-catalog.md +51 -0
  11. package/skills/sodax-build/knowledge/glossary.md +35 -0
  12. package/skills/sodax-build/knowledge/handoff.md +60 -0
  13. package/skills/sodax-build/knowledge/interview-guide.md +66 -0
  14. package/skills/sodax-build/knowledge/monetization.md +37 -0
  15. package/skills/sodax-build/knowledge/use-case-gallery.md +32 -0
  16. package/skills/sodax-dapp-kit/SKILL.md +6 -2
  17. package/skills/sodax-dapp-kit/auxiliary-services/SKILL.md +65 -0
  18. package/skills/sodax-dapp-kit/bitcoin/SKILL.md +57 -0
  19. package/skills/sodax-dapp-kit/bridge/SKILL.md +59 -0
  20. package/skills/sodax-dapp-kit/dex/SKILL.md +60 -0
  21. package/skills/sodax-dapp-kit/integration/knowledge/README.md +1 -1
  22. package/skills/sodax-dapp-kit/integration/knowledge/features/README.md +3 -2
  23. package/skills/sodax-dapp-kit/integration/knowledge/features/auxiliary-services.md +71 -11
  24. package/skills/sodax-dapp-kit/integration/knowledge/features/bitcoin.md +10 -6
  25. package/skills/sodax-dapp-kit/integration/knowledge/features/dex.md +2 -2
  26. package/skills/sodax-dapp-kit/integration/knowledge/features/leverage-yield.md +112 -0
  27. package/skills/sodax-dapp-kit/integration/knowledge/features/migration.md +1 -1
  28. package/skills/sodax-dapp-kit/integration/knowledge/features/money-market.md +6 -1
  29. package/skills/sodax-dapp-kit/integration/knowledge/features/swap.md +1 -1
  30. package/skills/sodax-dapp-kit/integration/knowledge/quickstart.md +2 -2
  31. package/skills/sodax-dapp-kit/integration/knowledge/recipes/README.md +1 -0
  32. package/skills/sodax-dapp-kit/integration/knowledge/recipes/backend-queries.md +23 -8
  33. package/skills/sodax-dapp-kit/integration/knowledge/recipes/bitcoin.md +8 -8
  34. package/skills/sodax-dapp-kit/integration/knowledge/recipes/leverage-yield.md +168 -0
  35. package/skills/sodax-dapp-kit/integration/knowledge/recipes/migration.md +1 -1
  36. package/skills/sodax-dapp-kit/integration/knowledge/recipes/setup.md +4 -4
  37. package/skills/sodax-dapp-kit/integration/knowledge/recipes/swap.md +1 -1
  38. package/skills/sodax-dapp-kit/integration/knowledge/recipes/wallet-connectivity.md +3 -0
  39. package/skills/sodax-dapp-kit/integration/knowledge/reference/glossary.md +1 -1
  40. package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md +67 -6
  41. package/skills/sodax-dapp-kit/integration/knowledge/reference/querykey-conventions.md +49 -0
  42. package/skills/sodax-dapp-kit/leverage-yield/SKILL.md +54 -0
  43. package/skills/sodax-dapp-kit/migration/SKILL.md +64 -0
  44. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md +1 -1
  45. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md +2 -2
  46. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/checklist.md +1 -1
  47. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/README.md +1 -1
  48. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/auxiliary-services.md +19 -10
  49. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/bitcoin.md +2 -2
  50. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/bridge.md +1 -1
  51. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/dex.md +1 -1
  52. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/migration.md +1 -1
  53. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/reference/renamed-hooks.md +3 -3
  54. package/skills/sodax-dapp-kit/money-market/SKILL.md +61 -0
  55. package/skills/sodax-dapp-kit/staking/SKILL.md +60 -0
  56. package/skills/sodax-dapp-kit/swap/SKILL.md +64 -0
  57. package/skills/sodax-sdk/SKILL.md +54 -50
  58. package/skills/sodax-sdk/backend-api/SKILL.md +58 -0
  59. package/skills/sodax-sdk/bridge/SKILL.md +53 -0
  60. package/skills/sodax-sdk/dex/SKILL.md +54 -0
  61. package/skills/sodax-sdk/integration/knowledge/README.md +5 -3
  62. package/skills/sodax-sdk/integration/knowledge/ai-rules.md +1 -1
  63. package/skills/sodax-sdk/integration/knowledge/architecture.md +26 -39
  64. package/skills/sodax-sdk/integration/knowledge/chain-specifics.md +57 -10
  65. package/skills/sodax-sdk/integration/knowledge/features/README.md +6 -3
  66. package/skills/sodax-sdk/integration/knowledge/features/backend-api.md +92 -0
  67. package/skills/sodax-sdk/integration/knowledge/features/bridge.md +48 -11
  68. package/skills/sodax-sdk/integration/knowledge/features/dex.md +7 -7
  69. package/skills/sodax-sdk/integration/knowledge/features/leverage-yield.md +175 -0
  70. package/skills/sodax-sdk/integration/knowledge/features/{icx-bnusd-baln.md → migration.md} +75 -30
  71. package/skills/sodax-sdk/integration/knowledge/features/money-market.md +20 -25
  72. package/skills/sodax-sdk/integration/knowledge/features/partner.md +86 -0
  73. package/skills/sodax-sdk/integration/knowledge/features/recovery.md +51 -0
  74. package/skills/sodax-sdk/integration/knowledge/features/staking.md +8 -3
  75. package/skills/sodax-sdk/integration/knowledge/features/swap.md +106 -22
  76. package/skills/sodax-sdk/integration/knowledge/features/swaps-api.md +171 -0
  77. package/skills/sodax-sdk/integration/knowledge/quickstart.md +1 -1
  78. package/skills/sodax-sdk/integration/knowledge/recipes/README.md +1 -0
  79. package/skills/sodax-sdk/integration/knowledge/recipes/backend-server-init.md +3 -3
  80. package/skills/sodax-sdk/integration/knowledge/recipes/gas-estimation.md +8 -4
  81. package/skills/sodax-sdk/integration/knowledge/recipes/initialize-sodax.md +34 -2
  82. package/skills/sodax-sdk/integration/knowledge/recipes/logging.md +102 -0
  83. package/skills/sodax-sdk/integration/knowledge/recipes/raw-tx-flow.md +28 -4
  84. package/skills/sodax-sdk/integration/knowledge/recipes/result-and-errors.md +1 -1
  85. package/skills/sodax-sdk/integration/knowledge/recipes/testing.md +7 -11
  86. package/skills/sodax-sdk/integration/knowledge/reference/README.md +1 -1
  87. package/skills/sodax-sdk/integration/knowledge/reference/chain-keys.md +40 -4
  88. package/skills/sodax-sdk/integration/knowledge/reference/error-codes.md +32 -9
  89. package/skills/sodax-sdk/integration/knowledge/reference/glossary.md +2 -2
  90. package/skills/sodax-sdk/integration/knowledge/reference/public-api.md +37 -4
  91. package/skills/sodax-sdk/leverage-yield/SKILL.md +50 -0
  92. package/skills/sodax-sdk/migration/SKILL.md +69 -0
  93. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/README.md +1 -1
  94. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/ai-rules.md +6 -10
  95. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/architecture.md +2 -2
  96. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/result-and-errors.md +3 -3
  97. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/type-system.md +6 -5
  98. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/checklist.md +2 -2
  99. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/README.md +4 -2
  100. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/backend-api.md +92 -0
  101. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/bridge.md +5 -5
  102. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/dex.md +2 -4
  103. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/{icx-bnusd-baln.md → migration.md} +31 -29
  104. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/money-market.md +2 -2
  105. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/partner.md +64 -0
  106. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/recovery.md +35 -0
  107. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/staking.md +8 -3
  108. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/swap.md +22 -18
  109. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/reference/sodax-config.md +19 -17
  110. package/skills/sodax-sdk/money-market/SKILL.md +56 -0
  111. package/skills/sodax-sdk/partner/SKILL.md +55 -0
  112. package/skills/sodax-sdk/recovery/SKILL.md +53 -0
  113. package/skills/sodax-sdk/staking/SKILL.md +53 -0
  114. package/skills/sodax-sdk/swap/SKILL.md +72 -0
  115. package/skills/sodax-sdk/swaps-api/SKILL.md +62 -0
  116. package/skills/sodax-wallet-sdk-core/SKILL.md +7 -3
  117. package/skills/sodax-wallet-sdk-core/bitcoin/SKILL.md +54 -0
  118. package/skills/sodax-wallet-sdk-core/evm/SKILL.md +54 -0
  119. package/skills/sodax-wallet-sdk-core/icon/SKILL.md +54 -0
  120. package/skills/sodax-wallet-sdk-core/injective/SKILL.md +54 -0
  121. package/skills/sodax-wallet-sdk-core/integration/knowledge/README.md +1 -1
  122. package/skills/sodax-wallet-sdk-core/integration/knowledge/ai-rules.md +2 -2
  123. package/skills/sodax-wallet-sdk-core/integration/knowledge/architecture.md +5 -5
  124. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/bitcoin.md +2 -2
  125. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/evm.md +2 -2
  126. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/icon.md +5 -5
  127. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/injective.md +4 -2
  128. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/near.md +1 -1
  129. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/solana.md +2 -2
  130. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/stacks.md +2 -2
  131. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/stellar.md +2 -2
  132. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/sui.md +1 -1
  133. package/skills/sodax-wallet-sdk-core/integration/knowledge/quickstart.md +1 -1
  134. package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/setup-private-key.md +2 -2
  135. package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/sign-and-broadcast.md +1 -0
  136. package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/testing.md +1 -1
  137. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/chain-support.md +3 -2
  138. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/interfaces.md +7 -5
  139. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/provider-classes.md +2 -2
  140. package/skills/sodax-wallet-sdk-core/migration-v1-to-v2/knowledge/README.md +1 -1
  141. package/skills/sodax-wallet-sdk-core/near/SKILL.md +54 -0
  142. package/skills/sodax-wallet-sdk-core/solana/SKILL.md +54 -0
  143. package/skills/sodax-wallet-sdk-core/stacks/SKILL.md +53 -0
  144. package/skills/sodax-wallet-sdk-core/stellar/SKILL.md +54 -0
  145. package/skills/sodax-wallet-sdk-core/sui/SKILL.md +53 -0
  146. package/skills/sodax-wallet-sdk-react/SKILL.md +5 -3
  147. package/skills/sodax-wallet-sdk-react/bridge-to-sdk/SKILL.md +56 -0
  148. package/skills/sodax-wallet-sdk-react/connect/SKILL.md +59 -0
  149. package/skills/sodax-wallet-sdk-react/integration/knowledge/architecture.md +3 -3
  150. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/chain-detection.md +1 -1
  151. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/connect-button.md +1 -1
  152. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/sign-message.md +10 -10
  153. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/switch-chain.md +1 -1
  154. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/api-surface.md +4 -4
  155. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/chain-support.md +4 -4
  156. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/connectors.md +1 -1
  157. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/hooks.md +5 -4
  158. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/wallet-brands.md +1 -1
  159. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/ai-rules.md +1 -1
  160. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/recipes/multi-chain-modal.md +57 -31
  161. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/recipes/ssr-setup.md +24 -19
  162. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/reference/config.md +1 -1
  163. package/skills/sodax-wallet-sdk-react/sign-message/SKILL.md +51 -0
  164. package/skills/sodax-wallet-sdk-react/switch-chain/SKILL.md +51 -0
  165. package/skills/sodax-wallet-sdk-react/wallet-modal/SKILL.md +54 -0
  166. package/skills/sodax-wallet-sdk-react/walletconnect/SKILL.md +52 -0
  167. package/skills/sodax-sdk/integration/knowledge/features/auxiliary-services.md +0 -189
  168. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/auxiliary-services.md +0 -156
@@ -0,0 +1,35 @@
1
+ # Glossary — DeFi jargon → plain English
2
+
3
+ For glossing terms during the interview. Apply **by tier** (see [`interview-guide.md`](./interview-guide.md)):
4
+
5
+ - **Tier A (non-coder):** gloss every term on first use, with the one-line plain version.
6
+ - **Tier B (semi-technical):** gloss once, then use the term.
7
+ - **Tier C (developer):** do not gloss.
8
+
9
+ **Rules:** never chain two glosses in one breath; after defining a term, re-ask the pending question. Keep the plain version first; the precise term is for the brief.
10
+
11
+ | Term | Plain English (say this first) | Precise note (for the brief) |
12
+ |---|---|---|
13
+ | **Hub-and-spoke** | "Everything routes through one central chain, so users can act from their own chain." | Sonic is the hub; other chains are spokes. |
14
+ | **Hub chain (Sonic)** | "The central chain SODAX uses behind the scenes." | The user rarely interacts with it directly. |
15
+ | **Spoke chain** | "Any chain a user actually starts from." | E.g. Ethereum, Base, Solana. |
16
+ | **Swap** | "Trade one coin for another." | Intent-based; filled by a solver, not a fixed pool. |
17
+ | **Bridge** | "Move the *same* coin to another chain." | Works for tokens sharing a hub vault. |
18
+ | **Intent** | "You say what you want; someone competes to do it for you." | On-chain order with a minimum-output floor. |
19
+ | **Solver** | "An off-chain service that finds you a price and fills your trade." | Sources its own liquidity; price is a live quote. |
20
+ | **Slippage / min output** | "The worst price you are willing to accept — you get at least that or it does not happen." | `minOutputAmount` floor on the intent. |
21
+ | **Money market** | "Lend your coins to earn, or borrow against what you hold." | Cross-chain supply/borrow. |
22
+ | **Staking** | "Lock the SODA token to earn." | SODA → xSoda vault share. |
23
+ | **Liquidity / LP** | "Put two coins into a shared pool so others can trade, and earn fees." | Concentrated-liquidity DEX. |
24
+ | **Allowance / approval** | "A one-time permission so the app can move a specific token for you." | ERC-20 approve step. |
25
+ | **Wallet** | "The app that holds your coins and signs actions (e.g. MetaMask)." | Per-chain provider in the SDK. |
26
+ | **Partner fee** | "The cut the app you built takes on each transaction." | See [`monetization.md`](./monetization.md). |
27
+ | **Gas** | "The small network fee paid to process a transaction." | Paid in the chain's native coin; not a SODAX fee. |
28
+ | **Token migration** | "Move an older ICON-era coin (ICX/BALN/bnUSD) into the new system." | Specific tokens only. |
29
+ | **Recovery** | "Getting back coins that got stuck." | Withdraw stuck hub-wallet assets to a spoke. |
30
+ | **Cross-chain** | "Doing something that spans two different blockchains at once — SODAX's specialty." | The hub routes the action between spokes; this is SODAX's main advantage. |
31
+ | **Stablecoin** | "A coin designed to hold a steady value, often about 1 US dollar (e.g. USDC)." | Peg stability is the issuer's promise, not SODAX's — never guarantee a peg. |
32
+ | **Testnet / mainnet** | "Mainnet is the real network with real money; testnet is a free practice copy." | Not every SODAX feature flow has a testnet — confirm per feature before assuming one exists. |
33
+ | **Smart contract** | "A program on the blockchain that runs exactly as written, with no middleman." | SODAX features are smart contracts the SDK calls for you. |
34
+
35
+ If a user asks about a term not listed here, give a one-line plain answer and, if it is an exact/enumerable fact (a specific token, chain, or number), fetch live source per the README policy rather than guessing.
@@ -0,0 +1,60 @@
1
+ # Handoff — product shape → developer skill(s)
2
+
3
+ The last step. Map the brief's build shape to the exact developer skill(s) the user loads next, plus ordered scaffolding steps. This is a **strict refinement of the package `AGENTS.md` router** — if they ever disagree, `AGENTS.md` wins.
4
+
5
+ **Hard rule:** name the developer skills in **prose only** (backticks). Never write a clickable link or a path into another skill — that is a forbidden cross-skill reference. This skill links only within its own `knowledge/`.
6
+
7
+ ## Decision table
8
+
9
+ | Product shape | Hand off to (in order, integration mode) | Start from (starter app, prose) |
10
+ |---|---|---|
11
+ | Web app: wallet + feature UI | `sodax-wallet-sdk-react` → `sodax-dapp-kit` (the matching feature) | the demo app (`apps/demo`): its provider setup + the matching feature page |
12
+ | React app calling the SDK directly | `sodax-wallet-sdk-react` → `sodax-sdk` (the matching feature) | the demo app (`apps/demo`) |
13
+ | Wallet UX is the hard part (Tier-A audience) | `sodax-wallet-sdk-react` (wallet-modal concern) → `sodax-dapp-kit` (feature) | the wallet-modal example app, then graft the feature from the demo app |
14
+ | Backend / bot / script | `sodax-sdk` (feature) → `sodax-wallet-sdk-core` (the chain, if it signs) | the node example app (`apps/node`, or `apps/node-cjs` for CommonJS) |
15
+ | Non-React browser | `sodax-wallet-sdk-core` (the chain) → `sodax-sdk` (feature) | the wallet-modal example app minus the React parts |
16
+ | Porting an existing v1 app | each dev skill above in **migration** mode first | the user's own repo |
17
+
18
+ **Partner fee** always adds the `sodax-sdk` partner feature; in a React app, also `sodax-dapp-kit`.
19
+
20
+ **Non-EVM chains:** if the product touches **any non-EVM chain**, add the matching chain in `sodax-wallet-sdk-core` to the handoff — each non-EVM chain needs its own wallet provider.
21
+
22
+ ## How to choose mode
23
+
24
+ - **Integration** (write new v2 code) — the default for a brand-new product.
25
+ - **Migration** (port v1 → v2) — only if the user already has existing v1 SODAX code. Do migration first, then integration for new code.
26
+
27
+ ## Ordered scaffolding steps (handed to the dev skill, not executed here)
28
+
29
+ Write these into the brief's section 9 so the dev skill can follow them:
30
+
31
+ 1. Scaffold the project (framework is the builder's choice — the SDK has no opinion).
32
+ 2. Install the SDK package(s) named in the handoff.
33
+ 3. Set up the wallet/provider stack (mirror the demo app's provider setup for React; a private-key provider for backend).
34
+ 4. Wire wallet connect (React) or instantiate the chain provider (backend).
35
+ 5. Build the **Phase-1 tracer-bullet feature only**.
36
+ 6. Attach the partner fee (if monetizing).
37
+ 7. Configure chains/RPC — **start in the safest supported environment** (testnet if the feature flow has one; many SODAX feature configs are mainnet-oriented, so confirm what's available from the dev skill / live source — do not assume testnet exists).
38
+ 8. Verify: a clean type-check and **one real end-to-end transaction**.
39
+
40
+ ## What to tell the user
41
+
42
+ End the handoff with a plain sentence the user can act on, e.g.: *"Load the `sodax-wallet-sdk-react` skill in integration mode, then the `sodax-dapp-kit` skill for the swap feature. Start from the demo app's provider setup. Your Phase-1 goal is one working cross-chain transfer in the safest supported environment (testnet if the feature flow supports it)."* — then **stop**. Do not write the code.
43
+
44
+ ## Structured handoff block (append to brief section 9)
45
+
46
+ After the prose handoff, append a machine-readable block so an orchestrator — or the next dev skill — can parse the routing deterministically. Use **YAML**, never ts/tsx. Fill only what the brief decided; omit unknowns rather than guessing:
47
+
48
+ ```yaml
49
+ handoff:
50
+ skills: # in load order; integration mode unless noted
51
+ - sodax-wallet-sdk-react
52
+ - sodax-dapp-kit
53
+ mode: integration # or "migration" (port v1 first), then integration
54
+ partner_fee: true # if true, also load the sodax-sdk partner feature (+ sodax-dapp-kit in React)
55
+ non_evm_chains: [] # each entry adds a sodax-wallet-sdk-core/<chain> provider
56
+ starter_app: apps/demo
57
+ phase1_goal: "one working cross-chain transfer in the safest supported environment"
58
+ ```
59
+
60
+ Skills are named as plain strings, not links. This block is a convenience contract, **not** a second source of truth — the prose handoff and the package `AGENTS.md` still govern if they ever disagree.
@@ -0,0 +1,66 @@
1
+ # Interview guide
2
+
3
+ The branching question tree the `sodax-build` workflow drives. Goal: turn a vague idea into a single, well-scoped Phase-1 product without making the user learn DeFi.
4
+
5
+ ## Rules (apply throughout)
6
+
7
+ - **One question at a time.** Never batch.
8
+ - **Always offer a recommended default** the user can accept ("Most people start with X — sound right?"), especially for Tier A.
9
+ - **Reflect the goal back in the user's own words** before mapping it to a feature.
10
+ - **Product language before jargon.** Ask about behavior ("move money to a friend on another chain"), not features ("bridge"). Gloss a term only when you must, per [`glossary.md`](./glossary.md).
11
+ - **Converge, don't expand.** Drive toward ONE primary goal (+ at most one secondary). Park everything else in "out of scope (v1)".
12
+ - **Honesty-gate** unsupported chains/assets and unknown exact values against [`chains-and-assets.md`](./chains-and-assets.md) — fetch live source rather than guess.
13
+
14
+ ## Stage 0 — Tech-comfort gate (sets the tier)
15
+
16
+ First question. Set a persistent tier that controls vocabulary and question count:
17
+
18
+ - **A — non-coder:** "I am not a developer" / business or product framing.
19
+ - **B — semi-technical:** builds apps, new to DeFi/crypto.
20
+ - **C — developer:** names languages, frameworks, or SDKs → likely belongs in a dev skill (re-check the SKILL.md STOP gate).
21
+
22
+ Soft-detect from their phrasing too; re-check at every stage.
23
+
24
+ ## Stage 1 — Goal in their own words
25
+
26
+ Open-ended: *"In one or two sentences, what do you want people to be able to do?"* Classify into an archetype internally, but **confirm it back in their words**. Lock a single primary goal.
27
+
28
+ ## Stage 2 — Map goal → feature (the branching core)
29
+
30
+ Each archetype opens 1–3 disambiguating questions phrased about **product behavior**, never requiring the user to name a feature. Mapping table:
31
+
32
+ | User says (plain English) | Disambiguator | SODAX feature |
33
+ |---|---|---|
34
+ | "move money / pay someone / send to another chain" | Same coin on the other side? | **Bridge** |
35
+ | "let people trade / convert one coin to another" | Different coin out? | **Swap** |
36
+ | "earn / savings / put money to work" | Lend out their own assets? | **Money market** (supply) |
37
+ | "earn by locking SODA" | Lock the SODA token? | **Staking** |
38
+ | "borrow against what they hold" | Use collateral? | **Money market** (borrow) |
39
+ | "provide liquidity / market-make" | Run an LP position? | **DEX** (concentrated liquidity) |
40
+ | "leveraged / amplified yield" (advanced — Tier B/C only) | Understands leverage risk? | **Leverage yield** (see [`feature-catalog.md`](./feature-catalog.md); never offer Tier A as "savings") |
41
+ | "move a legacy ICON-era token over" | Which token — ICX / BALN / bnUSD? | **Token migration** (else honesty-gate) |
42
+ | "launch a brand-new token" | — | **Honesty-gate**: SODAX does not mint new tokens |
43
+ | "get back funds stuck on the hub" | — | **Recovery** (usually secondary) |
44
+
45
+ > **Lead with cross-chain — it is SODAX's edge.** Swap vs Bridge is about the *coin*, not the chain: Swap = the output token differs (most powerfully **across chains**); Bridge = the *same* token moved to another chain. A same-chain conversion is still a Swap (not a Bridge); lead with the cross-chain angle — that is SODAX's strength.
46
+
47
+ Always plant the **monetization seed** here: *"Do you want to earn from this — now, later, or keep it free?"* (detail deferred to Stage 4).
48
+
49
+ See [`feature-catalog.md`](./feature-catalog.md) for the plain-English description of each feature, and [`use-case-gallery.md`](./use-case-gallery.md) for worked combinations.
50
+
51
+ ## Stage 3 — Users, chains, assets
52
+
53
+ - **Who uses it** and **on which chains**. Tier A gets a recommended default to confirm (e.g. "start with a small number of EVM chains — one major chain plus one lower-fee chain"). Confirm against [`chains-and-assets.md`](./chains-and-assets.md).
54
+ - **Honesty-gate** any unsupported chain.
55
+ - **Flag non-EVM assets**: if the product touches **any non-EVM chain**, note that it pulls in a chain-specific wallet provider — this changes the handoff (a matching chain skill in `sodax-wallet-sdk-core`). Confirm which chains are non-EVM against live source if it matters.
56
+
57
+ ## Stage 4 — Monetization detail (only if not "free")
58
+
59
+ Frame against [`monetization.md`](./monetization.md). Capture: percentage vs fixed; which actions carry the fee; where fees go (default: defer the fee address). **Treat the exact percentage cap as policy-sensitive** — prefer low, transparent fees; fetch live source before quoting an exact cap.
60
+
61
+ ## Stage 5 — Converge on scope + playback
62
+
63
+ - Force **one** Phase-1 tracer-bullet (the smallest end-to-end slice that delivers the core value).
64
+ - Capture an explicit **out-of-scope (v1)** list.
65
+ - Infer the **build shape**: browser + wallet UI → React path; service/bot → backend path; existing v1 code detected → migration mode. This drives [`handoff.md`](./handoff.md).
66
+ - **Playback:** restate the whole thing as plain bullets and ask for a single confirmation. Only after the user confirms, assemble the brief from [`brief-template.md`](./brief-template.md).
@@ -0,0 +1,37 @@
1
+ # Monetization — partner fees
2
+
3
+ > **Source & freshness.** Fee values are exact and **must not be quoted from memory as absolute**. The fee *types* (defined in `@sodax/types`) and the *runtime validation* (in `@sodax/sdk`) currently disagree — fetch both from live source before stating any number or cap. Where to look: the README *Source & freshness policy*.
4
+
5
+ The monetization mechanism for products built on SODAX is the **partner fee**: the app/integrator takes a cut on transactions routed through it. There are two distinct fees in play — be clear about which is which.
6
+
7
+ ## Two fees
8
+
9
+ - **Protocol (solver) fee — fixed, set by SODAX.** A small fixed protocol fee applies to swaps. The end-user and the integrator do not control it. Confirm the exact current value from live source before quoting it.
10
+ - **Partner fee — set by the integrator (the person building the product).** This is *your* revenue. The app decides the rate; the end-user does not. It can be a percentage or a fixed amount, and it is deducted from the input token of the transaction.
11
+
12
+ Both fees come out of the **input** side of a transaction, not the output, and they are denominated in the input token.
13
+
14
+ ## Partner fee — how to frame it (policy-sensitive)
15
+
16
+ The SDK source currently has conflicting documentation vs runtime validation. For product planning, treat fee percentage as a **policy-sensitive value**: prefer low, transparent fees; fetch live SDK/policy source before quoting an exact cap.
17
+
18
+ Concretely, when this comes up in the interview:
19
+
20
+ - Do **not** state an absolute maximum from memory. The type documentation and the runtime validation in the repo do not agree, so any single number quoted from memory risks being wrong.
21
+ - Frame it as a **product decision**: low, clearly-disclosed fees protect user trust and conversion. A high fee is technically expressible but is usually a bad product choice.
22
+ - For the brief, record the *intent* (e.g. "small percentage fee on swaps, disclosed to the user") and add a dev-time action: "confirm the current allowed fee range from live SDK source before shipping".
23
+ - **Make the mechanic concrete, but label it illustrative.** A non-technical user grasps the model faster with a worked figure — e.g. *"a 0.2% fee on $10,000 of swap volume ≈ $20"*. State plainly that this is an **illustration of the mechanic, not a revenue projection or promise**; the volume and the rate are the integrator's to decide.
24
+
25
+ ## What to capture in the brief (Stage 4)
26
+
27
+ - **Percentage vs fixed** — most products use a small percentage.
28
+ - **Which actions carry the fee** — e.g. swaps only, or swaps + bridges.
29
+ - **Fee recipient address** — default to *defer*; it is a deployment detail, not a Phase-1 blocker.
30
+ - **Disclosure** — note that the fee should be shown to the user (product/UX requirement, kept separate from the design itself).
31
+
32
+ ## Out of bounds
33
+
34
+ - **No yield/return promises.** Partner fees are revenue for the integrator, not a return for the end-user. Never present fees or any feature as guaranteed user earnings.
35
+ - **No investment advice.** This skill designs products. Risk and user-disclosure obligations are the integrator's responsibility — flag them, do not hand-wave them.
36
+
37
+ Taking a partner fee changes the handoff: it always adds the `sodax-sdk` partner feature, and in React also `sodax-dapp-kit`. See [`handoff.md`](./handoff.md).
@@ -0,0 +1,32 @@
1
+ # Use-case gallery
2
+
3
+ Worked product ideas → the SODAX features and chain shape they use. Use these to give a Tier A/B user concrete options and to seed the brief. Each entry is a **starting point**, not a fixed spec — adapt to the user's actual goal. All exact chains/tokens/fees must still be confirmed against live source.
4
+
5
+ | # | Product idea | Core feature(s) | Secondary | Typical shape |
6
+ |---|---|---|---|---|
7
+ | 1 | Cross-chain payments widget ("pay a friend on another chain") | Bridge (same coin) or Swap (different coin) | Partner fee | Web app + wallet |
8
+ | 2 | In-app "convert any token" button (same-chain *or* cross-chain) | Swap | Partner fee | Web app + wallet |
9
+ | 3 | Savings / "earn on your stablecoins" app | Money market (supply) | — | Web app + wallet |
10
+ | 4 | Borrow-against-holdings tool | Money market (borrow) | — | Web app + wallet |
11
+ | 5 | SODA staking dashboard | Staking | — | Web app + wallet |
12
+ | 6 | Liquidity-provider console | DEX | — | Web app + wallet |
13
+ | 7 | Telegram trading bot | Swap | Partner fee | Backend / bot |
14
+ | 8 | Treasury rebalancing script (server-side) | Swap + Bridge | — | Backend / script |
15
+ | 9 | ICON-ecosystem migration helper (ICX/BALN/bnUSD) | Token migration | — | Web app + wallet |
16
+ | 10 | Multi-chain "earn" aggregator front-end | Money market + Swap | Partner fee | Web app + wallet |
17
+ | 11 | Merchant checkout ("accept crypto, settle one chain") | Swap or Bridge | Partner fee | Web app or backend |
18
+ | 12 | Portfolio tool that also lets you act (swap/bridge in place) | Swap + Bridge | Partner fee | Web app + wallet |
19
+
20
+ ## How to use the gallery in the interview
21
+
22
+ - For a **Tier A** user who is unsure, offer 2–3 nearby ideas as recommended defaults ("a payments widget or a convert button — which is closer?").
23
+ - Map the chosen idea to its features via [`feature-catalog.md`](./feature-catalog.md), then disambiguate with [`interview-guide.md`](./interview-guide.md) Stage 2.
24
+ - The "typical shape" column previews the handoff — web+wallet vs backend vs migration drives [`handoff.md`](./handoff.md).
25
+ - If a product touches **any non-EVM chain**, flag the extra wallet-provider work in Stage 3 (each non-EVM chain needs its own provider).
26
+ - **Lead with cross-chain — it is SODAX's edge.** Swap is most compelling when the output lands on *another* chain; steer ideas toward that. A same-chain A → B conversion is also valid (entry #2), but cross-chain is where SODAX shines — lead with it. (Don't force a Bridge onto a same-chain idea either.)
27
+
28
+ ## Anti-patterns (honesty-gate these)
29
+
30
+ - "Launch my own token / ICO" → SODAX does not mint new tokens; only ICX/BALN/bnUSD **migration** exists.
31
+ - "Guaranteed X% yield" → never promise returns; yields are market-driven.
32
+ - "Use <chain SODAX does not support>" → honesty-gate against [`chains-and-assets.md`](./chains-and-assets.md).
@@ -1,6 +1,10 @@
1
1
  ---
2
2
  name: sodax-dapp-kit
3
- 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.'
3
+ description: 'Integrate SODAX into a React dapp with @sodax/dapp-kit — React Query hooks for swaps, lending/borrowing, staking, bridging, DEX, and token migration. INTEGRATION (write NEW code) — 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.'
4
+ license: MIT
5
+ metadata:
6
+ version: '0.0.1'
7
+ author: sodax
4
8
  ---
5
9
 
6
10
  # When to use this skill
@@ -32,7 +36,7 @@ Pick this mode when the consumer is a React dapp using `@sodax/dapp-kit` hooks.
32
36
  1. Read [`integration/knowledge/ai-rules.md`](./integration/knowledge/ai-rules.md) — DO / DO NOT / workflow / stop conditions.
33
37
  2. Read [`integration/knowledge/quickstart.md`](./integration/knowledge/quickstart.md) — install + wire providers + first feature.
34
38
  3. Read [`integration/knowledge/architecture.md`](./integration/knowledge/architecture.md) — hook shapes, queryKey conventions, `useSafeMutation`, `unwrapResult`, `Result<T>`.
35
- 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).
39
+ 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).
36
40
  5. Recipes → [`integration/knowledge/recipes/`](./integration/knowledge/recipes/) — `setup.md`, `wallet-connectivity.md`, per-feature, `mutation-error-handling.md`, `observability.md`, `invalidations.md`.
37
41
  6. Lookups → [`integration/knowledge/reference/`](./integration/knowledge/reference/) — `hooks-index.md`, `querykey-conventions.md`, `public-api.md`, `glossary.md`.
38
42
 
@@ -0,0 +1,65 @@
1
+ ---
2
+ name: sodax-dapp-kit-auxiliary-services
3
+ description: 'Granular skill for the @sodax/dapp-kit v2 auxiliary surfaces — partner fee claiming (useFeeClaimSwap, useApproveToken, useSetSwapPreference, useGetAutoSwapPreferences, useIsTokenApproved), recovery (useHubAssetBalances, useWithdrawHubAsset), read-only backend queries (useBackendIntentByTxHash, useBackendUserIntents, useBackendOrderbook, useBackendMoneyMarketPosition), the Swaps API v2 client hooks (useSwapsApiQuote, useSwapsApiSubmitTx, useSwapsApiStatus), and shared utilities (useSodaxContext, useHubProvider, useXBalances, useDeriveUserWalletAddress, useEstimateGas, useStellarTrustlineCheck, useRequestTrustline). Use when a React dapp task is partner fees, recovering stuck hub assets, backend data reads (intent tracking / orderbook / MM data, no wallet), or cross-cutting utilities (token balances, gas estimation, Stellar trustlines). Covers BOTH integration and migration. Links into the parent sodax-dapp-kit knowledge tree.'
4
+ license: MIT
5
+ metadata:
6
+ version: '0.0.1'
7
+ author: sodax
8
+ ---
9
+
10
+ # Auxiliary services (dapp-kit granular skill)
11
+
12
+ Granular skill for the smaller `@sodax/dapp-kit` v2 surfaces grouped together: **partner** (queryKey `partner`), **recovery** (`recovery`), **backend queries** (`backend`, read-only — no wallet), and **shared utilities** (`shared`). React-only — backend/Node uses `@sodax/sdk` directly.
13
+
14
+ ## Step 1 — Clarify with user before coding
15
+
16
+ 1. **New code or v1 → v2 port?**
17
+ 2. **Which surface?**
18
+ - **Partner fees:** `useIsTokenApproved` → `useApproveToken` → `useSetSwapPreference` → `useFeeClaimSwap` (returns `IntentAutoSwapResult`, NOT `SwapResponse`); `useGetAutoSwapPreferences`, `useFetchAssetsBalances` for reads.
19
+ - **Recovery:** `useHubAssetBalances` (list stuck hub assets) → `useWithdrawHubAsset` (withdraw one back to a spoke). Follows a *known* failed cross-chain op — investigate the failure first.
20
+ - **Backend reads (no wallet):** intent tracking (`useBackendIntentByTxHash` polls 1s, `useBackendIntentByHash`, `useBackendUserIntents`), orderbook (`useBackendOrderbook` — `pagination` nests under `params`), MM data (`useBackendMoneyMarketPosition` etc.), and the Swaps API v2 client (`useSwapsApi*` — e.g. `useSwapsApiSubmitTx`, `useSwapsApiSubmitTxStatus`, `useSwapsApiQuote`).
21
+ - **Shared utilities:** `useSodaxContext`, `useHubProvider`, `useXBalances` (needs `xService` from wallet-sdk-react), `useDeriveUserWalletAddress` / `useGetUserHubWalletAddress`, `useEstimateGas`, `useStellarTrustlineCheck` / `useRequestTrustline`.
22
+
23
+ ## Integration workflow (new v2 code)
24
+
25
+ 1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT (read first).
26
+ 2. [`../integration/knowledge/architecture.md`](../integration/knowledge/architecture.md) — hook shapes, `mutateAsyncSafe`, `unwrapResult`, queryKey conventions.
27
+ 3. [`../integration/knowledge/features/auxiliary-services.md`](../integration/knowledge/features/auxiliary-services.md) — full hook surface for all four surfaces, `useXBalances` shape, trustline pattern, default polling intervals.
28
+ 4. Worked examples:
29
+ - Backend reads → [`../integration/knowledge/recipes/backend-queries.md`](../integration/knowledge/recipes/backend-queries.md).
30
+ - `useXBalances` → [`../integration/knowledge/recipes/wallet-connectivity.md`](../integration/knowledge/recipes/wallet-connectivity.md).
31
+ 5. Call-shape choice → [`../integration/knowledge/recipes/mutation-error-handling.md`](../integration/knowledge/recipes/mutation-error-handling.md).
32
+
33
+ ### Auxiliary-specific anti-patterns (dapp-kit)
34
+
35
+ - **Treating `useFeeClaimSwap` `data` as a `SwapResponse`.** It's `IntentAutoSwapResult`.
36
+ - **Passing top-level `pagination` to `useBackendOrderbook` / `useBackendAllMoneyMarketBorrowers`.** It nests under `params`; without it those queries are disabled.
37
+ - **Calling `useXBalances` without `xService`.** Supply `xService` from `@sodax/wallet-sdk-react`'s `useXService`; the request-side key is `xChainId` (the cross-chain abstraction), distinct from the token-side `chainKey`.
38
+ - **Treating `useRequestTrustline` as a canonical mutation hook.** It takes a single positional `token` arg and returns `{ requestTrustline, isLoading, ... }`; the callback takes `{ token, amount, srcChainKey, walletProvider }` (NOT `account`/`asset`).
39
+ - **Running recovery on successful flows.** Recovery is a workaround for *failed* ops — `useHubAssetBalances` first, then withdraw the specific entry; investigate the original failure.
40
+ - **Leaving `useBackendIntentByTxHash` polling (1s) running after the intent resolves.**
41
+
42
+ ## Migration workflow (port v1 auxiliary hooks to v2)
43
+
44
+ 1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md) — DO / DO NOT (read first).
45
+ 2. Cross-cutting deltas: [`../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md`](../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md), [`../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md`](../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md), [`../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md`](../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md).
46
+ 3. [`../migration-v1-to-v2/knowledge/features/auxiliary-services.md`](../migration-v1-to-v2/knowledge/features/auxiliary-services.md) — small per-hook changes across partner / recovery / backend / shared.
47
+
48
+ ## Verification
49
+
50
+ 1. `pnpm tsc --noEmit` clean.
51
+ 2. `useBackendOrderbook` / paginated MM reads nest `pagination` under `params`.
52
+ 3. `useXBalances` is supplied an `xService`.
53
+ 4. Mutation flows (partner / recovery / submit) use `mutateAsyncSafe` and branch on `result.ok`.
54
+ 5. No `useSpokeProvider`, no hook-level `spokeProvider` (migration only).
55
+
56
+ ## Related granular skills (same family)
57
+
58
+ - [`../swap/SKILL.md`](../swap/SKILL.md) — `useSwapsApiSubmitTx` + intent tracking are the backend half of the step-by-step swap flow; partner fee-claim reuses the swap intent layer.
59
+ - [`../money-market/SKILL.md`](../money-market/SKILL.md) — backend MM reads complement the on-chain MM action hooks.
60
+
61
+ For multi-feature tasks, load the broad [`sodax-dapp-kit` skill](../SKILL.md).
62
+
63
+ ## Wallet connectivity (different SDK package family)
64
+
65
+ Partner/recovery mutations take a `walletProvider`; `useXBalances` needs an `xService`. **Also load the `sodax-wallet-sdk-react` skill (integration mode)** for `useWalletProvider` and `useXService`. (Backend read hooks need no wallet.)
@@ -0,0 +1,57 @@
1
+ ---
2
+ name: sodax-dapp-kit-bitcoin
3
+ description: 'Granular skill for the @sodax/dapp-kit v2 Bitcoin/Radfi feature only — React Query hooks for Bitcoin trading via the Radfi protocol: useRadfiAuth, useRadfiSession, useEnsureRadfiAccessToken, useTradingWallet, useFundTradingWallet, useRadfiWithdraw, useExpiredUtxos, useRenewUtxos, useBitcoinBalance, useTradingWalletBalance. This is a dapp-kit-UNIQUE surface (no @sodax/sdk equivalent — the flows are React-shaped). Use when a React dapp task is Bitcoin/Radfi (e.g. "Radfi session hook", "fund trading wallet hook", "Radfi withdraw in React", "manage Bitcoin UTXOs hook", "BIP322 auth with dapp-kit"). Covers BOTH integration (new v2 hooks) and migration (port v1 Radfi hooks — mostly signature tightening, flow unchanged). Links into the parent sodax-dapp-kit knowledge tree.'
4
+ license: MIT
5
+ metadata:
6
+ version: '0.0.1'
7
+ author: sodax
8
+ ---
9
+
10
+ # Bitcoin / Radfi (dapp-kit granular skill)
11
+
12
+ Granular skill for the Bitcoin trading hooks of `@sodax/dapp-kit` v2 — authenticate (BIP322), fund a trading wallet, withdraw, manage UTXOs via the Radfi protocol. queryKey/mutationKey first segment: `bitcoin`. **Dapp-kit-unique** — no `@sodax/sdk` equivalent.
13
+
14
+ ## Step 1 — Clarify with user before coding
15
+
16
+ 1. **New code or v1 → v2 port?**
17
+ 2. **Which stage?** Session/auth (`useRadfiAuth`, `useRadfiSession`, `useEnsureRadfiAccessToken`, `useTradingWallet`), balances (`useBitcoinBalance`, `useTradingWalletBalance`), operations (`useFundTradingWallet`, `useRadfiWithdraw`), UTXO maintenance (`useExpiredUtxos`, `useRenewUtxos`).
18
+ 3. **Session lifecycle handled?** `useRadfiSession(walletProvider)` manages login/refresh/auto-refresh + localStorage persistence; gate trading buttons on `isAuthed`.
19
+
20
+ ## Integration workflow (new v2 code)
21
+
22
+ 1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT (read first).
23
+ 2. [`../integration/knowledge/architecture.md`](../integration/knowledge/architecture.md) — hook shapes, `mutateAsyncSafe`, `unwrapResult`, queryKey conventions.
24
+ 3. [`../integration/knowledge/features/bitcoin.md`](../integration/knowledge/features/bitcoin.md) — full hook surface, session flow, mutation TVars, return shapes, polling notes.
25
+ 4. [`../integration/knowledge/recipes/bitcoin.md`](../integration/knowledge/recipes/bitcoin.md) — full worked examples (session, fund, withdraw, UTXO management).
26
+ 5. Call-shape choice → [`../integration/knowledge/recipes/mutation-error-handling.md`](../integration/knowledge/recipes/mutation-error-handling.md).
27
+
28
+ ### Bitcoin/Radfi-specific anti-patterns (dapp-kit)
29
+
30
+ - **Calling trading operations before auth.** Gate on `useRadfiSession(...).isAuthed`; the trading wallet is created during first authentication, not as a separate step.
31
+ - **Expecting `useTradingWallet` to fetch.** It's synchronous — reads the persisted session from localStorage (keyed by wallet address). Use it when you don't yet have a `walletProvider`.
32
+ - **Hand-rolling PSBT signing for withdrawals.** `useRadfiWithdraw` orchestrates the unsigned-PSBT → local-sign → co-sign → broadcast flow; consumers don't touch PSBTs directly.
33
+ - **Treating `useRadfiAuth` `data` as a full `RadfiSession`.** It's `RadfiAuthResult = { accessToken, refreshToken, tradingAddress }` (no `publicKey` in the return; it's persisted internally).
34
+ - **Leaving `useExpiredUtxos` polling (60s) on hidden UI.** Set `queryOptions.refetchInterval: false` when not visible.
35
+
36
+ ## Migration workflow (port v1 Radfi hooks to v2)
37
+
38
+ 1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md) — DO / DO NOT (read first).
39
+ 2. Cross-cutting deltas: [`../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md`](../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md), [`../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md`](../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md).
40
+ 3. [`../migration-v1-to-v2/knowledge/features/bitcoin.md`](../migration-v1-to-v2/knowledge/features/bitcoin.md) — Radfi flow is mostly unchanged; provider/session lifecycle hook signatures tightened.
41
+
42
+ ## Verification
43
+
44
+ 1. `pnpm tsc --noEmit` clean.
45
+ 2. Trading buttons gate on `isAuthed`.
46
+ 3. Mutation flows use `mutateAsyncSafe` and branch on `result.ok`.
47
+ 4. No hand-rolled PSBT signing; `useRadfiWithdraw` owns the flow.
48
+
49
+ ## Related granular skills (same family)
50
+
51
+ - [`../auxiliary-services/SKILL.md`](../auxiliary-services/SKILL.md) — `useXBalances` and other shared utilities used alongside Bitcoin UI.
52
+
53
+ For multi-feature tasks, load the broad [`sodax-dapp-kit` skill](../SKILL.md).
54
+
55
+ ## Wallet connectivity (different SDK package family)
56
+
57
+ These hooks take an `IBitcoinWalletProvider`. **Also load the `sodax-wallet-sdk-react` skill (integration mode)** to wire a Bitcoin wallet and obtain the provider via `useWalletProvider({ xChainId: ChainKeys.BITCOIN_MAINNET })`.
@@ -0,0 +1,59 @@
1
+ ---
2
+ name: sodax-dapp-kit-bridge
3
+ description: 'Granular skill for the @sodax/dapp-kit v2 bridge feature only — React Query hooks for cross-chain token transfer via the hub-and-spoke vault: useBridge, useBridgeApprove, useBridgeAllowance, useGetBridgeableAmount, useGetBridgeableTokens. Use when a React dapp task is specifically bridging (e.g. "useBridge with dapp-kit", "bridge tokens cross-chain in React", "check bridgeable amount hook", "list bridgeable destinations"). useBridge resolves to TxHashPair = { srcChainTxHash, dstChainTxHash }. Covers BOTH integration (new v2 hooks) and migration (port v1 bridge hooks — field renames srcChainId→srcChainKey / srcAsset→srcToken / dstAsset→dstToken, new required srcAddress, recipient unchanged, mutateAsyncSafe). Links into the parent sodax-dapp-kit knowledge tree. For backend/Node, use the sodax-sdk skill.'
4
+ license: MIT
5
+ metadata:
6
+ version: '0.0.1'
7
+ author: sodax
8
+ ---
9
+
10
+ # Bridge (dapp-kit granular skill)
11
+
12
+ Granular skill for the bridge hooks of `@sodax/dapp-kit` v2. queryKey/mutationKey first segment: `bridge`. React-only — backend uses `@sodax/sdk` directly.
13
+
14
+ ## Step 1 — Clarify with user before coding
15
+
16
+ 1. **New code or v1 → v2 port?**
17
+ 2. **Need a bridgeable precheck?** `useGetBridgeableAmount` (vault deposit/withdrawal cap, returns a `BridgeLimit`) and `useGetBridgeableTokens` (enumerate compatible destinations).
18
+ 3. **Allowance gating?** `useBridgeAllowance` + `useBridgeApprove` before `useBridge`.
19
+ 4. **Source/destination chains + recipient format** — confirm both are supported spokes and the `recipient` matches the destination chain encoding.
20
+
21
+ ## Integration workflow (new v2 code)
22
+
23
+ 1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT (read first).
24
+ 2. [`../integration/knowledge/architecture.md`](../integration/knowledge/architecture.md) — hook shapes, `mutateAsyncSafe`, `unwrapResult`, queryKey conventions.
25
+ 3. [`../integration/knowledge/features/bridge.md`](../integration/knowledge/features/bridge.md) — full hook surface, `CreateBridgeIntentParams` shape, `useBridgeAllowance` nesting, `BridgeLimit` return.
26
+ 4. [`../integration/knowledge/recipes/bridge.md`](../integration/knowledge/recipes/bridge.md) — full worked example.
27
+ 5. Call-shape choice → [`../integration/knowledge/recipes/mutation-error-handling.md`](../integration/knowledge/recipes/mutation-error-handling.md).
28
+
29
+ ### Bridge-specific anti-patterns (dapp-kit)
30
+
31
+ - **Destructuring `useBridge` `data` as an array or single hash.** It resolves to `TxHashPair = { srcChainTxHash, dstChainTxHash }` — destructure by name.
32
+ - **Treating `useGetBridgeableAmount` `data` as a bare bigint.** It's a `BridgeLimit = { amount, decimals, type }` — read `data.amount` / `data.decimals`.
33
+ - **Passing addresses + chain ids to `useGetBridgeableAmount`.** It takes two `XToken` objects (each carries its own `chainKey`); v1's 4-arg shape is gone.
34
+ - **Passing the bridge params directly under `params` on `useBridgeAllowance`.** They nest under `params.payload` alongside `walletProvider`.
35
+ - **Submitting an incompatible token pair.** Tokens bridge only if they share the same hub vault — gate with `useGetBridgeableTokens` (incompatible pairs reject with `VALIDATION_FAILED`).
36
+
37
+ ## Migration workflow (port v1 bridge hooks to v2)
38
+
39
+ 1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md) — DO / DO NOT (read first).
40
+ 2. Cross-cutting deltas: [`../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md`](../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md), [`../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md`](../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md), [`../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md`](../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md).
41
+ 3. [`../migration-v1-to-v2/knowledge/features/bridge.md`](../migration-v1-to-v2/knowledge/features/bridge.md) — `useBridge` param renames (`srcChainId` → `srcChainKey`, `dstChainId` → `dstChainKey`, `srcAsset` → `srcToken`, `dstAsset` → `dstToken`; new required `srcAddress`; `recipient` is UNCHANGED — NOT renamed to `dstAddress`); `useGetBridgeableAmount` shape change (bigint → `BridgeLimit`).
42
+
43
+ ## Verification
44
+
45
+ 1. `pnpm tsc --noEmit` clean.
46
+ 2. `useBridge` consumers destructure `{ srcChainTxHash, dstChainTxHash }` (no array/string).
47
+ 3. `useGetBridgeableAmount` consumers read `data.amount` (not a scalar).
48
+ 4. No `useSpokeProvider`, no `srcChainId`/`srcAsset`/`dstAsset` v1 field names (migration only); `recipient` stays `recipient` (do NOT rename to `dstAddress`).
49
+
50
+ ## Related granular skills (same family)
51
+
52
+ - [`../swap/SKILL.md`](../swap/SKILL.md) — intent-based cross-chain swaps (solver-routed; different from a direct vault bridge).
53
+ - [`../auxiliary-services/SKILL.md`](../auxiliary-services/SKILL.md) — recovery (`useWithdrawHubAsset`) for assets stranded on the hub after a failed bridge.
54
+
55
+ For multi-feature tasks, load the broad [`sodax-dapp-kit` skill](../SKILL.md).
56
+
57
+ ## Wallet connectivity (different SDK package family)
58
+
59
+ `walletProvider` flows through `mutate(vars)`. **Also load the `sodax-wallet-sdk-react` skill (integration mode)** to wire wallets and get a typed `walletProvider` via `useWalletProvider({ xChainId: chainKey })`.
@@ -0,0 +1,60 @@
1
+ ---
2
+ name: sodax-dapp-kit-dex
3
+ description: 'Granular skill for the @sodax/dapp-kit v2 DEX feature only — React Query hooks for concentrated-liquidity LP plus asset deposit/withdraw: useDexDeposit, useDexWithdraw, useSupplyLiquidity, useDecreaseLiquidity, useClaimRewards, useDexApprove/useDexAllowance, the useCreate*Params builders, and reads (usePools, usePoolData, usePositionInfo, useLiquidityAmounts). Use when a React dapp task is concentrated-liquidity LP (e.g. "create LP position with dapp-kit", "useSupplyLiquidity hook", "increase/decrease liquidity in React", "claim LP fees hook", "deposit hub assets for LP"). Two-step flow: deposit assets → supply liquidity. Covers BOTH integration (new v2 hooks) and migration (port v1 dex hooks — field renames + srcChainKey, mint/increase routing). Links into the parent sodax-dapp-kit knowledge tree. For backend/Node, use the sodax-sdk skill.'
4
+ license: MIT
5
+ metadata:
6
+ version: '0.0.1'
7
+ author: sodax
8
+ ---
9
+
10
+ # DEX (dapp-kit granular skill)
11
+
12
+ Granular skill for the concentrated-liquidity DEX hooks of `@sodax/dapp-kit` v2. queryKey/mutationKey first segment: `dex`. Two-step flow: `useDexDeposit` (spoke asset → hub ERC-4626 pool shares) then `useSupplyLiquidity` (shares → position). React-only — backend uses `@sodax/sdk` directly.
13
+
14
+ ## Step 1 — Clarify with user before coding
15
+
16
+ 1. **New code or v1 → v2 port?**
17
+ 2. **Which operation?** Asset deposit/withdraw (`useDexDeposit`/`useDexWithdraw`), supply liquidity (`useSupplyLiquidity` — mint-new OR increase-existing), decrease (`useDecreaseLiquidity`), claim fees (`useClaimRewards`).
18
+ 3. **Does opening a position require a deposit first?** Yes — positions hold hub pool shares; deposit from a spoke before supplying liquidity. UI flows usually combine the two steps.
19
+ 4. **Using the param builders?** `useCreate*Params` compute derived params (tick range, ERC-4626 conversions) client-side; spread their result into `mutate({ params: { ...result, srcChainKey, srcAddress }, walletProvider })`.
20
+
21
+ ## Integration workflow (new v2 code)
22
+
23
+ 1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT (read first).
24
+ 2. [`../integration/knowledge/architecture.md`](../integration/knowledge/architecture.md) — hook shapes, `mutateAsyncSafe`, `unwrapResult`, queryKey conventions.
25
+ 3. [`../integration/knowledge/features/dex.md`](../integration/knowledge/features/dex.md) — full hook surface, SDK param types, the FLAT-props param builders, position-lifecycle notes.
26
+ 4. [`../integration/knowledge/recipes/dex.md`](../integration/knowledge/recipes/dex.md) — full worked examples.
27
+ 5. Call-shape choice → [`../integration/knowledge/recipes/mutation-error-handling.md`](../integration/knowledge/recipes/mutation-error-handling.md).
28
+
29
+ ### DEX-specific anti-patterns (dapp-kit)
30
+
31
+ - **Skipping `useDexDeposit` before `useSupplyLiquidity`.** Positions reference hub pool shares; without a deposit there's nothing to provide.
32
+ - **Wrapping param builders in `{ params }`.** `useCreate*Params` take a FLAT props object (not `{ params }`-wrapped) and return memoized derived params; you add `srcChainKey` + `srcAddress` at the mutation call site.
33
+ - **Treating ticks as prices.** `tickLower`/`tickUpper` are logarithmic indices — convert with Q96 math / SDK helpers.
34
+ - **Calling a separate hook for increase-existing.** `useSupplyLiquidity` fans out to mint-new vs increase based on `params.tokenId` + `isValidPosition`; `useCreateSupplyLiquidityParams` handles the routing.
35
+ - **`usePositionInfo` `tokenId` is `string | null`, not bigint.**
36
+ - **Expecting `usePools` to auto-refresh.** It's `staleTime: Infinity` (static config).
37
+
38
+ ## Migration workflow (port v1 dex hooks to v2)
39
+
40
+ 1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md) — DO / DO NOT (read first).
41
+ 2. Cross-cutting deltas: [`../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md`](../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md), [`../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md`](../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md), [`../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md`](../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md).
42
+ 3. [`../migration-v1-to-v2/knowledge/features/dex.md`](../migration-v1-to-v2/knowledge/features/dex.md) — two-step flow unchanged; field renames + `srcChainKey` requirement; `useSupplyLiquidity` mint/increase routing.
43
+
44
+ ## Verification
45
+
46
+ 1. `pnpm tsc --noEmit` clean.
47
+ 2. Deposit precedes supply in combined flows.
48
+ 3. Param-builder output is spread with `srcChainKey`/`srcAddress` added at the call site.
49
+ 4. Mutation flows use `mutateAsyncSafe` and branch on `result.ok`.
50
+ 5. No `useSpokeProvider`, no hook-level `spokeProvider` (migration only).
51
+
52
+ ## Related granular skills (same family)
53
+
54
+ - [`../auxiliary-services/SKILL.md`](../auxiliary-services/SKILL.md) — recovery (`useWithdrawHubAsset`) for stuck hub LP assets; `useXBalances` / gas utilities.
55
+
56
+ For multi-feature tasks, load the broad [`sodax-dapp-kit` skill](../SKILL.md).
57
+
58
+ ## Wallet connectivity (different SDK package family)
59
+
60
+ `walletProvider` flows through `mutate(vars)`. **Also load the `sodax-wallet-sdk-react` skill (integration mode)** to wire wallets and get a typed `walletProvider` via `useWalletProvider({ xChainId: chainKey })`.
@@ -15,7 +15,7 @@ This tree documents v2 of the dapp-kit React hooks for **new consumers** buildin
15
15
  | [`features/bridge.md`](features/bridge.md) | Bridge hooks: `useBridge`, allowance/approve, bridgeable amount/tokens. |
16
16
  | [`features/dex.md`](features/dex.md) | DEX hooks: deposit/withdraw, supply/decrease liquidity, claim rewards, position info, pools. |
17
17
  | [`features/migration.md`](features/migration.md) | Migration hooks: ICX/bnUSD/BALN forward + reverse, allowance/approve. |
18
- | [`features/bitcoin.md`](features/bitcoin.md) | Radfi hooks (dapp-kit-unique): session, trading wallet, fund/withdraw, UTXOs. |
18
+ | [`features/bitcoin.md`](features/bitcoin.md) | Bound Exchange hooks (dapp-kit-unique): session, trading wallet, fund/withdraw, UTXOs. |
19
19
  | [`features/auxiliary-services.md`](features/auxiliary-services.md) | Partner, recovery, backend queries, shared (xBalances, gas estimation, trustlines). |
20
20
  | [`recipes/`](recipes/) | Copy-paste patterns: setup, wallet connectivity, per-feature flows, mutation error handling, observability, invalidations. |
21
21
  | [`reference/`](reference/) | Lookup tables: full hook index, queryKey conventions, public API surface, glossary. |
@@ -9,8 +9,9 @@ Per-feature reference docs. Each file documents the hooks, params types, return
9
9
  | [`staking.md`](staking.md) | SODA → xSODA staking: `useStake`, `useUnstake`, `useInstantUnstake`, `useClaim`, `useCancelUnstake`, allowance/approve, info/ratio reads. |
10
10
  | [`bridge.md`](bridge.md) | Cross-chain token bridging: `useBridge`, allowance/approve, bridgeable amount/tokens. |
11
11
  | [`dex.md`](dex.md) | Concentrated liquidity DEX: assets in/out, liquidity supply/decrease, claim rewards, position info, pool reads, param builders. |
12
+ | [`leverage-yield.md`](leverage-yield.md) | Leveraged-yield ERC-4626 vaults: `useLeverageYieldDeposit`/`Withdraw` (build) + `useLeverageYieldVaultSwap` (execute), effective APR / position / TVL / share-balance reads. |
12
13
  | [`migration.md`](migration.md) | Token migration: `useMigrateIcxToSoda`, `useRevertMigrateSodaToIcx`, `useMigratebnUSD`, `useMigrateBaln`, allowance/approve. |
13
- | [`bitcoin.md`](bitcoin.md) | Radfi (dapp-kit-unique): session, trading wallet, fund/withdraw, UTXOs. |
14
+ | [`bitcoin.md`](bitcoin.md) | Bound Exchange (dapp-kit-unique): session, trading wallet, fund/withdraw, UTXOs. |
14
15
  | [`auxiliary-services.md`](auxiliary-services.md) | Partner fee claiming, recovery, backend queries (intent tracking, orderbook, MM data), shared utilities (xBalances, gas, trustlines). |
15
16
 
16
17
  ## Reference vs recipes
@@ -20,7 +21,7 @@ Per-feature reference docs. Each file documents the hooks, params types, return
20
21
 
21
22
  ## Pair-completeness
22
23
 
23
- Every file in this directory has a sibling in [`features/`](../../../migration-v1-to-v2/knowledge/features/) with the same filename — the v1→v2 porting playbook for that feature. When you're deep in one, the other is one path-swap away.
24
+ Every file in this directory has a sibling in [`features/`](../../../migration-v1-to-v2/knowledge/features/) with the same filename — the v1→v2 porting playbook for that feature. When you're deep in one, the other is one path-swap away. **Exception:** features introduced in v2 with no v1 equivalent (`leverage-yield.md`) have no migration sibling — there is nothing to port.
24
25
 
25
26
  ## Cross-references
26
27