@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
|
@@ -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)
|