@sodax/skills 2.3.0-rc.2 → 2.3.0-rc.3

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 (41) hide show
  1. package/AGENTS.md +6 -4
  2. package/README.md +3 -2
  3. package/package.json +1 -1
  4. package/skills/sodax-build/SKILL.md +1 -0
  5. package/skills/sodax-build/knowledge/chains-and-assets.md +1 -1
  6. package/skills/sodax-dapp-kit/auxiliary-services/SKILL.md +1 -1
  7. package/skills/sodax-dapp-kit/bridge/SKILL.md +1 -0
  8. package/skills/sodax-dapp-kit/integration/knowledge/ai-rules.md +3 -0
  9. package/skills/sodax-dapp-kit/integration/knowledge/architecture.md +7 -3
  10. package/skills/sodax-dapp-kit/integration/knowledge/features/auxiliary-services.md +8 -3
  11. package/skills/sodax-dapp-kit/integration/knowledge/quickstart.md +2 -2
  12. package/skills/sodax-dapp-kit/integration/knowledge/recipes/setup.md +1 -1
  13. package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md +1 -1
  14. package/skills/sodax-dapp-kit/leverage-yield/SKILL.md +1 -0
  15. package/skills/sodax-dapp-kit/swap/SKILL.md +1 -0
  16. package/skills/sodax-sdk/SKILL.md +2 -1
  17. package/skills/sodax-sdk/bridge/SKILL.md +1 -1
  18. package/skills/sodax-sdk/bridge-api/SKILL.md +13 -8
  19. package/skills/sodax-sdk/integration/knowledge/ai-rules.md +5 -3
  20. package/skills/sodax-sdk/integration/knowledge/architecture.md +8 -8
  21. package/skills/sodax-sdk/integration/knowledge/features/backend-api.md +1 -1
  22. package/skills/sodax-sdk/integration/knowledge/features/bridge-api.md +43 -7
  23. package/skills/sodax-sdk/integration/knowledge/features/leverage-yield-api.md +38 -3
  24. package/skills/sodax-sdk/integration/knowledge/features/money-market.md +2 -0
  25. package/skills/sodax-sdk/integration/knowledge/features/swap.md +6 -2
  26. package/skills/sodax-sdk/integration/knowledge/features/swaps-api.md +36 -4
  27. package/skills/sodax-sdk/integration/knowledge/quickstart.md +4 -4
  28. package/skills/sodax-sdk/integration/knowledge/recipes/initialize-sodax.md +13 -6
  29. package/skills/sodax-sdk/integration/knowledge/recipes/logging.md +2 -4
  30. package/skills/sodax-sdk/integration/knowledge/recipes/testing.md +2 -2
  31. package/skills/sodax-sdk/leverage-yield/SKILL.md +1 -1
  32. package/skills/sodax-sdk/leverage-yield-api/SKILL.md +12 -10
  33. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/README.md +1 -1
  34. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/architecture.md +3 -3
  35. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/checklist.md +2 -2
  36. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/money-market.md +1 -1
  37. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/recipes.md +1 -1
  38. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/reference/sodax-config.md +1 -1
  39. package/skills/sodax-sdk/swap/SKILL.md +1 -1
  40. package/skills/sodax-sdk/swaps-api/SKILL.md +11 -9
  41. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/interfaces.md +3 -0
