@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
|
@@ -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
|
-
|
|
35
|
-
|
|
36
|
-
|
|
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
|
-
###
|
|
76
|
+
### Point tests at a sandbox backend
|
|
77
77
|
|
|
78
|
-
|
|
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
|
-
|
|
82
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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 (
|
|
39
|
-
| `SpokeChainKey` | `ChainKey`
|
|
40
|
-
| `EvmChainKey` | Subset of `ChainKey` for the
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
21
|
-
| **Feature (`SodaxFeature`)** | One of
|
|
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
|
|
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
|
|
107
|
-
type
|
|
108
|
-
type
|
|
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. |
|
|
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
|
|