@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.
Files changed (168) hide show
  1. package/.claude-plugin/plugin.json +1 -0
  2. package/AGENTS.md +123 -13
  3. package/README.md +5 -2
  4. package/package.json +1 -1
  5. package/skills/sodax-build/SKILL.md +90 -0
  6. package/skills/sodax-build/knowledge/README.md +35 -0
  7. package/skills/sodax-build/knowledge/brief-template.md +41 -0
  8. package/skills/sodax-build/knowledge/chains-and-assets.md +26 -0
  9. package/skills/sodax-build/knowledge/example-sessions.md +84 -0
  10. package/skills/sodax-build/knowledge/feature-catalog.md +51 -0
  11. package/skills/sodax-build/knowledge/glossary.md +35 -0
  12. package/skills/sodax-build/knowledge/handoff.md +60 -0
  13. package/skills/sodax-build/knowledge/interview-guide.md +66 -0
  14. package/skills/sodax-build/knowledge/monetization.md +37 -0
  15. package/skills/sodax-build/knowledge/use-case-gallery.md +32 -0
  16. package/skills/sodax-dapp-kit/SKILL.md +6 -2
  17. package/skills/sodax-dapp-kit/auxiliary-services/SKILL.md +65 -0
  18. package/skills/sodax-dapp-kit/bitcoin/SKILL.md +57 -0
  19. package/skills/sodax-dapp-kit/bridge/SKILL.md +59 -0
  20. package/skills/sodax-dapp-kit/dex/SKILL.md +60 -0
  21. package/skills/sodax-dapp-kit/integration/knowledge/README.md +1 -1
  22. package/skills/sodax-dapp-kit/integration/knowledge/features/README.md +3 -2
  23. package/skills/sodax-dapp-kit/integration/knowledge/features/auxiliary-services.md +71 -11
  24. package/skills/sodax-dapp-kit/integration/knowledge/features/bitcoin.md +10 -6
  25. package/skills/sodax-dapp-kit/integration/knowledge/features/dex.md +2 -2
  26. package/skills/sodax-dapp-kit/integration/knowledge/features/leverage-yield.md +112 -0
  27. package/skills/sodax-dapp-kit/integration/knowledge/features/migration.md +1 -1
  28. package/skills/sodax-dapp-kit/integration/knowledge/features/money-market.md +6 -1
  29. package/skills/sodax-dapp-kit/integration/knowledge/features/swap.md +1 -1
  30. package/skills/sodax-dapp-kit/integration/knowledge/quickstart.md +2 -2
  31. package/skills/sodax-dapp-kit/integration/knowledge/recipes/README.md +1 -0
  32. package/skills/sodax-dapp-kit/integration/knowledge/recipes/backend-queries.md +23 -8
  33. package/skills/sodax-dapp-kit/integration/knowledge/recipes/bitcoin.md +8 -8
  34. package/skills/sodax-dapp-kit/integration/knowledge/recipes/leverage-yield.md +168 -0
  35. package/skills/sodax-dapp-kit/integration/knowledge/recipes/migration.md +1 -1
  36. package/skills/sodax-dapp-kit/integration/knowledge/recipes/setup.md +4 -4
  37. package/skills/sodax-dapp-kit/integration/knowledge/recipes/swap.md +1 -1
  38. package/skills/sodax-dapp-kit/integration/knowledge/recipes/wallet-connectivity.md +3 -0
  39. package/skills/sodax-dapp-kit/integration/knowledge/reference/glossary.md +1 -1
  40. package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md +67 -6
  41. package/skills/sodax-dapp-kit/integration/knowledge/reference/querykey-conventions.md +49 -0
  42. package/skills/sodax-dapp-kit/leverage-yield/SKILL.md +54 -0
  43. package/skills/sodax-dapp-kit/migration/SKILL.md +64 -0
  44. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md +1 -1
  45. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md +2 -2
  46. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/checklist.md +1 -1
  47. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/README.md +1 -1
  48. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/auxiliary-services.md +19 -10
  49. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/bitcoin.md +2 -2
  50. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/bridge.md +1 -1
  51. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/dex.md +1 -1
  52. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/migration.md +1 -1
  53. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/reference/renamed-hooks.md +3 -3
  54. package/skills/sodax-dapp-kit/money-market/SKILL.md +61 -0
  55. package/skills/sodax-dapp-kit/staking/SKILL.md +60 -0
  56. package/skills/sodax-dapp-kit/swap/SKILL.md +64 -0
  57. package/skills/sodax-sdk/SKILL.md +54 -50
  58. package/skills/sodax-sdk/backend-api/SKILL.md +58 -0
  59. package/skills/sodax-sdk/bridge/SKILL.md +53 -0
  60. package/skills/sodax-sdk/dex/SKILL.md +54 -0
  61. package/skills/sodax-sdk/integration/knowledge/README.md +5 -3
  62. package/skills/sodax-sdk/integration/knowledge/ai-rules.md +1 -1
  63. package/skills/sodax-sdk/integration/knowledge/architecture.md +26 -39
  64. package/skills/sodax-sdk/integration/knowledge/chain-specifics.md +57 -10
  65. package/skills/sodax-sdk/integration/knowledge/features/README.md +6 -3
  66. package/skills/sodax-sdk/integration/knowledge/features/backend-api.md +92 -0
  67. package/skills/sodax-sdk/integration/knowledge/features/bridge.md +48 -11
  68. package/skills/sodax-sdk/integration/knowledge/features/dex.md +7 -7
  69. package/skills/sodax-sdk/integration/knowledge/features/leverage-yield.md +175 -0
  70. package/skills/sodax-sdk/integration/knowledge/features/{icx-bnusd-baln.md → migration.md} +75 -30
  71. package/skills/sodax-sdk/integration/knowledge/features/money-market.md +20 -25
  72. package/skills/sodax-sdk/integration/knowledge/features/partner.md +86 -0
  73. package/skills/sodax-sdk/integration/knowledge/features/recovery.md +51 -0
  74. package/skills/sodax-sdk/integration/knowledge/features/staking.md +8 -3
  75. package/skills/sodax-sdk/integration/knowledge/features/swap.md +106 -22
  76. package/skills/sodax-sdk/integration/knowledge/features/swaps-api.md +171 -0
  77. package/skills/sodax-sdk/integration/knowledge/quickstart.md +1 -1
  78. package/skills/sodax-sdk/integration/knowledge/recipes/README.md +1 -0
  79. package/skills/sodax-sdk/integration/knowledge/recipes/backend-server-init.md +3 -3
  80. package/skills/sodax-sdk/integration/knowledge/recipes/gas-estimation.md +8 -4
  81. package/skills/sodax-sdk/integration/knowledge/recipes/initialize-sodax.md +34 -2
  82. package/skills/sodax-sdk/integration/knowledge/recipes/logging.md +102 -0
  83. package/skills/sodax-sdk/integration/knowledge/recipes/raw-tx-flow.md +28 -4
  84. package/skills/sodax-sdk/integration/knowledge/recipes/result-and-errors.md +1 -1
  85. package/skills/sodax-sdk/integration/knowledge/recipes/testing.md +7 -11
  86. package/skills/sodax-sdk/integration/knowledge/reference/README.md +1 -1
  87. package/skills/sodax-sdk/integration/knowledge/reference/chain-keys.md +40 -4
  88. package/skills/sodax-sdk/integration/knowledge/reference/error-codes.md +32 -9
  89. package/skills/sodax-sdk/integration/knowledge/reference/glossary.md +2 -2
  90. package/skills/sodax-sdk/integration/knowledge/reference/public-api.md +37 -4
  91. package/skills/sodax-sdk/leverage-yield/SKILL.md +50 -0
  92. package/skills/sodax-sdk/migration/SKILL.md +69 -0
  93. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/README.md +1 -1
  94. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/ai-rules.md +6 -10
  95. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/architecture.md +2 -2
  96. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/result-and-errors.md +3 -3
  97. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/type-system.md +6 -5
  98. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/checklist.md +2 -2
  99. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/README.md +4 -2
  100. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/backend-api.md +92 -0
  101. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/bridge.md +5 -5
  102. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/dex.md +2 -4
  103. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/{icx-bnusd-baln.md → migration.md} +31 -29
  104. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/money-market.md +2 -2
  105. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/partner.md +64 -0
  106. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/recovery.md +35 -0
  107. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/staking.md +8 -3
  108. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/swap.md +22 -18
  109. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/reference/sodax-config.md +19 -17
  110. package/skills/sodax-sdk/money-market/SKILL.md +56 -0
  111. package/skills/sodax-sdk/partner/SKILL.md +55 -0
  112. package/skills/sodax-sdk/recovery/SKILL.md +53 -0
  113. package/skills/sodax-sdk/staking/SKILL.md +53 -0
  114. package/skills/sodax-sdk/swap/SKILL.md +72 -0
  115. package/skills/sodax-sdk/swaps-api/SKILL.md +62 -0
  116. package/skills/sodax-wallet-sdk-core/SKILL.md +7 -3
  117. package/skills/sodax-wallet-sdk-core/bitcoin/SKILL.md +54 -0
  118. package/skills/sodax-wallet-sdk-core/evm/SKILL.md +54 -0
  119. package/skills/sodax-wallet-sdk-core/icon/SKILL.md +54 -0
  120. package/skills/sodax-wallet-sdk-core/injective/SKILL.md +54 -0
  121. package/skills/sodax-wallet-sdk-core/integration/knowledge/README.md +1 -1
  122. package/skills/sodax-wallet-sdk-core/integration/knowledge/ai-rules.md +2 -2
  123. package/skills/sodax-wallet-sdk-core/integration/knowledge/architecture.md +5 -5
  124. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/bitcoin.md +2 -2
  125. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/evm.md +2 -2
  126. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/icon.md +5 -5
  127. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/injective.md +4 -2
  128. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/near.md +1 -1
  129. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/solana.md +2 -2
  130. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/stacks.md +2 -2
  131. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/stellar.md +2 -2
  132. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/sui.md +1 -1
  133. package/skills/sodax-wallet-sdk-core/integration/knowledge/quickstart.md +1 -1
  134. package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/setup-private-key.md +2 -2
  135. package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/sign-and-broadcast.md +1 -0
  136. package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/testing.md +1 -1
  137. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/chain-support.md +3 -2
  138. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/interfaces.md +7 -5
  139. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/provider-classes.md +2 -2
  140. package/skills/sodax-wallet-sdk-core/migration-v1-to-v2/knowledge/README.md +1 -1
  141. package/skills/sodax-wallet-sdk-core/near/SKILL.md +54 -0
  142. package/skills/sodax-wallet-sdk-core/solana/SKILL.md +54 -0
  143. package/skills/sodax-wallet-sdk-core/stacks/SKILL.md +53 -0
  144. package/skills/sodax-wallet-sdk-core/stellar/SKILL.md +54 -0
  145. package/skills/sodax-wallet-sdk-core/sui/SKILL.md +53 -0
  146. package/skills/sodax-wallet-sdk-react/SKILL.md +5 -3
  147. package/skills/sodax-wallet-sdk-react/bridge-to-sdk/SKILL.md +56 -0
  148. package/skills/sodax-wallet-sdk-react/connect/SKILL.md +59 -0
  149. package/skills/sodax-wallet-sdk-react/integration/knowledge/architecture.md +3 -3
  150. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/chain-detection.md +1 -1
  151. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/connect-button.md +1 -1
  152. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/sign-message.md +10 -10
  153. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/switch-chain.md +1 -1
  154. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/api-surface.md +4 -4
  155. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/chain-support.md +4 -4
  156. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/connectors.md +1 -1
  157. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/hooks.md +5 -4
  158. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/wallet-brands.md +1 -1
  159. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/ai-rules.md +1 -1
  160. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/recipes/multi-chain-modal.md +57 -31
  161. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/recipes/ssr-setup.md +24 -19
  162. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/reference/config.md +1 -1
  163. package/skills/sodax-wallet-sdk-react/sign-message/SKILL.md +51 -0
  164. package/skills/sodax-wallet-sdk-react/switch-chain/SKILL.md +51 -0
  165. package/skills/sodax-wallet-sdk-react/wallet-modal/SKILL.md +54 -0
  166. package/skills/sodax-wallet-sdk-react/walletconnect/SKILL.md +52 -0
  167. package/skills/sodax-sdk/integration/knowledge/features/auxiliary-services.md +0 -189
  168. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/auxiliary-services.md +0 -156