package/AGENTS.md CHANGED
@@ -10,7 +10,7 @@ This package ships **mode-gated broad SDK skills** (`skills/<name>/SKILL.md`, on
10
10
 
11
11
  | SDK package | Broad skill | Granular per-feature skills |
12
12
  |---|---|---|
13
- | `@sodax/sdk` | `sodax-sdk` | `sodax-sdk/swap`, `sodax-sdk/money-market`, `sodax-sdk/bridge`, `sodax-sdk/staking`, `sodax-sdk/dex`, `sodax-sdk/leverage-yield`, `sodax-sdk/migration`, `sodax-sdk/partner`, `sodax-sdk/recovery`, `sodax-sdk/sponsoring`, `sodax-sdk/backend-api`, `sodax-sdk/swaps-api`, `sodax-sdk/leverage-yield-api` |
13
+ | `@sodax/sdk` | `sodax-sdk` | `sodax-sdk/swap`, `sodax-sdk/money-market`, `sodax-sdk/bridge`, `sodax-sdk/staking`, `sodax-sdk/dex`, `sodax-sdk/leverage-yield`, `sodax-sdk/migration`, `sodax-sdk/partner`, `sodax-sdk/recovery`, `sodax-sdk/sponsoring`, `sodax-sdk/backend-api`, `sodax-sdk/swaps-api`, `sodax-sdk/bridge-api`, `sodax-sdk/leverage-yield-api` |
14
14
  | `@sodax/wallet-sdk-core` | `sodax-wallet-sdk-core` | `sodax-wallet-sdk-core/evm`, `sodax-wallet-sdk-core/solana`, `sodax-wallet-sdk-core/sui`, `sodax-wallet-sdk-core/bitcoin`, `sodax-wallet-sdk-core/stellar`, `sodax-wallet-sdk-core/icon`, `sodax-wallet-sdk-core/injective`, `sodax-wallet-sdk-core/near`, `sodax-wallet-sdk-core/stacks` |
15
15
  | `@sodax/wallet-sdk-react` | `sodax-wallet-sdk-react` | `sodax-wallet-sdk-react/connect`, `sodax-wallet-sdk-react/wallet-modal`, `sodax-wallet-sdk-react/bridge-to-sdk`, `sodax-wallet-sdk-react/switch-chain`, `sodax-wallet-sdk-react/sign-message`, `sodax-wallet-sdk-react/walletconnect`, `sodax-wallet-sdk-react/privy` |
16
16
  | `@sodax/dapp-kit` | `sodax-dapp-kit` | `sodax-dapp-kit/swap`, `sodax-dapp-kit/money-market`, `sodax-dapp-kit/staking`, `sodax-dapp-kit/bridge`, `sodax-dapp-kit/dex`, `sodax-dapp-kit/leverage-yield`, `sodax-dapp-kit/migration`, `sodax-dapp-kit/bitcoin`, `sodax-dapp-kit/auxiliary-services` |
@@ -26,7 +26,8 @@ Pick the consumer's situation, load the listed skills in order. Each entry names
26
26
  | Consumer is… | Load skills (mode) |
27
27
  |---|---|
28
28
  | **Not sure what to build / not a developer** (no SDK, feature, or concrete product chosen yet) | `sodax-build` (front-door ideation: interview → product brief → handoff; it names the dev skills to load next). Skip the moment any SDK / feature / hook is named |
29
- | **Scaffolding ONE specific Core SDK feature** (swap, money-market, bridge, staking, dex, leverage-yield, migration, partner, recovery, sponsoring, backend-api, swaps-api, leverage-yield-api) | `sodax-sdk/<feature>` (granular, covers both modes via internal links). Add `sodax-wallet-sdk-core` (integration) if it signs and lives outside React. Skip the broad `sodax-sdk` skill |
29
+ | **Asking the agent to make a swap or read live SODAX data now**, with no code to write | No skill. Use the [Builders MCP](https://docs.sodax.com/builders-mcp); its swap tools are not production ready yet. Load a skill once the task becomes writing code |
30
+ | **Scaffolding ONE specific Core SDK feature** (swap, money-market, bridge, staking, dex, leverage-yield, migration, partner, recovery, sponsoring, backend-api, swaps-api, bridge-api, leverage-yield-api) | `sodax-sdk/<feature>` (granular, covers both modes via internal links). Add `sodax-wallet-sdk-core` (integration) if it signs and lives outside React. Skip the broad `sodax-sdk` skill |
30
31
  | **Scaffolding ONE specific dapp-kit feature in React** (swap, money-market, staking, bridge, dex, leverage-yield, migration, bitcoin, auxiliary-services) | `sodax-wallet-sdk-react` (integration) → `sodax-dapp-kit/<feature>` (granular, covers both modes via internal links). Skip the broad `sodax-dapp-kit` skill. If the wallet concern is also settled (just a connect button, modal, bridge, etc.), narrow to `sodax-wallet-sdk-react/<concern>` too |
31
32
  | **Scaffolding ONE chain's wallet provider** (backend/Node/non-React: evm, solana, sui, bitcoin, stellar, icon, injective, near, stacks) | `sodax-wallet-sdk-core/<chain>` (granular, covers both modes) → `sodax-sdk/<feature>` for the operation it signs. Skip the broad `sodax-wallet-sdk-core` skill |
32
33
  | **Scaffolding ONE React wallet concern** (connect, wallet-modal, bridge-to-sdk, switch-chain, sign-message, walletconnect, privy) | `sodax-wallet-sdk-react/<concern>` (granular, covers both modes). Skip the broad `sodax-wallet-sdk-react` skill |
@@ -64,7 +65,7 @@ packages/skills/
64
65
  ├── sodax-sdk/ {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/,
65
66
  │ <feature>/SKILL.md children — swap, money-market, bridge, staking, dex,
66
67
  │ leverage-yield, migration, partner, recovery, sponsoring, backend-api,
67
- │ swaps-api, leverage-yield-api}
68
+ │ swaps-api, bridge-api, leverage-yield-api}
68
69
  ├── sodax-wallet-sdk-core/ {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/,
69
70
  │ <chain>/SKILL.md children — evm, solana, sui, bitcoin, stellar, icon,
70
71
  │ injective, near, stacks}
@@ -148,6 +149,7 @@ To add another meta skill later: drop `skills/<name>/SKILL.md` + a flat `knowled
148
149
  - **Skills link into knowledge by relative path.** From a SKILL.md, target paths look like `./integration/knowledge/ai-rules.md` or `./migration-v1-to-v2/knowledge/README.md`. Cross-mode links (between the two subtrees of the same skill) use a `<other-mode>/knowledge/<target>` segment, prefixed by `../` repeated enough times to climb out of the source subtree: depth-0 knowledge files (e.g. `<mode>/knowledge/README.md`, `quickstart.md`) use a `../../` prefix; depth-1 files (e.g. `<mode>/knowledge/features/*.md`, `<mode>/knowledge/recipes/*.md`) use `../../../`. The `check-skills.sh` validator verifies all resolve.
149
150
  - **Cross-SDK-package references are forbidden.** A skill MUST NOT link to (or cite a relative/absolute path into) a skill belonging to a different SDK package **family** (`sdk`, `wallet-sdk-core`, `wallet-sdk-react`, `dapp-kit`). Concretely: `sodax-dapp-kit` knowledge MUST NOT reference `sodax-sdk`, `sodax-wallet-sdk-react`, or `sodax-wallet-sdk-core` content via `../../<other-skill>/...`, GitHub URLs, or any other clickable form. Use prose pointers naming the sibling skill instead (e.g., *"load the `sodax-sdk` skill (integration mode)"*). **Intra-family links are allowed**: integration ↔ migration-v1-to-v2 subtrees within the SAME broad skill, broad ↔ granular within the same family (e.g. `sodax-sdk` ↔ `sodax-sdk/swap`), and granular ↔ granular under the same broad parent. These all ship together and document the same SDK package.
150
151
  - **Knowledge files** retain the structure they had under each package's `ai-exported/<mode>/` tree: `README.md`, `ai-rules.md`, `features/`, `recipes/`, `reference/`, plus `architecture.md`, `quickstart.md`, `chain-specifics.md`, and `breaking-changes/` where applicable. New files go under whichever subdirectory fits; both skills and knowledge are expected to evolve as the SDK does.
152
+ - **Example code lives in a test, not in prose.** `check:ai-snippets` compiles only the dapp-kit and wallet-sdk-react knowledge, so a runnable `@sodax/sdk` example goes in a `packages/sdk/src/**/*.test.ts` (typechecked by `checkTs`, run by `pnpm test`) and the page links it as `https://github.com/gosodax/sodax-sdks/blob/main/<path>`; `check:ai-structural` fails when that file is missing.
151
153
  - **No `bin`, no build, no runtime TypeScript** in this package — markdown only. `tsc` ships as a devDep purely so the validator scripts can typecheck doc fixtures. `pnpm --filter @sodax/skills check:ai` is the local validation gate; CI runs the same thing via the existing `check:ai` turbo task.
152
154
 
153
155
  ### Conventions inherited from the old `ai-exported/` tree
@@ -166,7 +168,7 @@ Chains seven sub-scripts. Each catches a distinct bug class — green guards tog
166
168
 
167
169
  | Sub-script | What it enforces | Source of truth | Opt-out |
168
170
  |---|---|---|---|
169
- | `check:ai-structural` | `.claude-plugin/plugin.json` parses and registers exactly the expected broad SDK skills + meta skills (the `EXPECTED_*` arrays in `check-skills.sh` are the source of truth); every SKILL.md (broad + bundled granular + meta) has valid `name:` / `description:` frontmatter; no orphan top-level skill dirs; every relative `.md` link resolves; every granular skill is linked from its parent SKILL.md (its "Prefer a granular skill" row), every `integration/knowledge/features/*.md` is named in the parent's integration section, and every registered description fits Claude Code's 1,536-character skill-listing cap. | this package's filesystem | none — structural |
171
+ | `check:ai-structural` | `.claude-plugin/plugin.json` parses and registers exactly the expected broad SDK skills + meta skills (the `EXPECTED_*` arrays in `check-skills.sh` are the source of truth); every SKILL.md (broad + bundled granular + meta) has valid `name:` / `description:` frontmatter; no orphan top-level skill dirs; every relative `.md` link resolves; every `https://github.com/gosodax/sodax-sdks/{blob,tree}/main/<path>` URL under `skills/` and in this package's top-level `.md` files, outside code spans and blocks, names a file or directory that exists in the repo, exact case (`scripts/check-repo-urls.mjs`, sharing the repo-root `scripts/check-doc-links.mjs`); every granular skill is linked from its parent SKILL.md (its "Prefer a granular skill" row), every `integration/knowledge/features/*.md` is named in the parent's integration section, and every registered description fits Claude Code's 1,536-character skill-listing cap. | this package's filesystem | none — structural |
170
172
  | `check:ai-imports` | Every `import … from '@sodax/<pkg>'` statement in `skills/sodax-<pkg>/{integration,migration-v1-to-v2}/knowledge/**/*.md` + each SDK package's README/AGENTS.md typechecks against `packages/<pkg>/src/index.ts`. Catches deleted / renamed exports. | `packages/<pkg>/src/index.ts` via fixture tsconfig `paths` | none |
171
173
  | `check:ai-snippets` | Every fenced ts/tsx code block in `skills/sodax-{dapp-kit,wallet-sdk-react}/{integration,migration-v1-to-v2}/knowledge/**/*.md` typechecks against the real SDK. Catches call-shape drift. Pattern-style blocks can opt out with the marker; real working examples still validate. | same as imports, plus `_ai-snippets-fixture/_preamble.d.ts` ambients | `// @ai-snippets-skip` as first content line of the block |
172
174
  | `check:ai-tsx-examples` | Every standalone `.tsx` file under `skills/sodax-<pkg>/integration/knowledge/examples/` typechecks as a complete module against the live `src/`. Catches export drift, hook-shape drift, and renamed-param drift in runnable user-facing examples. | each SDK package's `src/index.ts` (and `xchains/*` sub-paths for wallet-sdk-react) via fixture tsconfig `paths` | none — illustrative blocks live in `.md` via `@ai-snippets-skip`; `integration/knowledge/examples/` is for runnable code only |
package/README.md CHANGED
@@ -36,16 +36,17 @@ After install, your agent picks based on what you're building. Quick guide:
36
36
  | You're building | Load these skills (mode) |
37
37
  |---|---|
38
38
  | Not sure what to build yet / not a developer | `sodax-build` — it interviews you, writes a product brief, and names the skill to load next |
39
+ | Nothing — you want the agent to swap or read live SODAX data now | No skill — use the [Builders MCP](https://docs.sodax.com/builders-mcp) (its swap tools are not production ready yet) |
39
40
  | Backend / Node app (no React) using `@sodax/sdk` | `sodax-sdk` (integration) + `sodax-wallet-sdk-core` (integration; if signing) |
40
41
  | React dapp using `@sodax/dapp-kit` | `sodax-dapp-kit` (integration) + `sodax-wallet-sdk-react` (integration; always) + `sodax-sdk` (integration; for any unwrapped operations) |
41
42
  | React app calling the SDK directly (no `dapp-kit`) | `sodax-sdk` (integration) + `sodax-wallet-sdk-react` (integration) |
42
43
  | **Porting v1 code** | Same skills, switched to migration mode (each SKILL.md mode-gates by consumer signal). |
43
44
 
44
- `AGENTS.md` says the same thing in router form — your agent reads it first and picks.
45
+ `AGENTS.md` is the full router, with per-feature rows — your agent reads it first and picks.
45
46
 
46
47
  ## Why this exists
47
48
 
48
- LLM training data drifts: snippets from chat often use stale method names, reshaped types, or outdated error codes. Public docs help humans, not agents — an agent only reads what's in its context window. This package ships the right material in agent-native form so the agent reads it before generating code. The content is version-locked to the SDK — upgrade `@sodax/skills`, the docs upgrade with it.
49
+ LLM training data drifts: snippets from chat often use stale method names, reshaped types, or outdated error codes. Public docs help humans, not agents — an agent only reads what's in its context window. This package ships the right material in agent-native form so the agent reads it before generating code. An npm install of `@sodax/skills` at your SDK's version matches that SDK. The skills CLI installs from `main`, which can describe APIs newer than your installed SDK; confirm an import resolves against your installed version.
49
50
 
50
51
  ## Feedback
51
52
 
package/package.json CHANGED
@@ -4,7 +4,7 @@
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
7
- "version": "2.3.0-rc.2",
7
+ "version": "2.3.0-rc.3",
8
8
  "license": "MIT",
9
9
  "description": "AI-agent skills and knowledge for consumers of @sodax/* SDKs (Claude Code, Codex, Cursor, …)",
10
10
  "keywords": [
@@ -26,6 +26,7 @@ SODAX is **cross-chain DeFi** on a hub-and-spoke model (Sonic is the hub). **Its
26
26
  | `walletProvider`, `IEvmWalletProvider`, "sign on <chain>", a specific chain provider | `sodax-wallet-sdk-core` |
27
27
  | "connect button", "wallet modal", "switch chain", WalletConnect, "email login", Privy | `sodax-wallet-sdk-react` |
28
28
  | A named feature already chosen (swap / money market / staking / bridge / dex / leverage yield / migration / partner / recovery) **with** an SDK in mind | the matching dev skill above |
29
+ | "Swap this for me now", "what's the rate today": an action or live data, not something to build | no skill — point them at the SODAX Builders MCP (its swap tools are not production ready yet) |
29
30
 
30
31
  When in doubt about whether the *what* is decided, ask **one** question: *"Do you already know which SODAX feature you want, or are we still figuring that out?"* — decided → route; not decided → interview.
31
32
 
@@ -22,5 +22,5 @@ These names are **illustrative anchors only** — do not bake the actual chain l
22
22
 
23
23
  ## Assets
24
24
 
25
- - Bridgeability and per-feature token support are **runtime facts**, not a fixed table. "Can I bridge token X from chain A to B" is answered at runtime by the SDK, not by a baked list — note it as a dev-time check in the brief.
25
+ - Bridgeability and per-feature token support are **runtime facts**, not a fixed table. The live list comes from the backend (`sodax.api.swaps.getTokens()`, `sodax.api.bridge.getTokens()`, the bridgeable amount); the SDK's feature services accept only the tokens bundled with the installed version. Note it as a dev-time check in the brief.
26
26
  - Never promise a specific token is supported without confirming live source.
@@ -18,7 +18,7 @@ Granular skill for the smaller `@sodax/dapp-kit` v2 surfaces grouped together: *
18
18
  - **Partner fees:** `useIsTokenApproved` → `useApproveToken` → `useSetSwapPreference` → `useFeeClaimSwap` (returns `IntentAutoSwapResult`, NOT `SwapResponse`); `useGetAutoSwapPreferences`, `useFetchAssetsBalances` for reads.
19
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
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 client (`useSwapsApi*` — e.g. `useSwapsApiSubmitTx`, `useSwapsApiSubmitTxStatus`, `useSwapsApiQuote`).
21
- - **Swaps API swap with a wallet:** `useSwapsApiAllowance` first. Short allowance on an EVM source → `useSwapsApiBroadcastWithApproval` (the approval and the `/swaps/intents` tx in one EIP-5792 signature where the wallet can batch; a refusal means approve with `useSwapsApiApproveAndBroadcast`, create the intent again, sign it); otherwise sign the intent tx yourself. Then `useSwapsApiSubmitTx` with the `txHash`. Persist the batch id `onBatchSent` reports: a batch that comes back `ATOMIC_BATCH_UNCONFIRMED` may still land.
21
+ - **Swaps API swap with a wallet:** tokens from `useSwapsApiTokens` (they include tokens newer than the installed SDK), then `useSwapsApiAllowance`. Short allowance → `useSwapsApiBroadcastWithApproval` on an EVM source where your dapp-kit has it (one EIP-5792 signature where the wallet can batch; a refusal means approve, create the intent again, sign it), otherwise `useSwapsApiApproveAndBroadcast`. Otherwise sign the intent tx yourself. Then `useSwapsApiSubmitTx`. Signing per chain and the intent conversion: [`features/auxiliary-services.md`](../integration/knowledge/features/auxiliary-services.md) § Swaps API. Persist the batch id `onBatchSent` reports: a batch that comes back `ATOMIC_BATCH_UNCONFIRMED` may still land.
22
22
  - **Stellar prerequisites:** `useStellarGate` sequences the ordered prerequisites — the account must EXIST (sponsored activation, free to the user), must TRUST the token, and only then must be able to PAY for the trustline it needs. A freshly activated account holds zero XLM. An account that already holds the trustline needs no XLM at all, which is why affordability is checked last. A failed check sets `checkFailed` with `error`/`retry` — render it, or the fail-closed gate becomes an unexplained dead button. Lower-level: `useStellarAccountStatus`, `useStellarAccountActive`, `useSponsorConfig`, `useActivateStellarAccount`.
23
23
  - **Shared utilities:** `useSodaxContext`, `useHubProvider`, `useBalances` (SDK-backed — no `xService`, reads via `SodaxProvider`) / `useXBalances` (needs `xService` from wallet-sdk-react), `useDeriveUserWalletAddress` / `useGetUserHubWalletAddress`, `useEstimateGas`, `useStellarTrustlineCheck` / `useEstablishTrustline`.
24
24
 
@@ -17,6 +17,7 @@ Granular skill for the bridge hooks of `@sodax/dapp-kit` v2. queryKey/mutationKe
17
17
  2. **Need a bridgeable precheck?** `useGetBridgeableAmount` (vault deposit/withdrawal cap, returns a `BridgeLimit`) and `useGetBridgeableTokens` (enumerate compatible destinations).
18
18
  3. **Allowance gating?** `useBridgeWithApproval` folds the approval in (one EIP-5792 batch when the wallet can), labelled with `useBridgeApprovalStrategy`. The two-step alternative is `useBridgeAllowance` + `useBridgeApprove` before `useBridge`.
19
19
  4. **Source/destination chains + recipient format** — confirm both are supported spokes and the `recipient` matches the destination chain encoding.
20
+ 5. **Tokens newer than the installed SDK?** These hooks validate against the config bundled with `@sodax/sdk`. For tokens the backend lists after that release, use the `useBridgeApi*` hooks (the [`auxiliary-services`](../auxiliary-services/SKILL.md) skill) with tokens from `useBridgeApiTokens`.
20
21
 
21
22
  ## Integration workflow (new v2 code)
22
23
 
@@ -18,6 +18,9 @@ DO / DO NOT / workflow / stop conditions for AI agents writing v2 dapp-kit code.
18
18
 
19
19
  ## DO
20
20
 
21
+ - **DO** confirm a hook resolves against the installed `@sodax/dapp-kit` before building on it: these skills track `main`, which can be ahead of your release. If your dapp-kit has no `use*WithApproval` hook, use the allowance hook, the approve hook, then the plain action hook (a vault deposit approves through `useSwapAllowance` / `useSwapApprove`).
22
+ - **DO** take the token list for a `useSwapsApi*` / `useBridgeApi*` / `useLeverageYieldApi*` flow from `useSwapsApiTokens` / `useBridgeApiTokens`. The feature hooks accept only tokens bundled with the installed `@sodax/sdk`, and `initialize()` adds none (the `sodax-sdk` skill, "Where supported tokens come from").
23
+
21
24
  - **DO** call dapp-kit's exported hooks (which wrap `useSafeMutation`). Never call React Query's `useMutation` directly inside a wrapper around a dapp-kit hook — consumers depend on `mutateAsyncSafe`.
22
25
  - **DO** branch on `mutateAsyncSafe`'s `Result.ok` for sequenced flows (`if (!hasAllowance) await approve(...); await action(...);`). User-rejects are modal, not exceptional.
23
26
  - **DO** use `ChainKeys.X_MAINNET` constants for chain identifiers. Never hard-code chain key strings (`'sonic'`, `'0xa4b1.arbitrum'`).
@@ -225,7 +225,10 @@ each, resolving with `{ approveTxHash, resetTxHash? }` only once the final appro
225
225
  transaction that mines but reverts rejects the mutation naming that step, so the approve is never
226
226
  sent over a reset that did not take. Each also invalidates its own allowance query
227
227
  (`['swapsApi','allowance']` / `['bridgeApi','allowance']` / `['leverageYieldApi','allowance']`),
228
- because confirmation now happens inside the hook. Pick the one matching the action you are about to
228
+ because confirmation now happens inside the hook. Before invalidating, each re-checks its API's allowance
229
+ for up to about 15 seconds, since the API reads the chain through its own RPC, which can trail the node
230
+ that confirmed the approve; it resolves after that wait either way, so gate the next step on the
231
+ allowance query, not on mutation success. Pick the one matching the action you are about to
229
232
  take — each API builds its approval for its own hub spender, so an approval built by one does not
230
233
  satisfy the other. Only a leverage-yield **deposit** needs one; a withdraw spends `lsoda*` from the
231
234
  hub wallet and never approves.
@@ -240,8 +243,9 @@ means the batch may still land, so never let the user sign that swap again — r
240
243
  `confirmApprovalBatch` instead. A wallet that cannot batch (the Sonic hub never does), or refuses the batch
241
244
  before signing, rejects with an `isAtomicBatchRefusal` error and nothing sent: approve with
242
245
  `useSwapsApiApproveAndBroadcast`, create the intent again — a fresh deadline — and sign that. Pass
243
- `fallbackOnRefusal: true` to have the hook approve and then send the `intentTx` it was given; that intent was
244
- built before the approval, so its deadline has to outlast the approval's wait.
246
+ `fallbackOnRefusal: true` to have the hook approve, re-check the API's allowance for up to about 15 seconds like
247
+ the approve hooks, and then send the `intentTx` it was given; that intent was built before the approval, so its
248
+ deadline has to outlast the approval and that wait.
245
249
 
246
250
  All three, and `useSwapsApiBroadcastWithApproval` for its separate approval, accept an optional **`onProgress`** in their mutation vars. It reports each transaction as
247
251
  `{ step, phase, index, total, hash?, error? }` — `step` is `'allowance-reset'` or `'approve'`, `phase`
@@ -93,6 +93,10 @@ always approves, so check `useSwapsApiAllowance` first, and it stops at the broa
93
93
  then submit it. Its errors, the unconfirmed-batch rule and `fallbackOnRefusal` are in
94
94
  [architecture.md](../architecture.md#approve-hooks-can-prompt-the-wallet-twice).
95
95
 
96
+ On any other source, sign and broadcast `created.tx` with the source wallet provider, per chain type
97
+ (the `sodax-sdk` skill, Swaps API, "Sign and broadcast `tx`"). `created.intent` is an `IntentResponseV2` (decimal strings); convert its numeric
98
+ fields with `BigInt()` into the `IntentRequestV2` that the submit request takes.
99
+
96
100
  ```ts
97
101
  // @ai-snippets-skip
98
102
  const { mutateAsync: broadcastWithApproval } = useSwapsApiBroadcastWithApproval();
@@ -196,7 +200,7 @@ const { mutateAsync: submitBridgeTx } = useBridgeApiSubmitTx();
196
200
  await submitBridgeTx({ request, apiConfig: { baseURL: 'https://...' } });
197
201
  ```
198
202
 
199
- `useBridgeApiSubmitTxStatus` polls (1s) and returns `BridgeSubmitTxStatusResponseV2 | undefined`, running only when **both** `txHash` and `srcChainKey` are supplied; terminal states are `executed` / `failed` (no `posting_execution`), and it also stops on a set `abandonedAt` or once the backend rejects the API key. Every retrying `useBridgeApi*` hook defaults `retry` to `retryUnlessAuthFailure`, exactly as the swaps and leverage-yield hooks do. The fee / bridgeable-amount / bridgeable quotes are computable client-side (config + vault math) — prefer the on-chain `useGetBridgeableAmount` / `sodax.bridge.*` for a no-round-trip read; `useBridgeApiFee` / `useBridgeApiBridgeableAmount` / `useBridgeApiIsBridgeable` mirror the backend endpoints for HTTP parity.
203
+ `useBridgeApiSubmitTxStatus` polls (1s) and returns `BridgeSubmitTxStatusResponseV2 | undefined`, running only when **both** `txHash` and `srcChainKey` are supplied; terminal states are `executed` / `failed` (no `posting_execution`), and it also stops on a set `abandonedAt` or once the backend rejects the API key. Every retrying `useBridgeApi*` hook defaults `retry` to `retryUnlessAuthFailure`, exactly as the swaps and leverage-yield hooks do. The bridgeable-amount / bridgeable quotes also exist client-side (`useGetBridgeableAmount`, `sodax.bridge.*`), but those read the config bundled with the installed SDK and fail or return `false` for tokens newer than that release. With tokens from `useBridgeApiTokens`, gate the action on `useBridgeApiBridgeableAmount` (its `limit.amount` above zero); `useBridgeApiIsBridgeable` checks config only, and a zero-limit pair fails create-intent. Sign and broadcast the created `tx` per chain type, as for swaps.
200
204
 
201
205
  > Full list in [hooks-index.md](../reference/hooks-index.md); key shapes in [querykey-conventions.md](../reference/querykey-conventions.md). For non-React callers, `sodax.api.bridge` is documented in the `sodax-sdk` skill (integration mode).
202
206
 
@@ -212,11 +216,12 @@ useLeverageYieldApiCreateDepositIntent({ mutationOptions }); // mutation → so
212
216
  useLeverageYieldApiSubmitTxStatus({ params, queryOptions }); // query → sodax.api.leverageYield.getSubmitTxStatus
213
217
  ```
214
218
 
215
- Four deltas worth knowing:
219
+ Deltas worth knowing:
216
220
 
217
221
  - **Create-intent is split.** `useLeverageYieldApiCreateDepositIntent` (any token → `lsoda*`) vs `useLeverageYieldApiCreateWithdrawIntent` (`lsoda*` → any token), each with its own quote hook. Only the deposit path has an allowance step — a withdraw spends `lsoda*` from the hub wallet — so `useLeverageYieldApiAllowance` / `useLeverageYieldApiApprove` take the **deposit** body.
218
222
  - **`useLeverageYieldApiSubmitTx`'s `request` carries `operation`.** `LeverageYieldSubmitTxRequestV2` is the swaps `SubmitTxRequestV2` plus a required `operation: 'deposit' | 'withdraw'`; `relayData` is the payload **string**, as for swaps.
219
223
  - **Terminal submit-tx status is `solved`**, not the bridge API's `executed` — a vault swap is filled by the solver, so `posting_execution` applies too. `useLeverageYieldApiSubmitTxStatus` polls (1s) while both `txHash` and `srcChainKey` are supplied and stops on `solved` / `failed`, on a set `abandonedAt`, or once the backend rejects the API key.
224
+ - **You sign the built `tx` and convert the intent**, as for the Swaps API hooks above. Take input and output tokens from `useSwapsApiTokens`, which includes tokens newer than the installed SDK.
220
225
  - **`lsoda*` shares live in the derived HUB wallet, not the EOA.** Resolve it with `useGetUserHubWalletAddress` before reading `useLeverageYieldApiShareBalance` / `useLeverageYieldApiMaxWithdraw`, or the balance reads as zero.
221
226
 
222
227
  ```ts
@@ -226,7 +231,7 @@ const { mutateAsync: submitVaultTx } = useLeverageYieldApiSubmitTx();
226
231
  await submitVaultTx({ request, apiConfig: { baseURL: 'https://...' } });
227
232
  ```
228
233
 
229
- Prefer `useLeverageYieldApiApproveAndBroadcast` over `useLeverageYieldApiApprove`: a guarded deposit token can need its stale allowance cleared first, and the approve-and-broadcast hook owns plan → sign → broadcast → wait in that order (reporting each step through `onProgress`) and invalidates `['leverageYieldApi','allowance']` itself.
234
+ Prefer `useLeverageYieldApiApproveAndBroadcast` over `useLeverageYieldApiApprove`: a guarded deposit token can need its stale allowance cleared first, and the approve-and-broadcast hook owns plan → sign → broadcast → wait in that order (reporting each step through `onProgress`) and invalidates `['leverageYieldApi','allowance']` itself, after re-checking the API's allowance for up to about 15 seconds (the API's RPC can trail the node that confirmed the approve).
230
235
 
231
236
  > Full list in [hooks-index.md](../reference/hooks-index.md); key shapes in [querykey-conventions.md](../reference/querykey-conventions.md). For non-React callers, `sodax.api.leverageYield` is documented in the `sodax-sdk` skill (integration mode).
232
237
 
@@ -61,7 +61,7 @@ export function Providers({ children }: { children: React.ReactNode }) {
61
61
 
62
62
  ## 3. Initialize the SDK (optional)
63
63
 
64
- For the latest tokens / chains / fee parameters from the backend:
64
+ `sodax.config.initialize()` currently returns success without fetching anything, so this step is optional and adds no tokens:
65
65
 
66
66
  ```tsx
67
67
  import { useEffect } from 'react';
@@ -77,7 +77,7 @@ export function useInitializeSodax() {
77
77
  }
78
78
  ```
79
79
 
80
- Skipping this works — feature services fall back to packaged defaults — but you'll miss tokens / chains added after the SDK release.
80
+ Tokens and chains come from the installed `@sodax/sdk` version. For tokens the backend lists after that release, use the `useSwapsApi*`, `useBridgeApi*` and `useLeverageYieldApi*` hooks (the `auxiliary-services` skill), which leave token validation to the backend.
81
81
 
82
82
  ## 4. Get a wallet provider
83
83
 
@@ -123,7 +123,7 @@ const swap = useSwap({
123
123
 
124
124
  ## Initialize SDK (Optional)
125
125
 
126
- For dynamic config (latest tokens/chains from backend API):
126
+ `sodax.initialize()` currently returns success without fetching backend config; tokens and chains come from the installed SDK version. The call is optional:
127
127
 
128
128
  ```tsx
129
129
  import { useEffect } from 'react';
@@ -228,7 +228,7 @@ Typed React Query wrappers over the backend Swaps API (`sodax.api.swaps.*`), one
228
228
 
229
229
  ## Bridge API (`sodax.api.bridge`)
230
230
 
231
- Typed React Query wrappers over the backend Bridge API (`sodax.api.bridge.*`). Distinct from the on-chain `bridge/` hooks (`useBridge`/`useBridgeAllowance`/…), which drive `sodax.bridge` (the `BridgeService`). Smaller than the swaps family (no intent/solver surface). The fee / bridgeable-amount / bridgeable quotes are computable client-side (prefer the on-chain `useGetBridgeableAmount` / `sodax.bridge.*` — no round-trip), but are also mirrored here as HTTP hooks for parity.
231
+ Typed React Query wrappers over the backend Bridge API (`sodax.api.bridge.*`). Distinct from the on-chain `bridge/` hooks (`useBridge`/`useBridgeAllowance`/…), which drive `sodax.bridge` (the `BridgeService`). Smaller than the swaps family (no intent/solver surface). The bridgeable-amount / bridgeable quotes also exist on-chain (`useGetBridgeableAmount` / `sodax.bridge.*`, no round-trip) for tokens bundled with the installed SDK; for any other listed token use these HTTP hooks.
232
232
 
233
233
  | Hook | Type / Polling |
234
234
  |---|---|
@@ -19,6 +19,7 @@ Granular skill for the leverage-yield hooks of `@sodax/dapp-kit` v2. queryKey/mu
19
19
  3. **Approval?** `useLeverageYieldVaultSwapWithApproval` folds the deposit's approval in (one EIP-5792 batch when the wallet can), labelled with `useLeverageYieldApprovalStrategy`. The two-step alternative approves the spoke `inputToken` via the swap-domain `useSwapApprove` / `useSwapAllowance`. Withdraw needs no approval (`hubWalletSwap: true`).
20
20
  4. **Which vaults?** No hook — read the registry with `useSodaxContext().sodax.leverageYield.listVaults()` (synchronous, wrap in `useMemo`) and pass each entry's `vault` address to the hooks.
21
21
  5. **Which reads?** `useLeverageYieldEffectiveApr` (headline APR), `useLeverageYieldPosition` (LTV/health), `useLeverageYieldTotalAssets` (TVL), `useLeverageYieldPreviewRedeem` (price-per-share), `useLeverageYieldShareBalances` (per-chain balances — returns an array).
22
+ 6. **Tokens newer than the installed SDK?** The vault hooks quote and build against the tokens bundled with `@sodax/sdk`. For input or output tokens the backend lists after that release, use the `useLeverageYieldApi*` hooks (the [`auxiliary-services`](../auxiliary-services/SKILL.md) skill) with tokens from `useSwapsApiTokens`.
22
23
 
23
24
  ### Step 1b — leverage positions
24
25
 
@@ -19,6 +19,7 @@ Granular skill for the swap hooks of `@sodax/dapp-kit` v2. React-only — backen
19
19
  2. **Which hooks?** A whole swap form → `useSwapLifecycle` (one `state` + `next()`; the hooks below are its parts and stay available). Otherwise: quote/preview (`useQuote`), execute (`useSwap`, or `useSwapWithApproval` to fold the approval in — one EIP-5792 signature where the wallet can batch; `useSwapApprovalStrategy` labels it; `allowAccountUpgrade: false` keeps a wallet that would ask for a smart-account upgrade on the two-step path), allowance gate (`useSwapAllowance` + `useSwapApprove`), status polling (`useDetailedStatus` from the source tx — the default; `useStatus` only when you hold the hub tx hash), or limit orders (`useCreateLimitOrder` / `useCancelLimitOrder`).
20
20
  3. **Market order or limit order?** Limit orders use `useCreateLimitOrder` (no `deadline`; cancel manually via `useCancelLimitOrder`).
21
21
  4. **Imperative flow or render-driven?** Sequenced flows → `mutateAsyncSafe` (returns `Result<T>`, never rejects). Fire-and-forget → `mutate`.
22
+ 5. **Tokens newer than the installed SDK?** These hooks validate against the tokens bundled with `@sodax/sdk`. For tokens the backend lists after that release, use the `useSwapsApi*` hooks (the [`auxiliary-services`](../auxiliary-services/SKILL.md) skill) with tokens from `useSwapsApiTokens`.
22
23
 
23
24
  ## Integration workflow (new v2 code)
24
25
 
@@ -54,6 +54,7 @@ This skill documents the **SDK call sites** — what to import, how to construct
54
54
 
55
55
  - **Wallet provider implementations** (`IEvmWalletProvider`, `ISolanaWalletProvider`, etc.) → **load the `sodax-wallet-sdk-core` skill** (integration mode). It ships ready-made provider classes for all 9 chain families, both private-key (Node / scripts) and browser-extension modes. This skill only treats wallet providers as a contract (`declare const evmWallet: IEvmWalletProvider`).
56
56
  - **React hooks wrapping the SDK** → **load the `sodax-dapp-kit` skill** instead of this one.
57
+ - **Making a swap for the user now, or reading live SODAX data, with no code to write** → the [Builders MCP](https://docs.sodax.com/builders-mcp), no skill; its swap tools are not production ready yet. Come back to this skill once the task is writing code.
57
58
  - **Browser wallet connectivity** (connect / disconnect / chain switching for React apps) → **load the `sodax-wallet-sdk-react` skill**.
58
59
 
59
60
  ### App-layer concerns the SDK is intentionally silent on
@@ -91,7 +92,7 @@ Follow in order. Skipping `ai-rules.md` is the most common cause of agents rever
91
92
  2. **Every async public method returns `Result<T>`.** Branch on `result.ok`. No throws across service boundaries. Sub-Result forwarding is the default: `if (!sub.ok) return sub`.
92
93
  3. **Errors are `SodaxError<C>`.** A single class with a closed 13-code reason vocabulary plus a `feature` field. The pair `(feature, code)` is your discriminator. Use `isSodaxError(e)` (not bare `instanceof`).
93
94
  4. **Signed vs raw is a discriminated union.** `WalletProviderSlot<K, Raw>` enforces at compile time: `{ raw: false, walletProvider }` for signing, `{ raw: true }` for unsigned-tx building. Mixing them is a TypeScript error.
94
- 5. **Config is dynamic; overrides only land on `sodax.config`.** Always read via `sodax.config.*` (e.g. `sodax.config.spokeChainConfig[chainKey]`). Direct imports of `spokeChainConfig` / `sodaxConfig` from `@sodax/types` / `@sodax/sdk` are packaged-default snapshots and silently miss both `await sodax.config.initialize()` updates and `new Sodax(config)` overrides.
95
+ 5. **Overrides only land on `sodax.config`; tokens come from the installed version.** Always read via `sodax.config.*` (e.g. `sodax.config.spokeChainConfig[chainKey]`). Direct imports of `spokeChainConfig` / `sodaxConfig` from `@sodax/types` / `@sodax/sdk` are packaged-default snapshots and silently miss `new Sodax(config)` overrides. Feature services accept only tokens bundled with the installed `@sodax/sdk`; for newer ones see [`recipes/initialize-sodax.md`](integration/knowledge/recipes/initialize-sodax.md) § "Where supported tokens come from".
95
96
 
96
97
  ### Top traps, conventions, verification
97
98
 
@@ -16,7 +16,7 @@ Granular skill for `BridgeService` — `sodax.bridge`. Feature tag: `'bridge'`.
16
16
  1. **New code or v1 → v2 port?**
17
17
  2. **Signed flow (frontend) or unsigned-tx (backend)?**
18
18
  3. **Need a bridgeable-amount precheck?** Vault deposit limits may cap the transfer; `getBridgeableAmount` (or equivalent) read tells you the cap before submitting.
19
- 4. **One signature?** `bridgeWithApproval` folds the approval in (one EIP-5792 batch when the wallet can); `getApprovalStrategy` labels the button first. Plain `bridge()` expects the allowance to be set already.
19
+ 4. **One signature?** `bridgeWithApproval` folds the approval in (one EIP-5792 batch when the wallet can); `getApprovalStrategy` labels the button first. Plain `bridge()` expects the allowance to be set already; without `bridgeWithApproval`, set it with `isAllowanceValid()` + `approve()` first.
20
20
  5. **Source / destination chains** — confirm both are supported spoke chains, and the destination address format matches the chain (vd Stellar address starts with `G`, Solana base58, Bitcoin specific encodings).
21
21
 
22
22
  ## Integration workflow
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: sodax-sdk-bridge-api
3
- description: 'Granular skill for the @sodax/sdk v2 Bridge API client — `sodax.api.bridge` (class BridgeApiService), a typed HTTP client for the backend Bridge API (`/bridge/*`: tokens, allowance/approve, create-bridge-intent, submit-tx + status, fee/bridgeable-amount/bridgeable discovery). Every method returns Promise<Result<T>>, never throws, and validates the response. Use when the task calls the bridge backend directly (e.g. "sodax.api.bridge", "createBridgeIntent via the backend API", "submit bridge tx", "poll bridge submit-tx status", "bridge API v2", "point bridge at a custom endpoint", "bridge.useBackendSubmitTx"). For the higher-level end-to-end bridge orchestrator use the `bridge` skill instead. Skill links into the parent sodax-sdk knowledge tree.'
3
+ description: 'Granular skill for the @sodax/sdk v2 Bridge API client — `sodax.api.bridge` (class BridgeApiService), a typed HTTP client for the backend Bridge API (`/bridge/*`: tokens, allowance/approve, create-bridge-intent, submit-tx + status, fee/bridgeable-amount/bridgeable discovery). Every method returns Promise<Result<T>>, never throws, and validates the response. Use when the task calls the bridge backend directly (e.g. "sodax.api.bridge", "createBridgeIntent via the backend API", "submit bridge tx", "poll bridge submit-tx status", "approve and bridge in one signature", "bridge API v2", "point bridge at a custom endpoint", "bridge.useBackendSubmitTx"), or must bridge tokens the installed SDK does not bundle ("Unsupported spoke chain (…) token", "backend token list without upgrading the SDK"). For the higher-level bridge orchestrator, which accepts only bundled tokens, use the `bridge` skill instead. Skill links into the parent sodax-sdk knowledge tree.'
4
4
  ---
5
5
 
6
6
  # Bridge API (Core SDK granular skill)
@@ -17,16 +17,18 @@ validates the response. Errors carry `feature: 'backend'`, `context.api: 'bridge
17
17
  ## Step 1 — Clarify with user before coding
18
18
 
19
19
  1. **Which endpoint(s)?** Tokens · allowance/approve/create-bridge-intent · submit-tx/status · fee/bridgeable-amount/bridgeable discovery.
20
- 2. **Orchestrator or raw API?** If the user just wants "do a bridge", prefer `sodax.bridge` (the `bridge`
21
- skill). Use `sodax.api.bridge` when they need a single backend call or are building their own flow.
20
+ 2. **Orchestrator or raw API?** `sodax.bridge` (the `bridge` skill), its reads included, accepts only
21
+ tokens bundled with the installed `@sodax/sdk`. Use `sodax.api.bridge` end to end for tokens newer than
22
+ the installed SDK, where the backend validates, or for a single backend call. Otherwise prefer
23
+ `sodax.bridge` for "do a bridge".
22
24
  3. **Backend availability.** The `/bridge/*` routes are the newest backend surface; confirm the target host
23
25
  actually serves them (the on-chain `sodax.bridge` flow needs no backend).
24
26
 
25
27
  ## Integration workflow
26
28
 
27
29
  1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT (read first).
28
- 2. [`../integration/knowledge/features/bridge-api.md`](../integration/knowledge/features/bridge-api.md) — the full client: signatures, deltas vs swaps (no intent, FULL relayData envelope, 5-state tolerant status), common call shapes (create-intent, submit-tx + status), the read-only fee/bridgeable-amount/bridgeable discovery quotes, per-call overrides, `bridge.useBackendSubmitTx`.
29
- 3. For the end-to-end bridge flow that wraps these calls → [`../integration/knowledge/features/bridge.md`](../integration/knowledge/features/bridge.md); for the sibling swaps client → [`../integration/knowledge/features/swaps-api.md`](../integration/knowledge/features/swaps-api.md); for the read client (`sodax.backendApi`) → [`../integration/knowledge/features/backend-api.md`](../integration/knowledge/features/backend-api.md).
30
+ 2. [`../integration/knowledge/features/bridge-api.md`](../integration/knowledge/features/bridge-api.md) — the full client: signatures, deltas vs swaps (no intent, FULL relayData envelope, 5-state tolerant status), common call shapes (create-intent, submit-tx + status), the read-only fee/bridgeable-amount/bridgeable discovery quotes, per-call overrides, `bridge.useBackendSubmitTx`, and approving and bridging in one EIP-5792 signature.
31
+ 3. For the SDK bridge flow (local token checks; only its submit-tx leg calls this API) → [`../integration/knowledge/features/bridge.md`](../integration/knowledge/features/bridge.md); for the sibling swaps client → [`../integration/knowledge/features/swaps-api.md`](../integration/knowledge/features/swaps-api.md); for the read client (`sodax.backendApi`) → [`../integration/knowledge/features/backend-api.md`](../integration/knowledge/features/backend-api.md).
30
32
  4. Errors are `Result<T, SodaxError<'EXTERNAL_API_ERROR'>>` → [`../integration/knowledge/recipes/result-and-errors.md`](../integration/knowledge/recipes/result-and-errors.md) and [`../integration/knowledge/reference/error-codes.md`](../integration/knowledge/reference/error-codes.md).
31
33
 
32
34
  ### Bridge-API-specific anti-patterns
@@ -36,14 +38,15 @@ validates the response. Errors carry `feature: 'backend'`, `context.api: 'bridge
36
38
  - **Expecting an `intent` / `intent_hash`.** `createBridgeIntent` returns `{ tx, relayData }` only; submit-tx status terminal success is `status === 'executed' && result.dstIntentTxHash` (no solver `intent_hash`, no `'posting_execution'` state).
37
39
  - **Calling `getSubmitTxStatus` with only `txHash`.** Both `txHash` AND `srcChainKey` are required.
38
40
  - **Using SDK-domain param names in the body.** The wire DTO uses swaps naming (`inputToken`/`outputToken`/`inputAmount`/`srcAddress`/`dstAddress`); map SDK-domain `srcToken`/`dstToken`/`amount`/`recipient` via `toCreateBridgeIntentParamsV2`.
39
- - **Round-tripping the discovery quotes when a local read suffices.** `getFee` / `getBridgeableAmount` / `isBridgeable` are computable client-side — prefer `sodax.bridge.getFee` / `getBridgeableAmount` / `isBridgeable` (no network hop). Their backend endpoints exist (mirrored on this client) mainly for non-SDK HTTP callers / parity; the token *list*, by contrast, is only backend-served.
41
+ - **Gating the API path with the local reads.** `sodax.bridge.getBridgeableAmount` / `isBridgeable` read the bundled config and fail for tokens newer than the installed SDK. On the API path gate on `sodax.api.bridge.getBridgeableAmount` (limit above zero); see [`features/bridge-api.md`](../integration/knowledge/features/bridge-api.md) § "Deltas vs the Swaps API".
42
+ - **Assuming the approve needs its own prompt.** From an EVM spoke, an EIP-5792 wallet can sign `[resetTx?, approve, deposit]` once — see "Approve and bridge in one signature" in the bridge-api feature doc. In `@sodax/dapp-kit`, `useBridgeApiApproveAndBroadcast` approves separately; batching means running that flow with the SDK.
40
43
  - **Confusing `sodax.api.bridge` with `sodax.bridge`.** The former is the backend HTTP client; the latter is the on-chain vault orchestrator.
41
44
 
42
45
  ## Migration workflow (on-chain → API)
43
46
 
44
47
  There is **no v1 Bridge API** — the typed `sodax.api.bridge` client is v2-new. The relevant move is from the
45
48
  on-chain `sodax.bridge.bridge()` orchestrator to the API client (or to the orchestrator's default-on backend
46
- path via `bridge.useBackendSubmitTx`):
49
+ path via `bridge.useBackendSubmitTx`, which still checks tokens locally before handing the deposit to this API):
47
50
 
48
51
  1. [`../integration/knowledge/features/bridge.md`](../integration/knowledge/features/bridge.md) — the on-chain `BridgeService` orchestrator and the `bridge.useBackendSubmitTx` toggle that routes its spoke-deposit through this API with a client-side fallback.
49
52
  2. For the v1 → v2 reshape of the on-chain bridge itself (chain-key routing, `Result<T>`, error unions) → [`../migration-v1-to-v2/knowledge/features/bridge.md`](../migration-v1-to-v2/knowledge/features/bridge.md).
@@ -54,10 +57,12 @@ path via `bridge.useBackendSubmitTx`):
54
57
  2. Every `await sodax.api.bridge.<method>(...)` call site has `if (!result.ok)`.
55
58
  3. `submitTx.relayData` is the full `relayData` object (not `relayData.payload`); `getSubmitTxStatus` passes both `txHash` and `srcChainKey`.
56
59
  4. Bodies use the wire DTO names (`inputToken`/`outputToken`/`inputAmount`/`dstAddress`), mapped from SDK-domain params.
60
+ 5. Submit-tx status polling stops on `'executed'` (with `result.dstIntentTxHash`), `'failed'`, or a set `abandonedAt`.
61
+ 6. Tokens offered to users come from `getTokens()`, and the action is gated on the API bridgeable amount, when the flow must accept tokens newer than the installed SDK.
57
62
 
58
63
  ## Related granular skills (same family)
59
64
 
60
- - [`../bridge/SKILL.md`](../bridge/SKILL.md) — the end-to-end bridge orchestrator (`sodax.bridge`) that wraps these backend calls.
65
+ - [`../bridge/SKILL.md`](../bridge/SKILL.md) — the bridge orchestrator (`sodax.bridge`): it validates tokens locally and uses this API only for submit-tx.
61
66
  - [`../swaps-api/SKILL.md`](../swaps-api/SKILL.md) — the sibling swaps HTTP client this mirrors.
62
67
  - [`../backend-api/SKILL.md`](../backend-api/SKILL.md) — the `sodax.backendApi` read client (intent / orderbook / money-market reads + config).
63
68
 
@@ -11,13 +11,15 @@ DO / DO NOT / workflow / stop conditions for AI agents writing `@sodax/sdk` v2 c
11
11
  grep -rE '@sodax/(sdk|types)' --include='*.ts' --include='*.tsx' src/ # see what's already imported
12
12
  ```
13
13
 
14
- 2. **Always initialize first.** `new Sodax()` constructs the facade; `await sodax.config.initialize()` loads chain/token config from the backend (with packaged-defaults fallback). Skipping `initialize()` works but means stale defaults — `findSupportedTokenBySymbol` may return `undefined` for tokens added after the SDK release.
14
+ 2. **Tokens come from the installed SDK version.** `initialize()` fetches nothing, so `sodax.config` and the feature services know only the tokens bundled with that `@sodax/sdk` release and reject newer ones. For those, use the `sodax.api.*` clients; see [`recipes/initialize-sodax.md`](recipes/initialize-sodax.md) § "Where supported tokens come from".
15
15
  3. **Pick `raw: true` vs `raw: false` explicitly.** Reads and unsigned-tx-building flows take `raw: true` and don't need a wallet. Signed flows take `raw: false` + a chain-narrowed `walletProvider`. The discriminator is mandatory — without it the type system rejects the call. See [`architecture.md`](architecture.md) § 6.
16
16
  4. **Branch on `result.ok` before reading `.value` or `.error`.** Every async public method returns `Promise<Result<T, SodaxError>>`. `try/catch` does **not** catch SDK-level failures — see DO NOT § below.
17
17
  5. **Discriminate errors by `(error.feature, error.code)`.** Use `isSodaxError(e)` first, then switch on the pair. Don't string-match `error.message`.
18
18
 
19
19
  ## DO
20
20
 
21
+ - **DO** confirm an API resolves against the installed `@sodax/sdk` before building on it: these skills track `main`, which can be ahead of your release. If your SDK has no `*WithApproval` helper, use the allowance check, `approve`, then the plain call (`swap` / `bridge` / `vaultSwap`; a vault deposit approves its spoke input token with `sodax.swaps.isAllowanceValid` / `approve`).
22
+
21
23
  - **DO** branch on `result.ok` for every SDK call. Forward sub-`Result`s without re-wrapping (`if (!sub.ok) return sub`).
22
24
  - **DO** use `isSodaxError(e)` over bare `instanceof SodaxError`. Bundle-safe in cross-realm code (mixed ESM/CJS, monorepos with multiple package copies).
23
25
  - **DO** discriminate errors via `(error.feature, error.code)`. The narrow per-method code unions (e.g. `CreateSupplyIntentErrorCode`) enable exhaustive `switch`.
@@ -46,7 +48,7 @@ DO / DO NOT / workflow / stop conditions for AI agents writing `@sodax/sdk` v2 c
46
48
  | Signal | Why stop |
47
49
  |---|---|
48
50
  | User wants a chain not in `ChainKeys.*` | Adding a new chain requires SDK-level changes to `@sodax/types`/`@sodax/sdk` — out of scope for consumer code. |
49
- | User wants to skip `await sodax.config.initialize()` | Explain consequences: stale defaults, no awareness of new tokens / fee parameters. Don't silently skip. |
51
+ | User expects `await sodax.config.initialize()` to load new tokens | Explain that it fetches nothing today; tokens come from the installed SDK. Offer an SDK upgrade or the `sodax.api.*` path. |
50
52
  | User code expects sibling-package imports (e.g. `@sodax/wallet-sdk-core` instances) | Out of scope here — consumer owns the wallet-provider implementation. Document the `I*WalletProvider` shape they need to satisfy or instruct them to install `@sodax/wallet-sdk-core` separately and refer to that package's docs. |
51
53
  | User wants browser-extension wallet wiring inside SDK code | Not the SDK's concern. Consumer owns the wallet layer. |
52
54
 
@@ -70,7 +72,7 @@ grep -rE 'await sodax\.\w+\.\w+\([^)]*\)' src/ | grep -v '\.ok\|\.value\|\.error
70
72
 
71
73
  ## Done criteria
72
74
 
73
- - [ ] `await sodax.config.initialize()` runs at app startup (or before first feature call).
75
+ - [ ] The tokens offered to users come from the list the flow validates against: the installed SDK's lists for `sodax.<feature>.*`, the backend's `getTokens()` for `sodax.api.*`.
74
76
  - [ ] Every `await sodax.<feature>.<method>(...)` is followed by `if (!result.ok)` branching.
75
77
  - [ ] No `try/catch` wraps SDK calls expecting to catch `RELAY_TIMEOUT` / `EXECUTION_FAILED`.
76
78
  - [ ] No `import` from `@sodax/sdk/dist/...`.
@@ -7,7 +7,7 @@ Every v2 design concept the SDK rests on, in a single TOC-navigable file. Read e
7
7
  1. [Hub-and-spoke model](#1-hub-and-spoke-model) — Sonic is the hub; 20 spoke chains route through it.
8
8
  2. [`SpokeService` router](#2-spokeservice-router) — single internal dispatcher; no per-chain provider classes.
9
9
  3. [`Sodax` facade and service graph](#3-sodax-facade-and-service-graph) — one instance owns every feature service.
10
- 4. [`ConfigService`](#4-configservice) — dynamic config from backend with packaged-defaults fallback.
10
+ 4. [`ConfigService`](#4-configservice) — packaged config plus constructor overrides, and the lookups built from it.
11
11
  5. [`ChainKeys` and chain-key narrowing](#5-chainkeys-and-chain-key-narrowing) — `GetChainType<K>`, `GetWalletProviderType<K>`.
12
12
  6. [`WalletProviderSlot<K, Raw>`](#6-walletproviderslotk-raw) — discriminated union for signed vs raw flows.
13
13
  7. [`Result<T, SodaxError<C>>`](#7-resultt-sodaxerrorc) — every async public method returns this.
@@ -117,7 +117,7 @@ The `Sodax` class is the public entry point. It constructs and wires every servi
117
117
 
118
118
  ```ts
119
119
  const sodax = new Sodax(/* optional SodaxOptions */);
120
- await sodax.config.initialize(); // fetch dynamic config; fall back to packaged defaults
120
+ await sodax.config.initialize(); // optional; adds no tokens
121
121
 
122
122
  // All feature services accessed off the instance:
123
123
  await sodax.swaps.createIntent({ params, raw: false, walletProvider });
@@ -139,7 +139,7 @@ Sodax
139
139
  ├── recovery — RecoveryService (withdraw stuck hub-wallet assets)
140
140
  ├── backendApi — BackendApiService (intent lookup, orderbook, money-market reads, config fetching)
141
141
  ├── api — alias for backendApi; `api.swaps` is SwapsApiService (typed Swaps API client)
142
- ├── config — ConfigService (dynamic config; see § 4)
142
+ ├── config — ConfigService (packaged config + overrides; see § 4)
143
143
  ├── hubProvider — HubProvider (hub contract interactions; concrete impl `EvmHubProvider`)
144
144
  └── spoke — SpokeService (per-chain-family router; see § 2)
145
145
  ```
@@ -171,19 +171,19 @@ new Sodax(config?: SodaxOptions): Sodax;
171
171
 
172
172
  > **Not config slots** — `staking`, `migration`, `partner`/`partners`, `recovery` are services on the `Sodax` instance (`sodax.staking`, etc.) but they are **not** configurable via `SodaxConfig`. They run on packaged defaults; per-call params handle customization.
173
173
 
174
- In production, the packaged defaults are sufficient — pass nothing and call `await sodax.config.initialize()` to load fresh data from the backend.
174
+ In production, the packaged defaults are sufficient — pass nothing. They are fixed per SDK release; see § 4 for tokens listed after it.
175
175
 
176
176
  ---
177
177
 
178
178
  ## 4. `ConfigService`
179
179
 
180
- Replaces every static lookup table that v1 exported as a global (`hubAssets`, `moneyMarketSupportedTokens`, `solverSupportedTokens`, `SodaTokens`, etc.). Loads from the backend API on `initialize()`; falls back to packaged defaults from `@sodax/types` if the backend is unreachable.
180
+ Replaces every static lookup table that v1 exported as a global (`hubAssets`, `moneyMarketSupportedTokens`, `solverSupportedTokens`, `SodaTokens`, etc.). Serves the packaged defaults from `@sodax/types` merged with constructor overrides; `initialize()` does not fetch backend config today.
181
181
 
182
182
  ### Lifecycle
183
183
 
184
184
  ```ts
185
185
  const sodax = new Sodax();
186
- await sodax.config.initialize(); // network call + cache; fall back on failure
186
+ await sodax.config.initialize(); // optional; adds no tokens
187
187
 
188
188
  // After init:
189
189
  sodax.config.isValidSpokeChainKey(chainKey);
@@ -198,9 +198,9 @@ sodax.config.getSpokeChainKeyFromIntentRelayChainId(BigInt(...));
198
198
 
199
199
  Every feature service consumes `ConfigService` internally. The data flows through `XToken` (which now carries `vault` and `hubAsset` directly per token) and through service-method wrappers like `sodax.moneyMarket.getSupportedTokens()`.
200
200
 
201
- ### Why dynamic
201
+ ### Tokens newer than the installed SDK
202
202
 
203
- Chain configs (vault addresses, supported tokens, fee parameters) change between SDK releases. Dynamic loading means the SDK can pick up new chains and tokens without a version bump. The packaged defaults are a fallback for offline / sandbox / pre-release conditions.
203
+ `ConfigService` knows only the chains and tokens of the release it shipped with; `initialize()` does not fetch backend config yet. See [`recipes/initialize-sodax.md`](recipes/initialize-sodax.md) § "Where supported tokens come from".
204
204
 
205
205
  ### Custom backend
206
206
 
@@ -87,7 +87,7 @@ You rarely build this DTO yourself: `sodax.swaps.createIntent` takes the token v
87
87
  // `basePath: ''` because a local mock serves `/config/*` at its origin, with no `/be` mount.
88
88
  api: { baseApiConfig: { baseURL: 'http://localhost:4000', basePath: '' } },
89
89
  });
90
- await sodax.config.initialize();
90
+ await sodax.backendApi.getAllConfig();
91
91
  // → http://localhost:4000/config/all
92
92
  ```
93
93