@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 CHANGED
@@ -4,7 +4,7 @@
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
7
- "version": "2.1.0-rc.5",
7
+ "version": "2.1.0-rc.6",
8
8
  "license": "MIT",
9
9
  "description": "AI-agent skills and knowledge for consumers of @sodax/* SDKs (Claude Code, Codex, Cursor, …)",
10
10
  "keywords": [
@@ -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 | refetchInterval |
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 unconditionally once `intentTxHash` is supplied (it does not auto-stop on terminal states — your UI should disable rendering when no longer needed, or override `queryOptions.refetchInterval: false`). Port any v1 custom polling to `queryOptions.refetchInterval`.
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,