@@ -0,0 +1,102 @@
1
+ # Logging
2
+
3
+ The SDK routes all of its internal diagnostics through a single `SodaxLogger` instead of calling
4
+ `console.*` directly. Pick a preset or forward to a structured sink (Sentry, Pino, Datadog, …) without
5
+ patching globals.
6
+
7
+ ## Select a logger at construction
8
+
9
+ `logger` is a `Sodax` constructor option — a field on `SodaxOptions` (the constructor's parameter
10
+ type), kept off the `SodaxConfig` data contract because it is a client-side sink, not backend-fetched
11
+ config. It accepts a preset name or a custom implementation:
12
+
13
+ ```ts
14
+ import { Sodax } from '@sodax/sdk';
15
+
16
+ new Sodax(); // default — same as { logger: 'console' }
17
+ new Sodax({ logger: 'console' }); // mirror console.* output
18
+ new Sodax({ logger: 'silent' }); // drop all SDK logs
19
+ ```
20
+
21
+ The logger is resolved **once** at construction and held on `ConfigService` outside the swappable
22
+ dynamic config (read it back as `sodax.config.logger`). `await sodax.config.initialize()` fetches fresh
23
+ chain config from the backend but **never** replaces the logger — the backend cannot set or overwrite
24
+ it.
25
+
26
+ > Combine with the other constructor options freely — pass `logger` alongside `chains` / `api` /
27
+ > `solver` overrides in the same object. The constructor splits `logger` off the data override before
28
+ > merging, so it never lands in `sodax.instanceConfig`. See [`initialize-sodax.md`](initialize-sodax.md).
29
+
30
+ ## Custom sink
31
+
32
+ Implement the `SodaxLogger` interface and pass the instance:
33
+
34
+ ```ts
35
+ import { Sodax, type SodaxLogger } from '@sodax/sdk';
36
+
37
+ const sentryLogger: SodaxLogger = {
38
+ debug: (message, data) => Sentry.addBreadcrumb({ level: 'debug', message, data }),
39
+ info: (message, data) => Sentry.addBreadcrumb({ level: 'info', message, data }),
40
+ warn: (message, data) => Sentry.captureMessage(message, { level: 'warning', extra: data }),
41
+ error: (message, error, data) =>
42
+ error !== undefined
43
+ ? Sentry.captureException(error, { extra: { message, ...data } })
44
+ : Sentry.captureMessage(message, { level: 'error', extra: data }),
45
+ };
46
+
47
+ const sodax = new Sodax({ logger: sentryLogger });
48
+ ```
49
+
50
+ ## Interface
51
+
52
+ ```ts
53
+ import type { SodaxLogger, SodaxLoggerOption } from '@sodax/sdk';
54
+
55
+ // SodaxLogger:
56
+ // debug(message: string, data?: Record<string, unknown>): void;
57
+ // info(message: string, data?: Record<string, unknown>): void;
58
+ // warn(message: string, data?: Record<string, unknown>): void;
59
+ // error(message: string, error?: unknown, data?: Record<string, unknown>): void;
60
+ //
61
+ // SodaxLoggerOption = SodaxLogger | 'console' | 'silent';
62
+ ```
63
+
64
+ `error()` takes the thrown value as a separate second argument (before structured `data`) so adapters
65
+ can attach it as the exception — `warn` / `info` / `debug` take only `(message, data?)`. SDK errors are
66
+ `SodaxError` instances; their `toJSON()` is the canonical serialization surface (`JSON.stringify(error)`
67
+ invokes it automatically). For routing a failed `Result<T>`'s `error` into a sink, see the **Logging**
68
+ section of [`result-and-errors.md`](result-and-errors.md).
69
+
70
+ ## Built-in loggers and resolver
71
+
72
+ `consoleLogger`, `silentLogger`, and `resolveLogger(option)` are exported from `@sodax/sdk` for
73
+ composition — e.g. wrapping the console logger to add a prefix, or resolving a preset name yourself:
74
+
75
+ ```ts
76
+ import { consoleLogger, resolveLogger, type SodaxLogger } from '@sodax/sdk';
77
+
78
+ // Wrap the default to add a prefix
79
+ const prefixed: SodaxLogger = {
80
+ debug: (m, d) => consoleLogger.debug(`[sodax] ${m}`, d),
81
+ info: (m, d) => consoleLogger.info(`[sodax] ${m}`, d),
82
+ warn: (m, d) => consoleLogger.warn(`[sodax] ${m}`, d),
83
+ error: (m, e, d) => consoleLogger.error(`[sodax] ${m}`, e, d),
84
+ };
85
+
86
+ // Resolve a preset name to a concrete logger
87
+ const resolved = resolveLogger('silent'); // → silentLogger
88
+ ```
89
+
90
+ ## Coverage
91
+
92
+ All instance feature services (swap, bridge, money market, DEX, staking, partner, recovery, the spoke
93
+ services), `BackendApiService`, and the solver API client route through the configured logger. A small
94
+ number of pure utility / static-helper functions still call `console.*` directly because they have no
95
+ access to the instance logger.
96
+
97
+ ## Cross-references
98
+
99
+ - [`README.md`](README.md) — recipe index.
100
+ - [`initialize-sodax.md`](initialize-sodax.md) — the constructor options object `logger` lives in.
101
+ - [`result-and-errors.md`](result-and-errors.md) — routing a failed `Result<T>` into a logging sink.
102
+ - [`../reference/public-api.md`](../reference/public-api.md) — exported logger symbols.
@@ -18,6 +18,31 @@ const { tx, intent, relayData } = result.value;
18
18
  // - …
