@sodax/skills 2.0.0-rc.9 → 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 -9
- package/AGENTS.md +119 -14
- 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/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/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 +11 -6
- package/skills/sodax-sdk/backend-api/SKILL.md +21 -15
- package/skills/sodax-sdk/bridge/SKILL.md +4 -0
- package/skills/sodax-sdk/dex/SKILL.md +5 -1
- package/skills/sodax-sdk/integration/knowledge/README.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/ai-rules.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/architecture.md +24 -21
- package/skills/sodax-sdk/integration/knowledge/chain-specifics.md +57 -10
- package/skills/sodax-sdk/integration/knowledge/features/README.md +2 -1
- package/skills/sodax-sdk/integration/knowledge/features/backend-api.md +27 -16
- package/skills/sodax-sdk/integration/knowledge/features/bridge.md +15 -14
- 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/migration.md +73 -28
- package/skills/sodax-sdk/integration/knowledge/features/money-market.md +20 -25
- package/skills/sodax-sdk/integration/knowledge/features/partner.md +27 -4
- package/skills/sodax-sdk/integration/knowledge/features/recovery.md +5 -4
- package/skills/sodax-sdk/integration/knowledge/features/staking.md +2 -2
- package/skills/sodax-sdk/integration/knowledge/features/swap.md +42 -24
- 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 +5 -1
- 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 +1 -1
- 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 +1 -1
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/backend-api.md +23 -23
- 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/migration.md +29 -27
- 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 +10 -5
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/recovery.md +2 -2
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/staking.md +2 -2
- 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 +18 -16
- package/skills/sodax-sdk/money-market/SKILL.md +7 -3
- package/skills/sodax-sdk/partner/SKILL.md +4 -0
- package/skills/sodax-sdk/recovery/SKILL.md +5 -1
- package/skills/sodax-sdk/staking/SKILL.md +4 -0
- package/skills/sodax-sdk/swap/SKILL.md +8 -3
- 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
|
@@ -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;
|
|
@@ -7,9 +7,9 @@ Pair: [`features/migration.md`](../../../integration/knowledge/features/migratio
|
|
|
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/migration.md`](../../../integration/knowledge/features/migratio
|
|
|
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/migration.md`](../../../integration/knowledge/features/migratio
|
|
|
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
|
|
|
@@ -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`.
|
|
@@ -13,11 +13,16 @@ Standard pattern. Drop `spokeProvider`; pass `walletProvider`. Add `srcChainKey`
|
|
|
13
13
|
| Type | v1 shape | v2 shape | Notes |
|
|
14
14
|
|---|---|---|---|
|
|
15
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. |
|
|
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
17
|
|
|
18
18
|
## v1 → v2 error code crosswalk
|
|
19
19
|
|
|
20
|
-
|
|
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.).
|
|
21
26
|
|
|
22
27
|
## Per-method delta
|
|
23
28
|
|
|
@@ -27,10 +32,10 @@ Partner operations live on `sodax.partners.feeClaim` (a `PartnerFeeClaimService`
|
|
|
27
32
|
- await sodax.partners.claimFees({ /* … */ }, spokeProvider);
|
|
28
33
|
+ // Approve once, then configure auto-swap preference, then run swaps.
|
|
29
34
|
+ // Full method list lives in integration/features/partner.md.
|
|
30
|
-
+ const approved = await sodax.partners.feeClaim.isTokenApproved({
|
|
35
|
+
+ const approved = await sodax.partners.feeClaim.isTokenApproved({ srcChainKey, srcAddress, token });
|
|
31
36
|
+ if (approved.ok && !approved.value) {
|
|
32
37
|
+ await sodax.partners.feeClaim.approveToken({
|
|
33
|
-
+ params: {
|
|
38
|
+
+ params: { srcChainKey, srcAddress, token },
|
|
34
39
|
+ raw: false,
|
|
35
40
|
+ walletProvider,
|
|
36
41
|
+ });
|
|
@@ -40,7 +45,7 @@ Partner operations live on `sodax.partners.feeClaim` (a `PartnerFeeClaimService`
|
|
|
40
45
|
## Pitfalls
|
|
41
46
|
|
|
42
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.
|
|
43
|
-
2. **All 5 v1 partner errors collapse to `feature: 'partner'`.**
|
|
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`.
|
|
44
49
|
|
|
45
50
|
## Verification
|
|
46
51
|
|
|
@@ -11,10 +11,10 @@ Pair: [`features/recovery.md`](../../../integration/knowledge/features/recovery.
|
|
|
11
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
12
|
|
|
13
13
|
```ts
|
|
14
|
-
const balances = await sodax.recovery.fetchHubAssetBalances({
|
|
14
|
+
const balances = await sodax.recovery.fetchHubAssetBalances({ chainKey, srcAddress });
|
|
15
15
|
if (balances.ok && balances.value.length > 0) {
|
|
16
16
|
await sodax.recovery.withdrawHubAsset({
|
|
17
|
-
params: { /*
|
|
17
|
+
params: { /* token (the spoke-side token address, i.e. spokeTokenAddress), amount, srcChainKey, srcAddress (also the withdrawal destination) */ },
|
|
18
18
|
raw: false,
|
|
19
19
|
walletProvider: sonicWp,
|
|
20
20
|
});
|
|
@@ -38,7 +38,7 @@ Pair: [`features/staking.md`](../../../integration/knowledge/features/staking.md
|
|
|
38
38
|
### Renamed / re-shaped (not deleted)
|
|
39
39
|
|
|
40
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 `
|
|
41
|
+
- `getStakingInfoFromSpoke(srcAddress, srcChainKey)` — for the spoke-side flow; derives the hub wallet via `hubProvider.getUserHubWalletAddress` internally.
|
|
42
42
|
- `getStakingInfo(hubAddress: Address)` — direct hub-side read, kept public for when the hub address is already known.
|
|
43
43
|
|
|
44
44
|
### v1 → v2 error code crosswalk (staking-specific)
|
|
@@ -124,7 +124,7 @@ Cross-cutting traps (Result destructuring, error-model migration, srcChain/dstCh
|
|
|
124
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.
|
|
125
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.
|
|
126
126
|
3. **Forgetting to remove the v1 `account` field from params.** v2 uses `srcAddress`. If both are set, TypeScript rejects the literal.
|
|
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 `
|
|
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.
|
|
128
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.
|
|
129
129
|
|
|
130
130
|
## Verification
|
|
@@ -13,7 +13,7 @@ Pair: [`features/swap.md`](../../../integration/knowledge/features/swap.md).
|
|
|
13
13
|
- `dstChain` → `dstChainKey`
|
|
14
14
|
- **`Intent.srcChain` / `Intent.dstChain` are unchanged** (read shape) — they're `IntentRelayChainId` (bigint).
|
|
15
15
|
4. **`CreateIntentResult` shape changed.** v1 was a tuple `[spokeTxHash, intent, relayData]`; v2 is an object `{ tx, intent, relayData }`. Destructure accordingly.
|
|
16
|
-
5.
|
|
16
|
+
5. **Backend submit-tx moved to `sodax.api.swaps.submitTx`** (`SubmitTxRequestV2`, was v1 `SubmitSwapTxRequest`): `srcChainId` → `srcChainKey`, and `relayData` expects a **string** (`relayData.payload`), not the `RelayExtraData` object.
|
|
17
17
|
6. **Errors → `SodaxError` + `Result<T>`.** v1's `IntentError<IntentErrorCode>` is gone. Branch on `result.ok`; use `(error.feature, error.code)` for discrimination.
|
|
18
18
|
|
|
19
19
|
## Type / symbol cheat sheet
|
|
@@ -24,7 +24,7 @@ Pair: [`features/swap.md`](../../../integration/knowledge/features/swap.md).
|
|
|
24
24
|
|---|---|---|---|
|
|
25
25
|
| `CreateIntentParams` (request) | `srcChain`, `dstChain` | `srcChainKey`, `dstChainKey` | Now generic: `CreateIntentParams<K extends SpokeChainKey>`. |
|
|
26
26
|
| `CreateLimitOrderParams` (request) | `srcChain`, `dstChain` | `srcChainKey`, `dstChainKey` | `Omit<CreateIntentParams<K>, 'deadline'>`. |
|
|
27
|
-
| `
|
|
27
|
+
| `SubmitTxRequestV2` (backend req, was `SubmitSwapTxRequest`) | `srcChainId` | `srcChainKey` | Submitted via `sodax.api.swaps.submitTx`; `relayData: string` (was the object in v1). |
|
|
28
28
|
| `Intent` (read shape) | `srcChain`, `dstChain` | **unchanged** | `IntentRelayChainId` (bigint). Don't grep-replace blindly. |
|
|
29
29
|
| `XToken` | `xChainId` | `chainKey` | Type renamed from `Token` → `XToken`. |
|
|
30
30
|
| `CreateIntentResult` | tuple `[spokeTxHash, intent, relayData]` | object `{ tx, intent, relayData }` | Generic: `CreateIntentResult<K, Raw>`. |
|
|
@@ -63,7 +63,8 @@ Pair: [`features/swap.md`](../../../integration/knowledge/features/swap.md).
|
|
|
63
63
|
+ walletProvider: sourceWalletProvider,
|
|
64
64
|
+ });
|
|
65
65
|
+ if (!result.ok) return;
|
|
66
|
-
+ const {
|
|
66
|
+
+ const { solverExecutionResponse, intent, intentDeliveryInfo } = result.value;
|
|
67
|
+
+ // swap() returns SwapResponse = { solverExecutionResponse, intent, intentDeliveryInfo }
|
|
67
68
|
```
|
|
68
69
|
|
|
69
70
|
### `createIntent`
|
|
@@ -110,19 +111,22 @@ const result = await sodax.swaps.isAllowanceValid({ params, raw: true });
|
|
|
110
111
|
|
|
111
112
|
The underlying read doesn't consult the wallet provider; `raw: true` is the contract for read-only access.
|
|
112
113
|
|
|
113
|
-
### Backend submit-tx (`
|
|
114
|
+
### Backend submit-tx (`SubmitTxRequestV2`)
|
|
114
115
|
|
|
115
116
|
```diff
|
|
116
|
-
|
|
117
|
+
- const request: SubmitSwapTxRequest = {
|
|
118
|
+
+ const request: SubmitTxRequestV2 = {
|
|
117
119
|
txHash: spokeTxHash as string,
|
|
118
120
|
- srcChainId: sourceChain,
|
|
119
121
|
+ srcChainKey: src.chain,
|
|
120
122
|
walletAddress: sourceAccount.address ?? '',
|
|
121
|
-
|
|
123
|
+
- intent: swapIntentData, // was: V1 string/number-downcast shape
|
|
124
|
+
+ intent, // IntentRequestV2 — the createIntent intent passes through (bigint)
|
|
122
125
|
- relayData, // was the RelayExtraData object
|
|
123
126
|
+ relayData: relayData.payload, // now a string
|
|
124
127
|
};
|
|
125
|
-
|
|
128
|
+
- const submitResult = await sodax.backendApi.submitSwapTx(request);
|
|
129
|
+
+ const submitResult = await sodax.api.swaps.submitTx(request); // moved off BackendApiService
|
|
126
130
|
if (!submitResult.ok) return;
|
|
127
131
|
```
|
|
128
132
|
|
|
@@ -144,24 +148,24 @@ The underlying read doesn't consult the wallet provider; `raw: true` is the cont
|
|
|
144
148
|
if (!createIntentResult.ok) return;
|
|
145
149
|
- const [spokeTxHash, intent, relayData] = createIntentResult.value;
|
|
146
150
|
+ const { tx: spokeTxHash, intent, relayData } = createIntentResult.value;
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
- srcChain: Number(intent.srcChain),
|
|
150
|
-
- dstChain: Number(intent.dstChain),
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
const request: SubmitSwapTxRequest = {
|
|
151
|
+
- const swapIntentData: SwapIntentData = {
|
|
152
|
+
- /* … string/number downcasts of intent.* … */
|
|
153
|
+
- srcChain: Number(intent.srcChain),
|
|
154
|
+
- dstChain: Number(intent.dstChain),
|
|
155
|
+
- };
|
|
156
|
+
- const request: SubmitSwapTxRequest = {
|
|
157
|
+
+ const request: SubmitTxRequestV2 = {
|
|
155
158
|
txHash: spokeTxHash as string,
|
|
156
159
|
- srcChainId: sourceChain,
|
|
157
160
|
+ srcChainKey: src.chain,
|
|
158
161
|
walletAddress: sourceAccount.address ?? '',
|
|
159
|
-
|
|
162
|
+
- intent: swapIntentData,
|
|
163
|
+
+ intent, // IntentRequestV2 — bigint fields pass through, no downcast
|
|
160
164
|
- relayData,
|
|
161
165
|
+ relayData: relayData.payload,
|
|
162
166
|
};
|
|
163
167
|
- await submitSwapTx(request);
|
|
164
|
-
+ const submitResult = await sodax.
|
|
168
|
+
+ const submitResult = await sodax.api.swaps.submitTx(request);
|
|
165
169
|
+ if (!submitResult.ok) return;
|
|
166
170
|
};
|
|
167
171
|
```
|
|
@@ -172,7 +176,7 @@ Cross-cutting traps (Result destructuring, error-model migration, srcChain/dstCh
|
|
|
172
176
|
|
|
173
177
|
1. **Over-broad regex on `srcChain` / `dstChain`.** Request types renamed; `Intent` (read shape) didn't. Distinguish "I'm building a request" from "I'm reading an intent."
|
|
174
178
|
2. **`createIntent` success shape changed from tuple to object.** `{ tx, intent, relayData }`, not `[spokeTxHash, intent, relayData]`.
|
|
175
|
-
3. **`relayData` on `
|
|
179
|
+
3. **`relayData` on `SubmitTxRequestV2` is a `string`.** It's `relayData.payload`, not the full `RelayExtraData` object.
|
|
176
180
|
4. **`spokeTxHash` is `TxReturnType<K, false>`, not necessarily `string`.** For most chains it's a string already, but the SDK type is broader. Cast at the boundary when passing to APIs that strictly want `string`: `txHash: spokeTxHash as string`.
|
|
177
181
|
5. **`Intent.deadline` is `bigint`.** `Math.floor(Date.now() / 1000) + 60 * 5` returns a number; wrap in `BigInt(...)`.
|
|
178
182
|
6. **`IntentResponse.srcChain` / `dstChain` from the backend are `IntentRelayChainId` (number/bigint), not chain keys.** Convert via `sodax.config.getSpokeChainKeyFromIntentRelayChainId(BigInt(intent.dstChain))` when displaying.
|
|
@@ -1,19 +1,19 @@
|
|
|
1
1
|
# `SodaxConfig` constructor reshape
|
|
2
2
|
|
|
3
|
-
The v2 `Sodax` constructor accepts a `DeepPartial<
|
|
3
|
+
The v2 `Sodax` constructor accepts a `SodaxOptions` (`DeepPartial<SodaxDefaultConfig> & SodaxOptionalConfig`). Several config fields renamed, moved, or were added between v1 and v2; if your project passed a custom config, check these.
|
|
4
4
|
|
|
5
|
-
## v2
|
|
5
|
+
## v2 config data shape (`SodaxDefaultConfig`, source of truth)
|
|
6
6
|
|
|
7
|
-
Defined in `@sodax/types` (`packages/types/src/sodax-config/sodax-config.ts`):
|
|
7
|
+
Defined in `@sodax/types` (`packages/types/src/sodax-config/sodax-config.ts`). This is the static data contract the backend serves and the packaged defaults are built from; `SodaxConfig` is the merged result (`SodaxDefaultConfig & SodaxOptionalConfig`):
|
|
8
8
|
|
|
9
9
|
```ts
|
|
10
|
-
type
|
|
11
|
-
fee: PartnerFee | undefined; // global partner fee (overridable per-feature)
|
|
10
|
+
type SodaxDefaultConfig = {
|
|
12
11
|
chains: Record<SpokeChainKey, SpokeChainConfig>; // per-spoke-chain config (rpcUrl + tx polling + chain-specific shape)
|
|
13
|
-
swaps:
|
|
14
|
-
moneyMarket:
|
|
15
|
-
bridge:
|
|
16
|
-
dex:
|
|
12
|
+
swaps: SwapsDefaultConfig; // supported swap tokens per chain (+ per-feature partnerFee override)
|
|
13
|
+
moneyMarket: MoneyMarketDefaultConfig; // money market service config (+ per-feature partnerFee override)
|
|
14
|
+
bridge: BridgeDefaultConfig; // bridge partner-fee override
|
|
15
|
+
dex: DexDefaultConfig; // DEX service config
|
|
16
|
+
leverageYield: LeverageYieldDefaultConfig; // leverage-yield ERC-4626 vault registry (+ per-feature partnerFee override)
|
|
17
17
|
hub: HubConfig; // hub-chain (Sonic) provider config
|
|
18
18
|
api: ApiConfig; // backend API endpoint
|
|
19
19
|
solver: SolverConfig; // intent solver endpoint + contracts
|
|
@@ -21,7 +21,9 @@ type SodaxConfig = {
|
|
|
21
21
|
};
|
|
22
22
|
```
|
|
23
23
|
|
|
24
|
-
A matching default `sodaxConfig` const is exported from the same module — `new Sodax()` deep-merges your `DeepPartial<
|
|
24
|
+
A matching default `sodaxConfig` const is exported from the same module — `new Sodax()` deep-merges your `DeepPartial<SodaxDefaultConfig>` over it.
|
|
25
|
+
|
|
26
|
+
The `new Sodax(...)` argument is actually `SodaxOptions = DeepPartial<SodaxDefaultConfig> & SodaxOptionalConfig`, where `SodaxOptionalConfig` carries the client-side options `{ logger?; fee? }` plus the per-feature option objects. The global partner `fee` and `logger` are **client-side options, NOT `SodaxDefaultConfig` data fields**: the integrator sets them, they are resolved once, and they are never fetched from or overwritten by the backend config. Read the resolved global fee back via `sodax.config.fee`. It is the **fallback applied to any feature whose own `partnerFee` is unset** (effective fee = `featureFee ?? fee`, via `sodax.config.swapPartnerFee` / `moneyMarketPartnerFee` / `bridgePartnerFee` / `leverageYieldPartnerFee`). (Per-feature partner-fee overrides — `swaps.partnerFee`, `moneyMarket.partnerFee`, `bridge.partnerFee`, `leverageYield.partnerFee` — live on the feature options.)
|
|
25
27
|
|
|
26
28
|
## v1 shape (for reference)
|
|
27
29
|
|
|
@@ -47,7 +49,7 @@ All v1 fields were **optional**. v1 had **no** top-level `rpcConfig` on `SodaxCo
|
|
|
47
49
|
|
|
48
50
|
| v1 location | v2 location | Notes |
|
|
49
51
|
|---|---|---|
|
|
50
|
-
| `SodaxConfig.swaps` (`SolverConfigParams` — `{ intentsContract, solverApiEndpoint, protocolIntentsContract?, partnerFee? }`) | **Split into two:** `SodaxConfig.solver: SolverConfig` (`{ intentsContract, solverApiEndpoint, protocolIntentsContract }`) and `SodaxConfig.swaps: SwapsConfig` (supported tokens per chain — new in v2). | v1 partner-fee inside `SolverConfigParams` moves to the global `
|
|
52
|
+
| `SodaxConfig.swaps` (`SolverConfigParams` — `{ intentsContract, solverApiEndpoint, protocolIntentsContract?, partnerFee? }`) | **Split into two:** `SodaxConfig.solver: SolverConfig` (`{ intentsContract, solverApiEndpoint, protocolIntentsContract }`) and `SodaxConfig.swaps: SwapsConfig` (supported tokens per chain — new in v2). | v1 partner-fee inside `SolverConfigParams` moves to the global `SodaxOptions.fee` option or per-feature configs. |
|
|
51
53
|
| `SodaxConfig.hubProviderConfig` (`EvmHubProviderConfig` — `{ hubRpcUrl, chainConfig }`) | **`SodaxConfig.hub`** (`HubConfig` — full hub addresses + native token + bnUSD + polling + RPC URL). | Field renamed `hubProviderConfig` → `hub`. Shape expanded: v1 just had RPC URL + chain config; v2 ships the full hub-contract address map. |
|
|
52
54
|
| `SodaxConfig.moneyMarket` (`MoneyMarketConfigParams`) | `SodaxConfig.moneyMarket` (`MoneyMarketConfig` — required, shape changed). | Reshape, see `@sodax/types/src/common/common.ts` MoneyMarketConfig. |
|
|
53
55
|
| `SodaxConfig.bridge` (`BridgeServiceConfig`) | `SodaxConfig.bridge` (`BridgeConfig` — `{ partnerFee }`). | Reshape; smaller. |
|
|
@@ -58,7 +60,7 @@ All v1 fields were **optional**. v1 had **no** top-level `rpcConfig` on `SodaxCo
|
|
|
58
60
|
| `SodaxConfig.migration` (`MigrationServiceConfig`) | **Removed.** Migration service runs with hard-coded defaults. | No replacement on `SodaxConfig`. v2 surfaces customization via per-method params on `sodax.migration.*`, not constructor config — see [`../features/migration.md`](../features/migration.md). |
|
|
59
61
|
| `SodaxConfig.partners` (`PartnerServiceConfig`) | **Removed.** Partner service runs with defaults. | Per-claim partner-fee config now flows via call-level params on `sodax.partners.*` methods. |
|
|
60
62
|
| `SodaxConfig.sharedConfig` (`typeof defaultSharedConfig`) | **Removed.** | Absorbed into `ConfigService` + per-chain `SpokeChainConfig`. Override individual chains via `SodaxConfig.chains[key]`. |
|
|
61
|
-
| (none in v1) | **`
|
|
63
|
+
| (none in v1) | **`SodaxOptions.fee?: PartnerFee`** (new — a client-side option, NOT a `SodaxConfig` data field). | Global partner fee, set via `new Sodax({ fee })` and read back on `sodax.config.fee`. A client option like `logger` — never fetched from or overwritten by the backend. Per-feature overrides still live on `SodaxConfig` (`bridge.partnerFee`, `swaps.partnerFee`, `moneyMarket.partnerFee`). |
|
|
62
64
|
| (v1 had no top-level `configService` injection slot on `SodaxConfig` — `ConfigService` was always constructed internally from `backendApiConfig` + `sharedConfig`.) | Same — `ConfigService` is internal. v2 does **not** expose a typed slot to inject a custom `IConfigApi` either. To swap the backend in tests, point `SodaxConfig.api.baseURL` at a mock server. | See Pitfall below. |
|
|
63
65
|
|
|
64
66
|
Migration:
|
|
@@ -79,7 +81,7 @@ Migration:
|
|
|
79
81
|
- // RPC URLs were passed as a SEPARATE prop on the framework-layer SodaxProvider
|
|
80
82
|
- // (alongside the sodaxConfig). The Sodax constructor itself never saw rpcConfig.
|
|
81
83
|
|
|
82
|
-
+ // v2 — DeepPartial<
|
|
84
|
+
+ // v2 — SodaxOptions (DeepPartial<SodaxDefaultConfig> & client options) passed directly to new Sodax(...)
|
|
83
85
|
+ const sodax = new Sodax({
|
|
84
86
|
+ hub: { /* HubConfig — usually omit, default ships full hub addresses */ },
|
|
85
87
|
+ solver: {
|
|
@@ -91,7 +93,7 @@ Migration:
|
|
|
91
93
|
+ supportedTokens: { /* per-chain table */ },
|
|
92
94
|
+ },
|
|
93
95
|
+ relay: { /* RelayConfig — relayer URL + chain-id map */ },
|
|
94
|
-
+ fee: { address: '0x…', percentage: 10 }, // global partner fee (
|
|
96
|
+
+ fee: { address: '0x…', percentage: 10 }, // global partner fee — a SodaxOptions client option (not SodaxConfig data)
|
|
95
97
|
+ chains: {
|
|
96
98
|
+ [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://…' },
|
|
97
99
|
+ [ChainKeys.ARBITRUM_MAINNET]: { rpcUrl: 'https://…' },
|
|
@@ -113,12 +115,12 @@ See [`../breaking-changes/type-system.md`](../breaking-changes/type-system.md)
|
|
|
113
115
|
|
|
114
116
|
### Pitfall
|
|
115
117
|
|
|
116
|
-
If you previously injected a custom `ConfigService` for testing (a v1 escape hatch), v2 doesn't accept one at the top level — and unlike what earlier doc versions claimed, **v2 also doesn't expose a typed slot to inject a custom `
|
|
118
|
+
If you previously injected a custom `ConfigService` for testing (a v1 escape hatch), v2 doesn't accept one at the top level — and unlike what earlier doc versions claimed, **v2 also doesn't expose a typed slot to inject a custom `IConfigApiV1`**. The realistic options:
|
|
117
119
|
|
|
118
120
|
- Point `SodaxConfig.api.baseURL` at a local mock backend server.
|
|
119
121
|
- Construct your own `BackendApiService`-compatible object in your app/test bootstrap and swap it in where you control the `Sodax` instance.
|
|
120
122
|
|
|
121
|
-
The `SodaxConfig.api` field is `ApiConfig` (`{ baseURL, timeout, headers }`) — there is no `api.api` sub-field for
|
|
123
|
+
The `SodaxConfig.api` field is `ApiConfig` (`{ baseURL, timeout, headers }`) — there is no `api.api` sub-field for IConfigApiV1 injection.
|
|
122
124
|
|
|
123
125
|
### Pitfall — module-scope reads
|
|
124
126
|
|
|
@@ -1,6 +1,10 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: sodax-sdk-money-market
|
|
3
3
|
description: 'Granular skill for the @sodax/sdk v2 money-market feature only — cross-chain lending and borrowing (supply, borrow, withdraw, repay) and per-position reads. Use when the consumer task is specifically money-market (e.g. "supply on Sodax", "borrow against my position", "Sodax lending", "withdraw collateral", "repay debt", "cross-chain borrow"). Covers BOTH integration (write new v2 code) and migration (port v1 MoneyMarketService to v2). Skill links into the parent sodax-sdk knowledge tree — does NOT duplicate it. For React dapps, prefer the sodax-dapp-kit skill.'
|
|
4
|
+
license: MIT
|
|
5
|
+
metadata:
|
|
6
|
+
version: '0.0.1'
|
|
7
|
+
author: sodax
|
|
4
8
|
---
|
|
5
9
|
|
|
6
10
|
# Money Market (Core SDK granular skill)
|
|
@@ -13,7 +17,7 @@ Granular skill for the lending/borrowing feature of `@sodax/sdk` v2. Access via
|
|
|
13
17
|
2. **Which operation?** `supply`, `borrow`, `withdraw`, `repay`, or just position reads.
|
|
14
18
|
3. **Same-chain or cross-chain borrow?** `borrow` can deliver funds back to the source chain or to a different spoke chain.
|
|
15
19
|
4. **Signed flow or unsigned-tx (`createXxxIntent`)?**
|
|
16
|
-
5. **Need
|
|
20
|
+
5. **Need reserves / position reads** (aToken balances, reserves data, formatted summaries)? Those live on `sodax.moneyMarket.data`. Backend-indexed user position (`getMoneyMarketPosition`, asset lists) comes from `sodax.backendApi` — load [`../backend-api/SKILL.md`](../backend-api/SKILL.md) alongside.
|
|
17
21
|
|
|
18
22
|
## Integration workflow
|
|
19
23
|
|
|
@@ -28,9 +32,9 @@ Granular skill for the lending/borrowing feature of `@sodax/sdk` v2. Access via
|
|
|
28
32
|
|
|
29
33
|
### Money-market-specific anti-patterns
|
|
30
34
|
|
|
31
|
-
- **
|
|
35
|
+
- **Passing the hub asset address as `token`.** `MoneyMarketParams<K>.token` is the user's spoke-chain original asset address (e.g. `USDC_ARBITRUM.address` with `srcChainKey: ARBITRUM_MAINNET`), validated via `getSpokeTokenFromOriginalAssetAddress`; the hub asset is derived internally. Don't substitute a hub (`0x…` on Sonic) address.
|
|
32
36
|
- **Skipping allowance check before `supply` / `repay`.** Use `isAllowanceValid` then `approve` with the action-discriminated args.
|
|
33
|
-
- **
|
|
37
|
+
- **Routing reserve-data reads to `sodax.backendApi`.** Those live on `sodax.moneyMarket.data` (`getReservesData`, `getUserReservesData`, `getATokensBalances`, `getReservesHumanized`, `getUserReservesHumanized`, `formatUserSummary`).
|
|
34
38
|
|
|
35
39
|
## Migration workflow (v1 → v2)
|
|
36
40
|
|
|
@@ -1,6 +1,10 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: sodax-sdk-partner
|
|
3
3
|
description: 'Granular skill for the @sodax/sdk v2 partner-fee feature only — `PartnerService` (operations on `sodax.partners.feeClaim`). Token approval on the hub, auto-swap preferences, immediate fee-claim swap, intent-driven auto-swap, asset-balance reads. Use when the task is partner-fee work (e.g. "claim partner fee", "configure partner auto-swap preference", "approve partner fee token on Sodax hub", "Sodax PartnerService"). Covers BOTH integration and migration. Skill links into the parent sodax-sdk knowledge tree. For React dapps, prefer sodax-dapp-kit.'
|
|
4
|
+
license: MIT
|
|
5
|
+
metadata:
|
|
6
|
+
version: '0.0.1'
|
|
7
|
+
author: sodax
|
|
4
8
|
---
|
|
5
9
|
|
|
6
10
|
# Partner (Core SDK granular skill)
|
|
@@ -1,6 +1,10 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: sodax-sdk-recovery
|
|
3
3
|
description: 'Granular skill for the @sodax/sdk v2 recovery feature only — `RecoveryService` for withdrawing stuck hub-wallet assets back to a spoke chain. Use when the task is recovering assets stranded on the hub after a failed cross-chain operation (e.g. "recover stuck assets on Sonic", "Sodax RecoveryService", "fetchHubAssetBalances", "withdrawHubAsset", "stuck-asset withdrawal"). Service is NEW in v2 (no v1 equivalent). Covers BOTH integration and the v2-only migration note. Skill links into the parent sodax-sdk knowledge tree.'
|
|
4
|
+
license: MIT
|
|
5
|
+
metadata:
|
|
6
|
+
version: '0.0.1'
|
|
7
|
+
author: sodax
|
|
4
8
|
---
|
|
5
9
|
|
|
6
10
|
# Recovery (Core SDK granular skill)
|
|
@@ -27,7 +31,7 @@ Granular skill for `RecoveryService` — `sodax.recovery`. Feature tag for error
|
|
|
27
31
|
### Recovery-specific anti-patterns
|
|
28
32
|
|
|
29
33
|
- **Treating recovery as a routine flow.** It's a workaround for failures; calling it on successfully completed flows wastes gas and confuses users.
|
|
30
|
-
- **Skipping the balance read.** `fetchHubAssetBalances` returns the
|
|
34
|
+
- **Skipping the balance read.** `fetchHubAssetBalances` returns only the non-zero hub-asset balances for one spoke chain (it takes `{ chainKey, srcAddress }` and excludes leverage-yield vault share tokens); pick the entry to withdraw rather than guessing the address.
|
|
31
35
|
- **Ignoring the underlying failure.** Recovery moves the asset but doesn't explain why the original op failed — investigate first (relay timeout? bad params? destination chain issue?).
|
|
32
36
|
|
|
33
37
|
## Migration workflow (v1 → v2)
|
|
@@ -1,6 +1,10 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: sodax-sdk-staking
|
|
3
3
|
description: 'Granular skill for the @sodax/sdk v2 staking feature only — SODA ↔ xSoda staking via ERC-4626 vault. Stake, unstake (with penalty curve), instant unstake (slippage), claim, cancel unstake. Use when the task is staking (e.g. "stake SODA", "unstake xSoda", "claim Sodax staking rewards", "instant unstake with penalty", "cancel pending unstake", "get staking info from spoke"). Covers BOTH integration and migration. Skill links into the parent sodax-sdk knowledge tree. For React dapps, prefer sodax-dapp-kit.'
|
|
4
|
+
license: MIT
|
|
5
|
+
metadata:
|
|
6
|
+
version: '0.0.1'
|
|
7
|
+
author: sodax
|
|
4
8
|
---
|
|
5
9
|
|
|
6
10
|
# Staking (Core SDK granular skill)
|
|
@@ -1,6 +1,10 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: sodax-sdk-swap
|
|
3
3
|
description: 'Granular skill for the @sodax/sdk v2 swap feature only — intent-based swaps via solver (market orders + limit orders) and cancel/approve flows. Use when the consumer has decided the task is a swap (e.g. "swap with Sodax", "Sodax intent swap", "limit order on Sodax", "cross-chain swap via Sonic", "cancel a Sodax intent") and you want to skip loading the broad sodax-sdk skill. Covers BOTH integration (write new v2 swap code) and migration (port v1 swap to v2) — picks via Step 1 question. Skill is intentionally short and links into the parent sodax-sdk knowledge tree (../integration/knowledge/, ../migration-v1-to-v2/knowledge/) for full reference. For React dapps doing swaps, prefer the sodax-dapp-kit skill instead.'
|
|
4
|
+
license: MIT
|
|
5
|
+
metadata:
|
|
6
|
+
version: '0.0.1'
|
|
7
|
+
author: sodax
|
|
4
8
|
---
|
|
5
9
|
|
|
6
10
|
# Swap (Core SDK granular skill)
|
|
@@ -19,7 +23,7 @@ Swap has materially different code paths depending on the answers. Don't skip:
|
|
|
19
23
|
- Unsigned → `raw: true`, you handle relay yourself.
|
|
20
24
|
3. **One-shot `swap()` or step-by-step (`createIntent` → backend submit → `postExecution`)?**
|
|
21
25
|
- One-shot is the default for frontends. Step-by-step is for backends that already have a relay/orchestration layer.
|
|
22
|
-
4. **Market order or limit order?** Limit orders use a different params shape
|
|
26
|
+
4. **Market order or limit order?** Limit orders use a different params shape — `deadline` becomes optional (forced to `0n` internally), not required.
|
|
23
27
|
|
|
24
28
|
## Integration workflow (writing new v2 swap code)
|
|
25
29
|
|
|
@@ -37,7 +41,7 @@ Read in order. Skipping `ai-rules.md` is the most common cause of agents reverti
|
|
|
37
41
|
|
|
38
42
|
- **`try { await sodax.swaps.swap(...) } catch` for SDK-level failures.** v2 returns `Result<T>` — branch on `result.ok`. `catch` only fires for thrown exceptions (e.g. missing `walletProvider`), not for `RELAY_TIMEOUT` or `EXECUTION_FAILED`.
|
|
39
43
|
- **Forgetting the discriminator.** `raw: false` is required on signed swaps; without it TypeScript rejects `walletProvider`.
|
|
40
|
-
- **Calling `
|
|
44
|
+
- **Calling `sodax.api.swaps.submitTx` with the full `relayData` object.** The backend expects the `payload: string` field, not the wrapper.
|
|
41
45
|
|
|
42
46
|
## Migration workflow (port v1 swap to v2)
|
|
43
47
|
|
|
@@ -58,7 +62,8 @@ Read in order. Skipping `ai-rules.md` is the most common cause of agents reverti
|
|
|
58
62
|
- [`../money-market/SKILL.md`](../money-market/SKILL.md) — if the swap is followed by a supply/borrow action.
|
|
59
63
|
- [`../partner/SKILL.md`](../partner/SKILL.md) — partner fees on swap.
|
|
60
64
|
- [`../recovery/SKILL.md`](../recovery/SKILL.md) — stuck-asset recovery for failed swaps.
|
|
61
|
-
- [`../backend-api/SKILL.md`](../backend-api/SKILL.md) — `
|
|
65
|
+
- [`../backend-api/SKILL.md`](../backend-api/SKILL.md) — `sodax.api.swaps.submitTx` and intent / orderbook lookups (step-by-step swap flow + diagnostics).
|
|
66
|
+
- [`../swaps-api/SKILL.md`](../swaps-api/SKILL.md) — the typed Swaps API v2 backend client (`sodax.api.swaps`: quote, create-intent, submit-tx, fees) the swap flow calls under the hood.
|
|
62
67
|
|
|
63
68
|
For tasks spanning multiple features, load the broad [`sodax-sdk` skill](../SKILL.md) instead.
|
|
64
69
|
|