@sodax/skills 2.1.0-rc.8 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -4,7 +4,7 @@
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
7
- "version": "2.1.0-rc.8",
7
+ "version": "2.1.0",
8
8
  "license": "MIT",
9
9
  "description": "AI-agent skills and knowledge for consumers of @sodax/* SDKs (Claude Code, Codex, Cursor, …)",
10
10
  "keywords": [
@@ -121,11 +121,47 @@ type CreateIntentParams<K extends SpokeChainKey> = {
121
121
  allowPartialFill: boolean;
122
122
  solver?: `0x${string}`; // optional solver address; '0x0…0' for default
123
123
  data: `0x${string}`; // arbitrary calldata; '0x' for default
124
+ hook?: HookRequest; // route the output through a registered delivery hook — see below
125
+ deliveryData?: `0x${string}`; // low-level delivery payload; escape hatch, ignored when `hook` is set
124
126
  };
125
127
  ```
126
128
 
127
129
  `CreateLimitOrderParams<K>` is `Omit<CreateIntentParams<K>, 'deadline'> & { deadline?: bigint }` — it makes `deadline` optional rather than removing it; when omitted the SDK forces it to `0n` internally (limit orders use a different expiry mechanism).
128
130
 
131
+ ### Delivery hooks (`hook` / `deliveryData`)
132
+
133
+ By default an intent's output is transferred straight to `dstAddress`. A **delivery hook** instead hands
134
+ it to a contract on the destination spoke that acts on the recipient's behalf — `SpokeAssetManager` calls
135
+ `ISpokeReceiver(dstAddress).hook(token, amount, deliveryData)`.
136
+
137
+ Prefer `hook` over `deliveryData`: the SDK resolves the hook's deployed address and encodes its payload
138
+ from the registry (`spokeHooks` in `@sodax/types`), so the two can never drift.
139
+
140
+ ```ts
141
+ import { HookKind, getSpokeHook } from '@sodax/sdk';
142
+
143
+ // Which kinds exist, and on which chains, is registry data that grows — discover, don't hardcode.
144
+ const kind = HookKind.HYPERCORE_DEPOSIT; // any registered kind; see `HookKind` for the current set
145
+ if (!getSpokeHook(dstChainKey, kind)) return; // not deployed there → send a plain transfer instead
146
+
147
+ const params = {
148
+ // …the usual CreateIntentParams fields…
149
+ dstAddress: recipient, // the account the hook CREDITS — the SDK overwrites the on-chain
150
+ // dstAddress with the hook's own address
151
+ hook: { kind },
152
+ };
153
+ ```
154
+
155
+ - **Fails closed** — a kind not registered on `dstChainKey` throws at intent-construction time, before an
156
+ intent exists. A zero-address recipient is rejected for every hook (it would revert on arrival and
157
+ wedge the cross-chain message unrecoverably).
158
+ - **Best-effort on-chain** — a hook generally delivers plain tokens to the recipient rather than
159
+ reverting when it can't act (unsupported token, refusing target, amount below its minimum). Treat a
160
+ hooked intent as "the tokens arrive; the hook action may not". `supportedTokens` on a registry entry
161
+ describes that on-chain behaviour; the SDK does not reject a mismatched `outputToken` client-side.
162
+ - `deliveryData` is the escape hatch for a receiver **not** in the registry: opaque bytes whose schema the
163
+ receiver defines, and you point `dstAddress` at that receiver yourself. Ignored when `hook` is set.
164
+
129
165
  ## Common call shapes
130
166
 
131
167
  ### Quote before signing (preview / confirmation UX)
@@ -131,6 +131,26 @@ if (!created.ok) return;
131
131
  const { tx, intent, relayData } = created.value;
132
132
  ```
133
133
 
134
+ **Delivery hooks are deployment-dependent here.** `hook?: HookRequestV2` (`{ kind: HookKind }`) lives on
135
+ `SwapExtrasV2`, so it's structurally present on both `CreateIntentParamsV2` (`checkAllowance` /
136
+ `approve` / `createIntent` / `createLimitOrderIntent`) and `QuoteRequestV2` (`getQuote`), but only
137
+ `createIntent` / `createLimitOrderIntent` / `getQuote` with `includeTxData: true` actually consume it
138
+ — those are the only calls that build a delivery target. `checkAllowance` / `approve` inherit the
139
+ field but ignore it, same as `partnerFee` above: allowance-checking and approval are source-side only.
140
+ Unlike the SDK path, the hook is resolved **server-side**, so it only works when the backend forwards
141
+ the field *and* its pinned SDK has that kind registered for the request's destination chain —
142
+ `dstChainKey` everywhere except `getQuote`, which names it `tokenDstChainKey`; an unregistered kind
143
+ fails the request rather than falling back to a plain transfer. `dstAddress` still means the recipient the hook credits — the
144
+ backend substitutes the hook's own address on-chain. Whether the `getQuote` path forwards `hook` at all
145
+ is a backend question this SDK can't verify — confirm with the deployment before relying on it there.
146
+ The `deliveryData` payload encoding and the `supportedTokens` metadata-vs-enforcement distinction are
147
+ the full canonical contract on `SwapExtrasV2.hook`'s own doc comment in `@sodax/types`
148
+ (`backendApiV2.ts`) — read that before implementing server-side hook resolution.
149
+
150
+ When you need hook support independent of the deployment, build with `sodax.swaps` instead: it resolves
151
+ the hook client-side into `dstAddress`/`data`, and under the default `useBackendSubmitTx` still hands the
152
+ broadcast tx to this API's `submitTx`. See [`swap.md`](swap.md) § "Delivery hooks".
153
+
134
154
  ### Submit tx + poll status
135
155
 
136
156
  ```ts
@@ -128,6 +128,11 @@ import {
128
128
  type LeverageYieldVault,
129
129
  // …
130
130
 
131
+ // Delivery hooks (CreateIntentParams.hook — see features/swap.md)
132
+ HookKind,
133
+ type HookRequest,
134
+ getSpokeHook,
135
+
131
136
  // Backend / relay
132
137
  type IConfigApiV1,
133
138
  type SubmitTxRequestV2, // swaps API submit-tx request (sodax.api.swaps.submitTx)