@sodax/skills 2.0.0-rc.8 → 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -0
- package/AGENTS.md +123 -13
- package/README.md +5 -2
- package/package.json +1 -1
- package/skills/sodax-build/SKILL.md +90 -0
- package/skills/sodax-build/knowledge/README.md +35 -0
- package/skills/sodax-build/knowledge/brief-template.md +41 -0
- package/skills/sodax-build/knowledge/chains-and-assets.md +26 -0
- package/skills/sodax-build/knowledge/example-sessions.md +84 -0
- package/skills/sodax-build/knowledge/feature-catalog.md +51 -0
- package/skills/sodax-build/knowledge/glossary.md +35 -0
- package/skills/sodax-build/knowledge/handoff.md +60 -0
- package/skills/sodax-build/knowledge/interview-guide.md +66 -0
- package/skills/sodax-build/knowledge/monetization.md +37 -0
- package/skills/sodax-build/knowledge/use-case-gallery.md +32 -0
- package/skills/sodax-dapp-kit/SKILL.md +6 -2
- package/skills/sodax-dapp-kit/auxiliary-services/SKILL.md +65 -0
- package/skills/sodax-dapp-kit/bitcoin/SKILL.md +57 -0
- package/skills/sodax-dapp-kit/bridge/SKILL.md +59 -0
- package/skills/sodax-dapp-kit/dex/SKILL.md +60 -0
- package/skills/sodax-dapp-kit/integration/knowledge/README.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/features/README.md +3 -2
- package/skills/sodax-dapp-kit/integration/knowledge/features/auxiliary-services.md +71 -11
- package/skills/sodax-dapp-kit/integration/knowledge/features/bitcoin.md +10 -6
- package/skills/sodax-dapp-kit/integration/knowledge/features/dex.md +2 -2
- package/skills/sodax-dapp-kit/integration/knowledge/features/leverage-yield.md +112 -0
- package/skills/sodax-dapp-kit/integration/knowledge/features/migration.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/features/money-market.md +6 -1
- package/skills/sodax-dapp-kit/integration/knowledge/features/swap.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/quickstart.md +2 -2
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/README.md +1 -0
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/backend-queries.md +23 -8
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/bitcoin.md +8 -8
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/leverage-yield.md +168 -0
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/migration.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/setup.md +4 -4
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/swap.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/wallet-connectivity.md +3 -0
- package/skills/sodax-dapp-kit/integration/knowledge/reference/glossary.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md +67 -6
- package/skills/sodax-dapp-kit/integration/knowledge/reference/querykey-conventions.md +49 -0
- package/skills/sodax-dapp-kit/leverage-yield/SKILL.md +54 -0
- package/skills/sodax-dapp-kit/migration/SKILL.md +64 -0
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md +1 -1
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md +2 -2
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/checklist.md +1 -1
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/README.md +1 -1
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/auxiliary-services.md +19 -10
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/bitcoin.md +2 -2
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/bridge.md +1 -1
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/dex.md +1 -1
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/migration.md +1 -1
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/reference/renamed-hooks.md +3 -3
- package/skills/sodax-dapp-kit/money-market/SKILL.md +61 -0
- package/skills/sodax-dapp-kit/staking/SKILL.md +60 -0
- package/skills/sodax-dapp-kit/swap/SKILL.md +64 -0
- package/skills/sodax-sdk/SKILL.md +54 -50
- package/skills/sodax-sdk/backend-api/SKILL.md +58 -0
- package/skills/sodax-sdk/bridge/SKILL.md +53 -0
- package/skills/sodax-sdk/dex/SKILL.md +54 -0
- package/skills/sodax-sdk/integration/knowledge/README.md +5 -3
- package/skills/sodax-sdk/integration/knowledge/ai-rules.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/architecture.md +26 -39
- package/skills/sodax-sdk/integration/knowledge/chain-specifics.md +57 -10
- package/skills/sodax-sdk/integration/knowledge/features/README.md +6 -3
- package/skills/sodax-sdk/integration/knowledge/features/backend-api.md +92 -0
- package/skills/sodax-sdk/integration/knowledge/features/bridge.md +48 -11
- package/skills/sodax-sdk/integration/knowledge/features/dex.md +7 -7
- package/skills/sodax-sdk/integration/knowledge/features/leverage-yield.md +175 -0
- package/skills/sodax-sdk/integration/knowledge/features/{icx-bnusd-baln.md → migration.md} +75 -30
- package/skills/sodax-sdk/integration/knowledge/features/money-market.md +20 -25
- package/skills/sodax-sdk/integration/knowledge/features/partner.md +86 -0
- package/skills/sodax-sdk/integration/knowledge/features/recovery.md +51 -0
- package/skills/sodax-sdk/integration/knowledge/features/staking.md +8 -3
- package/skills/sodax-sdk/integration/knowledge/features/swap.md +106 -22
- package/skills/sodax-sdk/integration/knowledge/features/swaps-api.md +171 -0
- package/skills/sodax-sdk/integration/knowledge/quickstart.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/recipes/README.md +1 -0
- package/skills/sodax-sdk/integration/knowledge/recipes/backend-server-init.md +3 -3
- package/skills/sodax-sdk/integration/knowledge/recipes/gas-estimation.md +8 -4
- package/skills/sodax-sdk/integration/knowledge/recipes/initialize-sodax.md +34 -2
- package/skills/sodax-sdk/integration/knowledge/recipes/logging.md +102 -0
- package/skills/sodax-sdk/integration/knowledge/recipes/raw-tx-flow.md +28 -4
- package/skills/sodax-sdk/integration/knowledge/recipes/result-and-errors.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/recipes/testing.md +7 -11
- package/skills/sodax-sdk/integration/knowledge/reference/README.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/reference/chain-keys.md +40 -4
- package/skills/sodax-sdk/integration/knowledge/reference/error-codes.md +32 -9
- package/skills/sodax-sdk/integration/knowledge/reference/glossary.md +2 -2
- package/skills/sodax-sdk/integration/knowledge/reference/public-api.md +37 -4
- package/skills/sodax-sdk/leverage-yield/SKILL.md +50 -0
- package/skills/sodax-sdk/migration/SKILL.md +69 -0
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/README.md +1 -1
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/ai-rules.md +6 -10
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/architecture.md +2 -2
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/result-and-errors.md +3 -3
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/type-system.md +6 -5
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/checklist.md +2 -2
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/README.md +4 -2
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/backend-api.md +92 -0
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/bridge.md +5 -5
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/dex.md +2 -4
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/{icx-bnusd-baln.md → migration.md} +31 -29
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/money-market.md +2 -2
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/partner.md +64 -0
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/recovery.md +35 -0
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/staking.md +8 -3
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/swap.md +22 -18
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/reference/sodax-config.md +19 -17
- package/skills/sodax-sdk/money-market/SKILL.md +56 -0
- package/skills/sodax-sdk/partner/SKILL.md +55 -0
- package/skills/sodax-sdk/recovery/SKILL.md +53 -0
- package/skills/sodax-sdk/staking/SKILL.md +53 -0
- package/skills/sodax-sdk/swap/SKILL.md +72 -0
- package/skills/sodax-sdk/swaps-api/SKILL.md +62 -0
- package/skills/sodax-wallet-sdk-core/SKILL.md +7 -3
- package/skills/sodax-wallet-sdk-core/bitcoin/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/evm/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/icon/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/injective/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/integration/knowledge/README.md +1 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/ai-rules.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/architecture.md +5 -5
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/bitcoin.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/evm.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/icon.md +5 -5
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/injective.md +4 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/near.md +1 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/solana.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/stacks.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/stellar.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/sui.md +1 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/quickstart.md +1 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/setup-private-key.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/sign-and-broadcast.md +1 -0
- package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/testing.md +1 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/chain-support.md +3 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/interfaces.md +7 -5
- package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/provider-classes.md +2 -2
- package/skills/sodax-wallet-sdk-core/migration-v1-to-v2/knowledge/README.md +1 -1
- package/skills/sodax-wallet-sdk-core/near/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/solana/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/stacks/SKILL.md +53 -0
- package/skills/sodax-wallet-sdk-core/stellar/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/sui/SKILL.md +53 -0
- package/skills/sodax-wallet-sdk-react/SKILL.md +5 -3
- package/skills/sodax-wallet-sdk-react/bridge-to-sdk/SKILL.md +56 -0
- package/skills/sodax-wallet-sdk-react/connect/SKILL.md +59 -0
- package/skills/sodax-wallet-sdk-react/integration/knowledge/architecture.md +3 -3
- package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/chain-detection.md +1 -1
- package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/connect-button.md +1 -1
- package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/sign-message.md +10 -10
- package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/switch-chain.md +1 -1
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/api-surface.md +4 -4
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/chain-support.md +4 -4
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/connectors.md +1 -1
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/hooks.md +5 -4
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/wallet-brands.md +1 -1
- package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/ai-rules.md +1 -1
- package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/recipes/multi-chain-modal.md +57 -31
- package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/recipes/ssr-setup.md +24 -19
- package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/reference/config.md +1 -1
- package/skills/sodax-wallet-sdk-react/sign-message/SKILL.md +51 -0
- package/skills/sodax-wallet-sdk-react/switch-chain/SKILL.md +51 -0
- package/skills/sodax-wallet-sdk-react/wallet-modal/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-react/walletconnect/SKILL.md +52 -0
- package/skills/sodax-sdk/integration/knowledge/features/auxiliary-services.md +0 -189
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/auxiliary-services.md +0 -156
|
@@ -16,7 +16,9 @@ DO / DO NOT / workflow / stop conditions for AI agents porting v1 `@sodax/sdk` c
|
|
|
16
16
|
3. **Apply changes in order: type-level first, runtime second.** Type-level renames don't affect behavior; runtime patterns (Result branching, error model) require thinking. Doing them in the wrong order means the typecheck stays noisy and you can't see the real problems.
|
|
17
17
|
4. **Re-run `pnpm tsc --noEmit` after every step.** Each step should reduce the error count. If errors grow, you've introduced something — back out and try again.
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
> **v2 cross-cutting rules apply too.** Everything in [`integration/ai-rules.md`](../../integration/knowledge/ai-rules.md) (Result branching, `isSodaxError`, `TxHashPair`, `BalnSwapService` throws, package-root imports, no `@sodax/types` peer dep, …) holds when writing migrated code. The DO / DO NOT below are **migration-specific** rules on top.
|
|
20
|
+
|
|
21
|
+
## DO (migration-specific)
|
|
20
22
|
|
|
21
23
|
- **DO** start with mechanical type renames:
|
|
22
24
|
- `*_MAINNET_CHAIN_ID` → `ChainKeys.*` (regex: `(\w+)_MAINNET_CHAIN_ID` → `ChainKeys.$1_MAINNET`).
|
|
@@ -28,18 +30,12 @@ DO / DO NOT / workflow / stop conditions for AI agents porting v1 `@sodax/sdk` c
|
|
|
28
30
|
- **DO** add the `raw: false` (or `raw: true`) discriminator to every signed call shape that previously took `{ intentParams, spokeProvider }`. Also rename `intentParams` → `params` and drop `spokeProvider` in favor of `walletProvider`.
|
|
29
31
|
- **DO** convert v1 `try/catch` to `result.ok` branching last — touching every call site is the biggest commit, easiest to do once the type-level changes settled.
|
|
30
32
|
- **DO** treat the `Result<T>` ↔ `try/catch` migration as the *highest-leverage* change. If you stop early, ensure result branching is at least in place even if the surrounding error UX is rough.
|
|
31
|
-
- **DO** use `isSodaxError(e)` over bare `instanceof SodaxError` in the new error-handling branches. `instanceof` is fragile across bundle copies.
|
|
32
|
-
- **DO** branch on `(error.feature, error.code)` for fine-grained UX. The narrow per-method code unions enable exhaustive `switch`.
|
|
33
33
|
|
|
34
|
-
## DO NOT
|
|
34
|
+
## DO NOT (migration-specific)
|
|
35
35
|
|
|
36
|
-
- **DO NOT** grep-replace `srcChain` → `srcChainKey` blindly. The `Intent` *read* shape (returned from `createIntent` / `getIntentByHash` / etc.) keeps `srcChain` and `dstChain` as `IntentRelayChainId` (bigint) — those did **not** rename. Only **request** types changed (`CreateIntentParams`, `CreateLimitOrderParams`, `
|
|
36
|
+
- **DO NOT** grep-replace `srcChain` → `srcChainKey` blindly. The `Intent` *read* shape (returned from `createIntent` / `getIntentByHash` / etc.) keeps `srcChain` and `dstChain` as `IntentRelayChainId` (bigint) — those did **not** rename. Only **request** types changed (`CreateIntentParams`, `CreateLimitOrderParams`, `SubmitTxRequestV2`).
|
|
37
37
|
- **DO NOT** treat `instanceof MoneyMarketError` (or any other module-error class) as still working. Those classes are deleted. Replace with `isSodaxError(e) && e.feature === 'moneyMarket'`.
|
|
38
|
-
- **DO NOT**
|
|
39
|
-
- **DO NOT** assume `BalnSwapService` lock-management methods (`stake`, `unstake`, `claim`, `claimUnstaked`, `cancelUnstake`, `getDetailedUserLocks`) return `Result<T>`. They still throw — known carve-out. Keep `try/catch` for those specific calls.
|
|
40
|
-
- **DO NOT** keep `try/catch` blocks expecting them to catch SDK-level failures from non-Baln methods. v2 mutation methods resolve `{ ok: false, error }` rather than throwing — `catch` only fires for synchronous wrapper exceptions (e.g. missing `walletProvider`).
|
|
41
|
-
- **DO NOT** call `getStakingInfo(hubAddress)` in v2. It's `getStakingInfoFromSpoke(srcAddress, srcChainKey)` now. `getStakingInfo` is not a public method.
|
|
42
|
-
- **DO NOT** import `@sodax/types` as a peer dependency. It's bundled into `@sodax/sdk`'s public surface; declaring it separately invites version skew.
|
|
38
|
+
- **DO NOT** pass v1 spoke-side state into `getStakingInfo(hubAddress)`. The method is still public in v2 but expects a *hub* address. v1 call sites that used `spokeProvider`-derived data should switch to `getStakingInfoFromSpoke(srcAddress, srcChainKey)` which derives the hub wallet internally.
|
|
43
39
|
- **DO NOT** keep `try { await sodax.swaps.createIntent(...) } catch` and expect to inspect `e.code === 'CREATE_INTENT_FAILED'`. The v2 code is `INTENT_CREATION_FAILED` and lives on `result.error.code` (Result branch), not on a thrown error. See [`reference/error-code-crosswalk.md`](reference/error-code-crosswalk.md) for the full v1 → v2 code crosswalk.
|
|
44
40
|
|
|
45
41
|
## Stop conditions (defer to user)
|
|
@@ -175,8 +175,8 @@ If you pass a config override to `new Sodax({ ... })`, put solver endpoints in `
|
|
|
175
175
|
|
|
176
176
|
v1 had per-feature relay helpers (each feature module had its own `*WaitForRelay()` or `relay*Tx()` function). v2 centralises this into `IntentRelayApiService` with two public entry points:
|
|
177
177
|
|
|
178
|
-
- `submitTransaction(
|
|
179
|
-
- `relayTxAndWaitPacket({
|
|
178
|
+
- `submitTransaction(payload, apiUrl)` — TWO positional args (`payload: IntentRelayRequest<'submit'>`, `apiUrl: HttpUrl`), not an options object. POSTs the spoke transaction to the relay submit endpoint and resolves the relay's first-stage acknowledgement.
|
|
179
|
+
- `relayTxAndWaitPacket({ srcTxHash, data, chainKey, relayerApiEndpoint, timeout, pollTxHash? })` — `RelayAndWaitParams`: `data` is the whole `RelayExtraData` / `OnDemandRelayData` object, `chainKey` is the source `SpokeChainKey`. Runs `submitTransaction` and then polls until the destination packet reaches `executed`. Resolves with `{ srcTxHash, dstTxHash, packet }` on success.
|
|
180
180
|
|
|
181
181
|
Internally, every feature service now calls `relayTxAndWaitPacket` for the spoke→hub leg. Failures from this layer surface to consumers via `mapRelayFailure`.
|
|
182
182
|
|
|
@@ -45,7 +45,7 @@ The **complete list** of services whose public methods return `Result<T>`:
|
|
|
45
45
|
- `RecoveryService`
|
|
46
46
|
- `BackendApiService`
|
|
47
47
|
- `SpokeService` (router-level helpers)
|
|
48
|
-
- `
|
|
48
|
+
- `IConfigApiV1` implementations (every method)
|
|
49
49
|
|
|
50
50
|
Private helpers may still throw; the outer `try/catch` at each public method's boundary absorbs those and converts them to `{ ok: false, error }`.
|
|
51
51
|
|
|
@@ -126,7 +126,7 @@ A `try { await sodax.<method>(...) } catch` block in v2 only catches **exception
|
|
|
126
126
|
```ts
|
|
127
127
|
class SodaxError<C extends SodaxErrorCode = SodaxErrorCode> extends Error {
|
|
128
128
|
readonly code: C; // closed 13-code reason union
|
|
129
|
-
readonly feature: SodaxFeature; // 'swap' | 'moneyMarket' | 'bridge' | 'staking' | 'migration' | 'dex' | 'partner' | 'recovery'
|
|
129
|
+
readonly feature: SodaxFeature; // 'swap' | 'moneyMarket' | 'bridge' | 'staking' | 'migration' | 'dex' | 'partner' | 'recovery' | 'backend' | 'leverageYield'
|
|
130
130
|
readonly cause?: unknown;
|
|
131
131
|
readonly context?: SodaxErrorContext;
|
|
132
132
|
|
|
@@ -216,7 +216,7 @@ Every public method declares a `<MethodName>ErrorCode` narrow union built via `E
|
|
|
216
216
|
```ts
|
|
217
217
|
type CreateSupplyIntentErrorCode = Extract<
|
|
218
218
|
SodaxErrorCode,
|
|
219
|
-
'VALIDATION_FAILED' | 'INTENT_CREATION_FAILED' | 'UNKNOWN'
|
|
219
|
+
'USER_REJECTED' | 'VALIDATION_FAILED' | 'INTENT_CREATION_FAILED' | 'UNKNOWN'
|
|
220
220
|
>;
|
|
221
221
|
|
|
222
222
|
// In the queryFn or call site:
|
|
@@ -11,7 +11,7 @@ Every type-level rename and shape change introduced by v2. Fix these first — o
|
|
|
11
11
|
3. [Wallet-provider typing](#3-wallet-provider-typing) — `GetWalletProviderType<K>` and `WalletProviderSlot<K, Raw>` replace ad-hoc spoke-provider classes.
|
|
12
12
|
4. [`Token` / `XToken` field renames](#4-token--xtoken-field-renames) — `xChainId` → `chainKey`; `Token` → `XToken`.
|
|
13
13
|
5. [`RpcConfig` reshape](#5-rpcconfig-reshape) — now keyed by `ChainKey` values; chain-family-specific shapes for Bitcoin and Stellar.
|
|
14
|
-
6. [`
|
|
14
|
+
6. [`IConfigApiV1` Result-wrapping](#6-iconfigapiv1-result-wrapping) — every method returns `Promise<Result<T>>`.
|
|
15
15
|
7. [Address-type rename](#7-address-type-rename) — `AddressType` → `BtcAddressType`.
|
|
16
16
|
8. [Wallet-provider `chainType` discriminant](#8-wallet-provider-chaintype-discriminant) — every `I*WalletProvider` declares a literal field.
|
|
17
17
|
9. [`ChainId` / `SpokeChainId` → `SpokeChainKey`](#9-chainid--spokechainid--spokechainkey) — type alias rename.
|
|
@@ -47,6 +47,7 @@ v1 exported one constant per chain (`SONIC_MAINNET_CHAIN_ID`, `ARBITRUM_MAINNET_
|
|
|
47
47
|
| `BASE_MAINNET_CHAIN_ID` | `ChainKeys.BASE_MAINNET` | `'0x2105.base'` |
|
|
48
48
|
| `BSC_MAINNET_CHAIN_ID` | `ChainKeys.BSC_MAINNET` | `'0x38.bsc'` |
|
|
49
49
|
| `ETHEREUM_MAINNET_CHAIN_ID` | `ChainKeys.ETHEREUM_MAINNET` | `'ethereum'` |
|
|
50
|
+
| `HEDERA_MAINNET_CHAIN_ID` | `ChainKeys.HEDERA_MAINNET` | `'hedera'` |
|
|
50
51
|
| `HYPEREVM_MAINNET_CHAIN_ID` | `ChainKeys.HYPEREVM_MAINNET` | `'hyper'` |
|
|
51
52
|
| `ICON_MAINNET_CHAIN_ID` | `ChainKeys.ICON_MAINNET` | `'0x1.icon'` |
|
|
52
53
|
| `INJECTIVE_MAINNET_CHAIN_ID` | `ChainKeys.INJECTIVE_MAINNET` | `'injective-1'` |
|
|
@@ -192,7 +193,7 @@ v1 consumers reached into a global `hubAssets[chainId][address]` map to get the
|
|
|
192
193
|
|
|
193
194
|
### Pitfall
|
|
194
195
|
|
|
195
|
-
Read shapes like `Intent` and `IntentResponse` from the backend keep `srcChain` / `dstChain` as the **relay** chain id (numeric, `IntentRelayChainId`). They are **not** chain keys and were **not** renamed to `srcChainKey`/`dstChainKey`. Only **request** types (`CreateIntentParams`, `CreateLimitOrderParams`, `
|
|
196
|
+
Read shapes like `Intent` and `IntentResponse` from the backend keep `srcChain` / `dstChain` as the **relay** chain id (numeric, `IntentRelayChainId`). They are **not** chain keys and were **not** renamed to `srcChainKey`/`dstChainKey`. Only **request** types (`CreateIntentParams`, `CreateLimitOrderParams`, `SubmitTxRequestV2`) gained the `*ChainKey` field names.
|
|
196
197
|
|
|
197
198
|
### Exception — partner module read shapes DID rename
|
|
198
199
|
|
|
@@ -244,9 +245,9 @@ Bitcoin and Stellar have richer RPC needs than other chains (multiple endpoints,
|
|
|
244
245
|
|
|
245
246
|
---
|
|
246
247
|
|
|
247
|
-
## 6. `
|
|
248
|
+
## 6. `IConfigApiV1` Result-wrapping
|
|
248
249
|
|
|
249
|
-
Every method on the `
|
|
250
|
+
Every method on the `IConfigApiV1` contract changed signature in v2. v1 returned plain `Promise<T>` and threw on failure; v2 returns `Promise<Result<T>>` and never throws.
|
|
250
251
|
|
|
251
252
|
| Method | v1 return | v2 return |
|
|
252
253
|
|---|---|---|
|
|
@@ -257,7 +258,7 @@ Every method on the `IConfigApi` contract changed signature in v2. v1 returned p
|
|
|
257
258
|
| `getMoneyMarketTokensByChainId` | `Promise<XToken[]>` | `Promise<Result<XToken[]>>` |
|
|
258
259
|
| `getRelayChainIdMap` | (n/a in v1) | `Promise<Result<GetRelayChainIdMapApiResponse>>` (v2-new) |
|
|
259
260
|
|
|
260
|
-
If you implemented a custom `
|
|
261
|
+
If you implemented a custom `IConfigApiV1` (e.g. for a sandbox or test fixture), update every method signature. If you only consumed the default implementation through `Sodax.config`, the SDK already uses `Result` internally — your consumer-side code doesn't see the wrapping.
|
|
261
262
|
|
|
262
263
|
---
|
|
263
264
|
|
|
@@ -46,7 +46,7 @@ Work this top-down. Each step is independent enough to land as its own commit; t
|
|
|
46
46
|
the v2 shape is { tx, intent, relayData }. Stop destructuring tx-pair
|
|
47
47
|
results as arrays — every cross-chain mutation returns
|
|
48
48
|
TxHashPair = { srcChainTxHash, dstChainTxHash }.
|
|
49
|
-
[ ] 15. For every backend-API call site: every method on
|
|
49
|
+
[ ] 15. For every backend-API call site: every method on IConfigApiV1 now returns
|
|
50
50
|
Promise<Result<T>>. Wrap or unwrap accordingly.
|
|
51
51
|
[ ] 16. (Optional) Adopt isSodaxError(e) over instanceof SodaxError in cross-bundle
|
|
52
52
|
/ cross-realm contexts.
|
|
@@ -63,5 +63,5 @@ After items 1–17 land, the typecheck should be clean. The remaining work is pe
|
|
|
63
63
|
- Items 5–6, 11–12: [`breaking-changes/architecture.md`](breaking-changes/architecture.md).
|
|
64
64
|
- Items 7–8, 13: [`breaking-changes/architecture.md`](breaking-changes/architecture.md) § "WalletProviderSlot" + per-feature files.
|
|
65
65
|
- Items 9–10, 14, 16: [`breaking-changes/result-and-errors.md`](breaking-changes/result-and-errors.md).
|
|
66
|
-
- Item 15: [`features/
|
|
66
|
+
- Item 15: [`features/backend-api.md`](features/backend-api.md).
|
|
67
67
|
- Item 17 + the long tail: [`features/`](features/), one per feature you use.
|
|
@@ -9,8 +9,10 @@ One file per feature, paired with the v2 design counterpart in [`features/`](../
|
|
|
9
9
|
| Staking | [`staking.md`](staking.md) |
|
|
10
10
|
| Bridge | [`bridge.md`](bridge.md) |
|
|
11
11
|
| DEX | [`dex.md`](dex.md) |
|
|
12
|
-
| ICX/bnUSD/BALN | [`
|
|
13
|
-
|
|
|
12
|
+
| ICX/bnUSD/BALN | [`migration.md`](migration.md) |
|
|
13
|
+
| Partner | [`partner.md`](partner.md) — standard pattern; 5 v1 typed errors collapse into `SodaxError<C>` with `feature: 'partner'`. |
|
|
14
|
+
| Recovery | [`recovery.md`](recovery.md) — new in v2; no v1 equivalent. |
|
|
15
|
+
| Backend API | [`backend-api.md`](backend-api.md) — load-bearing change: every method now returns `Promise<Result<T>>`. |
|
|
14
16
|
|
|
15
17
|
## Reading order within a feature
|
|
16
18
|
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
# Backend API migration — v1 → v2
|
|
2
|
+
|
|
3
|
+
Pure-SDK migration playbook for `BackendApiService`. The load-bearing v1 → v2 change here is **`Result`-wrapping every method**.
|
|
4
|
+
|
|
5
|
+
Pair: [`features/backend-api.md`](../../../integration/knowledge/features/backend-api.md).
|
|
6
|
+
|
|
7
|
+
## TL;DR
|
|
8
|
+
|
|
9
|
+
1. **Every method now returns `Promise<Result<T>>`** (v1 returned plain `Promise<T>` and threw on failure). `IConfigApiV1` implementations must update method signatures.
|
|
10
|
+
2. **Swap-tx submission moved off `BackendApiService` onto the swaps API client** — `sodax.backendApi.submitSwapTx` is now `sodax.api.swaps.submitTx` (request `SubmitTxRequestV2`, response `SubmitTxResponseV2`). The request renamed `srcChainId` → `srcChainKey`, and `relayData` is a `string` (`relayData.payload`), not the `RelayExtraData` object. (Cross-cutting detail; covered in detail in [`swap.md`](swap.md).)
|
|
11
|
+
|
|
12
|
+
## Type / symbol cheat sheet
|
|
13
|
+
|
|
14
|
+
| Method | v1 return | v2 return |
|
|
15
|
+
|---|---|---|
|
|
16
|
+
| `submitSwapTx` → `sodax.api.swaps.submitTx` | `Promise<SubmitSwapTxResponse>` | `Promise<Result<SubmitTxResponseV2>>` |
|
|
17
|
+
| `getIntentByHash` | `Promise<IntentResponse>` | `Promise<Result<IntentResponse>>` |
|
|
18
|
+
| `getIntentByTxHash` | (n/a in v1) | `Promise<Result<IntentResponse>>` (v2-new) |
|
|
19
|
+
| `getOrderbook` (was `getSolverOrderbook`) | `Promise<OrderbookResponse>` | `Promise<Result<OrderbookResponse>>` (object `{ total, data: Array<{ intentState, intentData }> }`, not an array) |
|
|
20
|
+
| `getUserIntents` (was `getUserSwapHistory`) | `Promise<UserIntentsResponse>` | `Promise<Result<UserIntentsResponse>>` (`{ total, offset, limit, items: IntentResponse[] }` — intents under `.items`) |
|
|
21
|
+
| `getChains` | `Promise<ChainConfig[]>` | `Promise<Result<GetChainsApiResponse>>` |
|
|
22
|
+
| `getSwapTokens` | `Promise<SwapTokenConfig>` | `Promise<Result<GetSwapTokensApiResponse>>` |
|
|
23
|
+
| `getSwapTokensByChainId` | `Promise<XToken[]>` | `Promise<Result<XToken[]>>` |
|
|
24
|
+
| `getMoneyMarketTokens` | `Promise<MMTokenConfig>` | `Promise<Result<GetMoneyMarketTokensApiResponse>>` |
|
|
25
|
+
| `getMoneyMarketTokensByChainId` | `Promise<XToken[]>` | `Promise<Result<XToken[]>>` |
|
|
26
|
+
| `srcChainId` → `srcChainKey` (`SubmitTxRequestV2`) | numeric chain id | `srcChainKey` (spoke chain key string) |
|
|
27
|
+
| `relayData` (`SubmitTxRequestV2`) | `RelayExtraData` object | now `string` (use `relayData.payload`) |
|
|
28
|
+
|
|
29
|
+
## Per-method delta
|
|
30
|
+
|
|
31
|
+
```diff
|
|
32
|
+
- const response: SubmitSwapTxResponse = await sodax.backendApi.submitSwapTx(request);
|
|
33
|
+
- // throws on failure
|
|
34
|
+
+ const result = await sodax.api.swaps.submitTx({ // moved off BackendApiService
|
|
35
|
+
+ txHash: spokeTxHash as string,
|
|
36
|
+
+ srcChainKey: src.chain, // was: srcChainId
|
|
37
|
+
+ walletAddress: '0x…',
|
|
38
|
+
+ intent, // IntentRequestV2 (was: SwapIntentData)
|
|
39
|
+
+ relayData: relayData.payload, // was: relayData (object)
|
|
40
|
+
+ });
|
|
41
|
+
+ if (!result.ok) {
|
|
42
|
+
+ // result.error: SodaxError with feature: 'backend', context.api: 'swaps'
|
|
43
|
+
+ return;
|
|
44
|
+
+ }
|
|
45
|
+
+ const response = result.value; // SubmitTxResponseV2
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Custom `IConfigApiV1` (sandbox / test fixtures)
|
|
49
|
+
|
|
50
|
+
If you implemented `IConfigApiV1` for a sandbox or test fixture, two things changed in v2:
|
|
51
|
+
|
|
52
|
+
**1. Method signatures.** Every method now returns `Promise<Result<T>>` instead of throwing on failure:
|
|
53
|
+
|
|
54
|
+
```diff
|
|
55
|
+
const sandboxApi: IConfigApiV1 = {
|
|
56
|
+
- async getChains(): Promise<ChainConfig[]> {
|
|
57
|
+
- return [/* fixture */];
|
|
58
|
+
- },
|
|
59
|
+
- async getSwapTokens(): Promise<SwapTokenConfig> { /* … */ },
|
|
60
|
+
+ async getChains(): Promise<Result<readonly SpokeChainKey[]>> {
|
|
61
|
+
+ return { ok: true, value: [/* fixture: chain KEYS, not configs */] };
|
|
62
|
+
+ },
|
|
63
|
+
+ async getSwapTokens(): Promise<Result<Record<SpokeChainKey, readonly XToken[]>>> { /* … */ },
|
|
64
|
+
// …5 methods total
|
|
65
|
+
};
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
**2. Injection mechanism.** `SodaxConfig` does NOT expose a typed slot to inject a custom `IConfigApiV1` at construction. v1 patterns that passed a custom api into `new Sodax(...)` no longer typecheck. Point at a local mock via `SodaxConfig.api.baseURL`, or inject your own `BackendApiService`-compatible mock at the app layer. See [`../../../integration/knowledge/architecture.md`](../../../integration/knowledge/architecture.md) § 4 "Custom backend" for the v2 pattern.
|
|
69
|
+
|
|
70
|
+
## Pitfalls
|
|
71
|
+
|
|
72
|
+
1. **`SubmitTxRequestV2.relayData` is `string`, not the `RelayExtraData` object.** v1 took the object; v2 takes the `payload` field as a string.
|
|
73
|
+
2. **Backend + swaps-API errors both carry `feature: 'backend'`** with `context.endpoint`, but the `error.context.api` differs by client: `'backend'` for `BackendApiService` reads, `'swaps'` for `SwapsApiService` (`sodax.api.swaps`) calls. The domain feature tags (`'swap'`, `'moneyMarket'`, …) come from the on-chain feature services, not the HTTP clients. Use `(feature, context.api)` for logger tag pairs.
|
|
74
|
+
3. **Custom `IConfigApiV1` implementations must return `Result<T>`** — old throw-on-error implementations will compile-error against the v2 interface.
|
|
75
|
+
|
|
76
|
+
## Verification
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
pnpm -C <your-app-dir> checkTs
|
|
80
|
+
|
|
81
|
+
# Targeted scans:
|
|
82
|
+
grep -rE "srcChainId:\s*\w+|\.relayData(?!\s*\.payload)" src/ # legacy field name + non-string relayData
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
## Cross-references
|
|
86
|
+
|
|
87
|
+
- v2 backend API usage: [`features/backend-api.md`](../../../integration/knowledge/features/backend-api.md).
|
|
88
|
+
- submit-tx flow with `createIntent` upstream: [`./swap.md`](swap.md) (the swap migration covers the request-shape changes in detail).
|
|
89
|
+
- Partner migration (separate service): [`./partner.md`](partner.md).
|
|
90
|
+
- Recovery migration (separate service, new in v2): [`./recovery.md`](recovery.md).
|
|
91
|
+
- Result/error model: [`../breaking-changes/result-and-errors.md`](../breaking-changes/result-and-errors.md).
|
|
92
|
+
- `IConfigApiV1` Result-wrapping cross-cutting note: [`../breaking-changes/type-system.md`](../breaking-changes/type-system.md) § 6.
|
|
@@ -7,9 +7,9 @@ Pair: [`features/bridge.md`](../../../integration/knowledge/features/bridge.md).
|
|
|
7
7
|
## TL;DR
|
|
8
8
|
|
|
9
9
|
1. **Drop `spokeProvider`. Pass `walletProvider` directly.**
|
|
10
|
-
2. **Add `srcChainKey` + `srcAddress` to `
|
|
10
|
+
2. **Add `srcChainKey` + `srcAddress` to `CreateBridgeIntentParams<K>`.** Generic added.
|
|
11
11
|
3. **`bridge()` returns `Result<TxHashPair>`.** v1 returned a single `string` tx hash; v2 returns `{ srcChainTxHash, dstChainTxHash }` (the spoke + hub tx hashes) wrapped in `Result`.
|
|
12
|
-
4. **`createBridgeIntent()` is spoke-only — no relay.** Same shape as the swap `createIntent`: returns `{ tx,
|
|
12
|
+
4. **`createBridgeIntent()` is spoke-only — no relay.** Same shape as the swap `createIntent`: returns `IntentTxResult<K, Raw> = { tx, relayData }` for the spoke transaction. Useful when you need manual relay control.
|
|
13
13
|
5. **Read methods reshaped.** `getBridgeableAmount` returns `Promise<Result<BridgeLimit>>` (was `Promise<bigint>`) and now takes two `XToken` objects. `getBridgeableTokens` is synchronous (was async) and takes `(from, to, token)`.
|
|
14
14
|
6. **Errors → `SodaxError` + `Result<T>`.** v1's `BridgeError<BridgeErrorCode>` is gone.
|
|
15
15
|
|
|
@@ -72,7 +72,7 @@ Pair: [`features/bridge.md`](../../../integration/knowledge/features/bridge.md).
|
|
|
72
72
|
- await sodax.bridge.createBridgeIntent({ params, spokeProvider });
|
|
73
73
|
+ const result = await sodax.bridge.createBridgeIntent({ params, raw: false, walletProvider });
|
|
74
74
|
+ if (!result.ok) return;
|
|
75
|
-
+ const { tx,
|
|
75
|
+
+ const { tx, relayData } = result.value;
|
|
76
76
|
+ // Submit relayData.payload via your custom relay if needed.
|
|
77
77
|
```
|
|
78
78
|
|
|
@@ -92,13 +92,13 @@ Standard pattern:
|
|
|
92
92
|
|
|
93
93
|
```ts
|
|
94
94
|
await sodax.bridge.approve({
|
|
95
|
-
params: { srcChainKey, srcAddress,
|
|
95
|
+
params: { srcChainKey, srcAddress, srcToken, amount },
|
|
96
96
|
raw: false,
|
|
97
97
|
walletProvider,
|
|
98
98
|
});
|
|
99
99
|
|
|
100
100
|
const allowed = await sodax.bridge.isAllowanceValid({
|
|
101
|
-
params: { srcChainKey, srcAddress,
|
|
101
|
+
params: { srcChainKey, srcAddress, srcToken, amount },
|
|
102
102
|
raw: true, // read-only
|
|
103
103
|
});
|
|
104
104
|
```
|
|
@@ -66,14 +66,12 @@ Pair: [`features/dex.md`](../../../integration/knowledge/features/dex.md).
|
|
|
66
66
|
|
|
67
67
|
### `supplyLiquidity` (mint new) and `increaseLiquidity` (existing)
|
|
68
68
|
|
|
69
|
-
|
|
69
|
+
An `@sodax/sdk` consumer builds the `ClSupplyParams` object directly — there is no SDK-side params helper. (The `createSupplyLiquidityParamsProps` convenience helper lives only in `@sodax/dapp-kit`; don't import it from `@sodax/sdk`.) Construct the object inline and add `srcChainKey`/`srcAddress`:
|
|
70
70
|
|
|
71
71
|
```diff
|
|
72
|
-
- const params = createSupplyLiquidityParamsProps({ /* … */ });
|
|
73
72
|
- await sodax.dex.clService.supplyLiquidity({ params, spokeProvider });
|
|
74
|
-
+ const helperOutput = createSupplyLiquidityParamsProps({ /* … */ });
|
|
75
73
|
+ const srcAddress = (await walletProvider.getWalletAddress()) as `0x${string}`;
|
|
76
|
-
+ const params = {
|
|
74
|
+
+ const params = { srcChainKey, srcAddress, poolKey, tickLower, tickUpper, liquidity, amount0Max, amount1Max, sqrtPriceX96 };
|
|
77
75
|
+ const result = await sodax.dex.clService.supplyLiquidity({ params, raw: false, walletProvider });
|
|
78
76
|
+ if (!result.ok) return;
|
|
79
77
|
+ const { dstChainTxHash } = result.value;
|
package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/{icx-bnusd-baln.md → migration.md}
RENAMED
|
@@ -2,14 +2,14 @@
|
|
|
2
2
|
|
|
3
3
|
Pure-SDK migration playbook for `MigrationService` (the SDK module — not v1→v2 SDK porting).
|
|
4
4
|
|
|
5
|
-
Pair: [`features/
|
|
5
|
+
Pair: [`features/migration.md`](../../../integration/knowledge/features/migration.md).
|
|
6
6
|
|
|
7
7
|
## TL;DR
|
|
8
8
|
|
|
9
9
|
1. **Drop `spokeProvider`. Pass `walletProvider` directly.**
|
|
10
|
-
2. **Add `srcChainKey` + `srcAddress` to every action params.**
|
|
10
|
+
2. **Add `srcChainKey` + `srcAddress` to every action params.** The concrete migration param types are `IcxMigrateParams`, `UnifiedBnUSDMigrateParams<K>`, `IcxCreateRevertMigrationParams`, and `BalnMigrateParams`. Only `UnifiedBnUSDMigrateParams` is generic over `<K>`; the ICX and BALN types are **non-generic**. `MigrationParams<K>` is a **union** of these concrete types, not a base record.
|
|
11
11
|
3. **All 4 orchestrator methods return `Result<TxHashPair>`.** v1 returned a string tx hash and threw on error.
|
|
12
|
-
4. **`migratebnUSD` carries `direction` on error context** — `'forward'` (legacy → new) or `'reverse'` (new → legacy). The SDK detects direction from `(
|
|
12
|
+
4. **`migratebnUSD` carries `direction` on error context** — `'forward'` (legacy → new) or `'reverse'` (new → legacy). The SDK detects direction from `(srcbnUSD, dstbnUSD)` addresses.
|
|
13
13
|
5. **`BalnSwapService` lock-management methods STILL THROW.** `claim`, `claimUnstaked`, `stake`, `unstake`, `cancelUnstake`, `getDetailedUserLocks` — these 6 methods preserve the v1 throw-on-error contract. Wrap in `try/catch` until a future cleanup release converts them to `Result`.
|
|
14
14
|
6. **Errors → `SodaxError` + `Result<T>`.** v1's `MigrationError<MigrationErrorCode>` is gone.
|
|
15
15
|
|
|
@@ -19,9 +19,9 @@ Pair: [`features/icx-bnusd-baln.md`](../../../integration/knowledge/features/icx
|
|
|
19
19
|
|
|
20
20
|
| Type | v1 shape | v2 shape | Notes |
|
|
21
21
|
|---|---|---|---|
|
|
22
|
-
| `MigrationParams` | non-generic | `MigrationParams<K extends SpokeChainKey>`
|
|
23
|
-
| `UnifiedBnUSDMigrateParams` | non-generic | `UnifiedBnUSDMigrateParams<K>`
|
|
24
|
-
| `BalnSwapParams` | `{ amount, lockPeriodMonths }` | `
|
|
22
|
+
| `MigrationParams` | non-generic | `MigrationParams<K extends SpokeChainKey>` = union of `IcxMigrateParams \| UnifiedBnUSDMigrateParams<K> \| BalnMigrateParams` | Now a **union** of the concrete param types, not a base record. |
|
|
23
|
+
| `UnifiedBnUSDMigrateParams` | non-generic | `UnifiedBnUSDMigrateParams<K>` with `srcChainKey`, `srcAddress`, `srcbnUSD`, `dstChainKey`, `dstbnUSD`, `amount`, `dstAddress` (bnUSD fields typed `string`) | Generic added; bnUSD fields are `srcbnUSD`/`dstbnUSD`, and `dstChainKey` is required. |
|
|
24
|
+
| `BalnMigrateParams` (was `BalnSwapParams`) | `{ amount, lockPeriodMonths }` | `{ srcChainKey, srcAddress, amount, lockupPeriod: LockupPeriod, dstAddress, stake }` (**non-generic**) | Renamed; `lockupPeriod` is a `LockupPeriod` enum (seconds), `stake: boolean` required. |
|
|
25
25
|
|
|
26
26
|
### Deleted symbols
|
|
27
27
|
|
|
@@ -50,12 +50,13 @@ Pair: [`features/icx-bnusd-baln.md`](../../../integration/knowledge/features/icx
|
|
|
50
50
|
- await sodax.migration.migrateBnUSDForward({ amount, /* … */ }, spokeProvider);
|
|
51
51
|
- await sodax.migration.migrateBnUSDReverse({ amount, /* … */ }, spokeProvider);
|
|
52
52
|
|
|
53
|
-
+ // v2 has one method; SDK detects direction from (
|
|
53
|
+
+ // v2 has one method; SDK detects direction from (srcbnUSD, dstbnUSD):
|
|
54
54
|
+ const result = await sodax.migration.migratebnUSD({
|
|
55
55
|
+ params: {
|
|
56
56
|
+ srcChainKey, srcAddress,
|
|
57
|
-
+
|
|
58
|
-
+
|
|
57
|
+
+ srcbnUSD, // legacy or new bnUSD
|
|
58
|
+
+ dstChainKey, // required
|
|
59
|
+
+ dstbnUSD, // the other one
|
|
59
60
|
+ amount,
|
|
60
61
|
+ dstAddress,
|
|
61
62
|
+ },
|
|
@@ -83,24 +84,24 @@ Standard pattern:
|
|
|
83
84
|
+ const { srcChainTxHash, dstChainTxHash } = result.value;
|
|
84
85
|
```
|
|
85
86
|
|
|
86
|
-
`migrateBaln` adds `
|
|
87
|
+
`migrateBaln` adds `lockupPeriod: LockupPeriod` (a `LockupPeriod` enum measured in **seconds**: `NO_LOCKUP` / `SIX_MONTHS` / `TWELVE_MONTHS` / `EIGHTEEN_MONTHS` / `TWENTY_FOUR_MONTHS` → 0/6/12/18/24 months) plus a required `stake: boolean` to the params. Reward multiplier ranges 0.5x (`NO_LOCKUP`) – 1.5x (`TWENTY_FOUR_MONTHS`).
|
|
87
88
|
|
|
88
89
|
### Approve / allowance — action-discriminated
|
|
89
90
|
|
|
91
|
+
`action` is the **second positional argument**, typed `MigrationAction = 'migrate' | 'revert'` — not a field inside `params`:
|
|
92
|
+
|
|
90
93
|
```ts
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
raw: false,
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
raw: true, // read-only
|
|
100
|
-
});
|
|
94
|
+
// approve: action-wrapped params, then the action arg
|
|
95
|
+
await sodax.migration.approve(
|
|
96
|
+
{ params, raw: false, walletProvider },
|
|
97
|
+
'migrate', // or 'revert'
|
|
98
|
+
);
|
|
99
|
+
|
|
100
|
+
// isAllowanceValid: BARE migration params (no wrapper, NOT Raw-generic, no `raw` flag) + action arg
|
|
101
|
+
const allowed = await sodax.migration.isAllowanceValid(params, 'migrate');
|
|
101
102
|
```
|
|
102
103
|
|
|
103
|
-
### `getAvailableAmount` (
|
|
104
|
+
### `getAvailableAmount` (total available SODA liquidity in the migration contract)
|
|
104
105
|
|
|
105
106
|
```diff
|
|
106
107
|
- const amount: bigint = await sodax.migration.icx.getAvailableAmount(spokeProvider);
|
|
@@ -114,11 +115,12 @@ const allowed = await sodax.migration.isAllowanceValid({
|
|
|
114
115
|
```diff
|
|
115
116
|
try {
|
|
116
117
|
- const tx = await sodax.migration.balnSwapService.stake({ amount, lockPeriod }, spokeProvider);
|
|
117
|
-
+
|
|
118
|
-
+
|
|
119
|
-
+
|
|
120
|
-
+
|
|
121
|
-
+
|
|
118
|
+
+ // stake(user, params, walletProviderSlot) — positional args, not an action wrapper:
|
|
119
|
+
+ const tx = await sodax.migration.balnSwapService.stake(
|
|
120
|
+
+ userAddress, // Address of the lock owner on the Sonic hub
|
|
121
|
+
+ { lockId }, // BalnLockParams
|
|
122
|
+
+ walletProviderSlot,
|
|
123
|
+
+ );
|
|
122
124
|
/* … */
|
|
123
125
|
} catch (e) {
|
|
124
126
|
/* still v1-style: catch the throw */
|
|
@@ -131,9 +133,9 @@ const allowed = await sodax.migration.isAllowanceValid({
|
|
|
131
133
|
|
|
132
134
|
Cross-cutting traps (Result destructuring, error-model migration, srcChain/dstChain renames, etc.) live in [`../ai-rules.md`](../ai-rules.md). The list below is feature-specific — typecheck fingerprints, return-shape diffs, and gotchas unique to this feature.
|
|
133
135
|
|
|
134
|
-
1. **`migratebnUSD` direction detection.** v1 had explicit forward/reverse methods; v2 detects from `(
|
|
136
|
+
1. **`migratebnUSD` direction detection.** v1 had explicit forward/reverse methods; v2 detects from `(srcbnUSD, dstbnUSD)`. If both are on the same side (both legacy or both new), the SDK rejects with `VALIDATION_FAILED`. Use the `direction` field on `error.context` to disambiguate in error messaging.
|
|
135
137
|
2. **BALN lock methods don't return `Result`.** Be careful migrating wrappers — if your wrapper assumes Result-shape, lock methods will produce `undefined.ok` runtime errors. Keep the `try/catch` shape.
|
|
136
|
-
3. **`
|
|
138
|
+
3. **`lockupPeriod` is a `LockupPeriod` enum (in seconds), not a numeric months union.** Pass enum members, not raw numbers: `LockupPeriod.NO_LOCKUP` / `SIX_MONTHS` / `TWELVE_MONTHS` / `EIGHTEEN_MONTHS` / `TWENTY_FOUR_MONTHS` (mapping to 0/6/12/18/24 months — there are no 1/2/3-month options). `BalnMigrateParams` also requires `stake: boolean`.
|
|
137
139
|
4. **`getAvailableAmount` lives on the sub-service `sodax.migration.icxMigration` and takes no arguments.** v1 expected `(spokeProvider)`; v2 reads on-chain SODA liquidity directly from the hub provider, so the method needs no chain context. Sub-service field names: `sodax.migration.icxMigration`, `sodax.migration.bnUSDMigrationService`, `sodax.migration.balnSwapService`.
|
|
138
140
|
5. **`destinationExecution` phase on bnUSD errors** — these errors land **after** the relay succeeds. The spoke and hub txs may already exist; the destination-side finalization is what failed. Distinguish from primary relay errors (`phase: 'relay'`) when surfacing UX.
|
|
139
141
|
|
|
@@ -147,5 +149,5 @@ grep -rE "spokeProvider:\s*\w+|migrateBnUSDForward\b|migrateBnUSDReverse\b|isMig
|
|
|
147
149
|
|
|
148
150
|
## Cross-references
|
|
149
151
|
|
|
150
|
-
- v2 token migration usage: [`features/
|
|
152
|
+
- v2 token migration usage: [`features/migration.md`](../../../integration/knowledge/features/migration.md).
|
|
151
153
|
- Cross-cutting prerequisites listed in [`../README.md`](../README.md).
|
|
@@ -12,7 +12,7 @@ Pair: [`features/money-market.md`](../../../integration/knowledge/features/money
|
|
|
12
12
|
4. **`MoneyMarketSupplyParams` etc. are now generic** (`MoneyMarketSupplyParams<K extends SpokeChainKey>`). Add a chain-key generic to your params variables, or let TS infer from a literal `srcChainKey`.
|
|
13
13
|
5. **Replace `moneyMarketSupportedTokens[chainId]` with `sodax.moneyMarket.getSupportedTokensByChainId(chainKey)`.**
|
|
14
14
|
6. **Replace `hubAssets[chainId][address]?.vault` with `token.vault`** (now baked into `XToken`). Same for `token.hubAsset`.
|
|
15
|
-
7. **`sodax.moneyMarket.
|
|
15
|
+
7. **`sodax.moneyMarket.data.getATokenData(aToken)` returns a plain `Erc20Token`** (`{ name, symbol, decimals, address }`), not a full `XToken`. No `chainKey` / `hubAsset` / `vault` on the result — look up the full `XToken` via `sodax.config.getMoneyMarketToken(chainKey, address)` if needed.
|
|
16
16
|
8. **Errors → `SodaxError` + `Result<T>`.** v1's `MoneyMarketError<MoneyMarketErrorCode>` is gone. The CODE moved from `error.code` to `error.message`-style? **No** — it's still on `error.code`, but the union changed (see crosswalk below).
|
|
17
17
|
|
|
18
18
|
## Type / symbol cheat sheet
|
|
@@ -192,7 +192,7 @@ Cross-cutting traps (Result destructuring, error-model migration, srcChain/dstCh
|
|
|
192
192
|
|
|
193
193
|
1. **Forgetting `srcChainKey` + `srcAddress` in params.** TypeScript surfaces this as `error TS1360: Type '{ token, amount, action }' does not satisfy the expected type 'MoneyMarketSupplyParams'`. Add both required fields.
|
|
194
194
|
2. **Borrow/repay default delivery to source.** Omit `dstChainKey`/`dstAddress` if you want same-chain. Don't pass them as the same value as `srcChainKey` / `srcAddress` — let the default kick in.
|
|
195
|
-
3. **`sodax.moneyMarket.
|
|
195
|
+
3. **`sodax.moneyMarket.data.getATokenData(aToken)` returns a plain `Erc20Token`.** `{ name, symbol, decimals, address }`, not a full `XToken` — no `chainKey` / `vault` / `hubAsset` on the result. Look up the full `XToken` via `sodax.config.getMoneyMarketToken(chainKey, address)` separately if you need those fields.
|
|
196
196
|
4. **`hubAssets` is gone.** Anything that walked it for vault lookup must use `token.vault` directly.
|
|
197
197
|
5. **`baseChainInfo[chain].id` is gone — entries have `.key`.** Common in `ChainSelector`-style components.
|
|
198
198
|
6. **`spokeProvider.chainConfig.chain.type === 'EVM'`** is gone. Use `getChainType(chainKey) === 'EVM'` from `@sodax/sdk`.
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# Partner migration — v1 → v2
|
|
2
|
+
|
|
3
|
+
Pure-SDK migration playbook for `PartnerService`.
|
|
4
|
+
|
|
5
|
+
Pair: [`features/partner.md`](../../../integration/knowledge/features/partner.md).
|
|
6
|
+
|
|
7
|
+
## TL;DR
|
|
8
|
+
|
|
9
|
+
Standard pattern. Drop `spokeProvider`; pass `walletProvider`. Add `srcChainKey` + `srcAddress` to claim params. v1's 5 typed errors collapse into `SodaxError<C>` with `feature: 'partner'`.
|
|
10
|
+
|
|
11
|
+
## Type / symbol cheat sheet
|
|
12
|
+
|
|
13
|
+
| Type | v1 shape | v2 shape | Notes |
|
|
14
|
+
|---|---|---|---|
|
|
15
|
+
| Partner action params | non-generic | now generic `<K>` with `srcChainKey`, `srcAddress` | |
|
|
16
|
+
| Partner errors (5 types) | `PartnerFeeClaimError<...>` and 4 siblings | `SodaxError<C>` with `feature: 'partner'` | All 5 v1 typed errors collapse into `SodaxError`, but onto FOUR distinct codes (see crosswalk). |
|
|
17
|
+
|
|
18
|
+
## v1 → v2 error code crosswalk
|
|
19
|
+
|
|
20
|
+
The v1 partner errors collapse into `SodaxError<C>` with `feature: 'partner'`, but they do NOT all become `EXECUTION_FAILED`. The service emits FOUR distinct codes, with `error.context.action` (and `error.context.method` for reads) discriminating between the operations:
|
|
21
|
+
|
|
22
|
+
- `VALIDATION_FAILED` — same-token guard (output token equals the fee token) in `createIntentAutoSwap` / `swap`.
|
|
23
|
+
- `APPROVE_FAILED` — `approveToken` failure.
|
|
24
|
+
- `EXECUTION_FAILED` — the swap-wait / on-chain execution failure in the auto-swap flow.
|
|
25
|
+
- `LOOKUP_FAILED` — all read methods (`isTokenApproved`, `getUserIntent`, `getIntentDetails`, balance/preference reads, etc.).
|
|
26
|
+
|
|
27
|
+
## Per-method delta
|
|
28
|
+
|
|
29
|
+
Partner operations live on `sodax.partners.feeClaim` (a `PartnerFeeClaimService`), not directly on `sodax.partners`. v1 method names also changed:
|
|
30
|
+
|
|
31
|
+
```diff
|
|
32
|
+
- await sodax.partners.claimFees({ /* … */ }, spokeProvider);
|
|
33
|
+
+ // Approve once, then configure auto-swap preference, then run swaps.
|
|
34
|
+
+ // Full method list lives in integration/features/partner.md.
|
|
35
|
+
+ const approved = await sodax.partners.feeClaim.isTokenApproved({ srcChainKey, srcAddress, token });
|
|
36
|
+
+ if (approved.ok && !approved.value) {
|
|
37
|
+
+ await sodax.partners.feeClaim.approveToken({
|
|
38
|
+
+ params: { srcChainKey, srcAddress, token },
|
|
39
|
+
+ raw: false,
|
|
40
|
+
+ walletProvider,
|
|
41
|
+
+ });
|
|
42
|
+
+ }
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## Pitfalls
|
|
46
|
+
|
|
47
|
+
1. **Partner methods moved.** They live on `sodax.partners.feeClaim`, not `sodax.partners` directly. The parent only exposes `feeClaim` and `config` as public fields.
|
|
48
|
+
2. **All 5 v1 partner errors collapse to `feature: 'partner'`.** They span four codes — `VALIDATION_FAILED`, `APPROVE_FAILED`, `EXECUTION_FAILED`, `LOOKUP_FAILED` — not a single `EXECUTION_FAILED`. Discriminate on `error.code` plus `error.context.action` / `error.context.method`.
|
|
49
|
+
|
|
50
|
+
## Verification
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
pnpm -C <your-app-dir> checkTs
|
|
54
|
+
|
|
55
|
+
# Targeted scans:
|
|
56
|
+
grep -rE "spokeProvider:\s*\w+|isPartnerError\b|PartnerFeeClaimError\b" src/
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## Cross-references
|
|
60
|
+
|
|
61
|
+
- v2 partner usage: [`features/partner.md`](../../../integration/knowledge/features/partner.md).
|
|
62
|
+
- Stuck-asset recovery migration (separate service, new in v2): [`./recovery.md`](recovery.md).
|
|
63
|
+
- Backend API migration (the load-bearing `Result`-wrapping change): [`./backend-api.md`](backend-api.md).
|
|
64
|
+
- Result/error model: [`../breaking-changes/result-and-errors.md`](../breaking-changes/result-and-errors.md).
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# Recovery migration — v1 → v2
|
|
2
|
+
|
|
3
|
+
Pure-SDK migration playbook for `RecoveryService`.
|
|
4
|
+
|
|
5
|
+
Pair: [`features/recovery.md`](../../../integration/knowledge/features/recovery.md).
|
|
6
|
+
|
|
7
|
+
## TL;DR
|
|
8
|
+
|
|
9
|
+
**`RecoveryService` is new in v2.** No v1 equivalent — there's no migration to do for code that didn't exist before. This file exists so the v1 → v2 audit doesn't miss the addition.
|
|
10
|
+
|
|
11
|
+
If you have v1 code that worked around the absence (e.g. manually walked the hub wallet abstraction to find stuck assets), replace it with `fetchHubAssetBalances` + `withdrawHubAsset`:
|
|
12
|
+
|
|
13
|
+
```ts
|
|
14
|
+
const balances = await sodax.recovery.fetchHubAssetBalances({ chainKey, srcAddress });
|
|
15
|
+
if (balances.ok && balances.value.length > 0) {
|
|
16
|
+
await sodax.recovery.withdrawHubAsset({
|
|
17
|
+
params: { /* token (the spoke-side token address, i.e. spokeTokenAddress), amount, srcChainKey, srcAddress (also the withdrawal destination) */ },
|
|
18
|
+
raw: false,
|
|
19
|
+
walletProvider: sonicWp,
|
|
20
|
+
});
|
|
21
|
+
}
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
See [`features/recovery.md`](../../../integration/knowledge/features/recovery.md) for the full method signatures and error codes.
|
|
25
|
+
|
|
26
|
+
## Pitfalls
|
|
27
|
+
|
|
28
|
+
1. **Recovery is not a replacement for real error handling.** Use it after investigating why the original cross-chain operation failed — relay timeouts may resolve on retry; structural failures need fixing first.
|
|
29
|
+
|
|
30
|
+
## Cross-references
|
|
31
|
+
|
|
32
|
+
- v2 recovery usage: [`features/recovery.md`](../../../integration/knowledge/features/recovery.md).
|
|
33
|
+
- Partner migration (separate service): [`./partner.md`](partner.md).
|
|
34
|
+
- Backend API migration (separate service): [`./backend-api.md`](backend-api.md).
|
|
35
|
+
- Result/error model: [`../breaking-changes/result-and-errors.md`](../breaking-changes/result-and-errors.md).
|
|
@@ -26,16 +26,21 @@ Pair: [`features/staking.md`](../../../integration/knowledge/features/staking.md
|
|
|
26
26
|
| `InstantUnstakeParams` | `{ amount, minAmount, account, action: 'instantUnstake' }` | `{ srcChainKey, srcAddress, amount, minAmount, action: 'instantUnstake' }` | |
|
|
27
27
|
| `ClaimParams` | `{ requestId, amount, action: 'claim' }` | `{ srcChainKey, srcAddress, requestId, amount, action: 'claim' }` | Adds chain context. |
|
|
28
28
|
| `CancelUnstakeParams` | `{ requestId, action: 'cancelUnstake' }` | `{ srcChainKey, srcAddress, requestId, action: 'cancelUnstake' }` | Adds chain context. |
|
|
29
|
-
| `getStakingInfo` (read) | `(spokeProvider) => Promise<StakingInfo>` | `(srcAddress, srcChainKey) => Promise<Result<StakingInfo>>` |
|
|
29
|
+
| `getStakingInfo` (read) | `(spokeProvider) => Promise<StakingInfo>` | `getStakingInfoFromSpoke(srcAddress, srcChainKey) => Promise<Result<StakingInfo>>` (or `getStakingInfo(hubAddress)` if you already have the hub address) | v1 took a `spokeProvider` and resolved internally; v2 splits this into two public reads — `getStakingInfoFromSpoke` for spoke-side resolution, `getStakingInfo` for direct hub-side reads. Both return `Result`. |
|
|
30
30
|
| `getUnstakingInfo` (read) | `(userAddress, spokeProvider)` | `(srcAddress, srcChainKey)` | v1 ignored `userAddress`; v2 reads it for real. |
|
|
31
31
|
| `getUnstakingInfoWithPenalty` (read) | new (v2) | `(srcAddress, srcChainKey) => Promise<Result<UnstakingInfo & { requestsWithPenalty: UnstakeRequestWithPenalty[] }>>` | Wraps `getUnstakingInfo`'s base shape with a penalty-augmented request list. |
|
|
32
32
|
|
|
33
33
|
### Deleted symbols
|
|
34
34
|
|
|
35
35
|
- `StakingError<StakingErrorCode>` and `isStakingError` — replaced by `SodaxError<C>` + `feature: 'staking'`.
|
|
36
|
-
- v1 `getStakingInfo(hubAddress, …)` — not exposed as a public method in v2. Use `getStakingInfoFromSpoke(srcAddress, srcChainKey)`; the SDK derives the hub wallet via `HubService.getUserHubWalletAddress` internally.
|
|
37
36
|
- `spokeProvider instanceof SonicSpokeProvider` runtime checks — replace with `isHubChainKeyType(chainKey)` from `@sodax/sdk`.
|
|
38
37
|
|
|
38
|
+
### Renamed / re-shaped (not deleted)
|
|
39
|
+
|
|
40
|
+
- v1 `getStakingInfo(spokeProvider)` had implicit spoke-side resolution. v2 surfaces two public reads instead:
|
|
41
|
+
- `getStakingInfoFromSpoke(srcAddress, srcChainKey)` — for the spoke-side flow; derives the hub wallet via `hubProvider.getUserHubWalletAddress` internally.
|
|
42
|
+
- `getStakingInfo(hubAddress: Address)` — direct hub-side read, kept public for when the hub address is already known.
|
|
43
|
+
|
|
39
44
|
### v1 → v2 error code crosswalk (staking-specific)
|
|
40
45
|
|
|
41
46
|
| v1 `StakingErrorCode` | v2 code + context |
|
|
@@ -119,7 +124,7 @@ Cross-cutting traps (Result destructuring, error-model migration, srcChain/dstCh
|
|
|
119
124
|
1. **Wrong return shape for actions.** Treating `stake/unstake/etc.` as returning `Result<TxReturnType<K, false>>` (single hash) is **wrong** — they return `Result<TxHashPair>` because they always relay spoke→hub. Only `approve` returns a single hash.
|
|
120
125
|
2. **Forgetting `raw: true` on the allowance query.** TypeScript error: `Property 'walletProvider' is missing`. `isAllowanceValid` requires `WalletProviderSlot<K, Raw>`; `raw: false` would force a wallet provider. Use `raw: true` for read-only.
|
|
121
126
|
3. **Forgetting to remove the v1 `account` field from params.** v2 uses `srcAddress`. If both are set, TypeScript rejects the literal.
|
|
122
|
-
4.
|
|
127
|
+
4. **Confusing `getStakingInfo` and `getStakingInfoFromSpoke`.** Both are public in v2 — pick by which address you have. `getStakingInfo(hubAddress: Address)` reads the hub wallet directly; `getStakingInfoFromSpoke(srcAddress, srcChainKey)` derives the hub wallet from a spoke address via `hubProvider.getUserHubWalletAddress`, then delegates. Passing a spoke address into `getStakingInfo` returns wrong data (no hub-wallet resolution); always use the spoke variant when starting from a spoke address.
|
|
123
128
|
5. **`UnstakingInfo` no longer accepts `userAddress` separately.** v1 took both `spokeProvider` and `userAddress` props but ignored `userAddress` inside. v2 takes `srcAddress` and uses it.
|
|
124
129
|
|
|
125
130
|
## Verification
|