@sodax/skills 2.1.0-rc.5 → 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 +1 -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/features/swap.md +31 -0
- package/skills/sodax-sdk/integration/knowledge/reference/public-api.md +5 -0
package/package.json
CHANGED
|
@@ -335,7 +335,7 @@ and origin gating are the real controls. Proxy through your own backend if that
|
|
|
335
335
|
| `useBackendOrderbook` | none | `staleTime: 30s` — fresh-window, no background refetch |
|
|
336
336
|
| `useExpiredUtxos` (bitcoin) | 60s | refetchInterval |
|
|
337
337
|
| `useQuote` (swap) | 3s | refetchInterval |
|
|
338
|
-
| `useStatus` (swap) | 3s |
|
|
338
|
+
| `useStatus` (swap) | 3s | stops on status `3`/`4`, and after 40 consecutive NOT_FOUND fetches |
|
|
339
339
|
| `useSwapAllowance` (swap) | 2s | refetchInterval |
|
|
340
340
|
| `useMMAllowance` (mm) | 5s | refetchInterval; `enabled: false` for borrow/withdraw actions |
|
|
341
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']`. |
|
|
@@ -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:
|
|
@@ -176,6 +176,11 @@ import {
|
|
|
176
176
|
BackendHttpError,
|
|
177
177
|
isBackendHttpError, // bundle-safe guard; prefer over instanceof
|
|
178
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
|
+
|
|
179
184
|
// Read shapes
|
|
180
185
|
type Intent,
|
|
181
186
|
type IntentResponse,
|