@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
|
@@ -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. |
|
|
@@ -55,10 +57,10 @@ All v1 fields were **optional**. v1 had **no** top-level `rpcConfig` on `SodaxCo
|
|
|
55
57
|
| `SodaxConfig.relayerApiEndpoint: HttpUrl` (string) | **`SodaxConfig.relay`** (`RelayConfig` — object with relayer URL + chain-id map). | Renamed + reshaped from string to object. |
|
|
56
58
|
| `SodaxConfig.backendApiConfig` (`BackendApiConfig`) | **`SodaxConfig.api`** (`ApiConfig`). | Renamed. |
|
|
57
59
|
| (Separate `rpcConfig` prop on the framework-layer SodaxProvider, NOT a `SodaxConfig` field) | **`SodaxConfig.chains`** (`Record<SpokeChainKey, SpokeChainConfig>`). | v2 absorbs RPC URLs + polling + chain-specific extras into the `SodaxConfig.chains` mapped type. v1's separate `rpcConfig` provider prop is gone. The standalone `RpcConfig` type still ships from `@sodax/types` for utility use (e.g. the demo's `providers.tsx` declares a local `RpcConfig` then maps values into `chains`), but it is not a `SodaxConfig` field. |
|
|
58
|
-
| `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/
|
|
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
|
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: sodax-sdk-money-market
|
|
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
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Money Market (Core SDK granular skill)
|
|
11
|
+
|
|
12
|
+
Granular skill for the lending/borrowing feature of `@sodax/sdk` v2. Access via `sodax.moneyMarket`. Feature tag for errors: `'moneyMarket'`.
|
|
13
|
+
|
|
14
|
+
## Step 1 — Clarify with user before coding
|
|
15
|
+
|
|
16
|
+
1. **New code or v1 → v2 port?**
|
|
17
|
+
2. **Which operation?** `supply`, `borrow`, `withdraw`, `repay`, or just position reads.
|
|
18
|
+
3. **Same-chain or cross-chain borrow?** `borrow` can deliver funds back to the source chain or to a different spoke chain.
|
|
19
|
+
4. **Signed flow or unsigned-tx (`createXxxIntent`)?**
|
|
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.
|
|
21
|
+
|
|
22
|
+
## Integration workflow
|
|
23
|
+
|
|
24
|
+
1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT.
|
|
25
|
+
2. [`../integration/knowledge/features/money-market.md`](../integration/knowledge/features/money-market.md) — `MoneyMarketService` API, action params, hub-asset / aToken mapping.
|
|
26
|
+
3. Path-specific recipe:
|
|
27
|
+
- Signed → [`../integration/knowledge/recipes/signed-tx-flow.md`](../integration/knowledge/recipes/signed-tx-flow.md)
|
|
28
|
+
- Backend / unsigned → [`../integration/knowledge/recipes/raw-tx-flow.md`](../integration/knowledge/recipes/raw-tx-flow.md)
|
|
29
|
+
4. Gas estimation before action methods → [`../integration/knowledge/recipes/gas-estimation.md`](../integration/knowledge/recipes/gas-estimation.md).
|
|
30
|
+
5. Errors (`feature: 'moneyMarket'`) → [`../integration/knowledge/recipes/result-and-errors.md`](../integration/knowledge/recipes/result-and-errors.md) and [`../integration/knowledge/reference/error-codes.md`](../integration/knowledge/reference/error-codes.md).
|
|
31
|
+
6. Reading user position → load [`../backend-api/SKILL.md`](../backend-api/SKILL.md) for `BackendApiService.getMoneyMarketPosition`, `getAllMoneyMarketAssets`, etc.
|
|
32
|
+
|
|
33
|
+
### Money-market-specific anti-patterns
|
|
34
|
+
|
|
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.
|
|
36
|
+
- **Skipping allowance check before `supply` / `repay`.** Use `isAllowanceValid` then `approve` with the action-discriminated args.
|
|
37
|
+
- **Routing reserve-data reads to `sodax.backendApi`.** Those live on `sodax.moneyMarket.data` (`getReservesData`, `getUserReservesData`, `getATokensBalances`, `getReservesHumanized`, `getUserReservesHumanized`, `formatUserSummary`).
|
|
38
|
+
|
|
39
|
+
## Migration workflow (v1 → v2)
|
|
40
|
+
|
|
41
|
+
1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md).
|
|
42
|
+
2. [`../migration-v1-to-v2/knowledge/features/money-market.md`](../migration-v1-to-v2/knowledge/features/money-market.md) — v1 `MoneyMarketError` → v2 `SodaxError<C>` with `feature: 'moneyMarket'`.
|
|
43
|
+
3. Add `srcChainKey` + `srcAddress` to every action params object — these were not in v1 shapes.
|
|
44
|
+
|
|
45
|
+
## Verification
|
|
46
|
+
|
|
47
|
+
1. `pnpm tsc --noEmit` clean.
|
|
48
|
+
2. Every `await sodax.moneyMarket.<method>(...)` has `if (!result.ok)` branching.
|
|
49
|
+
3. `instanceof MoneyMarketError` → `isSodaxError(e) && e.feature === 'moneyMarket'`.
|
|
50
|
+
|
|
51
|
+
## Related granular skills (same family)
|
|
52
|
+
|
|
53
|
+
- [`../backend-api/SKILL.md`](../backend-api/SKILL.md) — reads (`BackendApiService`) for user position, asset metadata, suppliers/borrowers lists.
|
|
54
|
+
- [`../swap/SKILL.md`](../swap/SKILL.md) — when supplying collateral that requires an upstream swap.
|
|
55
|
+
|
|
56
|
+
For multi-feature tasks, load the broad [`sodax-sdk` skill](../SKILL.md).
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: sodax-sdk-partner
|
|
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
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Partner (Core SDK granular skill)
|
|
11
|
+
|
|
12
|
+
Granular skill for `PartnerService` — `sodax.partners`. Operations live on `sodax.partners.feeClaim` (the parent only exposes `feeClaim` and `config`). Feature tag for errors: `'partner'`.
|
|
13
|
+
|
|
14
|
+
## Step 1 — Clarify with user before coding
|
|
15
|
+
|
|
16
|
+
1. **New code or v1 → v2 port?**
|
|
17
|
+
2. **Which operation?**
|
|
18
|
+
- One-time setup: `isTokenApproved` → `approveToken` → `setSwapPreference`.
|
|
19
|
+
- Recurring: `swap` (immediate) or `createIntentAutoSwap` (intent-driven auto-swap).
|
|
20
|
+
- Reads: `getAutoSwapPreferences`, `fetchAssetsBalances`.
|
|
21
|
+
3. **Signed flow or unsigned-tx?**
|
|
22
|
+
|
|
23
|
+
## Integration workflow
|
|
24
|
+
|
|
25
|
+
1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md).
|
|
26
|
+
2. [`../integration/knowledge/features/partner.md`](../integration/knowledge/features/partner.md) — `PartnerService` API, common call shape (approve → preference → swap).
|
|
27
|
+
3. Path-specific recipe:
|
|
28
|
+
- Signed → [`../integration/knowledge/recipes/signed-tx-flow.md`](../integration/knowledge/recipes/signed-tx-flow.md)
|
|
29
|
+
- Unsigned → [`../integration/knowledge/recipes/raw-tx-flow.md`](../integration/knowledge/recipes/raw-tx-flow.md)
|
|
30
|
+
4. Errors (`feature: 'partner'`) → [`../integration/knowledge/reference/error-codes.md`](../integration/knowledge/reference/error-codes.md).
|
|
31
|
+
|
|
32
|
+
### Partner-specific anti-patterns
|
|
33
|
+
|
|
34
|
+
- **Calling `sodax.partners.claimFees(...)`.** Method doesn't exist on `sodax.partners` directly — all fee-claim operations live on `sodax.partners.feeClaim`.
|
|
35
|
+
- **Skipping the `isTokenApproved` check before fee claim.** The partner's fee token must be approved on the hub once; subsequent claims reuse the allowance.
|
|
36
|
+
- **Forgetting to `setSwapPreference`.** Without an auto-swap preference, partner-collected fees stay in the original asset.
|
|
37
|
+
|
|
38
|
+
## Migration workflow (v1 → v2)
|
|
39
|
+
|
|
40
|
+
1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md).
|
|
41
|
+
2. [`../migration-v1-to-v2/knowledge/features/partner.md`](../migration-v1-to-v2/knowledge/features/partner.md) — drop `spokeProvider`, add `walletProvider`, `srcChainKey`, `srcAddress`. All 5 v1 typed errors collapse into `SodaxError<C>` with `feature: 'partner'`.
|
|
42
|
+
|
|
43
|
+
## Verification
|
|
44
|
+
|
|
45
|
+
1. `pnpm tsc --noEmit` clean.
|
|
46
|
+
2. Every `await sodax.partners.feeClaim.<method>(...)` has `if (!result.ok)`.
|
|
47
|
+
3. No `instanceof PartnerFeeClaimError` (or the 4 sibling v1 error classes).
|
|
48
|
+
|
|
49
|
+
## Related granular skills (same family)
|
|
50
|
+
|
|
51
|
+
- [`../recovery/SKILL.md`](../recovery/SKILL.md) — partner-collected funds stuck on the hub.
|
|
52
|
+
- [`../backend-api/SKILL.md`](../backend-api/SKILL.md) — backend HTTP client for tracking partner-claim intents.
|
|
53
|
+
- [`../swap/SKILL.md`](../swap/SKILL.md) — partner-fee `swap` and `createIntentAutoSwap` reuse the swap intent layer.
|
|
54
|
+
|
|
55
|
+
For multi-feature tasks, load the broad [`sodax-sdk` skill](../SKILL.md).
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: sodax-sdk-recovery
|
|
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
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Recovery (Core SDK granular skill)
|
|
11
|
+
|
|
12
|
+
Granular skill for `RecoveryService` — `sodax.recovery`. Feature tag for errors: `'recovery'`. Service is **new in v2** — no v1 equivalent.
|
|
13
|
+
|
|
14
|
+
## Step 1 — Clarify with user before coding
|
|
15
|
+
|
|
16
|
+
1. **What's the trigger?** Recovery should follow a *known* failed cross-chain operation. If the user can't name the failure, investigate the original op first.
|
|
17
|
+
2. **Which operation?**
|
|
18
|
+
- `fetchHubAssetBalances` (read; list stuck hub assets for the user).
|
|
19
|
+
- `withdrawHubAsset` (mutation; withdraw one entry back to a chosen spoke chain).
|
|
20
|
+
3. **Signed flow or unsigned-tx?** `withdrawHubAsset` follows the same `WalletProviderSlot<K, Raw>` pattern as other mutations.
|
|
21
|
+
|
|
22
|
+
## Integration workflow
|
|
23
|
+
|
|
24
|
+
1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md).
|
|
25
|
+
2. [`../integration/knowledge/features/recovery.md`](../integration/knowledge/features/recovery.md) — `RecoveryService` API + when-to-use guidance.
|
|
26
|
+
3. Path-specific recipe:
|
|
27
|
+
- Signed → [`../integration/knowledge/recipes/signed-tx-flow.md`](../integration/knowledge/recipes/signed-tx-flow.md)
|
|
28
|
+
- Unsigned → [`../integration/knowledge/recipes/raw-tx-flow.md`](../integration/knowledge/recipes/raw-tx-flow.md)
|
|
29
|
+
4. Errors (`feature: 'recovery'`) → [`../integration/knowledge/reference/error-codes.md`](../integration/knowledge/reference/error-codes.md).
|
|
30
|
+
|
|
31
|
+
### Recovery-specific anti-patterns
|
|
32
|
+
|
|
33
|
+
- **Treating recovery as a routine flow.** It's a workaround for failures; calling it on successfully completed flows wastes gas and confuses users.
|
|
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.
|
|
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?).
|
|
36
|
+
|
|
37
|
+
## Migration workflow (v1 → v2)
|
|
38
|
+
|
|
39
|
+
1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md).
|
|
40
|
+
2. [`../migration-v1-to-v2/knowledge/features/recovery.md`](../migration-v1-to-v2/knowledge/features/recovery.md) — service is new in v2; no port to do. If you have v1 workaround code that walked the hub wallet abstraction manually, replace it with `fetchHubAssetBalances` + `withdrawHubAsset`.
|
|
41
|
+
|
|
42
|
+
## Verification
|
|
43
|
+
|
|
44
|
+
1. `pnpm tsc --noEmit` clean.
|
|
45
|
+
2. Every `await sodax.recovery.<method>(...)` has `if (!result.ok)`.
|
|
46
|
+
3. Any v1 ad-hoc "find stuck assets" workaround code is removed.
|
|
47
|
+
|
|
48
|
+
## Related granular skills (same family)
|
|
49
|
+
|
|
50
|
+
- [`../swap/SKILL.md`](../swap/SKILL.md), [`../bridge/SKILL.md`](../bridge/SKILL.md), [`../money-market/SKILL.md`](../money-market/SKILL.md), etc. — the upstream features whose failures may strand assets.
|
|
51
|
+
- [`../backend-api/SKILL.md`](../backend-api/SKILL.md) — intent / tx lookups to diagnose the original failure before recovering.
|
|
52
|
+
|
|
53
|
+
For multi-feature tasks, load the broad [`sodax-sdk` skill](../SKILL.md).
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: sodax-sdk-staking
|
|
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
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Staking (Core SDK granular skill)
|
|
11
|
+
|
|
12
|
+
Granular skill for `StakingService` — `sodax.staking`. Feature tag: `'staking'`.
|
|
13
|
+
|
|
14
|
+
## Step 1 — Clarify with user before coding
|
|
15
|
+
|
|
16
|
+
1. **New code or v1 → v2 port?**
|
|
17
|
+
2. **Which operation?** `stake`, `unstake`, `instantUnstake` (penalty), `claim`, `cancelUnstake`.
|
|
18
|
+
3. **Cross-chain** (staking from a spoke chain) **or hub-side** (Sonic)? Staking from a spoke routes through the relay.
|
|
19
|
+
4. **Need user staking info?**
|
|
20
|
+
- From a **spoke** address (most consumer code): `getStakingInfoFromSpoke(srcAddress, srcChainKey)` — resolves spoke → hub then reads.
|
|
21
|
+
- From a **hub** address directly (already on Sonic): `getStakingInfo(hubAddress)`. Both are public reads on `StakingService`.
|
|
22
|
+
|
|
23
|
+
## Integration workflow
|
|
24
|
+
|
|
25
|
+
1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md).
|
|
26
|
+
2. [`../integration/knowledge/features/staking.md`](../integration/knowledge/features/staking.md) — `StakingService` API, penalty curve, instant-unstake slippage, claim flow.
|
|
27
|
+
3. Path-specific recipe:
|
|
28
|
+
- Signed → [`../integration/knowledge/recipes/signed-tx-flow.md`](../integration/knowledge/recipes/signed-tx-flow.md)
|
|
29
|
+
- Unsigned → [`../integration/knowledge/recipes/raw-tx-flow.md`](../integration/knowledge/recipes/raw-tx-flow.md)
|
|
30
|
+
4. Errors (`feature: 'staking'`) → [`../integration/knowledge/reference/error-codes.md`](../integration/knowledge/reference/error-codes.md).
|
|
31
|
+
|
|
32
|
+
### Staking-specific anti-patterns
|
|
33
|
+
|
|
34
|
+
- **Passing a spoke address to `getStakingInfo`.** It expects a hub address. Use `getStakingInfoFromSpoke(srcAddress, srcChainKey)` if you only have the spoke address — it derives the hub wallet internally.
|
|
35
|
+
- **Forgetting allowance before `stake`.** Like other action services, requires `approve` + `isAllowanceValid` flow.
|
|
36
|
+
|
|
37
|
+
## Migration workflow (v1 → v2)
|
|
38
|
+
|
|
39
|
+
1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md).
|
|
40
|
+
2. [`../migration-v1-to-v2/knowledge/features/staking.md`](../migration-v1-to-v2/knowledge/features/staking.md) — v1 `StakingError` → v2 `SodaxError<C>` with `feature: 'staking'`. If v1 code passed a spoke address into `getStakingInfo`, switch to `getStakingInfoFromSpoke(srcAddress, srcChainKey)` instead (v2 added it as the spoke-side wrapper; the hub-side `getStakingInfo(hubAddress)` is still public).
|
|
41
|
+
|
|
42
|
+
## Verification
|
|
43
|
+
|
|
44
|
+
1. `pnpm tsc --noEmit` clean.
|
|
45
|
+
2. Every `await sodax.staking.<method>(...)` has `if (!result.ok)`.
|
|
46
|
+
3. `getStakingInfo` call sites pass a hub address (not a spoke address); spoke-side reads use `getStakingInfoFromSpoke`.
|
|
47
|
+
|
|
48
|
+
## Related granular skills (same family)
|
|
49
|
+
|
|
50
|
+
- [`../migration/SKILL.md`](../migration/SKILL.md) — BALN → SODA migration also stakes (lockup periods 0–24 months); use it for BALN-specific lock flows.
|
|
51
|
+
- [`../recovery/SKILL.md`](../recovery/SKILL.md) — recovery for stuck staking-related assets.
|
|
52
|
+
|
|
53
|
+
For multi-feature tasks, load the broad [`sodax-sdk` skill](../SKILL.md).
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: sodax-sdk-swap
|
|
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
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Swap (Core SDK granular skill)
|
|
11
|
+
|
|
12
|
+
Granular skill for the swap feature of `@sodax/sdk` v2. Source-of-truth reference lives in the parent broad skill's knowledge tree — this file is the focused workflow only.
|
|
13
|
+
|
|
14
|
+
## Step 1 — Clarify with user before coding
|
|
15
|
+
|
|
16
|
+
Swap has materially different code paths depending on the answers. Don't skip:
|
|
17
|
+
|
|
18
|
+
1. **Are you writing new code, or porting v1 code to v2?**
|
|
19
|
+
- New code → § Integration workflow below.
|
|
20
|
+
- Port v1 → v2 → § Migration workflow.
|
|
21
|
+
2. **Signed flow (frontend wallet, browser/RN) or unsigned-tx flow (backend / custom relay)?**
|
|
22
|
+
- Signed → `raw: false` + `walletProvider`.
|
|
23
|
+
- Unsigned → `raw: true`, you handle relay yourself.
|
|
24
|
+
3. **One-shot `swap()` or step-by-step (`createIntent` → backend submit → `postExecution`)?**
|
|
25
|
+
- One-shot is the default for frontends. Step-by-step is for backends that already have a relay/orchestration layer.
|
|
26
|
+
4. **Market order or limit order?** Limit orders use a different params shape — `deadline` becomes optional (forced to `0n` internally), not required.
|
|
27
|
+
|
|
28
|
+
## Integration workflow (writing new v2 swap code)
|
|
29
|
+
|
|
30
|
+
Read in order. Skipping `ai-rules.md` is the most common cause of agents reverting to v1 patterns.
|
|
31
|
+
|
|
32
|
+
1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT list.
|
|
33
|
+
2. [`../integration/knowledge/features/swap.md`](../integration/knowledge/features/swap.md) — `SwapService` API surface, action params, return shapes, error codes (`feature: 'swap'`).
|
|
34
|
+
3. Path-specific recipe:
|
|
35
|
+
- Signed one-shot → [`../integration/knowledge/recipes/signed-tx-flow.md`](../integration/knowledge/recipes/signed-tx-flow.md)
|
|
36
|
+
- Backend step-by-step → [`../integration/knowledge/recipes/raw-tx-flow.md`](../integration/knowledge/recipes/raw-tx-flow.md) + [`../integration/knowledge/recipes/backend-server-init.md`](../integration/knowledge/recipes/backend-server-init.md)
|
|
37
|
+
4. Error handling for swap-specific codes (`INTENT_CREATION_FAILED`, `EXECUTION_FAILED`, `RELAY_TIMEOUT`, solver-side `EXTERNAL_API_ERROR`) → [`../integration/knowledge/recipes/result-and-errors.md`](../integration/knowledge/recipes/result-and-errors.md) and [`../integration/knowledge/reference/error-codes.md`](../integration/knowledge/reference/error-codes.md).
|
|
38
|
+
5. Cross-chain destination quirks (Stellar trustline, BTC PSBT, Solana PDA) → [`../integration/knowledge/chain-specifics.md`](../integration/knowledge/chain-specifics.md).
|
|
39
|
+
|
|
40
|
+
### Swap-specific anti-patterns
|
|
41
|
+
|
|
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`.
|
|
43
|
+
- **Forgetting the discriminator.** `raw: false` is required on signed swaps; without it TypeScript rejects `walletProvider`.
|
|
44
|
+
- **Calling `sodax.api.swaps.submitTx` with the full `relayData` object.** The backend expects the `payload: string` field, not the wrapper.
|
|
45
|
+
|
|
46
|
+
## Migration workflow (port v1 swap to v2)
|
|
47
|
+
|
|
48
|
+
1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md) — DO / DO NOT (read first).
|
|
49
|
+
2. [`../migration-v1-to-v2/knowledge/features/swap.md`](../migration-v1-to-v2/knowledge/features/swap.md) — v1 → v2 swap port playbook.
|
|
50
|
+
3. Cross-cutting renames (apply repo-wide before swap-specific edits) → [`../migration-v1-to-v2/knowledge/breaking-changes/type-system.md`](../migration-v1-to-v2/knowledge/breaking-changes/type-system.md).
|
|
51
|
+
4. Error code crosswalk (v1 `IntentError` → v2 `SodaxError<C>` with `feature: 'swap'`) → [`../migration-v1-to-v2/knowledge/reference/error-code-crosswalk.md`](../migration-v1-to-v2/knowledge/reference/error-code-crosswalk.md).
|
|
52
|
+
|
|
53
|
+
## Verification
|
|
54
|
+
|
|
55
|
+
1. `pnpm tsc --noEmit` from the consumer repo exits clean.
|
|
56
|
+
2. Every `await sodax.swaps.<method>(...)` call site has `if (!result.ok)` branching.
|
|
57
|
+
3. No `xToken.xChainId`, no `*_MAINNET_CHAIN_ID`, no `*SpokeProvider` references (migration only).
|
|
58
|
+
4. `isSodaxError(e)` (not bare `instanceof SodaxError`) in cross-bundle code.
|
|
59
|
+
|
|
60
|
+
## Related granular skills (same family)
|
|
61
|
+
|
|
62
|
+
- [`../money-market/SKILL.md`](../money-market/SKILL.md) — if the swap is followed by a supply/borrow action.
|
|
63
|
+
- [`../partner/SKILL.md`](../partner/SKILL.md) — partner fees on swap.
|
|
64
|
+
- [`../recovery/SKILL.md`](../recovery/SKILL.md) — stuck-asset recovery for failed swaps.
|
|
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.
|
|
67
|
+
|
|
68
|
+
For tasks spanning multiple features, load the broad [`sodax-sdk` skill](../SKILL.md) instead.
|
|
69
|
+
|
|
70
|
+
## Wallet provider (different SDK package family)
|
|
71
|
+
|
|
72
|
+
This skill treats `walletProvider` as a contract (`IEvmWalletProvider` etc.) — it does not instantiate one. For Node bots / scripts / non-React backends that need a wallet implementation (private-key EVM, Solana keypair, Stellar SDK, etc.), **also load the `sodax-wallet-sdk-core` skill (integration mode)**. That package ships ready-made `I*WalletProvider` classes for all 9 chain families.
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: sodax-sdk-swaps-api
|
|
3
|
+
description: 'Granular skill for the @sodax/sdk v2 Swaps API client — `sodax.api.swaps` (class SwapsApiService), a typed HTTP client for the backend Swaps API v2 (`/swaps/*`, 21 endpoints: quote, deadline, allowance/approve, create-intent, intent submit/status/cancel/hash/packet/extra-data, limit orders, gas estimate, partner/solver fees, submit-tx + status). Every method returns Promise<Result<T>>, never throws, and validates the response. Use when the task calls the swaps backend directly (e.g. "get a swap quote from the Sodax backend", "sodax.api.swaps", "submit swap tx", "createIntent via the backend API", "poll submit-tx status", "swaps API v2", "point swaps at a custom endpoint"). For the higher-level end-to-end swap orchestrator use the `swap` skill instead. Skill links into the parent sodax-sdk knowledge tree.'
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Swaps API (Core SDK granular skill)
|
|
7
|
+
|
|
8
|
+
Granular skill for `sodax.api.swaps` (class `SwapsApiService`) — the typed HTTP client for the backend
|
|
9
|
+
**Swaps API v2** (`/swaps/*`). `sodax.api` is an alias for `sodax.backendApi`; `.swaps` is the swaps
|
|
10
|
+
client. 21 endpoints, one method each; every method returns `Promise<Result<T>>` (never throws) and
|
|
11
|
+
validates the response. Errors carry `feature: 'backend'`, `context.api: 'swaps'`, `context.endpoint`.
|
|
12
|
+
|
|
13
|
+
> Lower-level than `sodax.swaps`: this is the raw backend HTTP surface. For the end-to-end
|
|
14
|
+
> create→relay→post-execution swap orchestrator, use the [`swap`](../swap/SKILL.md) skill.
|
|
15
|
+
|
|
16
|
+
## Step 1 — Clarify with user before coding
|
|
17
|
+
|
|
18
|
+
1. **Which endpoint(s)?** Tokens · quote/deadline · allowance/approve/create-intent · intent lifecycle
|
|
19
|
+
(submit/status/cancel/hash/packet/extra-data/fill/get) · limit-orders/gas/fees · submit-tx/status.
|
|
20
|
+
2. **Orchestrator or raw API?** If the user just wants "do a swap", prefer `sodax.swaps` (the `swap`
|
|
21
|
+
skill). Use `sodax.api.swaps` when they need a single backend call (a quote, a fee, a status poll) or
|
|
22
|
+
are building their own flow.
|
|
23
|
+
3. **Custom endpoint?** Does the swaps API live at a different host than the base backend API? If so, the
|
|
24
|
+
`CustomApiConfig` variant is needed (see anti-patterns + the feature doc).
|
|
25
|
+
|
|
26
|
+
## Integration workflow
|
|
27
|
+
|
|
28
|
+
1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT (read first).
|
|
29
|
+
2. [`../integration/knowledge/features/swaps-api.md`](../integration/knowledge/features/swaps-api.md) — the full 21-endpoint client: signatures, wire shapes (bigint vs decimal string), common call shapes (quote, create-intent, submit-tx + status), per-call overrides, custom endpoint.
|
|
30
|
+
3. For the end-to-end swap flow that wraps these calls → [`../integration/knowledge/features/swap.md`](../integration/knowledge/features/swap.md); for the sibling read client (`sodax.backendApi`) → [`../integration/knowledge/features/backend-api.md`](../integration/knowledge/features/backend-api.md).
|
|
31
|
+
4. Errors are `Result<T, SodaxError<'EXTERNAL_API_ERROR'>>` → [`../integration/knowledge/recipes/result-and-errors.md`](../integration/knowledge/recipes/result-and-errors.md) and [`../integration/knowledge/reference/error-codes.md`](../integration/knowledge/reference/error-codes.md).
|
|
32
|
+
|
|
33
|
+
### Swaps-API-specific anti-patterns
|
|
34
|
+
|
|
35
|
+
- **`try/catch` for failures.** Every method returns `Result<T>` — branch on `result.ok`. `catch` won't fire for HTTP/timeout/validation failures.
|
|
36
|
+
- **Passing the `RelayExtraData` object** to `submitTx`'s `relayData`. The field is a `string` — pass `relayData.payload`.
|
|
37
|
+
- **Stringifying `intent` numerics yourself.** `IntentRequestV2` fields are `bigint`; the client serializes them to decimal strings — pass the bigint intent through as-is.
|
|
38
|
+
- **Calling `getSubmitTxStatus` with only `txHash`.** Both `txHash` AND `srcChainKey` are required.
|
|
39
|
+
- **Confusing `sodax.api.swaps` with `sodax.swaps`.** The former is the backend HTTP client; the latter is the on-chain intent orchestrator.
|
|
40
|
+
|
|
41
|
+
## Migration workflow (v1 → v2)
|
|
42
|
+
|
|
43
|
+
The typed `sodax.api.swaps` client is **v2-new** (v1 had no equivalent typed swaps client — quotes went
|
|
44
|
+
through the solver and submit-tx lived on `sodax.backendApi.submitSwapTx`). The relevant v1 → v2 deltas it
|
|
45
|
+
builds on are covered in the existing swap + backend-api migration docs:
|
|
46
|
+
|
|
47
|
+
1. [`../migration-v1-to-v2/knowledge/features/swap.md`](../migration-v1-to-v2/knowledge/features/swap.md) — create-intent / submit-tx request-shape changes (`srcChainId` → `srcChainKey`, `relayData` object → string, bigint intent).
|
|
48
|
+
2. [`../migration-v1-to-v2/knowledge/features/backend-api.md`](../migration-v1-to-v2/knowledge/features/backend-api.md) — submit-tx moved off `BackendApiService` onto `sodax.api.swaps.submitTx`, and the `Result`-wrapping contract.
|
|
49
|
+
|
|
50
|
+
## Verification
|
|
51
|
+
|
|
52
|
+
1. `pnpm tsc --noEmit` clean.
|
|
53
|
+
2. Every `await sodax.api.swaps.<method>(...)` call site has `if (!result.ok)`.
|
|
54
|
+
3. `submitTx.relayData` is `relayData.payload` (string); `getSubmitTxStatus` passes both `txHash` and `srcChainKey`.
|
|
55
|
+
4. Intent-bearing bodies pass the `bigint` `IntentRequestV2` through unmodified (no manual `.toString()`).
|
|
56
|
+
|
|
57
|
+
## Related granular skills (same family)
|
|
58
|
+
|
|
59
|
+
- [`../swap/SKILL.md`](../swap/SKILL.md) — the end-to-end swap orchestrator (`sodax.swaps`) that wraps these backend calls.
|
|
60
|
+
- [`../backend-api/SKILL.md`](../backend-api/SKILL.md) — the sibling `sodax.backendApi` read client (intent / orderbook / money-market reads + config).
|
|
61
|
+
|
|
62
|
+
For multi-feature tasks, load the broad [`sodax-sdk` skill](../SKILL.md).
|
|
@@ -1,6 +1,10 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: sodax-wallet-sdk-core
|
|
3
|
-
description: '
|
|
3
|
+
description: 'Sign and broadcast SODAX transactions from a backend, script, CI, bot, or non-React app with @sodax/wallet-sdk-core — one wallet-provider class per chain family (EVM, Solana, Sui, Bitcoin, Stellar, ICON, Injective, NEAR, Stacks). INTEGRATION (write NEW code) — the low-level multi-chain wallet layer (one provider class per chain family across 9 chain types). Each class accepts either a private-key config (Node scripts, CI, bots, indexers) or a browser-extension config (custom non-React browser flows) and signs + broadcasts transactions. Use whenever a backend, script, test, or non-React browser flow needs to instantiate a wallet provider directly — `EvmWalletProvider`, `SolanaWalletProvider`, etc. Triggers on "instantiate EvmWalletProvider", "sign a tx from a Node script", "wallet provider for backend", "private-key signing", "wallet-sdk-core setup", any `*WalletProvider` class name. For React dapps prefer `sodax-wallet-sdk-react` instead — most React consumers never touch this package directly and get a typed `IXxxWalletProvider` via `useWalletProvider(...)`. MIGRATION (port v1 → v2) — v1 → v2 changes are additive (same class names, same config-type names, same config shapes). The only mechanical migration is replacing deep imports from v1''s flat `wallet-providers/<chain>.ts` layout with barrel imports, plus optionally adopting the new `defaults` field and re-imported library types. Triggers on imports from `@sodax/wallet-sdk-core/wallet-providers/…`, bumping from an older RC, or adopting new additive `defaults` / `*WalletDefaults` / `*Policy` fields. Most projects don''t need a wallet-sdk-core migration — the real migration target is usually `@sodax/sdk` or `@sodax/types`. Load this skill if EITHER applies; the body gates by mode.'
|
|
4
|
+
license: MIT
|
|
5
|
+
metadata:
|
|
6
|
+
version: '0.0.1'
|
|
7
|
+
author: sodax
|
|
4
8
|
---
|
|
5
9
|
|
|
6
10
|
# When to use this skill
|
|
@@ -27,7 +31,7 @@ Direct usage of `@sodax/wallet-sdk-core` is the right choice for:
|
|
|
27
31
|
### Workflow
|
|
28
32
|
|
|
29
33
|
1. Read [`integration/knowledge/ai-rules.md`](./integration/knowledge/ai-rules.md) — DO / DON'T + workflow + stop conditions.
|
|
30
|
-
2. Read [`integration/knowledge/architecture.md`](./integration/knowledge/architecture.md) — mental model: `BaseWalletProvider`, dual-config discriminants (
|
|
34
|
+
2. Read [`integration/knowledge/architecture.md`](./integration/knowledge/architecture.md) — mental model: `BaseWalletProvider`, dual-config discriminants (Bitcoin/Stellar via an explicit `type` field, every other chain via field presence), shallow `defaults` merge, library-exports.
|
|
31
35
|
3. Read [`integration/knowledge/quickstart.md`](./integration/knowledge/quickstart.md) — copy-paste minimal example for the chain you need.
|
|
32
36
|
4. For your chain, read [`integration/knowledge/features/`](./integration/knowledge/features/) — per-chain config table + methods + gotchas (one file per chain family).
|
|
33
37
|
5. Task-specific recipes → [`integration/knowledge/recipes/`](./integration/knowledge/recipes/) — `setup-private-key.md`, `setup-browser-extension.md`, `sign-and-broadcast.md`, `defaults-and-overrides.md`, `library-exports.md`, `bridge-to-sdk.md` (pass provider to `@sodax/sdk`).
|
|
@@ -35,7 +39,7 @@ Direct usage of `@sodax/wallet-sdk-core` is the right choice for:
|
|
|
35
39
|
|
|
36
40
|
### Conventions to follow (integration)
|
|
37
41
|
|
|
38
|
-
- **Dual-config discriminant.**
|
|
42
|
+
- **Dual-config discriminant.** **Bitcoin and Stellar** configs carry an explicit `type` discriminator (`'PRIVATE_KEY'` for Node / scripts or `'BROWSER_EXTENSION'` for consumer dApps); **every other chain** (EVM, Solana, Sui, ICON, Injective, NEAR, Stacks) discriminates by field presence (e.g. `privateKey` vs `walletClient`/`wallet`). Either way, pick ONE variant — don't merge them.
|
|
39
43
|
- **`defaults` is a shallow merge.** Each provider accepts a `defaults` field for per-method overrides (e.g. `waitForTransactionReceipt`, `gasPrice`). The merge into the per-call options is **shallow**, not deep. Top-level keys overwrite wholesale.
|
|
40
44
|
- **Use barrel imports**, not deep imports. Import classes from `@sodax/wallet-sdk-core`, not from `@sodax/wallet-sdk-core/wallet-providers/<chain>.ts`.
|
|
41
45
|
- **Re-import chain SDK types from the barrel.** `@sodax/wallet-sdk-core` re-exports the types you need (e.g. `WalletClient` from viem, `SuiClient` from `@mysten/sui`). Don't add the underlying SDK as a direct dep — risks version skew.
|