@sodax/skills 2.3.0-rc.2 → 2.3.0-rc.3
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/AGENTS.md +6 -4
- package/README.md +3 -2
- package/package.json +1 -1
- package/skills/sodax-build/SKILL.md +1 -0
- package/skills/sodax-build/knowledge/chains-and-assets.md +1 -1
- package/skills/sodax-dapp-kit/auxiliary-services/SKILL.md +1 -1
- package/skills/sodax-dapp-kit/bridge/SKILL.md +1 -0
- package/skills/sodax-dapp-kit/integration/knowledge/ai-rules.md +3 -0
- package/skills/sodax-dapp-kit/integration/knowledge/architecture.md +7 -3
- package/skills/sodax-dapp-kit/integration/knowledge/features/auxiliary-services.md +8 -3
- package/skills/sodax-dapp-kit/integration/knowledge/quickstart.md +2 -2
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/setup.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md +1 -1
- package/skills/sodax-dapp-kit/leverage-yield/SKILL.md +1 -0
- package/skills/sodax-dapp-kit/swap/SKILL.md +1 -0
- package/skills/sodax-sdk/SKILL.md +2 -1
- package/skills/sodax-sdk/bridge/SKILL.md +1 -1
- package/skills/sodax-sdk/bridge-api/SKILL.md +13 -8
- package/skills/sodax-sdk/integration/knowledge/ai-rules.md +5 -3
- package/skills/sodax-sdk/integration/knowledge/architecture.md +8 -8
- package/skills/sodax-sdk/integration/knowledge/features/backend-api.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/features/bridge-api.md +43 -7
- package/skills/sodax-sdk/integration/knowledge/features/leverage-yield-api.md +38 -3
- package/skills/sodax-sdk/integration/knowledge/features/money-market.md +2 -0
- package/skills/sodax-sdk/integration/knowledge/features/swap.md +6 -2
- package/skills/sodax-sdk/integration/knowledge/features/swaps-api.md +36 -4
- package/skills/sodax-sdk/integration/knowledge/quickstart.md +4 -4
- package/skills/sodax-sdk/integration/knowledge/recipes/initialize-sodax.md +13 -6
- package/skills/sodax-sdk/integration/knowledge/recipes/logging.md +2 -4
- package/skills/sodax-sdk/integration/knowledge/recipes/testing.md +2 -2
- package/skills/sodax-sdk/leverage-yield/SKILL.md +1 -1
- package/skills/sodax-sdk/leverage-yield-api/SKILL.md +12 -10
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/README.md +1 -1
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/architecture.md +3 -3
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/checklist.md +2 -2
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/money-market.md +1 -1
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/recipes.md +1 -1
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/reference/sodax-config.md +1 -1
- package/skills/sodax-sdk/swap/SKILL.md +1 -1
- package/skills/sodax-sdk/swaps-api/SKILL.md +11 -9
- package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/interfaces.md +3 -0
|
@@ -39,7 +39,7 @@ sodax.api.bridge.createBridgeIntent(body: CreateBridgeIntentParamsV2, config?):
|
|
|
39
39
|
sodax.api.bridge.submitTx(body: BridgeSubmitTxRequestV2, config?): Promise<Result<BridgeSubmitTxResponseV2>>;
|
|
40
40
|
sodax.api.bridge.getSubmitTxStatus(query: BridgeSubmitTxStatusQueryV2, config?): Promise<Result<BridgeSubmitTxStatusResponseV2>>;
|
|
41
41
|
|
|
42
|
-
// Discovery / quote — read-only
|
|
42
|
+
// Discovery / quote — read-only. The local sodax.bridge.* reads accept only bundled tokens; these accept any listed one.
|
|
43
43
|
sodax.api.bridge.getFee(body: BridgeFeeRequestV2, config?): Promise<Result<BridgeFeeResponseV2>>;
|
|
44
44
|
sodax.api.bridge.getBridgeableAmount(body: BridgeQuoteRequestV2, config?): Promise<Result<BridgeableAmountResponseV2>>;
|
|
45
45
|
sodax.api.bridge.isBridgeable(body: BridgeQuoteRequestV2, config?): Promise<Result<BridgeableCheckResponseV2>>;
|
|
@@ -64,10 +64,12 @@ Bridge is **vault-backed, not solver-based**, so the surface is smaller and a fe
|
|
|
64
64
|
`dstAddress`), NOT the SDK-domain `srcToken`/`dstToken`/`amount`/`recipient`. The mapper
|
|
65
65
|
`toCreateBridgeIntentParamsV2(params, extras?)` converts SDK-domain params (and serializes the `bigint`
|
|
66
66
|
amount) to this wire DTO.
|
|
67
|
-
- **Discovery quotes (`getFee` / `getBridgeableAmount` / `isBridgeable`)
|
|
68
|
-
`sodax.bridge.getFee(...)` / `getBridgeableAmount(...)` / `isBridgeable({ from, to })
|
|
69
|
-
|
|
70
|
-
|
|
67
|
+
- **Discovery quotes (`getFee` / `getBridgeableAmount` / `isBridgeable`) also exist client-side** as
|
|
68
|
+
`sodax.bridge.getFee(...)` / `getBridgeableAmount(...)` / `isBridgeable({ from, to })`. The last two read the
|
|
69
|
+
config bundled with the installed SDK, so they fail or return `false` for tokens newer than that release; use
|
|
70
|
+
this client's versions for such tokens. `getFee` takes no token and works for any. Gate the action on `getBridgeableAmount`'s `limit.amount` being above
|
|
71
|
+
zero: the backend `isBridgeable` checks config only, and a zero-limit pair fails `createBridgeIntent` with
|
|
72
|
+
422. The token *list* is backend-served via `getTokens` / `getTokensByChain`.
|
|
71
73
|
|
|
72
74
|
## `approve` can return two transactions
|
|
73
75
|
|
|
@@ -79,7 +81,8 @@ zeroed.
|
|
|
79
81
|
Broadcast `resetTx` first and wait for it to be mined, then broadcast `tx`. As separate transactions
|
|
80
82
|
they cannot go out together: the approval is only valid once the reset has landed on-chain. An
|
|
81
83
|
EIP-5792 atomic batch is different — it runs its calls in order, so it can carry both (the SDK's
|
|
82
|
-
`bridgeWithApproval` does, see `bridge.md
|
|
84
|
+
`bridgeWithApproval` does, see `bridge.md`; for the API client, see
|
|
85
|
+
[Approve and bridge in one signature](#approve-and-bridge-in-one-signature)). Submitting `tx` while a non-zero stale allowance
|
|
83
86
|
remains is a guaranteed revert.
|
|
84
87
|
|
|
85
88
|
```ts
|
|
@@ -96,6 +99,30 @@ await sendTransaction(tx);
|
|
|
96
99
|
The field is optional and absent for every other token, so ignoring it keeps existing behaviour —
|
|
97
100
|
it just cannot rescue a wallet stuck on a guarded token.
|
|
98
101
|
|
|
102
|
+
## Approve and bridge in one signature
|
|
103
|
+
|
|
104
|
+
When `checkAllowance` reports the allowance short, an EVM spoke source with an EIP-5792 wallet can send
|
|
105
|
+
`[resetTx?, approve tx, deposit tx]` from `approve` and `createBridgeIntent` as one atomic batch: one wallet
|
|
106
|
+
prompt instead of two or three. This works because `/bridge/intents` builds the deposit without reading the
|
|
107
|
+
allowance, and `/bridge/approve` targets the spender that deposit pulls from. Finish with `submitTx`
|
|
108
|
+
(see [Submit tx + poll status](#submit-tx--poll-status)), passing the deposit `txHash`, `srcChainKey`,
|
|
109
|
+
`walletAddress` and the full `relayData`. Persist that body before the call: once the deposit is out, a
|
|
110
|
+
failed `submitTx` is retried on its own, never by running the flow again.
|
|
111
|
+
|
|
112
|
+
The batch, refusal and unconfirmed-batch rules are the ones in
|
|
113
|
+
[Approve and send the intent in one signature](./swaps-api.md#approve-and-send-the-intent-in-one-signature).
|
|
114
|
+
Before waiting on the batch, persist from `onBatchSent` what a resume after a reload needs: the batch id,
|
|
115
|
+
the batch's call count and the `submitTx` body except `txHash`. Resume an unconfirmed batch with
|
|
116
|
+
`confirmApprovalBatch` and finish it with that state; while the batch may still land, never create the
|
|
117
|
+
intent again or rerun the flow. A resume that returns `INTENT_CREATION_FAILED` with
|
|
118
|
+
`context.reason: 'atomic-batch-failed'` means nothing landed: drop the saved state and run the flow again.
|
|
119
|
+
After a refused batch, submit the `relayData` of the re-created intent. In React, no `sodax-dapp-kit` hook
|
|
120
|
+
batches this flow: `useBridgeApiApproveAndBroadcast` approves in its own prompts. The runnable flow is
|
|
121
|
+
[`bridgeApiApprovalBatch.test.ts`](https://github.com/gosodax/sodax-sdks/blob/main/packages/sdk/src/backendApi/bridgeApiApprovalBatch.test.ts): it asserts the
|
|
122
|
+
batch order, the refusal fallback, a `submitTx` retry and both outcomes of a resume from the persisted
|
|
123
|
+
state. That a hub source or a wallet that cannot batch stays sequential is asserted in
|
|
124
|
+
[`approvalBatch.test.ts`](https://github.com/gosodax/sodax-sdks/blob/main/packages/sdk/src/shared/utils/approvalBatch.test.ts).
|
|
125
|
+
|
|
99
126
|
## Common call shapes
|
|
100
127
|
|
|
101
128
|
### Allowance · approve · create intent (shared body)
|
|
@@ -109,6 +136,11 @@ const body = {
|
|
|
109
136
|
srcAddress, dstAddress, // dstAddress is the SDK domain `recipient`
|
|
110
137
|
};
|
|
111
138
|
|
|
139
|
+
// Gate on live capacity before any approval: a listed pair can have a zero (or negative) limit, and an
|
|
140
|
+
// amount above the limit fails createBridgeIntent (422). `limit.decimals` is the limit's own unit.
|
|
141
|
+
const bridgeable = await sodax.api.bridge.getBridgeableAmount({ srcChainKey, dstChainKey, inputToken, outputToken });
|
|
142
|
+
if (!bridgeable.ok || BigInt(bridgeable.value.limit.amount) <= 0n) return;
|
|
143
|
+
|
|
112
144
|
const allowance = await sodax.api.bridge.checkAllowance(body);
|
|
113
145
|
if (allowance.ok && !allowance.value.valid) {
|
|
114
146
|
const approved = await sodax.api.bridge.approve(body);
|
|
@@ -128,7 +160,8 @@ const { tx, relayData } = created.value; // no `intent`
|
|
|
128
160
|
### Submit tx + poll status
|
|
129
161
|
|
|
130
162
|
```ts
|
|
131
|
-
// Sign + broadcast `tx`
|
|
163
|
+
// Sign + broadcast `tx` per chain type (swaps-api.md § "Sign and broadcast `tx`"), then hand the spoke
|
|
164
|
+
// tx hash back with the FULL relayData envelope.
|
|
132
165
|
const submit = await sodax.api.bridge.submitTx({
|
|
133
166
|
txHash, srcChainKey, walletAddress,
|
|
134
167
|
relayData, // the whole { address, payload } object, NOT relayData.payload
|
|
@@ -141,6 +174,7 @@ if (status.ok && status.value.data.status === 'executed') {
|
|
|
141
174
|
status.value.data.result?.dstIntentTxHash; // destination tx hash (no intent_hash)
|
|
142
175
|
}
|
|
143
176
|
// Lifecycle: 'pending' → 'relaying' → 'relayed' → 'executed' | 'failed'.
|
|
177
|
+
// Stop polling on 'executed', 'failed', or a set `data.abandonedAt` (processing budget exhausted).
|
|
144
178
|
```
|
|
145
179
|
|
|
146
180
|
## Per-call overrides & custom endpoint
|
|
@@ -161,6 +195,8 @@ move the whole backend (including bridge) to a custom host, use the `CustomApiCo
|
|
|
161
195
|
|
|
162
196
|
`bridge.useBackendSubmitTx` (default `true`) routes the end-to-end `sodax.bridge.bridge()` through this
|
|
163
197
|
API (`submit-tx` + status poll) with an automatic fall back to the client-side relay on any non-success.
|
|
198
|
+
It still validates tokens against the installed SDK's bundled config before that, so it does not accept
|
|
199
|
+
tokens newer than the release; for those, call this client end to end.
|
|
164
200
|
Set `new Sodax({ bridge: { useBackendSubmitTx: false } })` to force the client-side path. Independent of
|
|
165
201
|
`swaps.useBackendSubmitTx`. See [`bridge.md`](bridge.md) and the `CONFIGURE_SDK` doc.
|
|
166
202
|
|
|
@@ -112,6 +112,10 @@ quote.value.quotedAmount; // expected lsoda* shares, decimal string
|
|
|
112
112
|
// Pass query `{ includeTxData: true }` (and srcAddress on the body) to also get `txData`.
|
|
113
113
|
```
|
|
114
114
|
|
|
115
|
+
Take `tokenSrc` (and a withdraw's `outputToken`) from `sodax.api.swaps.getTokens()`, not from
|
|
116
|
+
`getSupportedSolverTokens` or `sodax.config`: those list only the tokens bundled with the installed SDK,
|
|
117
|
+
while this API accepts the tokens the backend supports.
|
|
118
|
+
|
|
115
119
|
### Create deposit intent
|
|
116
120
|
|
|
117
121
|
```ts
|
|
@@ -144,14 +148,45 @@ if (allowance.ok && !allowance.value.valid) {
|
|
|
144
148
|
}
|
|
145
149
|
```
|
|
146
150
|
|
|
151
|
+
### Approve and deposit in one signature
|
|
152
|
+
|
|
153
|
+
When `checkAllowance` reports the allowance short, an EVM spoke source with an EIP-5792 wallet can send
|
|
154
|
+
`[resetTx?, approve tx, deposit tx]` from `approve` and `createDepositIntent` as one atomic batch: one wallet
|
|
155
|
+
prompt instead of two or three. This works because `createDepositIntent` builds the deposit without reading
|
|
156
|
+
the allowance, and `approve` targets the spender that deposit pulls from. Finish with `submitTx` (see
|
|
157
|
+
[Submit tx + poll status](#submit-tx--poll-status)), `operation: 'deposit'`, passing the deposit `txHash`,
|
|
158
|
+
`srcChainKey`, `walletAddress`, the `intent` converted with `toIntentRequest`, and `relayData.payload`.
|
|
159
|
+
Persist that body before the call, with the wire `intent` (decimal strings, so it survives
|
|
160
|
+
`JSON.stringify`): once the deposit is out, a failed `submitTx` is retried on its own, never by running the
|
|
161
|
+
flow again.
|
|
162
|
+
|
|
163
|
+
The batch, refusal and unconfirmed-batch rules are the ones in
|
|
164
|
+
[Approve and send the intent in one signature](./swaps-api.md#approve-and-send-the-intent-in-one-signature).
|
|
165
|
+
Before waiting on the batch, persist from `onBatchSent` what a resume after a reload needs: the batch id,
|
|
166
|
+
the batch's call count and the `submitTx` body except `txHash`. Resume an unconfirmed batch with
|
|
167
|
+
`confirmApprovalBatch` and finish it with that state; while the batch may still land, never create the
|
|
168
|
+
intent again or rerun the flow. A resume that returns `INTENT_CREATION_FAILED` with
|
|
169
|
+
`context.reason: 'atomic-batch-failed'` means nothing landed: drop the saved state and run the flow again.
|
|
170
|
+
After a refused batch, submit the `intent` and `relayData` of the deposit intent you created again. In
|
|
171
|
+
React, no `sodax-dapp-kit` hook batches this flow: `useLeverageYieldApiApproveAndBroadcast` approves in its
|
|
172
|
+
own prompts. The runnable flow is
|
|
173
|
+
[`leverageYieldApiApprovalBatch.test.ts`](https://github.com/gosodax/sodax-sdks/blob/main/packages/sdk/src/backendApi/leverageYieldApiApprovalBatch.test.ts): it asserts the
|
|
174
|
+
batch order, the new intent after a refusal, a `submitTx` retry and both outcomes of a resume from the
|
|
175
|
+
persisted state.
|
|
176
|
+
That a hub source or a wallet that cannot batch stays sequential is asserted in
|
|
177
|
+
[`approvalBatch.test.ts`](https://github.com/gosodax/sodax-sdks/blob/main/packages/sdk/src/shared/utils/approvalBatch.test.ts).
|
|
178
|
+
|
|
147
179
|
### Submit tx + poll status
|
|
148
180
|
|
|
181
|
+
Sign and broadcast `tx` on `srcChainKey` first, as in [`swaps-api.md`](swaps-api.md) § "Sign and broadcast
|
|
182
|
+
`tx`"; the returned hash is the `txHash` below.
|
|
183
|
+
|
|
149
184
|
```ts
|
|
150
|
-
// `intent`
|
|
185
|
+
// Convert the create-intent `intent` (decimal strings) with `toIntentRequest`, as in swaps-api.md § "Submit tx + poll status".
|
|
151
186
|
// `LeverageYieldSubmitTxRequestV2` is the swaps body PLUS a required `operation` discriminator, which the
|
|
152
187
|
// backend needs to record the queued row as a vault deposit or withdrawal.
|
|
153
188
|
const submit = await sodax.api.leverageYield.submitTx({
|
|
154
|
-
txHash, srcChainKey, walletAddress, intent,
|
|
189
|
+
txHash, srcChainKey, walletAddress, intent: toIntentRequest(intent),
|
|
155
190
|
relayData: relayData.payload, // string — the payload, not the RelayExtraData object
|
|
156
191
|
operation: 'deposit', // required: 'deposit' | 'withdraw'
|
|
157
192
|
});
|
|
@@ -161,7 +196,7 @@ if (!submit.ok) return;
|
|
|
161
196
|
const status = await sodax.api.leverageYield.getSubmitTxStatus({ txHash, srcChainKey });
|
|
162
197
|
// A vault swap IS a solver swap, so terminal success is 'solved' — NOT the bridge API's 'executed'.
|
|
163
198
|
if (status.ok && status.value.data.status === 'solved') { /* settled */ }
|
|
164
|
-
// Lifecycle: 'pending' → 'relaying' → 'relayed' → 'posting_execution' → 'solved' | 'failed'.
|
|
199
|
+
// Lifecycle: 'pending' → 'relaying' → 'relayed' → 'posting_execution' → 'posted_execution' → 'solved' | 'failed'.
|
|
165
200
|
// A set `abandonedAt` is terminal too, even while `status` is still non-terminal.
|
|
166
201
|
```
|
|
167
202
|
|
|
@@ -114,6 +114,8 @@ await sodax.moneyMarket.borrow({
|
|
|
114
114
|
|
|
115
115
|
Same-chain borrow: omit `dstChainKey` and `dstAddress`.
|
|
116
116
|
|
|
117
|
+
Borrow reads the token's reserve on the hub first. When the pool cannot lend it (borrowing disabled on a collateral-only reserve, or the reserve is frozen or paused) it returns `VALIDATION_FAILED` with `context.field: 'token'` and sends nothing. Hide the option up front with `borrowingEnabled` from the reserve data.
|
|
118
|
+
|
|
117
119
|
### Repay (cross-chain — pay from a different chain than the debt)
|
|
118
120
|
|
|
119
121
|
```ts
|
|
@@ -13,6 +13,10 @@ not select a solver endpoint. `isSwapSupportedToken` accepts both tiers, so do n
|
|
|
13
13
|
use it to establish production readiness. Query the list for the environment the
|
|
14
14
|
integration targets instead of hardcoding symbols.
|
|
15
15
|
|
|
16
|
+
These lists, and the tokens `sodax.swaps` accepts, are bundled with the installed `@sodax/sdk`.
|
|
17
|
+
For a token the backend lists after that release, use `sodax.api.swaps` end to end
|
|
18
|
+
([`swaps-api.md`](swaps-api.md)); `initialize()` does not add tokens.
|
|
19
|
+
|
|
16
20
|
A production promotion retains staging availability through `getStagingSolverTokens`.
|
|
17
21
|
Do not treat absence from `stagingSwapSupportedTokens` as absence from staging;
|
|
18
22
|
production tokens are supplied by the union accessor.
|
|
@@ -79,7 +83,7 @@ sodax.swaps.getApprovalStrategy<K extends SpokeChainKey>(
|
|
|
79
83
|
sodax.swaps.getSwapSpeedTier(params: { srcToken: XToken; dstToken: XToken }): SwapSpeedTierResult;
|
|
80
84
|
// Synchronous, offline, no Result wrapper — estimates settlement speed from SDK config alone
|
|
81
85
|
// (no network / on-chain / backend call). SwapSpeedTierResult = { tier: 'fast'|'normal'|'slow', estimatedSeconds }.
|
|
82
|
-
// A token whose `vault` is a money-market reserve (sodaAsset) settles faster; an Ethereum leg adds a fixed penalty.
|
|
86
|
+
// A token whose `vault` is a non-RWA money-market reserve (sodaAsset) settles faster; an Ethereum leg adds a fixed penalty.
|
|
83
87
|
// Safe to call synchronously while rendering a quote (e.g. an ETA badge next to the output amount).
|
|
84
88
|
|
|
85
89
|
sodax.swaps.getStatus(
|
|
@@ -275,7 +279,7 @@ const { quoted_amount } = quote.value; // bigint output amount in dst-token un
|
|
|
275
279
|
```ts
|
|
276
280
|
const inputToken = sodax.config.findSupportedTokenBySymbol(ChainKeys.ARBITRUM_MAINNET, 'USDC');
|
|
277
281
|
const outputToken = sodax.config.findSupportedTokenBySymbol(ChainKeys.STELLAR_MAINNET, 'XLM');
|
|
278
|
-
if (!inputToken || !outputToken) throw new Error('Token
|
|
282
|
+
if (!inputToken || !outputToken) throw new Error('Token not bundled with this @sodax/sdk version');
|
|
279
283
|
|
|
280
284
|
const result = await sodax.swaps.swap({
|
|
281
285
|
params: {
|
|
@@ -235,12 +235,43 @@ When you need hook support independent of the deployment, build with `sodax.swap
|
|
|
235
235
|
the hook client-side into `dstAddress`/`data`, and under the default `useBackendSubmitTx` still hands the
|
|
236
236
|
broadcast tx to this API's `submitTx`. See [`swap.md`](swap.md) § "Delivery hooks".
|
|
237
237
|
|
|
238
|
+
### Sign and broadcast `tx`
|
|
239
|
+
|
|
240
|
+
The API returns an unsigned transaction for `srcChainKey`; the SDK and dapp-kit have no helper that signs
|
|
241
|
+
it. Sign and broadcast it with that chain's wallet provider, dispatching on the chain type:
|
|
242
|
+
|
|
243
|
+
| Chain type | Wallet-provider call | Notes |
|
|
244
|
+
|---|---|---|
|
|
245
|
+
| EVM | `sendTransaction(tx, { expectedChainId: getEvmViemChain(srcChainKey).id })` | binds the send to the source network |
|
|
246
|
+
| Solana, Stellar, Stacks, Injective | `signAndSendTransaction(tx)` | optional on these interfaces: check it exists first |
|
|
247
|
+
| Sui | `signAndExecuteTxn({ toJSON: async () => tx.data })` | `tx.data` is the base64 transaction |
|
|
248
|
+
| ICON | `sendTransaction(tx as unknown as IcxCallTransaction)` | the runtime value is an `IcxCallTransaction`, but `RawTxReturnType`'s ICON variant is typed differently |
|
|
249
|
+
| NEAR | `signAndSubmitTxn(tx)` | |
|
|
250
|
+
| Bitcoin | `sodax.spoke.getSpokeService(ChainKeys.BITCOIN_MAINNET).signAndSubmitRawTransaction({ rawTx: tx, walletProvider, relayData, accessToken })` | needs a Bound Exchange session; put its token in the request body's `bound.accessToken` too. `relayData` fields are typed `Hex` here, plain strings on the API response |
|
|
251
|
+
|
|
252
|
+
Each call returns the source-chain hash, which is the `txHash` for `submitTx`. Stacks request bodies also
|
|
253
|
+
need `srcPublicKey`. An `approve` plan (`{ tx, resetTx? }`) is broadcast the same way, `resetTx` first and
|
|
254
|
+
mined before `tx`. The Bridge and Leverage Yield API clients return the same `tx` shapes, so this table
|
|
255
|
+
applies to them too.
|
|
256
|
+
|
|
238
257
|
### Submit tx + poll status
|
|
239
258
|
|
|
240
259
|
```ts
|
|
241
|
-
//
|
|
260
|
+
// createIntent returns IntentResponseV2 (decimal strings); submitTx takes IntentRequestV2 (bigint).
|
|
261
|
+
function toIntentRequest(intent: IntentResponseV2): IntentRequestV2 {
|
|
262
|
+
return {
|
|
263
|
+
...intent,
|
|
264
|
+
intentId: BigInt(intent.intentId),
|
|
265
|
+
inputAmount: BigInt(intent.inputAmount),
|
|
266
|
+
minOutputAmount: BigInt(intent.minOutputAmount),
|
|
267
|
+
deadline: BigInt(intent.deadline),
|
|
268
|
+
srcChain: BigInt(intent.srcChain),
|
|
269
|
+
dstChain: BigInt(intent.dstChain),
|
|
270
|
+
};
|
|
271
|
+
}
|
|
272
|
+
|
|
242
273
|
const submit = await sodax.api.swaps.submitTx({
|
|
243
|
-
txHash, srcChainKey, walletAddress, intent,
|
|
274
|
+
txHash, srcChainKey, walletAddress, intent: toIntentRequest(intent),
|
|
244
275
|
relayData: relayData.payload, // string — the payload, not the RelayExtraData object
|
|
245
276
|
});
|
|
246
277
|
if (!submit.ok) return;
|
|
@@ -249,6 +280,7 @@ if (!submit.ok) return;
|
|
|
249
280
|
const status = await sodax.api.swaps.getSubmitTxStatus({ txHash, srcChainKey });
|
|
250
281
|
if (status.ok && status.value.data.status === 'solved') { /* settled */ }
|
|
251
282
|
// Lifecycle: 'pending' → 'relaying' → 'relayed' → 'posting_execution' → 'posted_execution' → 'solved' | 'failed'.
|
|
283
|
+
// Stop polling on 'solved', 'failed', or a set `data.abandonedAt` (processing budget exhausted).
|
|
252
284
|
```
|
|
253
285
|
|
|
254
286
|
## Status fields — three distinct `status` values (don't conflate)
|
|
@@ -301,8 +333,8 @@ The swaps slice layers over the base slice over the defaults (per field), so a c
|
|
|
301
333
|
const r = await sodax.api.swaps.getQuote(body);
|
|
302
334
|
if (!r.ok) {
|
|
303
335
|
// r.error: SodaxError<'EXTERNAL_API_ERROR'> — feature: 'backend', context.api: 'swaps',
|
|
304
|
-
// context.endpoint: '/swaps/quote'. The transport failure (
|
|
305
|
-
// a shape-validation issue) is on r.error.cause.
|
|
336
|
+
// context.endpoint: '/swaps/quote'. The transport failure (NETWORK_ERROR / TIMEOUT_ERROR / HTTP_ERROR /
|
|
337
|
+
// a shape-validation issue) is on r.error.cause, its code mirrored on r.error.context.code.
|
|
306
338
|
return;
|
|
307
339
|
}
|
|
308
340
|
```
|
|
@@ -55,7 +55,7 @@ Examples in this guide use TypeScript `declare const` placeholders so the surfac
|
|
|
55
55
|
import { Sodax } from '@sodax/sdk';
|
|
56
56
|
|
|
57
57
|
const sodax = new Sodax();
|
|
58
|
-
await sodax.config.initialize(); //
|
|
58
|
+
await sodax.config.initialize(); // optional; adds no tokens
|
|
59
59
|
|
|
60
60
|
// All feature services are wired and ready:
|
|
61
61
|
// sodax.swaps, sodax.moneyMarket, sodax.bridge, sodax.staking,
|
|
@@ -222,7 +222,7 @@ The errors most likely to hit on a fresh install or first port.
|
|
|
222
222
|
|
|
223
223
|
### `sodax.config.findSupportedTokenBySymbol` returns `undefined`
|
|
224
224
|
|
|
225
|
-
- `
|
|
225
|
+
- The token is not bundled with your `@sodax/sdk` version; `initialize()` does not add tokens. Upgrade, or take tokens from `sodax.api.swaps.getTokens()` and use the `sodax.api.*` clients. See [`recipes/initialize-sodax.md`](recipes/initialize-sodax.md) § "Where supported tokens come from".
|
|
226
226
|
|
|
227
227
|
### "Property 'xChainId' does not exist on type 'XToken'"
|
|
228
228
|
|
|
@@ -236,9 +236,9 @@ The errors most likely to hit on a fresh install or first port.
|
|
|
236
236
|
|
|
237
237
|
- For EVM chains, `GetAddressType<K>` is `` `0x${string}` ``. Cast at the boundary: `(await walletProvider.getWalletAddress()) as \`0x${string}\``. See [`recipes/`](recipes/) § "Chain-key narrowing".
|
|
238
238
|
|
|
239
|
-
### `
|
|
239
|
+
### `unsupported token_src` / `Unsupported spoke chain … token` for a token the backend lists
|
|
240
240
|
|
|
241
|
-
-
|
|
241
|
+
- `sodax.swaps`, `sodax.bridge` and `sodax.leverageYield` validate against the tokens bundled with your SDK version before sending anything. Upgrade `@sodax/sdk`, or run the flow on `sodax.api.swaps` / `sodax.api.bridge` / `sodax.api.leverageYield`, where the backend validates. See [`recipes/initialize-sodax.md`](recipes/initialize-sodax.md) § "Where supported tokens come from".
|
|
242
242
|
|
|
243
243
|
### Stellar bridge / swap fails with `'Trustline missing'`
|
|
244
244
|
|
|
@@ -6,7 +6,7 @@ The minimal init — packaged defaults, no config override:
|
|
|
6
6
|
import { Sodax } from '@sodax/sdk';
|
|
7
7
|
|
|
8
8
|
const sodax = new Sodax();
|
|
9
|
-
await sodax.config.initialize(); //
|
|
9
|
+
await sodax.config.initialize(); // optional; adds no tokens
|
|
10
10
|
|
|
11
11
|
// All feature services are wired and ready:
|
|
12
12
|
const result = sodax.config.isValidSpokeChainKey(ChainKeys.ARBITRUM_MAINNET); // returns boolean (sync)
|
|
@@ -71,13 +71,20 @@ await sodax.config.initialize();
|
|
|
71
71
|
|
|
72
72
|
> Both knobs target the same physical chain (Sonic) but back distinct clients, so set **both** for end-to-end hub resilience — `hub.rpcUrls` covers the hub provider and `chains.[SONIC_MAINNET].rpcUrls` covers the swap/intent path. Omit them to keep the single-endpoint default (fully backward compatible). The endpoint list is read once at `new Sodax(...)` time.
|
|
73
73
|
|
|
74
|
-
###
|
|
74
|
+
### What `initialize()` does today
|
|
75
75
|
|
|
76
|
-
`config.initialize()`
|
|
76
|
+
`config.initialize()` returns `{ ok: true }` without fetching anything: the instance keeps the packaged config merged with your constructor overrides, and `isInitialized()` stays `false`. Calling it once at startup is harmless; don't `await` it inside every feature call.
|
|
77
77
|
|
|
78
|
-
###
|
|
78
|
+
### Where supported tokens come from
|
|
79
79
|
|
|
80
|
-
|
|
80
|
+
The SDK knows the chains and tokens bundled with the installed `@sodax/sdk` version, and nothing newer. That decides what happens to a token the backend lists after your release:
|
|
81
|
+
|
|
82
|
+
| Path | Token check | Token newer than the installed SDK |
|
|
83
|
+
|---|---|---|
|
|
84
|
+
| `sodax.swaps`, `sodax.bridge`, `sodax.leverageYield` and their dapp-kit hooks | client side, against the bundled list, before any request | rejected (`unsupported token_src`, `Unsupported spoke chain token` (swaps, leverage yield) / `Unsupported spoke chain (<chain>) token` (bridge)) |
|
|
85
|
+
| `sodax.api.swaps`, `sodax.api.bridge`, `sodax.api.leverageYield` and the `useSwapsApi*`, `useBridgeApi*`, `useLeverageYieldApi*` hooks | backend, against its own list | accepted |
|
|
86
|
+
|
|
87
|
+
When the app must offer tokens the installed SDK does not bundle, or cannot upgrade: take the token list from `sodax.api.swaps.getTokens()` (bridge: `sodax.api.bridge.getTokens()`), and run the whole flow on the API client: quote, approve, create intent, sign and broadcast the returned `tx`, `submitTx`, poll status. See [`../features/swaps-api.md`](../features/swaps-api.md), [`../features/bridge-api.md`](../features/bridge-api.md) and [`../features/leverage-yield-api.md`](../features/leverage-yield-api.md). Otherwise, upgrade `@sodax/sdk` to get the new tokens on the feature services.
|
|
81
88
|
|
|
82
89
|
## Module-scope reads (no Sodax instance needed)
|
|
83
90
|
|
|
@@ -102,7 +109,7 @@ export const SUPPORTED_TOKENS_PER_CHAIN = sodaxConfig.swaps.supportedTokens;
|
|
|
102
109
|
| Per-chain spoke config (rpcUrl, nativeToken, addresses, supportedTokens, polling) | `spokeChainConfig[ChainKeys.X_MAINNET]` (from `@sodax/types` / `@sodax/sdk`) | `sodax.config.spokeChainConfig[ChainKeys.X_MAINNET]` *or* `sodax.config.getChainConfig(ChainKeys.X_MAINNET)` |
|
|
103
110
|
| Money market reserve assets | `sodaxConfig.moneyMarket.supportedReserveAssets` | `sodax.config.getMoneyMarketReserveAssets()` |
|
|
104
111
|
|
|
105
|
-
> **Static vs dynamic — and the override-gap consequence.** `sodaxConfig` / `hubConfig` / `spokeChainConfig` are **packaged-default snapshots** frozen at SDK release time. They are safe at module scope but
|
|
112
|
+
> **Static vs dynamic — and the override-gap consequence.** `sodaxConfig` / `hubConfig` / `spokeChainConfig` are **packaged-default snapshots** frozen at SDK release time. They are safe at module scope but **won't reflect overrides passed to `new Sodax(config)`** — those merge into `sodax.config` (the `ConfigService`) but never mutate the static imports. So once a `Sodax` instance exists, prefer the instance-scope readers in the right column above — particularly `sodax.config.spokeChainConfig` over the same-named static import — or you will silently fall back to the packaged defaults for any chain you customized.
|
|
106
113
|
|
|
107
114
|
|
|
108
115
|
## Cross-references
|
|
@@ -18,10 +18,8 @@ new Sodax({ logger: 'console' }); // mirror console.* output
|
|
|
18
18
|
new Sodax({ logger: 'silent' }); // drop all SDK logs
|
|
19
19
|
```
|
|
20
20
|
|
|
21
|
-
The logger is resolved **once** at construction and held on `ConfigService` outside the
|
|
22
|
-
|
|
23
|
-
chain config from the backend but **never** replaces the logger — the backend cannot set or overwrite
|
|
24
|
-
it.
|
|
21
|
+
The logger is resolved **once** at construction and held on `ConfigService` outside the config
|
|
22
|
+
object (read it back as `sodax.config.logger`), so nothing the backend sends can set or overwrite it.
|
|
25
23
|
|
|
26
24
|
> Combine with the other constructor options freely — pass `logger` alongside `chains` / `api` /
|
|
27
25
|
> `solver` overrides in the same object. The merged options land on `sodax.instanceConfig` (including the
|
|
@@ -75,7 +75,7 @@ if (!result.ok) {
|
|
|
75
75
|
|
|
76
76
|
### Point tests at a sandbox backend
|
|
77
77
|
|
|
78
|
-
There is no constructor slot to inject a custom `IConfigApiV1` — the only backend knob is `api` (`ApiConfig = BackendApiConfig | CustomApiConfig`: pass a flat `{ baseURL, basePath?, timeout?, headers? }`, or a `CustomApiConfig` with separate `baseApiConfig` / `swapsApiConfig` endpoints). To
|
|
78
|
+
There is no constructor slot to inject a custom `IConfigApiV1` — the only backend knob is `api` (`ApiConfig = BackendApiConfig | CustomApiConfig`: pass a flat `{ baseURL, basePath?, timeout?, headers? }`, or a `CustomApiConfig` with separate `baseApiConfig` / `swapsApiConfig` endpoints). To send backend API calls to a sandbox or local mock server, set `api.baseURL`. Chain and token config stays packaged; `initialize()` does not fetch it:
|
|
79
79
|
|
|
80
80
|
```ts
|
|
81
81
|
import { Sodax } from '@sodax/sdk';
|
|
@@ -85,7 +85,7 @@ const sodax = new Sodax({
|
|
|
85
85
|
// serves `/config/*` at its origin needs `basePath: ''`.
|
|
86
86
|
api: { baseApiConfig: { baseURL: 'https://sandbox-api.example.com', basePath: '' } },
|
|
87
87
|
});
|
|
88
|
-
await sodax.
|
|
88
|
+
await sodax.backendApi.getAllConfig(); // → https://sandbox-api.example.com/config/all
|
|
89
89
|
```
|
|
90
90
|
|
|
91
91
|
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.
|
|
@@ -15,7 +15,7 @@ Granular skill for `LeverageYieldService` — `sodax.leverageYield`. Feature tag
|
|
|
15
15
|
|
|
16
16
|
0. **Vault or leverage position?** Ask this first — they share the service and nothing else. A **vault** is one pooled ERC-4626 position at a single target LTV, entered/exited as an intent swap (`deposit` / `withdraw` / `vaultSwap`). A **leverage position** is the user's own AAVE account, cloned per position, with its own eMode category and leverage tier (`openLeveragePosition` and friends). "Deposit into a leverage vault" is the first; "open a leverage position", "adjust my leverage", "close my position" is the second. If the answer is positions, jump to Step 1b.
|
|
17
17
|
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. **Except Bitcoin:** vault swaps refuse it on either side with `VALIDATION_FAILED`.
|
|
18
|
-
2. **Build vs execute.** `deposit` / `withdraw` only *build* a `LeverageYieldSwapPayload`; `vaultSwap` *executes* it end-to-end. Spread the built payload into `vaultSwap({ ...payload, walletProvider })`. `vaultSwapWithApproval` does the same with the deposit's approval folded in (one EIP-5792 batch when the wallet can); `getApprovalStrategy` predicts the path.
|
|
18
|
+
2. **Build vs execute.** `deposit` / `withdraw` only *build* a `LeverageYieldSwapPayload`; `vaultSwap` *executes* it end-to-end. Spread the built payload into `vaultSwap({ ...payload, walletProvider })`. `vaultSwapWithApproval` does the same with the deposit's approval folded in (one EIP-5792 batch when the wallet can); `getApprovalStrategy` predicts the path. Without `vaultSwapWithApproval`, approve the deposit's input token with `sodax.swaps.isAllowanceValid()` / `approve()`, then `vaultSwap`.
|
|
19
19
|
3. **End-to-end or manual relay?** By default `vaultSwap` creates the intent and hands it to the backend submit-tx flow, which relays and notifies the solver; on any backend non-success it falls back to verify → relay → notify client-side, and then resolves before the fill (opt out of the backend path with `leverageYield: { useBackendSubmitTx: false }`). For a fully manual flow, use `createVaultIntent`, relay yourself, and finish with the public `notifySolver`.
|
|
20
20
|
4. **Which vaults?** `listVaults()` (synchronous registry: `{ name, vault, asset, borrowToken, lsdSource? }`); pass `vault` to every call.
|
|
21
21
|
5. **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).
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: sodax-sdk-leverage-yield-api
|
|
3
|
-
description: 'Granular skill for the @sodax/sdk v2 Leverage Yield API client — `sodax.api.leverageYield` (class LeverageYieldApiService), a typed HTTP client for the backend Leverage Yield API (`/leverage-yield/*`, 33 endpoints: vault registry, vault reads (asset/position/APR/effective-APR/LSD-APR/total-assets/previews/share-balance/max-withdraw), deposit & withdraw quote, deadline, allowance/approve, create-deposit-intent & create-withdraw-intent, intent submit/status/cancel/hash/packet/extra-data/fill/get, gas estimate, partner/solver fees, submit-tx + status). Every method returns Promise<Result<T>>, never throws, and validates the response. Use when the task calls the leverage-yield backend directly (e.g. "sodax.api.leverageYield", "leverage vault APR from the backend", "vault position from the API", "leverage-yield deposit quote", "createDepositIntent via the backend API", "leverage-yield API v2"). For the higher-level
|
|
3
|
+
description: 'Granular skill for the @sodax/sdk v2 Leverage Yield API client — `sodax.api.leverageYield` (class LeverageYieldApiService), a typed HTTP client for the backend Leverage Yield API (`/leverage-yield/*`, 33 endpoints: vault registry, vault reads (asset/position/APR/effective-APR/LSD-APR/total-assets/previews/share-balance/max-withdraw), deposit & withdraw quote, deadline, allowance/approve, create-deposit-intent & create-withdraw-intent, intent submit/status/cancel/hash/packet/extra-data/fill/get, gas estimate, partner/solver fees, submit-tx + status). Every method returns Promise<Result<T>>, never throws, and validates the response. Use when the task calls the leverage-yield backend directly (e.g. "sodax.api.leverageYield", "leverage vault APR from the backend", "vault position from the API", "leverage-yield deposit quote", "createDepositIntent via the backend API", "approve and deposit in one signature", "leverage-yield API v2"), or must accept tokens the installed SDK does not bundle ("unsupported token_src"). For the higher-level vault-swap orchestrator, which accepts only bundled tokens, use the `leverage-yield` skill instead. Skill links into the parent sodax-sdk knowledge tree.'
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Leverage Yield API (Core SDK granular skill)
|
|
@@ -24,18 +24,19 @@ this is the leverage-yield sibling of the [`swaps-api`](../swaps-api/SKILL.md) s
|
|
|
24
24
|
previews/share-balance/max-withdraw) · deposit/withdraw quote · deadline · allowance/approve ·
|
|
25
25
|
create-deposit-intent / create-withdraw-intent · intent lifecycle (submit/status/cancel/hash/packet/
|
|
26
26
|
extra-data/fill/get) · gas/fees · submit-tx/status.
|
|
27
|
-
2. **Orchestrator or raw API?**
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
27
|
+
2. **Orchestrator or raw API?** `sodax.leverageYield` (the `leverage-yield` skill) quotes and builds
|
|
28
|
+
locally, so it accepts only tokens bundled with the installed `@sodax/sdk`. Use `sodax.api.leverageYield`
|
|
29
|
+
end to end for tokens newer than the installed SDK, where the backend validates, or for a single backend
|
|
30
|
+
call (a vault APR, a position read, a quote, a status poll). Otherwise prefer `sodax.leverageYield` for
|
|
31
|
+
"deposit into / withdraw from a leverage vault".
|
|
31
32
|
3. **Deposit vs withdraw?** Create-intent is split: `createDepositIntent` (any token → `lsoda*`, needs a
|
|
32
33
|
spoke allowance) vs `createWithdrawIntent` (`lsoda*` → any token, hub-wallet swap, no spoke allowance).
|
|
33
34
|
|
|
34
35
|
## Integration workflow
|
|
35
36
|
|
|
36
37
|
1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT (read first).
|
|
37
|
-
2. [`../integration/knowledge/features/leverage-yield-api.md`](../integration/knowledge/features/leverage-yield-api.md) — the full 33-endpoint client: signatures, wire shapes (bigint vs decimal string), common call shapes (vault reads, deposit quote, create-intent, submit-tx + status), per-call overrides, custom endpoint, the `useBackendSubmitTx` service option.
|
|
38
|
-
3. For the
|
|
38
|
+
2. [`../integration/knowledge/features/leverage-yield-api.md`](../integration/knowledge/features/leverage-yield-api.md) — the full 33-endpoint client: signatures, wire shapes (bigint vs decimal string), common call shapes (vault reads, deposit quote, create-intent, submit-tx + status), per-call overrides, custom endpoint, the `useBackendSubmitTx` service option, and approving and depositing in one EIP-5792 signature.
|
|
39
|
+
3. For the SDK vault-swap flow (local quote and build; only its submit-tx leg calls this API) → [`../integration/knowledge/features/leverage-yield.md`](../integration/knowledge/features/leverage-yield.md); for the intent-sibling swaps client → [`../integration/knowledge/features/swaps-api.md`](../integration/knowledge/features/swaps-api.md).
|
|
39
40
|
4. Errors are `Result<T, SodaxError<'EXTERNAL_API_ERROR'>>` → [`../integration/knowledge/recipes/result-and-errors.md`](../integration/knowledge/recipes/result-and-errors.md) and [`../integration/knowledge/reference/error-codes.md`](../integration/knowledge/reference/error-codes.md).
|
|
40
41
|
|
|
41
42
|
### Leverage-Yield-API-specific anti-patterns
|
|
@@ -45,7 +46,8 @@ this is the leverage-yield sibling of the [`swaps-api`](../swaps-api/SKILL.md) s
|
|
|
45
46
|
- **Omitting `operation` on `submitTx`.** `LeverageYieldSubmitTxRequestV2` is the swaps body PLUS a required `operation: 'deposit' | 'withdraw'` — the backend records the queued row from it.
|
|
46
47
|
- **Polling for `'executed'`.** A vault swap IS a solver swap, so terminal success is `'solved'` (`'executed'` is the *bridge* API's terminal state). A set `abandonedAt` is terminal too.
|
|
47
48
|
- **Broadcasting `approve`'s `tx` without its `resetTx`.** `ApproveResponseV2` is `{ tx, resetTx? }`; a guarded input token needs `resetTx` MINED first or the approve reverts. In `@sodax/dapp-kit`, prefer `useLeverageYieldApiApproveAndBroadcast`, which owns that ordering.
|
|
48
|
-
- **
|
|
49
|
+
- **Passing the create-intent `intent` straight to `submitTx`.** It is `IntentResponseV2` (decimal strings); `submitTx` takes `IntentRequestV2` (bigint). Convert it with `toIntentRequest` ([`features/swaps-api.md`](../integration/knowledge/features/swaps-api.md) § "Submit tx + poll status"); don't stringify bigints yourself.
|
|
50
|
+
- **Assuming the approve needs its own prompt.** From an EVM spoke, an EIP-5792 wallet can sign `[resetTx?, approve, deposit]` once — see "Approve and deposit in one signature" in the leverage-yield-api feature doc. `useLeverageYieldApiApproveAndBroadcast` above approves separately; batching means running that flow with the SDK.
|
|
49
51
|
- **Checking allowance for a withdraw.** `createWithdrawIntent` is a hub-wallet swap (spends `lsoda*` from the hub wallet) — there is no spoke allowance step. `checkAllowance`/`approve` take the **deposit** params only.
|
|
50
52
|
- **Calling `getSubmitTxStatus` with only `txHash`.** Both `txHash` AND `srcChainKey` are required.
|
|
51
53
|
- **Confusing `sodax.api.leverageYield` with `sodax.leverageYield`.** The former is the backend HTTP client; the latter is the on-chain vault-swap orchestrator.
|
|
@@ -65,12 +67,12 @@ the swap + backend-api migration docs if you need the deltas:
|
|
|
65
67
|
2. Every `await sodax.api.leverageYield.<method>(...)` call site has `if (!result.ok)`.
|
|
66
68
|
3. `submitTx.relayData` is `relayData.payload` (string), `submitTx` carries `operation`, and `getSubmitTxStatus` passes both `txHash` and `srcChainKey`.
|
|
67
69
|
4. Submit-tx status polling stops on `'solved'` / `'failed'` / `abandonedAt` — not on `'executed'`.
|
|
68
|
-
5.
|
|
70
|
+
5. The `intent` given to `submitTx` is an `IntentRequestV2` (bigint) converted from the create-intent `IntentResponseV2`; no manual `.toString()`.
|
|
69
71
|
6. Allowance/approve are used only for the deposit path (withdraw is a hub-wallet swap), and a returned `resetTx` is broadcast and mined before `tx`.
|
|
70
72
|
|
|
71
73
|
## Related granular skills (same family)
|
|
72
74
|
|
|
73
|
-
- [`../leverage-yield/SKILL.md`](../leverage-yield/SKILL.md) — the
|
|
75
|
+
- [`../leverage-yield/SKILL.md`](../leverage-yield/SKILL.md) — the vault-swap orchestrator (`sodax.leverageYield`): it quotes and builds locally against the bundled tokens and uses this API only for submit-tx.
|
|
74
76
|
- [`../swaps-api/SKILL.md`](../swaps-api/SKILL.md) — the intent-sibling Swaps API client (`sodax.api.swaps`), same intent-relay/gas/fee/submit-tx wire shapes.
|
|
75
77
|
- [`../backend-api/SKILL.md`](../backend-api/SKILL.md) — the sibling `sodax.backendApi` read client (intent / orderbook / money-market reads + config).
|
|
76
78
|
|
|
@@ -10,7 +10,7 @@ v2 was a deep architectural reshape, not a feature release. Five orthogonal chan
|
|
|
10
10
|
2. **`Result<T>` everywhere.** Every async public method on every service returns `Promise<Result<T, SodaxError<C>>>`. v1 throw-on-error patterns are gone.
|
|
11
11
|
3. **One canonical error class.** `SodaxError<C>` with a closed 13-code vocabulary plus `feature: 'swap' | 'moneyMarket' | …`. The per-module typed error unions (`MoneyMarketError<Code>`, `IntentError<Code>`, `StakingError<Code>`, `BridgeError<Code>`, `MigrationError<Code>`, `AssetServiceError<Code>`, `ConcentratedLiquidityError<Code>`, partner errors, …) are deleted.
|
|
12
12
|
4. **`WalletProviderSlot<K, Raw>` is the discriminated union.** Every signed-execution method takes `{ raw: false, walletProvider }` (chain-narrowed via `GetWalletProviderType<K>`); every raw-tx-building method takes `{ raw: true }` (no wallet provider). Compile-time enforced.
|
|
13
|
-
5. **`ConfigService` is the preferred lookup surface.** `hubAssets` and `*_MAINNET_CHAIN_ID` constants **are deleted** (won't compile). `moneyMarketSupportedTokens`, `SodaTokens`, `supportedSpokeChains` **are still exported** as packaged-default constants (so v1 imports keep compiling), but prefer `sodax.config.*` / `sodax.moneyMarket.getSupportedTokens*()` — those reflect
|
|
13
|
+
5. **`ConfigService` is the preferred lookup surface.** `hubAssets` and `*_MAINNET_CHAIN_ID` constants **are deleted** (won't compile). `moneyMarketSupportedTokens`, `SodaTokens`, `supportedSpokeChains` **are still exported** as packaged-default constants (so v1 imports keep compiling), but prefer `sodax.config.*` / `sodax.moneyMarket.getSupportedTokens*()` — those reflect your `new Sodax(config)` overrides. See [`breaking-changes/architecture.md`](breaking-changes/architecture.md) § 2 for the per-symbol table.
|
|
14
14
|
|
|
15
15
|
The remainder is per-feature (return shape diffs, field renames, new required params like `srcAddress`).
|
|
16
16
|
|
|
@@ -107,7 +107,7 @@ If your project's v1 wrapper code instantiated `*SpokeProvider` classes, don't t
|
|
|
107
107
|
|
|
108
108
|
### Static defaults — still exported, prefer the service API
|
|
109
109
|
|
|
110
|
-
These v1 names still ship through `@sodax/sdk` (re-exported from `@sodax/types`), so a v1 `import { ... } from '@sodax/sdk'` will not break.
|
|
110
|
+
These v1 names still ship through `@sodax/sdk` (re-exported from `@sodax/types`), so a v1 `import { ... } from '@sodax/sdk'` will not break. Both paths return packaged values (`initialize()` does not fetch backend config); the service API also reflects `new Sodax(config)` overrides, so prefer it.
|
|
111
111
|
|
|
112
112
|
| v1 export | v2 status | Preferred v2 API |
|
|
113
113
|
|---|---|---|
|
|
@@ -120,11 +120,11 @@ These v1 names still ship through `@sodax/sdk` (re-exported from `@sodax/types`)
|
|
|
120
120
|
|
|
121
121
|
### What replaces them
|
|
122
122
|
|
|
123
|
-
`ConfigService` is a stateful service owned by `Sodax`. It
|
|
123
|
+
`ConfigService` is a stateful service owned by `Sodax`. It holds the packaged defaults from `@sodax/types` merged with constructor overrides (`initialize()` does not fetch backend config today), and every lookup goes through it:
|
|
124
124
|
|
|
125
125
|
```ts
|
|
126
126
|
const sodax = new Sodax(/* optional config override */);
|
|
127
|
-
await sodax.config.initialize(); //
|
|
127
|
+
await sodax.config.initialize(); // optional; adds no tokens
|
|
128
128
|
|
|
129
129
|
// Token lookups
|
|
130
130
|
const usdc = sodax.config.findSupportedTokenBySymbol(ChainKeys.ARBITRUM_MAINNET, 'USDC');
|
|
@@ -37,8 +37,8 @@ Work this top-down. Each step is independent enough to land as its own commit; t
|
|
|
37
37
|
SodaTokens, supportedSpokeChains) with the equivalent sodax.config.* /
|
|
38
38
|
sodax.moneyMarket.getSupportedTokens*() call. Per-symbol deleted-vs-
|
|
39
39
|
still-exported status: see breaking-changes/architecture.md § 2.
|
|
40
|
-
[ ] 12.
|
|
41
|
-
|
|
40
|
+
[ ] 12. Optional: await sodax.config.initialize() at app startup. It fetches nothing
|
|
41
|
+
today; tokens and chains come from the installed SDK version.
|
|
42
42
|
[ ] 13. Add { raw: true } to any read-only allowance check that previously took
|
|
43
43
|
a spoke provider but didn't actually consult it (the underlying SDK
|
|
44
44
|
method now requires WalletProviderSlot).
|
|
@@ -30,7 +30,7 @@ Pair: [`features/money-market.md`](../../../integration/knowledge/features/money
|
|
|
30
30
|
|
|
31
31
|
- `moneyMarketSupportedTokens` — `Record<SpokeChainKey, XToken[]>` global. Use `sodax.moneyMarket.getSupportedTokensByChainId(chainKey)` / `getSupportedTokens()`.
|
|
32
32
|
- `hubAssets` — vault address lookup global. Use `XToken.vault` / `XToken.hubAsset` directly.
|
|
33
|
-
- `SodaTokens` — hub-vault registry. It is feature-neutral: a vault listed there is not necessarily a money-market reserve (
|
|
33
|
+
- `SodaTokens` — hub-vault registry. It is feature-neutral: a vault listed there is not necessarily a money-market reserve (most Robinhood tokenized equities are swap-only, for example). Never derive reserve support from it — use `sodax.config.getMoneyMarketReserveAssets()`.
|
|
34
34
|
- `MoneyMarketError<MoneyMarketErrorCode>` and `isMoneyMarketError` — replaced by `SodaxError<C>` + `isSodaxError(e) && e.feature === 'moneyMarket'`.
|
|
35
35
|
|
|
36
36
|
### v1 → v2 error code crosswalk (money-market-specific)
|
|
@@ -142,7 +142,7 @@ The real v2 answer: read directly from the packaged-default const `sodaxConfig`,
|
|
|
142
142
|
+ const moneyMarketTokens = sodaxConfig.moneyMarket.supportedTokens;
|
|
143
143
|
```
|
|
144
144
|
|
|
145
|
-
> **Once you have a `Sodax` instance**, prefer `sodax.config.*` (`sodax.config.getHubChainConfig()`, `sodax.config.getMoneyMarketReserveAssets()`, etc.). The service-API path reflects
|
|
145
|
+
> **Once you have a `Sodax` instance**, prefer `sodax.config.*` (`sodax.config.getHubChainConfig()`, `sodax.config.getMoneyMarketReserveAssets()`, etc.). The service-API path reflects your constructor overrides; `sodaxConfig` is a packaged-default snapshot frozen at SDK release time.
|
|
146
146
|
|
|
147
147
|
For hub-only module-scope reads, `hubConfig` is also exported directly:
|
|
148
148
|
|
|
@@ -141,7 +141,7 @@ const HUB_WALLET = hubConfig.addresses.hubWallet; // module-scope OK
|
|
|
141
141
|
const DEFAULT_RELAY = sodaxConfig.relay; // module-scope OK
|
|
142
142
|
```
|
|
143
143
|
|
|
144
|
-
`hubConfig` / `sodaxConfig` are the **packaged defaults** — the
|
|
144
|
+
`hubConfig` / `sodaxConfig` are the **packaged defaults** — the values `ConfigService` serves (`initialize()` fetches nothing today). Once you have a `Sodax` instance, prefer `sodax.config.getHubChainConfig()` / `sodax.config.*` so your `new Sodax(config)` overrides take effect.
|
|
145
145
|
|
|
146
146
|
---
|
|
147
147
|
|
|
@@ -22,7 +22,7 @@ Swap has materially different code paths depending on the answers. Don't skip:
|
|
|
22
22
|
- Signed → `raw: false` + `walletProvider`.
|
|
23
23
|
- Unsigned → `raw: true`, you handle relay yourself.
|
|
24
24
|
3. **One-shot `swap()` or step-by-step (`createIntent` → backend submit → `postExecution`)?**
|
|
25
|
-
- One-shot is the default for frontends. If the token may need an approval, prefer `swapWithApproval()` — it approves only when needed, and on an EIP-5792 wallet does approve + swap in one signature (`getApprovalStrategy()` tells you which path it will take). A wallet that must first upgrade the account (`'ready'`) prompts for it; pass `allowAccountUpgrade: false` to skip that and approve separately, e.g. after a `USER_REJECTED` with `context.reason === ACCOUNT_UPGRADE_DECLINED`. Step-by-step is for backends that already have a relay/orchestration layer.
|
|
25
|
+
- One-shot is the default for frontends. If the token may need an approval, prefer `swapWithApproval()` — it approves only when needed, and on an EIP-5792 wallet does approve + swap in one signature (`getApprovalStrategy()` tells you which path it will take). A wallet that must first upgrade the account (`'ready'`) prompts for it; pass `allowAccountUpgrade: false` to skip that and approve separately, e.g. after a `USER_REJECTED` with `context.reason === ACCOUNT_UPGRADE_DECLINED`. Step-by-step is for backends that already have a relay/orchestration layer. If your SDK has no `swapWithApproval()`, gate with `isAllowanceValid()`, call `approve()` and wait for it, then `swap()`.
|
|
26
26
|
- Step-by-step code must reproduce BOTH paths `swap()` runs internally — the backend submit-tx attempt *and* the client-side relay fallback on any non-success. The helpers behind `swap()` are package-internal, so the loop is hand-written: [`../integration/knowledge/recipes/manual-submit-tx-with-fallback.md`](../integration/knowledge/recipes/manual-submit-tx-with-fallback.md).
|
|
27
27
|
4. **Market order or limit order?** Limit orders use a different params shape — `deadline` becomes optional (forced to `0n` internally), not required.
|
|
28
28
|
|