@sodax/skills 2.3.0-rc.1 → 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.
- package/AGENTS.md +6 -4
- package/README.md +3 -2
- package/package.json +1 -1
- package/skills/sodax-build/SKILL.md +1 -0
- package/skills/sodax-build/knowledge/chains-and-assets.md +1 -1
- package/skills/sodax-dapp-kit/auxiliary-services/SKILL.md +1 -1
- package/skills/sodax-dapp-kit/bridge/SKILL.md +1 -0
- package/skills/sodax-dapp-kit/integration/knowledge/ai-rules.md +3 -0
- package/skills/sodax-dapp-kit/integration/knowledge/architecture.md +7 -3
- package/skills/sodax-dapp-kit/integration/knowledge/features/auxiliary-services.md +8 -3
- package/skills/sodax-dapp-kit/integration/knowledge/features/leverage-yield.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/quickstart.md +2 -2
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/setup.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md +1 -1
- package/skills/sodax-dapp-kit/leverage-yield/SKILL.md +2 -1
- package/skills/sodax-dapp-kit/swap/SKILL.md +1 -0
- package/skills/sodax-sdk/SKILL.md +2 -1
- package/skills/sodax-sdk/bridge/SKILL.md +1 -1
- package/skills/sodax-sdk/bridge-api/SKILL.md +13 -8
- package/skills/sodax-sdk/integration/knowledge/ai-rules.md +5 -3
- package/skills/sodax-sdk/integration/knowledge/architecture.md +8 -8
- package/skills/sodax-sdk/integration/knowledge/features/backend-api.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/features/bridge-api.md +43 -7
- package/skills/sodax-sdk/integration/knowledge/features/leverage-yield-api.md +38 -3
- package/skills/sodax-sdk/integration/knowledge/features/leverage-yield.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/features/money-market.md +2 -0
- package/skills/sodax-sdk/integration/knowledge/features/swap.md +10 -2
- package/skills/sodax-sdk/integration/knowledge/features/swaps-api.md +36 -4
- package/skills/sodax-sdk/integration/knowledge/quickstart.md +4 -4
- package/skills/sodax-sdk/integration/knowledge/recipes/initialize-sodax.md +13 -6
- package/skills/sodax-sdk/integration/knowledge/recipes/logging.md +2 -4
- package/skills/sodax-sdk/integration/knowledge/recipes/testing.md +2 -2
- package/skills/sodax-sdk/leverage-yield/SKILL.md +2 -2
- package/skills/sodax-sdk/leverage-yield-api/SKILL.md +12 -10
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/README.md +1 -1
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/architecture.md +3 -3
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/checklist.md +2 -2
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/money-market.md +1 -1
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/recipes.md +1 -1
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/reference/sodax-config.md +1 -1
- package/skills/sodax-sdk/swap/SKILL.md +1 -1
- package/skills/sodax-sdk/swaps-api/SKILL.md +11 -9
- 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
|
-
| **
|
|
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`
|
|
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.
|
|
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
|
@@ -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.
|
|
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:** `
|
|
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.
|
|
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
|
|
244
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
|
@@ -50,7 +50,7 @@ type UseLeverageYieldDepositVars = LeverageYieldSwapDepositParams;
|
|
|
50
50
|
// { vault: Address; srcChainKey; srcAddress; inputToken; inputAmount: bigint;
|
|
51
51
|
// minOutputAmount: bigint; deadline?: bigint; solver?: Address; partnerFee? }
|
|
52
52
|
|
|
53
|
-
// withdraw — lsoda* shares → any token on any chain (hub-wallet sourced)
|
|
53
|
+
// withdraw — lsoda* shares → any token on any chain but Bitcoin (hub-wallet sourced)
|
|
54
54
|
type UseLeverageYieldWithdrawVars = LeverageYieldSwapWithdrawParams;
|
|
55
55
|
// { vault: Address; srcChainKey; srcAddress; dstChainKey; outputToken;
|
|
56
56
|
// inputAmount: bigint; minOutputAmount: bigint; recipient?; deadline?; solver? }
|
|
@@ -61,7 +61,7 @@ export function Providers({ children }: { children: React.ReactNode }) {
|
|
|
61
61
|
|
|
62
62
|
## 3. Initialize the SDK (optional)
|
|
63
63
|
|
|
64
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|---|---|
|
|
@@ -14,11 +14,12 @@ Granular skill for the leverage-yield hooks of `@sodax/dapp-kit` v2. queryKey/mu
|
|
|
14
14
|
## Step 1 — Clarify with user before coding
|
|
15
15
|
|
|
16
16
|
0. **Vault or leverage position?** Ask first — they share the `leverageYield` key namespace and nothing else. A **vault** is one pooled ERC-4626 position at a single target LTV (`useLeverageYield*`). A **leverage position** is the user's own AAVE account, cloned per position (`useLeveragePosition*`, `useOpenLeveragePosition`). `useLeverageYieldPosition` is the **vault's** snapshot — it is not a leverage position. If the answer is positions, jump to Step 1b.
|
|
17
|
-
1. **Deposit or withdraw?** Deposit = any token → `lsoda*` shares (lands in the hub wallet). Withdraw = `lsoda*` shares → any token on any chain.
|
|
17
|
+
1. **Deposit or withdraw?** Deposit = any token → `lsoda*` shares (lands in the hub wallet). Withdraw = `lsoda*` shares → any token on any chain. **Except Bitcoin:** vault swaps refuse it on either side with `VALIDATION_FAILED`.
|
|
18
18
|
2. **Build vs execute.** `useLeverageYieldDeposit` / `useLeverageYieldWithdraw` only *build* a `LeverageYieldSwapPayload`; `useLeverageYieldVaultSwap` *executes* it (create → relay → notify solver). You always need both.
|
|
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. **
|
|
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
|
|
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?**
|
|
21
|
-
|
|
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
|
|
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
|
-
- **
|
|
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
|
|
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. **
|
|
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
|
|
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
|
-
- [ ]
|
|
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) —
|
|
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(); //
|
|
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 (
|
|
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
|
|
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.).
|
|
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(); //
|
|
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
|
-
###
|
|
201
|
+
### Tokens newer than the installed SDK
|
|
202
202
|
|
|
203
|
-
|
|
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.
|
|
90
|
+
await sodax.backendApi.getAllConfig();
|
|
91
91
|
// → http://localhost:4000/config/all
|
|
92
92
|
```
|
|
93
93
|
|