19
19
  ```
20
20
 
21
+ ### Chain-specific raw inputs (`extras`)
22
+
23
+ Some chains need a per-action input on the **raw** path, supplied via the chain-key-gated `extras` slot:
24
+
25
+ - **Stacks** (`raw: true`): `extras.srcPublicKey` is **required** — the unsigned source tx is built from the signer public key (a `SP…` address can't yield it). Omitting it fails fast with a `VALIDATION_FAILED` `SodaxError` before any network call.
26
+ - **Bitcoin** TRADING mode (`raw: true`): `extras.bound.accessToken` carries a Bound Exchange token so the PSBT build authenticates (`bound` is the Bitcoin-gated slot that groups Bound/Radfi inputs). It falls back to the RadfiProvider instance token (`new Sodax({ ... })` with `radfi.accessToken`, or `radfi.setRadfiAccessToken(token)`) when omitted; with no token anywhere the call fails with a legible `RadfiApiError`.
27
+
28
+ ```ts
29
+ // Stacks raw intent — srcPublicKey is mandatory:
30
+ await sodax.swaps.createIntent({
31
+ params: { ...params, srcChainKey: ChainKeys.STACKS_MAINNET },
32
+ extras: { srcPublicKey },
33
+ raw: true,
34
+ });
35
+
36
+ // Bitcoin raw intent (TRADING) — bound.accessToken (or a seeded radfi token):
37
+ await sodax.swaps.createIntent({
38
+ params: { ...params, srcChainKey: ChainKeys.BITCOIN_MAINNET },
39
+ extras: { bound: { accessToken } },
40
+ raw: true,
41
+ });
42
+ ```
43
+
44
+ > **Note (Bitcoin):** even on the `raw: true` path, a Bitcoin TRADING intent makes a live Bound Exchange call to resolve the trading-wallet address (`getEffectiveWalletAddress`) before the PSBT is built. The unsigned PSBT is returned for you to sign offline, but the address lookup is **not** offline — Bound must be reachable, and a valid `accessToken` (per-action or seeded) is required for it.
45
+
21
46
  Submit the raw tx via your own signing infrastructure. Once you have the spoke tx hash, you'll typically need to manually call the relay to complete the cross-chain flow:
22
47
 
23
48
  ```ts
@@ -31,10 +56,9 @@ const spokeTxHash = await mySigningInfra.signAndBroadcast(tx);
31
56
  // the relay payload returned by `createIntent`.
32
57
  const relayResult = await relayTxAndWaitPacket({
33
58
  relayerApiEndpoint,
34
- srcChainKey: params.srcChainKey,
35
- dstChainKey: params.dstChainKey,
36
- txHash: spokeTxHash,
37
- payload: relayData.payload,
59
+ chainKey: params.srcChainKey,
60
+ srcTxHash: spokeTxHash,
61
+ data: relayData, // the whole RelayExtraData ({ address, payload }), not just .payload
38
62
  timeout: 60_000,
39
63
  });
40
64
  ```
@@ -31,7 +31,7 @@ const { tx, intent, relayData } = result.value;
31
31
  When you know the method, the narrow code union from its declaration enables an exhaustive switch:
32
32
 
33
33
  ```ts
34
- type CreateSupplyIntentErrorCode = 'VALIDATION_FAILED' | 'INTENT_CREATION_FAILED' | 'UNKNOWN';
34
+ type CreateSupplyIntentErrorCode = 'USER_REJECTED' | 'VALIDATION_FAILED' | 'INTENT_CREATION_FAILED' | 'UNKNOWN';
35
35
 
36
36
  const result = await sodax.moneyMarket.createSupplyIntent({ params, raw: true });
