@sodax/skills 2.1.0-rc.4 → 2.1.0-rc.6
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/package.json +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/features/auxiliary-services.md +13 -1
- package/skills/sodax-dapp-kit/integration/knowledge/features/swap.md +31 -1
- package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md +2 -1
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/swap.md +1 -1
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/reference/renamed-hooks.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/architecture.md +5 -4
- package/skills/sodax-sdk/integration/knowledge/features/backend-api.md +7 -3
- package/skills/sodax-sdk/integration/knowledge/features/bridge-api.md +4 -2
- package/skills/sodax-sdk/integration/knowledge/features/swap.md +31 -0
- package/skills/sodax-sdk/integration/knowledge/features/swaps-api.md +20 -4
- package/skills/sodax-sdk/integration/knowledge/recipes/initialize-sodax.md +5 -2
- package/skills/sodax-sdk/integration/knowledge/recipes/testing.md +4 -2
- package/skills/sodax-sdk/integration/knowledge/reference/public-api.md +10 -2
- package/skills/sodax-sdk/swaps-api/SKILL.md +3 -1
package/package.json
CHANGED
|
@@ -75,6 +75,18 @@ useSwapsApiSubmitTx({ mutationOptions }); // mutation → sodax.ap
|
|
|
75
75
|
useSwapsApiSubmitTxStatus({ params, queryOptions }); // query → sodax.api.swaps.getSubmitTxStatus
|
|
76
76
|
```
|
|
77
77
|
|
|
78
|
+
These hooks forward the body verbatim, so `partnerFee` has no default (SDK fee config does not
|
|
79
|
+
apply). Put the same value on quote and create-intent:
|
|
80
|
+
|
|
81
|
+
```ts
|
|
82
|
+
// @ai-snippets-skip
|
|
83
|
+
const partnerFee = { address: '0xSonicFeeReceiver', percentage: 10 }; // 10 = 0.1% (bps)
|
|
84
|
+
const { data: quote } = useSwapsApiQuote({ params: { body: { ...quoteBody, partnerFee } } });
|
|
85
|
+
await createIntent({ body: { ...intentBody, partnerFee } });
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
See the `sodax-sdk` skill (integration mode), `swaps-api.md` § `partnerFee`.
|
|
89
|
+
|
|
78
90
|
`useSwapsApiSubmitTx` is a mutation hook — per-call config (e.g. backend base URL) flows through `mutate(vars)`. The `request` is a `SubmitTxRequestV2` (`{ txHash, srcChainKey, walletAddress, intent, relayData }`):
|
|
79
91
|
|
|
80
92
|
```ts
|
|
@@ -323,7 +335,7 @@ and origin gating are the real controls. Proxy through your own backend if that
|
|
|
323
335
|
| `useBackendOrderbook` | none | `staleTime: 30s` — fresh-window, no background refetch |
|
|
324
336
|
| `useExpiredUtxos` (bitcoin) | 60s | refetchInterval |
|
|
325
337
|
| `useQuote` (swap) | 3s | refetchInterval |
|
|
326
|
-
| `useStatus` (swap) | 3s |
|
|
338
|
+
| `useStatus` (swap) | 3s | stops on status `3`/`4`, and after 40 consecutive NOT_FOUND fetches |
|
|
327
339
|
| `useSwapAllowance` (swap) | 2s | refetchInterval |
|
|
328
340
|
| `useMMAllowance` (mm) | 5s | refetchInterval; `enabled: false` for borrow/withdraw actions |
|
|
329
341
|
| Reserves data (mm) | 5s | `useReservesData` / `useReservesHumanized` / user position hooks |
|
|
@@ -13,6 +13,7 @@ Pair: [`features/swap.md`](../../../migration-v1-to-v2/knowledge/features/swap.m
|
|
|
13
13
|
useQuote({ params: { payload }, queryOptions }); // Real-time quote (3s)
|
|
14
14
|
useSwapAllowance({ params: { payload, srcChainKey, walletProvider }, queryOptions }); // allowance (2s)
|
|
15
15
|
useStatus({ params: { intentTxHash }, queryOptions }); // Intent execution status (3s)
|
|
16
|
+
useDetailedStatus({ params: { srcChainKey, srcTxHash }, queryOptions }); // Swap status by source tx (3s)
|
|
16
17
|
|
|
17
18
|
// Mutations — domain inputs flow through mutate(vars), see Mutation params below
|
|
18
19
|
useSwap({ mutationOptions });
|
|
@@ -76,6 +77,15 @@ type UseStatusParams = ReadHookParams<
|
|
|
76
77
|
Result<SolverIntentStatusResponse, SolverErrorResponse> | undefined,
|
|
77
78
|
{ intentTxHash: Hex | undefined }
|
|
78
79
|
>;
|
|
80
|
+
|
|
81
|
+
// useDetailedStatus — keyed on the SOURCE tx (useStatus takes the HUB tx). Also Result-wrapped.
|
|
82
|
+
type UseDetailedStatusParams = ReadHookParams<
|
|
83
|
+
Result<DetailedSwapStatus, DetailedStatusError> | undefined,
|
|
84
|
+
{ srcChainKey: SpokeChainKey | undefined; srcTxHash: string | undefined }
|
|
85
|
+
>;
|
|
86
|
+
// DetailedSwapStatus is a tagged union — narrow on `source`, do not read `.status` off the top level:
|
|
87
|
+
// { source: 'backend'; data: SubmitTxStatusDataV2 }
|
|
88
|
+
// | { source: 'solver'; dstTxHash: Hex; data: SolverIntentStatusResponse }
|
|
79
89
|
```
|
|
80
90
|
|
|
81
91
|
## Return shapes
|
|
@@ -89,7 +99,27 @@ type UseStatusParams = ReadHookParams<
|
|
|
89
99
|
| `useCreateLimitOrder` | `SafeUseMutationResult<{ intent, intentDeliveryInfo, ... }, Error, ...>` |
|
|
90
100
|
| `useQuote` | `UseQueryResult<Result<SolverIntentQuoteResponse, SolverErrorResponse> \| undefined, Error>` — `data?.ok` branching required; polls 3 s |
|
|
91
101
|
| `useSwapAllowance` | `UseQueryResult<boolean, Error>` — `data` is already-unwrapped `boolean \| undefined`; truthy when approved; polls 2 s |
|
|
92
|
-
| `useStatus` | `UseQueryResult<Result<SolverIntentStatusResponse, SolverErrorResponse> \| undefined, Error>` — Result-wrapped like `useQuote`; `data?.ok` branching required; polls 3 s |
|
|
102
|
+
| `useStatus` | `UseQueryResult<Result<SolverIntentStatusResponse, SolverErrorResponse> \| undefined, Error>` — Result-wrapped like `useQuote`; `data?.ok` branching required; polls 3 s; stops on status `3`/`4`, and after 40 consecutive NOT_FOUND fetches |
|
|
103
|
+
| `useDetailedStatus` | `UseQueryResult<Result<DetailedSwapStatus, DetailedStatusError> \| undefined, Error>` — Result-wrapped tagged union; polls 3 s; stops when the answering source is terminal (backend `'solved'`, or solver `SOLVED`/`FAILED`), and — like `useStatus` — after 40 consecutive ambiguous reads (solver `NOT_FOUND`, or a relay with no packet for the tx); a dependency outage keeps polling |
|
|
104
|
+
|
|
105
|
+
### `useStatus` vs `useDetailedStatus`
|
|
106
|
+
|
|
107
|
+
Different transactions — pick by which hash you hold:
|
|
108
|
+
|
|
109
|
+
- `useStatus` takes the **hub** tx hash (`intentDeliveryInfo.dstTxHash`) and always asks the solver.
|
|
110
|
+
- `useDetailedStatus` takes the **source** tx hash plus chain key (`intentDeliveryInfo.srcTxHash` + `srcChainKey`) and routes to whichever source can answer.
|
|
111
|
+
|
|
112
|
+
`useDetailedStatus` invents no status of its own — it returns the backend submit-tx record while that is in play, otherwise the solver's answer, tagged with `source`. The union is discriminated, so narrow on the field (no type guards are exported):
|
|
113
|
+
|
|
114
|
+
```ts
|
|
115
|
+
// @ai-snippets-skip
|
|
116
|
+
if (data?.ok) {
|
|
117
|
+
if (data.value.source === 'backend') data.value.data.status; // 'pending' | … | 'solved' | 'failed'
|
|
118
|
+
if (data.value.source === 'solver') data.value.data.status; // SolverIntentStatusCode
|
|
119
|
+
}
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
That is what distinguishes it from `useSwapsApiSubmitTxStatus`, which reads the backend record directly — 404 when none exists, and a stale or abandoned record for a swap the client-side fallback completed. A swap whose relay packet has not landed has no hub tx hash and reads as `LOOKUP_FAILED`; that spends the same 40-read budget as a solver `NOT_FOUND`, so a swap nothing can resolve stops instead of polling forever. A dependency outage does **not** spend the budget — it keeps polling so the read recovers on its own.
|
|
93
123
|
|
|
94
124
|
## Gotchas
|
|
95
125
|
|
|
@@ -19,7 +19,8 @@ Comprehensive hook table across 12 feature domains. Use this when you know the f
|
|
|
19
19
|
| `useSwap` | Mutation | Execute a complete cross-chain swap |
|
|
20
20
|
| `useSwapAllowance` | Query | Check token approval status |
|
|
21
21
|
| `useSwapApprove` | Mutation | Approve tokens for the swap contract |
|
|
22
|
-
| `useStatus` | Query | Track intent execution status (polls 3s once `intentTxHash` supplied; Result-wrapped data) |
|
|
22
|
+
| `useStatus` | Query | Track intent execution status (polls 3s once `intentTxHash` supplied; stops on `3`/`4` and after 40 consecutive NOT_FOUND fetches; Result-wrapped data) |
|
|
23
|
+
| `useDetailedStatus` | Query | Track a swap from its source tx (`{ srcChainKey, srcTxHash }`; polls 3s; Result-wrapped; stops on the answering source's terminal state and after 40 consecutive ambiguous reads — solver NOT_FOUND, or a relay with no packet for the tx; outages keep polling). Returns a tagged union — backend submit-tx record or solver answer — narrow on `source`. Unlike `useSwapsApiSubmitTxStatus`, answers for both `swap()` completion paths |
|
|
23
24
|
| `useCancelSwap` | Mutation | Cancel an active swap intent |
|
|
24
25
|
| `useCreateLimitOrder` | Mutation | Create a limit order (no deadline) |
|
|
25
26
|
| `useCancelLimitOrder` | Mutation | Cancel a limit order |
|
|
@@ -122,7 +122,7 @@ Same shape changes as `useSwap` — drop `spokeProvider`, move domain inputs to
|
|
|
122
122
|
## Pitfalls
|
|
123
123
|
|
|
124
124
|
1. **`Intent.srcChain` / `Intent.dstChain` look like they should rename.** They didn't. Those are read-shape `IntentRelayChainId` (bigint), distinct from request-side `srcChainKey` / `dstChainKey`. Don't grep-replace.
|
|
125
|
-
2. **`useStatus` polling default.** v2 polls every 3 s
|
|
125
|
+
2. **`useStatus` polling default.** v2 polls every 3 s once `intentTxHash` is supplied, then stops on status `3` (SOLVED) / `4` (FAILED), and after 40 consecutive successful fetches while status stays `-1` (NOT_FOUND). In-flight `1` / `2` reset that streak and keep polling. Override with `queryOptions.refetchInterval`. Port any v1 custom polling to `queryOptions.refetchInterval`.
|
|
126
126
|
3. **`useQuote` data is `Result<T>`** — branch on `data?.ok` before reading `data.value.quoted_amount`.
|
|
127
127
|
|
|
128
128
|
## Cross-references
|
|
@@ -21,7 +21,7 @@ These keep their name but their TypeScript signature is different. Usually requi
|
|
|
21
21
|
| `useSwap` | Hook init: `(spokeProvider) → ({ mutationOptions })`. Vars: `{ params } → { params, walletProvider }`. |
|
|
22
22
|
| `useSwapAllowance` | Query params: `(params, spokeProvider) → { params: { payload, srcChainKey, walletProvider } }`. SDK request nested under `params.payload`. Data unwrapped to `boolean`. |
|
|
23
23
|
| `useSwapApprove` | Return: `{ approve, isLoading } → SafeUseMutationResult` (with `mutateAsync` / `isPending`). Vars accept `CreateIntentParams \| CreateLimitOrderParams`. TData is `TxReturnType<K, false>` (chain-keyed receipt union). |
|
|
24
|
-
| `useStatus` | Now `useStatus({ params: { intentTxHash } })` — single-object shape AND key renamed from `intentHash` → `intentTxHash`. Data is `Result<SolverIntentStatusResponse, SolverErrorResponse> \| undefined` (Result-wrapped). Polls 3s. |
|
|
24
|
+
| `useStatus` | Now `useStatus({ params: { intentTxHash } })` — single-object shape AND key renamed from `intentHash` → `intentTxHash`. Data is `Result<SolverIntentStatusResponse, SolverErrorResponse> \| undefined` (Result-wrapped). Polls 3s; stops on `3`/`4` and after 40 consecutive NOT_FOUND fetches. |
|
|
25
25
|
| `useQuote` | Now `useQuote({ params: { payload } })` — SDK request nested under `params.payload` (NOT directly under `params`). Data is `Result<SolverIntentQuoteResponse, SolverErrorResponse> \| undefined`. Polls 3s. |
|
|
26
26
|
| `useCancelSwap` / `useCancelLimitOrder` | TVars are FLAT (no `params` wrapper): `{ srcChainKey, intent, walletProvider }`. |
|
|
27
27
|
| `useCreateLimitOrder` | Hook init: `(spokeProvider) → ({ mutationOptions })`. Vars: `{ params, walletProvider }`. mutationKey is `['swap', 'limitOrder', 'create']`. |
|
|
@@ -163,7 +163,7 @@ new Sodax(config?: SodaxOptions): Sodax;
|
|
|
163
163
|
- `dex: DexConfig` — DEX pool/asset config.
|
|
164
164
|
- `leverageYield: LeverageYieldConfig` — registry of leverage-yield ERC-4626 vaults on the hub.
|
|
165
165
|
- `hub: HubConfig` — hub-chain (Sonic) full address map + RPC URL + polling config. Accepts an optional `rpcUrls` failover list (and `rpcOptions` tuning) — see [`recipes/initialize-sodax.md`](recipes/initialize-sodax.md).
|
|
166
|
-
- `api: ApiConfig` — backend API config: flat `
|
|
166
|
+
- `api: ApiConfig` — backend API config: flat `BackendApiConfig` (`{ baseURL, basePath?, timeout, headers }`, shared by `sodax.backendApi` and the swaps client `sodax.api.swaps`) or nested `CustomApiConfig` (`{ baseApiConfig?, swapsApiConfig? }`) to point the swaps API at its own endpoint. `baseURL` is the gateway root; each service appends its own path below it.
|
|
167
167
|
- `solver: SolverConfig` — `{ intentsContract, solverApiEndpoint, protocolIntentsContract }`.
|
|
168
168
|
- `relay: RelayConfig` — intent relay endpoint + chain-id map.
|
|
169
169
|
|
|
@@ -202,15 +202,16 @@ Chain configs (vault addresses, supported tokens, fee parameters) change between
|
|
|
202
202
|
|
|
203
203
|
### Custom backend
|
|
204
204
|
|
|
205
|
-
Point at a custom backend URL via `SodaxConfig.api
|
|
205
|
+
Point at a custom backend URL via `SodaxConfig.api`. `baseURL` is the gateway root; the data API's `/be`
|
|
206
|
+
mount is appended below it, so a sandbox serving `/config/*` at its bare origin needs `basePath: ''`:
|
|
206
207
|
|
|
207
208
|
```ts
|
|
208
209
|
const sodax = new Sodax({
|
|
209
|
-
api: { baseURL: 'https://sandbox-api.example.com' },
|
|
210
|
+
api: { baseApiConfig: { baseURL: 'https://sandbox-api.example.com', basePath: '' } },
|
|
210
211
|
});
|
|
211
212
|
```
|
|
212
213
|
|
|
213
|
-
`SodaxConfig.api` is `ApiConfig` — the flat `
|
|
214
|
+
`SodaxConfig.api` is `ApiConfig` — the flat `BackendApiConfig` (`{ baseURL, basePath?, timeout, headers }`) shared by both backend clients, or the nested `CustomApiConfig` (`{ baseApiConfig?, swapsApiConfig? }`) to point the swaps API (`sodax.api.swaps`) at its own endpoint. `baseURL` is the gateway root and every service appends its own path below it (`/be`, `/swaps`, `/bridge`, `/sponsorships/stellar`), so it must never carry a service segment; `basePath` overrides the data API's mount for a non-gateway deployment. Pass any subset via `DeepPartial`. v2 does not provide a typed slot to inject a custom `IConfigApiV1` implementation at construction; if you need to mock the backend for tests, point `baseURL` at a local mock server (with `basePath: ''` when it serves the routes at its origin), or construct your own `BackendApiService`-compatible mock and inject it where you control the `Sodax` instance (e.g. dependency-injected in your app layer).
|
|
214
215
|
|
|
215
216
|
---
|
|
216
217
|
|
|
@@ -64,7 +64,7 @@ source token rejects a non-zero to non-zero allowance change (Ethereum USDT is t
|
|
|
64
64
|
today) **and** the wallet already holds a stale allowance — broadcast it first, wait for it to be
|
|
65
65
|
mined, then broadcast `tx`. Absent for every other token, so a client that ignores it keeps working.
|
|
66
66
|
|
|
67
|
-
`CreateIntentParamsV2` is the shared wire-level request body behind the typed `/swaps/allowance/check`, `/swaps/approve`, and `/swaps/intents` calls (the `IBackendApiV2` methods the SDK drives internally). It inherits the swap extras — `partnerFee`, `srcPublicKey`, and `bound` — from `SwapExtrasV2`, the JSON-safe mirror of the SDK `SwapExtras` (`QuoteRequestV2` inherits the same trio for its `includeTxData=true` path). For Bitcoin **TRADING**-mode `raw` intents the Bound Exchange (Radfi) token is carried as `bound.accessToken` — passed in the request body instead of an `x-bound-access-token` header so it stays inside the typed DTO. Required only when the source chain is Bitcoin in TRADING mode; ignored otherwise.
|
|
67
|
+
`CreateIntentParamsV2` is the shared wire-level request body behind the typed `/swaps/allowance/check`, `/swaps/approve`, and `/swaps/intents` calls (the `IBackendApiV2` methods the SDK drives internally). It inherits the swap extras — `partnerFee`, `srcPublicKey`, and `bound` — from `SwapExtrasV2`, the JSON-safe mirror of the SDK `SwapExtras` (`QuoteRequestV2` inherits the same trio for its `includeTxData=true` path). `partnerFee` has no default on this path — see [`swaps-api.md`](swaps-api.md) § `partnerFee`. For Bitcoin **TRADING**-mode `raw` intents the Bound Exchange (Radfi) token is carried as `bound.accessToken` — passed in the request body instead of an `x-bound-access-token` header so it stays inside the typed DTO. Required only when the source chain is Bitcoin in TRADING mode; ignored otherwise.
|
|
68
68
|
|
|
69
69
|
You rarely build this DTO yourself: `sodax.swaps.createIntent` takes the token via the chain-key-gated `extras.bound.accessToken` slot and maps it onto `CreateIntentParamsV2.bound.accessToken`. See [`swap.md`](swap.md) § `SwapExtras` and [`../chain-specifics.md`](../chain-specifics.md) § "Bitcoin PSBT and Bound Exchange" for the consumer-facing flow and token-injection points.
|
|
70
70
|
|
|
@@ -76,12 +76,16 @@ You rarely build this DTO yourself: `sodax.swaps.createIntent` takes the token v
|
|
|
76
76
|
|
|
77
77
|
```ts
|
|
78
78
|
const sodax = new Sodax({
|
|
79
|
-
|
|
79
|
+
// `basePath: ''` because a local mock serves `/config/*` at its origin, with no `/be` mount.
|
|
80
|
+
api: { baseApiConfig: { baseURL: 'http://localhost:4000', basePath: '' } },
|
|
80
81
|
});
|
|
81
82
|
await sodax.config.initialize();
|
|
83
|
+
// → http://localhost:4000/config/all
|
|
82
84
|
```
|
|
83
85
|
|
|
84
|
-
`SodaxConfig.api` is `ApiConfig` — either the flat `
|
|
86
|
+
`SodaxConfig.api` is `ApiConfig` — either the flat `BackendApiConfig` (`{ baseURL, basePath?, timeout, headers }`, shared by the base API and the swaps client) or the nested `CustomApiConfig` (`{ baseApiConfig?, swapsApiConfig? }`) to point the swaps API at its own endpoint. Pass any subset via `DeepPartial`. See [`./swaps-api.md`](swaps-api.md) § "Custom endpoint for the swaps API".
|
|
87
|
+
|
|
88
|
+
`baseURL` is the **gateway root** — each service appends its own path below it, so the backend data API requests `<baseURL>/be/config/all` by default. `basePath` is that mount, and the only reason to set it is a deployment that does not use the gateway. Never put a service segment (`/be`, `/swaps`, `/bridge`) in `baseURL` itself — it would also relocate the sibling services. A `baseURL` ending in `/be` is trimmed with a deprecation warning; do not rely on that.
|
|
85
89
|
|
|
86
90
|
2. **Inject your own `BackendApiService`-compatible mock at the app layer** (dependency-injected where you control the `Sodax` instance), rather than via the constructor.
|
|
87
91
|
|
|
@@ -108,10 +108,12 @@ if (status.ok && status.value.data.status === 'executed') {
|
|
|
108
108
|
Every method accepts a trailing `RequestOverrideConfig` to redirect a single call or attach headers:
|
|
109
109
|
|
|
110
110
|
```ts
|
|
111
|
-
|
|
111
|
+
// `baseURL` is the gateway ROOT — the SDK appends `/bridge/*` itself. Never include a service segment.
|
|
112
|
+
await sodax.api.bridge.getTokens({ baseURL: 'https://staging.example/v1', headers: { 'X-Trace': 'abc' } });
|
|
112
113
|
```
|
|
113
114
|
|
|
114
|
-
The Bridge API has no dedicated config slice — it always shares the base backend host
|
|
115
|
+
The Bridge API has no dedicated config slice — it always shares the base backend host, reached as
|
|
116
|
+
`/bridge/*` on the gateway root (a sibling of the data API's `/be` mount, not a child of it). To
|
|
115
117
|
move the whole backend (including bridge) to a custom host, use the `CustomApiConfig` `baseApiConfig` slice
|
|
116
118
|
(see [`backend-api.md`](backend-api.md) § "Custom backend").
|
|
117
119
|
|
|
@@ -45,8 +45,39 @@ sodax.swaps.cancelLimitOrder<K>(/* … */): Promise<Result<TxHashPair, SodaxErro
|
|
|
45
45
|
|
|
46
46
|
sodax.swaps.approve<K, Raw>(/* … */): Promise<Result<TxReturnType<K, Raw>, SodaxError>>;
|
|
47
47
|
sodax.swaps.isAllowanceValid<K, Raw>(/* … */): Promise<Result<boolean, SodaxError>>;
|
|
48
|
+
|
|
49
|
+
sodax.swaps.getStatus(
|
|
50
|
+
request: SolverIntentStatusRequest, // { intent_tx_hash } — the HUB (Sonic) tx hash
|
|
51
|
+
): Promise<Result<SolverIntentStatusResponse, SolverErrorResponse>>; // legacy error shape, NOT SodaxError
|
|
52
|
+
|
|
53
|
+
sodax.swaps.getDetailedStatus(
|
|
54
|
+
params: { srcChainKey: SpokeChainKey; srcTxHash: string }, // the SOURCE-chain tx hash
|
|
55
|
+
): Promise<Result<DetailedSwapStatus, SodaxError<'LOOKUP_FAILED'>>>;
|
|
56
|
+
// Routes to the backend submit-tx record or the solver. Does NOT define a new status vocabulary.
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## Reading swap status
|
|
60
|
+
|
|
61
|
+
Three readers. Pick by which transaction hash you hold:
|
|
62
|
+
|
|
63
|
+
- **`sodax.api.swaps.getSubmitTxStatus({ txHash, srcChainKey })`** — the backend worker record, keyed on the **source** tx. Answers **404** when no record exists (`useBackendSubmitTx: false`, or the submit never landed). Otherwise the record may be *stale*: `swap()` submits before falling back to the client-side relay, so a fallback-completed swap leaves a `pending`/`relaying`/abandoned record behind.
|
|
64
|
+
- **`sodax.swaps.getStatus({ intent_tx_hash })`** — the solver's view of one intent, keyed on the **hub** tx hash (`intentDeliveryInfo.dstTxHash`). Returns the legacy `SolverErrorResponse` error shape, so do not `switch (error.code)` on it.
|
|
65
|
+
- **`sodax.swaps.getDetailedStatus({ srcChainKey, srcTxHash })`** — routes between the two, keyed on the **source** tx. Use this when you only have the source hash and do not know which path the swap took.
|
|
66
|
+
|
|
67
|
+
`getDetailedStatus` defines no status of its own. It returns whichever source can answer, tagged, with that source's payload unmodified. The union is discriminated on `source` — no type guards are exported, narrow on the field:
|
|
68
|
+
|
|
69
|
+
```ts
|
|
70
|
+
type DetailedSwapStatus =
|
|
71
|
+
| { source: 'backend'; data: SubmitTxStatusDataV2 } // same as getSubmitTxStatus
|
|
72
|
+
| { source: 'solver'; dstTxHash: Hex; data: SolverIntentStatusResponse }; // same as getStatus
|
|
73
|
+
|
|
74
|
+
if (status.source === 'backend') status.data.processingAttempts;
|
|
48
75
|
```
|
|
49
76
|
|
|
77
|
+
Routing: backend record while it is in play (`success: true` and not abandoned) → `source: 'backend'`. **Any** unusable backend response — 404, `success: false`, transport/server error, or a record the backend gave up on (`failed` or `abandonedAt`) — resolves the hub tx hash and asks the solver → `source: 'solver'`. On the default path the abandoned-record branch is the common one, not the 404: the record usually exists, and abandonment is what signals the client-side fallback ran.
|
|
78
|
+
|
|
79
|
+
The only error is `LOOKUP_FAILED`, meaning no source could answer — usually the relay has not delivered the packet, so there is no hub tx hash. When polling, branch on `error.context.reason`: `DETAILED_STATUS_NOT_DELIVERED` is the ambiguous miss (indistinguishable from "still in flight" — bound it with a retry budget), set only when the backend also answered. Anything else, including a relay miss behind a backend outage, is a dependency failing right now and should be retried until it recovers. Point-in-time — poll it yourself, or use dapp-kit's `useDetailedStatus`.
|
|
80
|
+
|
|
50
81
|
## Action params shape
|
|
51
82
|
|
|
52
83
|
Generic `K extends SpokeChainKey` carries the literal source chain key. `WalletProviderSlot<K, Raw>` is intersected:
|
|
@@ -89,15 +89,26 @@ client serializes them to decimal strings on the wire. Server-returned intents (
|
|
|
89
89
|
back with those fields as decimal **`string`** (outbound JSON can't carry bigint). The `amount` /
|
|
90
90
|
`inputAmount` fields on the quote / create-intent request bodies are already decimal **strings**.
|
|
91
91
|
|
|
92
|
+
## `partnerFee`
|
|
93
|
+
|
|
94
|
+
Optional on the type, but no default: the backend does not fill it in, and
|
|
95
|
+
`new Sodax({ fee })` / `new Sodax({ swaps: { partnerFee } })` only reach the
|
|
96
|
+
`sodax.swaps` orchestrator — not this wire path. Send the same value on quote and
|
|
97
|
+
create-intent. `checkAllowance` / `approve` inherit the field but ignore it.
|
|
98
|
+
Bridge API v2 is different: omitted `partnerFee` falls back to `bridgePartnerFee`.
|
|
99
|
+
|
|
92
100
|
## Common call shapes
|
|
93
101
|
|
|
94
102
|
### Quote
|
|
95
103
|
|
|
96
104
|
```ts
|
|
105
|
+
const partnerFee = { address: '0xSonicFeeReceiver', percentage: 10 }; // 10 = 0.1% (bps)
|
|
106
|
+
|
|
97
107
|
const quote = await sodax.api.swaps.getQuote({
|
|
98
108
|
tokenSrc, tokenSrcChainKey, tokenDst, tokenDstChainKey,
|
|
99
109
|
amount: '1000000', // smallest unit, decimal string
|
|
100
110
|
quoteType: 'exact_input',
|
|
111
|
+
partnerFee,
|
|
101
112
|
});
|
|
102
113
|
if (!quote.ok) return;
|
|
103
114
|
quote.value.quotedAmount; // decimal string
|
|
@@ -114,6 +125,7 @@ const created = await sodax.api.swaps.createIntent({
|
|
|
114
125
|
deadline: '0', // "0" → no expiry (limit-order semantics)
|
|
115
126
|
allowPartialFill: false,
|
|
116
127
|
srcAddress, dstAddress,
|
|
128
|
+
partnerFee,
|
|
117
129
|
});
|
|
118
130
|
if (!created.ok) return;
|
|
119
131
|
const { tx, intent, relayData } = created.value;
|
|
@@ -151,20 +163,24 @@ Every method accepts a trailing `RequestOverrideConfig` to redirect a single cal
|
|
|
151
163
|
attach request-specific headers (auth, tracing), overriding the service config:
|
|
152
164
|
|
|
153
165
|
```ts
|
|
154
|
-
|
|
166
|
+
// `baseURL` is the gateway ROOT — the SDK appends `/swaps/*` itself. Never include a service segment.
|
|
167
|
+
await sodax.api.swaps.getTokens({ baseURL: 'https://staging.example/v1', headers: { 'X-Trace': 'abc' } });
|
|
155
168
|
```
|
|
156
169
|
|
|
157
170
|
## Custom endpoint for the swaps API
|
|
158
171
|
|
|
159
|
-
|
|
172
|
+
`baseURL` is the gateway root, shared by every service; the swaps client appends `/swaps/*` below it just
|
|
173
|
+
as `sodax.backendApi` appends its own `/be` mount. Never put a service segment in `baseURL` — a value
|
|
174
|
+
ending in `/be` resolves swaps to `/v1/be/swaps/submit-tx`, which the gateway does not route (the SDK
|
|
175
|
+
trims that suffix, but do not rely on it).
|
|
160
176
|
To point the swaps API at its own host (separate from the base backend API), construct `Sodax` with the
|
|
161
177
|
**`CustomApiConfig`** variant of `ApiConfig` (`{ baseApiConfig?, swapsApiConfig? }`) instead of the flat
|
|
162
|
-
`
|
|
178
|
+
`BackendApiConfig`:
|
|
163
179
|
|
|
164
180
|
```ts
|
|
165
181
|
const sodax = new Sodax({
|
|
166
182
|
api: {
|
|
167
|
-
baseApiConfig: { baseURL: 'https://api.example/v1
|
|
183
|
+
baseApiConfig: { baseURL: 'https://api.example/v1' },
|
|
168
184
|
swapsApiConfig: { baseURL: 'https://swaps.example/v1' },
|
|
169
185
|
},
|
|
170
186
|
});
|
|
@@ -25,9 +25,12 @@ const config: SodaxOptions = {
|
|
|
25
25
|
[ChainKeys.SONIC_MAINNET]: { rpcUrl: process.env.SONIC_RPC_URL },
|
|
26
26
|
[ChainKeys.ARBITRUM_MAINNET]: { rpcUrl: process.env.ARBITRUM_RPC_URL },
|
|
27
27
|
},
|
|
28
|
-
// Backend API override (default: https://api.sodax.com/v1
|
|
28
|
+
// Backend API override. `baseURL` is the gateway ROOT (default: https://api.sodax.com/v1); each
|
|
29
|
+
// service appends its own path below it (`/be`, `/swaps`, `/bridge`, `/sponsorships/stellar`).
|
|
30
|
+
// A sandbox that serves `/config/*` at its bare origin has no `/be` mount, so say so with
|
|
31
|
+
// `basePath: ''` — otherwise the data API requests `<origin>/be/config/all`.
|
|
29
32
|
api: {
|
|
30
|
-
baseURL: 'https://my-sandbox-backend.example.com',
|
|
33
|
+
baseApiConfig: { baseURL: 'https://my-sandbox-backend.example.com', basePath: '' },
|
|
31
34
|
},
|
|
32
35
|
// Solver endpoints (default: https://api.sodax.com/v1/intent + production contracts).
|
|
33
36
|
solver: {
|
|
@@ -75,13 +75,15 @@ 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 =
|
|
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 run tests against a sandbox or local mock server, set `api.baseURL` and let `initialize()` fetch config from it:
|
|
79
79
|
|
|
80
80
|
```ts
|
|
81
81
|
import { Sodax } from '@sodax/sdk';
|
|
82
82
|
|
|
83
83
|
const sodax = new Sodax({
|
|
84
|
-
|
|
84
|
+
// `baseURL` is the gateway root; the data API's `/be` mount is appended below it. A mock that
|
|
85
|
+
// serves `/config/*` at its origin needs `basePath: ''`.
|
|
86
|
+
api: { baseApiConfig: { baseURL: 'https://sandbox-api.example.com', basePath: '' } },
|
|
85
87
|
});
|
|
86
88
|
await sodax.config.initialize();
|
|
87
89
|
```
|
|
@@ -138,11 +138,14 @@ import {
|
|
|
138
138
|
type IntentRelayChainId,
|
|
139
139
|
|
|
140
140
|
// Backend API config + per-call override
|
|
141
|
-
type ApiConfig, //
|
|
142
|
-
type BaseApiConfig,
|
|
141
|
+
type ApiConfig, // BackendApiConfig | CustomApiConfig
|
|
142
|
+
type BaseApiConfig, // { baseURL, timeout, headers } — baseURL is the GATEWAY ROOT
|
|
143
|
+
type BackendApiConfig, // BaseApiConfig & { basePath? } — the data API's mount, default '/be'
|
|
143
144
|
type CustomApiConfig, // point the swaps / sponsoring API at its own endpoint
|
|
144
145
|
type SwapsApiConfig,
|
|
145
146
|
type SponsoringApiConfig, // BaseApiConfig & { apiKey? } — own host, own x-api-key
|
|
147
|
+
DEFAULT_API_BASE_URL, // 'https://api.sodax.com/v1' — the root every service resolves
|
|
148
|
+
BACKEND_API_BASE_PATH, // '/be'
|
|
146
149
|
DEFAULT_SPONSORING_API_ENDPOINT,
|
|
147
150
|
SPONSORING_API_STELLAR_BASE_PATH,
|
|
148
151
|
type RequestOverrideConfig, // per-call override on any backendApi / sodax.api.swaps method
|
|
@@ -173,6 +176,11 @@ import {
|
|
|
173
176
|
BackendHttpError,
|
|
174
177
|
isBackendHttpError, // bundle-safe guard; prefer over instanceof
|
|
175
178
|
|
|
179
|
+
// Backend intent events — `IntentResponse.events` is `unknown[]`
|
|
180
|
+
isFillEvent, // narrows an events entry to a recorded `intent-filled`
|
|
181
|
+
type FillEvent, // { txHash, intentState.remainingInput } — '0' means the fill settled
|
|
182
|
+
// the whole intent; with allowPartialFill it can be non-zero
|
|
183
|
+
|
|
176
184
|
// Read shapes
|
|
177
185
|
type Intent,
|
|
178
186
|
type IntentResponse,
|
|
@@ -32,6 +32,7 @@ validates the response. Errors carry `feature: 'backend'`, `context.api: 'swaps'
|
|
|
32
32
|
|
|
33
33
|
### Swaps-API-specific anti-patterns
|
|
34
34
|
|
|
35
|
+
- **Omitting `partnerFee` on `getQuote` / `createIntent`.** Optional on the type only — no backend/SDK default. Ask for a real fee receiver; never invent one or use the zero address.
|
|
35
36
|
- **`try/catch` for failures.** Every method returns `Result<T>` — branch on `result.ok`. `catch` won't fire for HTTP/timeout/validation failures.
|
|
36
37
|
- **Passing the `RelayExtraData` object** to `submitTx`'s `relayData`. The field is a `string` — pass `relayData.payload`.
|
|
37
38
|
- **Stringifying `intent` numerics yourself.** `IntentRequestV2` fields are `bigint`; the client serializes them to decimal strings — pass the bigint intent through as-is.
|
|
@@ -52,7 +53,8 @@ builds on are covered in the existing swap + backend-api migration docs:
|
|
|
52
53
|
1. `pnpm tsc --noEmit` clean.
|
|
53
54
|
2. Every `await sodax.api.swaps.<method>(...)` call site has `if (!result.ok)`.
|
|
54
55
|
3. `submitTx.relayData` is `relayData.payload` (string); `getSubmitTxStatus` passes both `txHash` and `srcChainKey`.
|
|
55
|
-
4.
|
|
56
|
+
4. Every `getQuote` / `createIntent` body carries the same `partnerFee` (real receiver), or the user said they are not monetizing.
|
|
57
|
+
5. Intent-bearing bodies pass the `bigint` `IntentRequestV2` through unmodified (no manual `.toString()`).
|
|
56
58
|
|
|
57
59
|
## Related granular skills (same family)
|
|
58
60
|
|