37
37
  if (!result.ok) {
@@ -73,25 +73,21 @@ if (!result.ok) {
73
73
  }
74
74
  ```
75
75
 
76
- ### Custom `IConfigApi` for sandbox
76
+ ### Point tests at a sandbox backend
77
77
 
78
- ```ts
79
- import { Sodax, type IConfigApi } from '@sodax/sdk';
78
+ There is no constructor slot to inject a custom `IConfigApiV1` — the only backend knob is `api` (`ApiConfig = BaseApiConfig | CustomApiConfig`: pass a flat `{ baseURL, timeout?, headers? }`, or a `CustomApiConfig` with separate `baseApiConfig` / `swapsApiConfig` endpoints). To run tests against a sandbox or local mock server, set `api.baseURL` and let `initialize()` fetch config from it:
80
79
 
81
- const sandboxApi: IConfigApi = {
82
- async getChains() { return { ok: true, value: [/* fixture */] }; },
83
- async getSwapTokens() { return { ok: true, value: { /* … */ } }; },
84
- async getSwapTokensByChainId(chainKey) { return { ok: true, value: [/* … */] }; },
85
- async getMoneyMarketTokens() { return { ok: true, value: { /* … */ } }; },
86
- async getMoneyMarketTokensByChainId(chainKey) { return { ok: true, value: [/* … */] }; },
87
- };
80
+ ```ts
81
+ import { Sodax } from '@sodax/sdk';
88
82
 
89
83
  const sodax = new Sodax({
90
- backendApi: { url: 'unused', api: sandboxApi },
84
+ api: { baseURL: 'https://sandbox-api.example.com' },
91
85
  });
92
86
  await sodax.config.initialize();
93
87
  ```
94
88
 
89
+ For fully offline unit tests, stub at the `Sodax` boundary instead (see "Mock the entire `Sodax` instance" above) rather than trying to inject a backend implementation.
90
+
95
91
  ---
96
92
 
97
93
  ## Cross-references
@@ -6,7 +6,7 @@ Lookup tables and inventories. Each file is focused on one domain — token-chea
6
6
  |---|---|
7
7
  | [`chain-keys.md`](chain-keys.md) | All 20 `ChainKeys.*` values × chain family × address-type mapping. Chain-family helper functions. Type aliases (`ChainKey`, `SpokeChainKey`, `EvmChainKey`, `HubChainKey`). |
8
8
  | [`wallet-providers.md`](wallet-providers.md) | `I*WalletProvider` interfaces per chain family. `chainType` discriminant. `GetWalletProviderType<K>`. `IWalletProvider` broad union. Implementation source (consumer's own, or `@sodax/wallet-sdk-core` separate package). |
9
- | [`error-codes.md`](error-codes.md) | The 13 unified `SodaxErrorCode` values + meanings + retry guidance + common context fields. The 8 `SodaxFeature` tags. The `SodaxPhase` orchestration tags. Per-method narrow code unions for every public method on every service. |
9
+ | [`error-codes.md`](error-codes.md) | The 13 unified `SodaxErrorCode` values + meanings + retry guidance + common context fields. The 9 `SodaxFeature` tags (8 domain + `'backend'` for the HTTP-client layer). The `SodaxPhase` orchestration tags. Per-method narrow code unions for every public method on every service. |
10
10
  | [`public-api.md`](public-api.md) | What `@sodax/sdk` barrel exports. Import-rule contract (root-only, no deep imports, types re-exported from `@sodax/types`). |
11
11
  | [`glossary.md`](glossary.md) | Domain terms (hub, spoke, intent, relay, vault, hub-wallet abstraction, etc.) used throughout the docs. |
12
12
 
@@ -1,6 +1,6 @@
1
1
  # Chain keys
2
2
 
3
- 20 supported chains. The `ChainKey` type is the union of every `ChainKeys.*` value. `SpokeChainKey` is the same minus `ChainKeys.SONIC_MAINNET` (the hub).
3
+ 21 supported chains. The `ChainKey` type is the union of every `ChainKeys.*` value. **`SpokeChainKey` is the same union — it includes Sonic.** The "spoke" naming refers to how feature services type their `srcChainKey` parameter (they accept the hub too — bridge / swap / staking etc. all run from Sonic as source via the hub-wallet abstraction). When you specifically need "EVM chains excluding the hub" use `EVM_SPOKE_ONLY_CHAIN_KEYS` / `isEvmSpokeOnlyChainKeyType`.
4
4
 
5
5
  | `ChainKeys.*` | String value | Family | Hub vs spoke | Address type |
6
6
  |---|---|---|---|---|
@@ -16,6 +16,7 @@
16
16
  | `LIGHTLINK_MAINNET` | `'lightlink'` | EVM | spoke | `0x${string}` |
17
17
  | `REDBELLY_MAINNET` | `'redbelly'` | EVM | spoke | `0x${string}` |
18
18
  | `KAIA_MAINNET` | `'0x2019.kaia'` | EVM | spoke | `0x${string}` |
19
+ | `HEDERA_MAINNET` | `'hedera'` | EVM | spoke | `0x${string}` |
19
20
  | `SOLANA_MAINNET` | `'solana'` | SOLANA | spoke | base58 PublicKey string |
20
21
  | `SUI_MAINNET` | `'sui'` | SUI | spoke | `0x${string}` (32-byte) |
21
22
  | `STELLAR_MAINNET` | `'stellar'` | STELLAR | spoke | `G…` |
@@ -35,9 +36,9 @@
35
36
 
36
37
  | Type | What it is |
37
38
  |---|---|
38
- | `ChainKey` | Union of all `ChainKeys.*` values (20 chains). |
39
- | `SpokeChainKey` | `ChainKey` minus `'sonic'` (19 spoke chains). |
40
- | `EvmChainKey` | Subset of `ChainKey` for the 12 EVM chains. |
39
+ | `ChainKey` | Union of all `ChainKeys.*` values (21 chains). |
40
+ | `SpokeChainKey` | Same union as `ChainKey` — includes Sonic (21 chains). For "EVM chains excluding the hub" use `EvmSpokeOnlyChainKey`. |
41
+ | `EvmChainKey` | Subset of `ChainKey` for the 13 EVM chains. |
41
42
  | `HubChainKey` | The literal `'sonic'`. |
42
43
 
43
44
  ### Chain-family helpers
@@ -60,6 +61,41 @@ import {
60
61
 
61
62
  ---
62
63
 
64
+ ## Chain metadata (`baseChainInfo`)
65
+
66
+ `baseChainInfo` (exported from `@sodax/sdk`, re-exported from `@sodax/types`) maps every `ChainKey` to a static `BaseChainInfo` record:
67
+
68
+ | Field | Type | Notes |
69
+ |---|---|---|
70
+ | `name` | `string` | Human-readable chain name. |
71
+ | `key` | `ChainKey` | The chain key (equals the map key). |
72
+ | `chainId` | `string \| number` | Native chain id — number for EVM, string for non-EVM. |
73
+ | `type` | `ChainType` | Chain family — same value as `getChainType(key)`. |
74
+ | `mainnet` | `boolean` | Whether the entry is a mainnet chain. |
75
+ | `logo` | `string` | Default chain logo URL (see below). |
76
+ | `explorer` | `{ baseUrl; txUrl; addressUrl; contractUrl }` | Block-explorer URL templates. |
77
+
78
+ ```ts
79
+ import { baseChainInfo, ChainKeys } from '@sodax/sdk';
80
+
81
+ const { name, logo, explorer } = baseChainInfo[ChainKeys.BASE_MAINNET];
82
+ ```
83
+
84
+ ### Chain logos
85
+
86
+ Each entry's `logo` is a default logo URL — **read `baseChainInfo[key].logo` for chain icons; never hardcode icon paths.** The URL is built from the exported `CHAIN_LOGO_BASE_URL` as `${CHAIN_LOGO_BASE_URL}/${key}.png`:
87
+
88
+ ```ts
89
+ import { baseChainInfo, CHAIN_LOGO_BASE_URL, ChainKeys } from '@sodax/sdk';
90
+
91
+ baseChainInfo[ChainKeys.SONIC_MAINNET].logo;
92
+ // → `${CHAIN_LOGO_BASE_URL}/sonic.png`
93
+ ```
94
+
95
+ The PNGs are hosted in the repo's `@sodax/assets` package and served from `main` via `raw.githubusercontent.com` — so a newly added logo only resolves once merged to `main`. They are not bundled into the SDK.
96
+
97
+ ---
98
+
63
99
 
64
100
  ## Cross-references
65
101
 
@@ -1,9 +1,10 @@
1
1
  # Error codes
2
2
 
3
- All 13 codes the SDK can emit. Each error is `SodaxError<C>` where `C` is one of these. The producing feature is on `error.feature`.
3
+ All 14 codes the SDK can emit. Each error is `SodaxError<C>` where `C` is one of these. The producing feature is on `error.feature`.
4
4
 
5
5
  | Code | Meaning | Common `error.context` fields | Retry advice |
6
6
  |---|---|---|---|
7
+ | `USER_REJECTED` | User cancelled the wallet prompt (signing / approval / connection). Classified at the source by `intentCreationFailed` / `approveFailed` wrappers via a built-in detector that recognises viem `4001` / `UserRejectedRequestError`, ICON Hana `CANCEL_SIGNING` / `-31002`, and name + message patterns from Solana / Sui / Stellar / Stacks / NEAR / Injective wallets. | `phase` (set to whichever phase the wrapper was wrapping: `'intentCreation'` or `'approve'`), `action` | No — user-initiated. Render a "Cancelled" UI, not a failure. |
7
8
  | `VALIDATION_FAILED` | Pre-flight invariant tripped (input shape, unsupported chain, etc.). | `field`, `reason`, `phase: 'validate'` | No — fix the input. |
8
9
  | `INTENT_CREATION_FAILED` | Building the intent / payload failed. | `phase: 'intentCreation'`, `action` | Sometimes — depends on root cause (`error.cause`). |
9
10
  | `EXECUTION_FAILED` | Orchestrator-level catch-all (multi-step op didn't complete). | `action`, `phase: 'execution'` or `'postExecution'` | Sometimes — inspect cause. |
@@ -29,7 +30,9 @@ type SodaxFeature =
29
30
  | 'migration'
30
31
  | 'dex'
31
32
  | 'partner'
32
- | 'recovery';
33
+ | 'recovery'
34
+ | 'backend' // HTTP-client layer (BackendApiService / SwapsApiService) — not a domain feature
35
+ | 'leverageYield';
33
36
  ```
34
37
 
35
38
  The `(feature, code)` pair is the canonical discriminator. Loggers tag both fields; switch statements branch on both.
@@ -75,10 +78,10 @@ Narrow code unions per public method. Use these for exhaustive `switch` discrimi
75
78
 
76
79
  ```ts
77
80
  // 'create*Intent' methods
78
- type CreateIntentErrorCode = 'VALIDATION_FAILED' | 'INTENT_CREATION_FAILED' | 'UNKNOWN';
81
+ type CreateIntentErrorCode = 'USER_REJECTED' | 'VALIDATION_FAILED' | 'INTENT_CREATION_FAILED' | 'UNKNOWN';
79
82
 
80
83
  // 'approve' methods
81
- type ApproveErrorCode = 'VALIDATION_FAILED' | 'APPROVE_FAILED' | 'UNKNOWN';
84
+ type ApproveErrorCode = 'USER_REJECTED' | 'VALIDATION_FAILED' | 'APPROVE_FAILED' | 'UNKNOWN';
82
85
 
83
86
  // 'isAllowanceValid' methods
84
87
  type AllowanceCheckErrorCode = 'VALIDATION_FAILED' | 'ALLOWANCE_CHECK_FAILED' | 'UNKNOWN';
@@ -95,7 +98,7 @@ type LookupErrorCode = 'VALIDATION_FAILED' | 'LOOKUP_FAILED' | 'UNKNOWN';
95
98
  | Method | Narrow code union |
96
99
  |---|---|
97
100
  | `createIntent` | `CreateIntentErrorCode` |
98
- | `swap` | All of {`VALIDATION_FAILED`, `INTENT_CREATION_FAILED`, `EXECUTION_FAILED`, `TX_VERIFICATION_FAILED`, `TX_SUBMIT_FAILED`, `RELAY_TIMEOUT`, `RELAY_FAILED`, `EXTERNAL_API_ERROR`, `UNKNOWN`} |
101
+ | `swap` | All of {`USER_REJECTED`, `VALIDATION_FAILED`, `INTENT_CREATION_FAILED`, `EXECUTION_FAILED`, `TX_VERIFICATION_FAILED`, `TX_SUBMIT_FAILED`, `RELAY_TIMEOUT`, `RELAY_FAILED`, `EXTERNAL_API_ERROR`, `UNKNOWN`} |
99
102
  | `postExecution` | `EXECUTION_FAILED \| EXTERNAL_API_ERROR \| UNKNOWN` (with `phase: 'postExecution'`) |
100
103
  | `createLimitOrder`, `createLimitOrderIntent` | `CreateIntentErrorCode` |
101
104
  | `cancelIntent`, `cancelLimitOrder` | `EXECUTION_FAILED \| VALIDATION_FAILED \| UNKNOWN` |
@@ -104,12 +107,12 @@ type LookupErrorCode = 'VALIDATION_FAILED' | 'LOOKUP_FAILED' | 'UNKNOWN';
104
107
 
105
108
  | Method | Narrow code union |
106
109
  |---|---|
107
- | `supply`, `borrow`, `withdraw`, `repay` | `VALIDATION_FAILED \| INTENT_CREATION_FAILED \| EXECUTION_FAILED \| TX_VERIFICATION_FAILED \| TX_SUBMIT_FAILED \| RELAY_TIMEOUT \| RELAY_FAILED \| UNKNOWN` (with `action` discriminator) |
110
+ | `supply`, `borrow`, `withdraw`, `repay` | `USER_REJECTED \| VALIDATION_FAILED \| INTENT_CREATION_FAILED \| EXECUTION_FAILED \| TX_VERIFICATION_FAILED \| TX_SUBMIT_FAILED \| RELAY_TIMEOUT \| RELAY_FAILED \| UNKNOWN` (with `action` discriminator) |
108
111
  | `createSupplyIntent`, `createBorrowIntent`, `createWithdrawIntent`, `createRepayIntent` | `CreateIntentErrorCode` |
109
112
  | `approve` | `ApproveErrorCode` |
110
113
  | `isAllowanceValid` | `AllowanceCheckErrorCode` |
111
114
  | `estimateGas` | `GasEstimationErrorCode` |
112
- | Read-only methods (reserves, user data, etc.) | `LookupErrorCode` |
115
+ | Read methods (`sodax.moneyMarket.data.*` — reserves, user data, aToken balances) | throw on failure (bare `Promise<T>`, **not** a `Result`) — wrap in try/catch |
113
116
 
114
117
  ### Staking (`feature: 'staking'`)
115
118
 
@@ -150,11 +153,31 @@ type LookupErrorCode = 'VALIDATION_FAILED' | 'LOOKUP_FAILED' | 'UNKNOWN';
150
153
  | `createXxxIntent` (4 of these) | `CreateIntentErrorCode` |
151
154
  | `approve` | `ApproveErrorCode` |
152
155
  | `isAllowanceValid` | `AllowanceCheckErrorCode` |
153
- | `getAvailableAmount` | `LookupErrorCode` |
156
+
157
+ > `getAvailableAmount` is **not** a public `MigrationService` method — it's an internal `icxMigration` sub-service helper, so it carries no public narrow code union.
154
158
 
155
159
  ### Partner (`feature: 'partner'`) and Recovery (`feature: 'recovery'`)
156
160
 
157
- Both follow the same shape: action methods get the full exec union (`'EXECUTION_FAILED' \| 'INTENT_CREATION_FAILED' \| ...`), read methods get `LookupErrorCode`, approve methods get `ApproveErrorCode`.
161
+ Both follow the same shape: action methods get the full exec union (`'EXECUTION_FAILED' \| 'INTENT_CREATION_FAILED' \| ...`), read methods get `LookupErrorCode`, approve methods get `ApproveErrorCode` (so partner's `approve` can emit `'USER_REJECTED'`).
162
+
163
+ ### Backend / Swaps API (`feature: 'backend'`)
164
+
165
+ `BackendApiService` (`sodax.backendApi`) and the Swaps API v2 client (`sodax.api.swaps`) are the HTTP-client layer — not domain features. Every method returns `Result<T, SodaxError<'EXTERNAL_API_ERROR'>>` with `context.endpoint`, and the transport failure (timeout / non-2xx / response-shape mismatch) preserved on `error.cause`. `context.api` distinguishes the two clients: `'backend'` for `BackendApiService`, `'swaps'` for the `sodax.api.swaps` client.
166
+
167
+ ### Leverage Yield (`feature: 'leverageYield'`)
168
+
169
+ Action discriminator on `context.action`: `'deposit' \| 'withdraw' \| 'approve' \| 'allowanceCheck' \| 'vaultSwap'`.
170
+
171
+ | Method | Narrow code union |
172
+ |---|---|
173
+ | `deposit`, `withdraw`, `createVaultIntent` | `CreateIntentErrorCode` (create-intent subset) |
174
+ | `vaultSwap` | All exec codes: `VALIDATION_FAILED \| INTENT_CREATION_FAILED \| TX_VERIFICATION_FAILED \| TX_SUBMIT_FAILED \| RELAY_TIMEOUT \| RELAY_FAILED \| EXECUTION_FAILED \| EXTERNAL_API_ERROR \| UNKNOWN` |
175
+ | `notifySolver` | `EXECUTION_FAILED \| EXTERNAL_API_ERROR \| UNKNOWN` (with `phase: 'postExecution'`) |
176
+ | `approve` | `ApproveErrorCode` |
177
+ | `isAllowanceValid` | `AllowanceCheckErrorCode` (action `'allowanceCheck'`) |
178
+ | `getApr`, `getEffectiveApr`, `getLsdApr`, `getPosition`, `getTotalAssets`, `previewDeposit`, `previewWithdraw`, `previewRedeem`, `getMaxWithdraw`, `getMaxWithdrawForUser`, `getShareBalance`, `getShareBalanceForUser`, `getAsset` | `LookupErrorCode` (with `method` discriminator) |
179
+
180
+ Relay/tx-verification codes appear only on `vaultSwap`; `createVaultIntent` stays within the create-intent subset. `notifySolver` is public (manual create→relay→notify) and emits the post-execution subset.
158
181
 
159
182
  ---
160
183
 
@@ -17,8 +17,8 @@
17
17
  | **Hub wallet abstraction** | A user-specific contract on the hub that holds funds during cross-chain ops. Resolved via `EvmHubProvider.getUserHubWalletAddress(...)`. |
18
18
  | **`Result<T>`** | The `{ ok: true; value: T } \| { ok: false; error: E }` discriminated union returned by every async public method. |
19
19
  | **`SodaxError<C>`** | The canonical error class. Discriminated by `(feature, code)`. |
20
- | **Code (`SodaxErrorCode`)** | One of 13 reason-only error codes. See § 3. |
21
- | **Feature (`SodaxFeature`)** | One of 8 producing features (`'swap'`, `'moneyMarket'`, …). |
20
+ | **Code (`SodaxErrorCode`)** | One of 14 reason-only error codes. See § 3. |
21
+ | **Feature (`SodaxFeature`)** | One of 9 domain features (`'swap'`, `'moneyMarket'`, …, `'leverageYield'`) plus `'backend'` for the HTTP-client layer (`BackendApiService` / `sodax.api.swaps`). |
22
22
  | **Phase (`SodaxPhase`)** | The orchestration step at which an error occurred. See § 3. |
23
23
  | **Action (`error.context.action`)** | The user-facing operation that triggered the error (`'supply'`, `'stake'`, `'migrateBaln'`, …). |
24
24
  | **`raw: true / false`** | The discriminator on `WalletProviderSlot<K, Raw>`. `true` = build unsigned tx; `false` = sign and broadcast. |
@@ -2,21 +2,35 @@
2
2
 
3
3
  Import everything from `@sodax/sdk`. The barrel re-exports the entire `@sodax/types` surface — you don't need a separate `@sodax/types` dependency.
4
4
 
5
+ `sodax.api` is an alias for `sodax.backendApi`; `sodax.api.swaps` is the typed Swaps API v2 client (`SwapsApiService`) — see [`../features/swaps-api.md`](../features/swaps-api.md).
6
+
5
7
  ### Top-level exports
6
8
 
7
9
  ```ts
8
10
  import {
9
11
  // Main entry
10
12
  Sodax,
11
- type SodaxConfig,
13
+ type SodaxOptions, // constructor param: DeepPartial<SodaxDefaultConfig> & client options (logger + global fee)
14
+ type SodaxConfig, // merged result: SodaxDefaultConfig & client options (e.g. sodax.instanceConfig)
15
+ type SodaxDefaultConfig, // static data contract the backend serves / defaults are built from
12
16
  type DeepPartial,
13
17
 
18
+ // Logging (see recipes/logging.md)
19
+ type SodaxLogger,
20
+ type SodaxLoggerOption,
21
+ consoleLogger,
22
+ silentLogger,
23
+ resolveLogger,
24
+
14
25
  // Chain keys + narrowing
15
26
  ChainKeys,
16
27
  type ChainKey,
17
28
  type SpokeChainKey,
18
29
  type HubChainKey,
19
30
  type EvmChainKey,
31
+ baseChainInfo, // per-chain static metadata (name, key, logo, explorer, …)
32
+ type BaseChainInfo,
33
+ CHAIN_LOGO_BASE_URL, // base URL for default chain logos — baseChainInfo[key].logo
20
34
  getChainType,
21
35
  isEvmChainKeyType,
22
36
  isSolanaChainKeyType,
@@ -59,6 +73,7 @@ import {
59
73
  dexInvariant,
60
74
  partnerInvariant,
61
75
  recoveryInvariant,
76
+ leverageYieldInvariant,
62
77
  mapRelayFailure,
63
78
 
64
79
  // Tokens
@@ -100,17 +115,35 @@ import {
100
115
  type ClClaimRewardsParams,
101
116
  type MigrationParams,
102
117
  type UnifiedBnUSDMigrateParams,
118
+ type LeverageYieldSwapDepositParams,
119
+ type LeverageYieldSwapWithdrawParams,
120
+ type LeverageYieldSwapPayload,
121
+ type VaultSwapActionParams,
122
+ type VaultSwapResponse,
123
+ type CreateVaultIntentResult,
124
+ type LeverageYieldApr,
125
+ type LeverageYieldEffectiveApr,
126
+ type LeverageYieldLsdApr,
127
+ type LeverageYieldPosition,
128
+ type LeverageYieldVault,
103
129
  // …
104
130
 
105
131
  // Backend / relay
106
- type IConfigApi,
107
- type SubmitSwapTxRequest,
108
- type SubmitSwapTxResponse,
132
+ type IConfigApiV1,
133
+ type SubmitTxRequestV2, // swaps API submit-tx request (sodax.api.swaps.submitTx)
134
+ type SubmitTxResponseV2, // swaps API submit-tx response
109
135
  relayTxAndWaitPacket, // function — runs spoke→hub relay submit + wait
110
136
  submitTransaction, // function — relay submit ack only
111
137
  type RelayExtraData,
112
138
  type IntentRelayChainId,
113
139
 
140
+ // Backend API config + per-call override
141
+ type ApiConfig, // BaseApiConfig | CustomApiConfig
142
+ type BaseApiConfig,
143
+ type CustomApiConfig, // point the swaps API at its own endpoint
144
+ type SwapsApiConfig,
145
+ type RequestOverrideConfig, // per-call override on any backendApi / sodax.api.swaps method
146
+
114
147
  // Read shapes
115
148
  type Intent,
116
149
  type IntentResponse,
@@ -0,0 +1,50 @@
1
+ ---
2
+ name: sodax-sdk-leverage-yield
3
+ description: 'Granular skill for the @sodax/sdk v2 leverage-yield feature only — leveraged-yield ERC-4626 vaults on Sonic via LeverageYieldService. Deposit any token → lsoda* shares, withdraw shares → any token (both as solver-tradeable intent swaps), createVaultIntent/vaultSwap/notifySolver, Sonic-direct approve/isAllowanceValid, and reads (getApr, getEffectiveApr, getPosition, getTotalAssets, preview*, getMaxWithdraw*, getShareBalance*, listVaults). Use when the task is leverage-yield vaults (e.g. "deposit into a leverage vault", "withdraw lsoda shares", "vault APR / effective APR", "leverage vault position / health factor", "lsoda share balance"). New in v2 — integration only, no v1 migration path. 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
+ # Leverage Yield (Core SDK granular skill)
11
+
12
+ Granular skill for `LeverageYieldService` — `sodax.leverageYield`. Feature tag: `'leverageYield'`. **New in v2; no v1 migration path.**
13
+
14
+ ## Step 1 — Clarify with user before coding
15
+
16
+ 1. **Deposit or withdraw?** Deposit = any spoke token → `lsoda*` shares (delivered to the user's hub wallet). Withdraw = `lsoda*` shares (in the hub wallet) → any token on any chain.
17
+ 2. **Build vs execute.** `deposit` / `withdraw` only *build* a `LeverageYieldSwapPayload`; `vaultSwap` *executes* it end-to-end. Spread the built payload into `vaultSwap({ ...payload, walletProvider })`.
18
+ 3. **End-to-end or manual relay?** `vaultSwap` does create → verify → relay → notify. For backend submit-tx, use `createVaultIntent` then relay yourself and finish with the public `notifySolver`.
19
+ 4. **Reads?** `getEffectiveApr` (headline, AAVE + LSD), `getApr` (AAVE-only — can be negative), `getPosition`, `getTotalAssets`, `previewRedeem`, `getMaxWithdrawForUser` / `getShareBalanceForUser` (resolve the hub wallet from a spoke address internally).
20
+
21
+ ## Integration workflow
22
+
23
+ 1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md).
24
+ 2. [`../integration/knowledge/features/leverage-yield.md`](../integration/knowledge/features/leverage-yield.md) — `LeverageYieldService` API, the share-as-token model, deposit/withdraw/vaultSwap flows, APR math.
25
+ 3. Path-specific recipe:
26
+ - Signed → [`../integration/knowledge/recipes/signed-tx-flow.md`](../integration/knowledge/recipes/signed-tx-flow.md)
27
+ - Unsigned → [`../integration/knowledge/recipes/raw-tx-flow.md`](../integration/knowledge/recipes/raw-tx-flow.md)
28
+ 4. Errors (`feature: 'leverageYield'`) → [`../integration/knowledge/reference/error-codes.md`](../integration/knowledge/reference/error-codes.md).
29
+
30
+ ### Leverage-yield-specific anti-patterns
31
+
32
+ - **Expecting `deposit` / `withdraw` to broadcast.** They are builders returning a `LeverageYieldSwapPayload`. Execute via `vaultSwap({ ...payload, walletProvider })`.
33
+ - **Using `getApr` as the headline number.** For LSD-backed vaults the AAVE-only spread is often negative; `getEffectiveApr` folds in the LSD staking yield (the real source of return).
34
+ - **Passing a spoke address to `getShareBalance` / `getMaxWithdraw`.** Those take a hub address. Use the `*ForUser(vault, srcChainKey, srcAddress)` variants to resolve the hub wallet first.
35
+ - **Gating withdraw on `approve` / `isAllowanceValid`.** Those are Sonic-direct allowance helpers for the vault's underlying asset; the swap-style withdraw authorises the share spend via a hub-wallet `Connection.sendMessage` (`hubWalletSwap: true`).
36
+ - **Quoting on the pre-fee amount.** A deposit's per-intent `partnerFee` is deducted from `inputAmount` before the swap — quote (via the swap solver, `token_dst` = vault) on the post-fee amount.
37
+
38
+ ## Verification
39
+
40
+ 1. `pnpm tsc --noEmit` clean.
41
+ 2. Every `await sodax.leverageYield.<method>(...)` has `if (!result.ok)`.
42
+ 3. Deposit/withdraw build a payload that is then run through `vaultSwap` (or `createVaultIntent` + relay + `notifySolver`).
43
+ 4. APR display uses `getEffectiveApr`; share/withdraw sizing from a spoke address uses the `*ForUser` reads.
44
+
45
+ ## Related granular skills (same family)
46
+
47
+ - [`../swap/SKILL.md`](../swap/SKILL.md) — `vaultSwap` is a leverage-yield copy of the swap intent flow; quote `minOutputAmount` via the solver quote there.
48
+ - [`../recovery/SKILL.md`](../recovery/SKILL.md) — recover stuck hub-wallet assets (including `lsoda*` shares) back to a spoke chain.
49
+
50
+ For multi-feature tasks, load the broad [`sodax-sdk` skill](../SKILL.md).
@@ -0,0 +1,69 @@
1
+ ---
2
+ name: sodax-sdk-migration
3
+ description: 'Granular skill for the @sodax/sdk v2 token-migration feature only — `MigrationService` (`sodax.migration`) covering ICX ↔ SODA, legacy bnUSD ↔ new bnUSD, and BALN → SODA with lockup multipliers. Use when the task is migrating legacy ICON-ecosystem tokens to SODAX (e.g. "migrate ICX to SODA", "revert SODA back to ICX", "swap legacy bnUSD on Sui/Stellar/ICON to new bnUSD", "migrate BALN with lock period for reward multiplier", "claim staked BALN"). IMPORTANT — this is NOT the same as v1 → v2 SDK migration (porting old SDK code). That is a separate cross-cutting concern handled by the broad sodax-sdk skill in migration mode and the migration-v1-to-v2/ knowledge subtree. Same word, different concept. 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
+ # Token migration (Core SDK granular skill)
11
+
12
+ Granular skill for `MigrationService` — the SDK module that migrates legacy ICON-ecosystem tokens. Access via `sodax.migration` (with sub-services `sodax.migration.icxMigration`, `sodax.migration.bnUSDMigrationService`, `sodax.migration.balnSwapService`). Feature tag: `'migration'`.
13
+
14
+ > **Important disambiguation.** This skill is about the `MigrationService` SDK module. It is **NOT** about porting v1 SDK code to v2 — that lives under the broad `sodax-sdk` skill (migration mode) and the [`../migration-v1-to-v2/knowledge/`](../migration-v1-to-v2/knowledge/) subtree of this package. Same word, different concept.
15
+
16
+ ## Step 0 — Confirm this IS a token-protocol migration
17
+
18
+ The word "migrate" is overloaded. This skill only handles **legacy ICON-ecosystem token swaps to SODAX assets** (ICX → SODA, legacy bnUSD → new bnUSD, BALN → SODA). If the user phrases the task as:
19
+
20
+ - *"move / send / transfer SODA from chain A to chain B"* → that's a **bridge** (vault-pair) or a **swap** (solver-routed). Load `sodax-sdk-bridge` or `sodax-sdk-swap` instead.
21
+ - *"migrate my v1 SDK code to v2"* → that's the SDK port. Load the broad `sodax-sdk` skill in migration mode and the `migration-v1-to-v2/` knowledge subtree.
22
+
23
+ Only continue here if the task involves one of the three legacy-token sources below.
24
+
25
+ ## Step 1 — Clarify with user before coding
26
+
27
+ 1. **Which token are you migrating?**
28
+ - **ICX / wICX** ↔ SODA → `sodax.migration.icxMigration`.
29
+ - **Legacy bnUSD** (ICON / Sui / Stellar) ↔ **new bnUSD** (EVM chains) → `sodax.migration.bnUSDMigrationService`.
30
+ - **BALN** → SODA with optional lockup (0–24 months, multiplier 0.5x–1.5x) → `sodax.migration.balnSwapService`.
31
+ 2. **Forward** (legacy → new) **or revert** (new → legacy, ICX only)?
32
+ 3. **For BALN: lock period?** No lock = baseline; longer lock = higher reward multiplier.
33
+ 4. **Signed or unsigned-tx flow?**
34
+ 5. **Need orchestrated full flow** (`migrateXxx`) **or just intent creation** (`createMigrateXxxIntent`)?
35
+
36
+ ## Integration workflow
37
+
38
+ 1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md).
39
+ 2. [`../integration/knowledge/features/migration.md`](../integration/knowledge/features/migration.md) — `MigrationService` API surface and the three sub-services.
40
+ 3. Path-specific recipe:
41
+ - Signed → [`../integration/knowledge/recipes/signed-tx-flow.md`](../integration/knowledge/recipes/signed-tx-flow.md)
42
+ - Unsigned → [`../integration/knowledge/recipes/raw-tx-flow.md`](../integration/knowledge/recipes/raw-tx-flow.md)
43
+ 4. Errors (`feature: 'migration'`) → [`../integration/knowledge/reference/error-codes.md`](../integration/knowledge/reference/error-codes.md).
44
+
45
+ ### Token-migration-specific anti-patterns
46
+
47
+ - **Assuming `BalnSwapService.stake/unstake/claim/...` return `Result<T>`.** They still THROW — deliberate tech debt. Wrap them in `try/catch` until cleaned up.
48
+ - **Using `migration` (the SDK module) and `migration-v1-to-v2` (the SDK port) interchangeably.** Different concerns; reading one playbook for the other will produce broken code.
49
+ - **Misreading `getAvailableAmount`.** It lives on `sodax.migration.icxMigration`, takes **no arguments**, and reads the migration contract's **total available SODA liquidity** on the hub — it is not a per-user "claimable from a partial migration" amount.
50
+
51
+ ## Migration workflow (v1 → v2 of the SDK itself)
52
+
53
+ If the user is porting v1 `MigrationService` code to v2:
54
+
55
+ 1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md).
56
+ 2. [`../migration-v1-to-v2/knowledge/features/migration.md`](../migration-v1-to-v2/knowledge/features/migration.md) — v1 `MigrationError` → v2 `SodaxError<C>` with `feature: 'migration'`. Note the BALN lock-method carve-out (still throws).
57
+
58
+ ## Verification
59
+
60
+ 1. `pnpm tsc --noEmit` clean.
61
+ 2. Every `await sodax.migration.<method>(...)` (orchestrators + intent creators) has `if (!result.ok)`.
62
+ 3. BALN lock-method calls (`stake`, `unstake`, `claim`, `claimUnstaked`, `cancelUnstake`, `getDetailedUserLocks`) remain wrapped in `try/catch` — they do not return `Result<T>`.
63
+
64
+ ## Related granular skills (same family)
65
+
66
+ - [`../staking/SKILL.md`](../staking/SKILL.md) — generic SODA staking (different from BALN lockup, which migrates BALN → SODA in one step).
67
+ - [`../recovery/SKILL.md`](../recovery/SKILL.md) — recovery for stuck migration assets on the hub.
68
+
69
+ For multi-feature tasks, load the broad [`sodax-sdk` skill](../SKILL.md).
@@ -41,7 +41,7 @@ Same word, different concept across versions. Skim before reading the breaking-c
41
41
  | **config** | A `SodaxConfig` object passed at construction with hard-coded chain/token tables. Solver endpoints lived under `SodaxConfig.swaps`. | A `Sodax` instance owns a `ConfigService` that loads from the backend API, with packaged defaults as fallback. `sodax.config.*` is the lookup surface. **Solver endpoints moved to `SodaxConfig.solver`** (not `swaps`); `swaps` is `SwapsConfig` (supported tokens). |
42
42
  | **`xChainId` field on tokens** | Field name on the `Token` type. | Renamed: `XToken.chainKey`. Type also renamed: `Token` → `XToken`. |
43
43
  | **`hubAssets` / `moneyMarketSupportedTokens`** | Static `Record` global maps imported and walked. | `hubAssets` **deleted** — won't compile. `moneyMarketSupportedTokens` **still exported** as a packaged default, but prefer `sodax.config.*` and `sodax.moneyMarket.getSupportedTokens*()` so backend updates take effect. Each `XToken` now carries `vault` and `hubAsset` directly. |
44
- | **`SubmitSwapTxRequest.srcChainId`** | Numeric chain id field on the backend submit-swap request. | Renamed: `srcChainKey: SpokeChainKey`. |
44
+ | **`SubmitSwapTxRequest.srcChainId`** | Numeric chain id field on the v1 backend submit-swap request. | `srcChainKey` on `SubmitTxRequestV2`; submit-tx also moved to `sodax.api.swaps.submitTx`. |
45
45
  | **`Intent.srcChain` / `Intent.dstChain`** | Read shape: `IntentRelayChainId` (bigint). | **Unchanged.** This is the relay chain id, not a spoke chain key. A blanket grep-replace `srcChain`→`srcChainKey` will break this. |
46
46
  | **`AddressType`** | Bitcoin-specific address-type union. | Renamed: `BtcAddressType`. (Generic name freed up.) |
47
47