@sodax/skills 2.1.0-rc.7 → 2.1.0-rc.9
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/architecture.md +24 -13
- package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md +3 -2
- package/skills/sodax-dapp-kit/integration/knowledge/reference/querykey-conventions.md +1 -0
- package/skills/sodax-sdk/integration/knowledge/architecture.md +8 -6
- package/skills/sodax-sdk/integration/knowledge/features/bridge-api.md +32 -1
- package/skills/sodax-sdk/integration/knowledge/features/bridge.md +10 -0
- package/skills/sodax-sdk/integration/knowledge/features/swap.md +36 -0
- package/skills/sodax-sdk/integration/knowledge/features/swaps-api.md +20 -0
- package/skills/sodax-sdk/integration/knowledge/reference/chain-keys.md +4 -3
- package/skills/sodax-sdk/integration/knowledge/reference/public-api.md +5 -0
- package/skills/sodax-wallet-sdk-core/evm/SKILL.md +3 -3
- package/skills/sodax-wallet-sdk-core/integration/knowledge/README.md +1 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/quickstart.md +1 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/chain-support.md +3 -2
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/chain-support.md +2 -2
package/package.json
CHANGED
|
@@ -210,24 +210,35 @@ resolves with is the **last** transaction's.
|
|
|
210
210
|
Nothing about the hook contract changes and there is no flag to set. What matters for UI:
|
|
211
211
|
|
|
212
212
|
- An `isPending` that renders a single "Approving…" now spans two wallet prompts. Say so in the copy,
|
|
213
|
-
or the second prompt reads as a bug.
|
|
213
|
+
or the second prompt reads as a bug. On the unsigned paths, pass `onProgress` (below) and name the
|
|
214
|
+
step instead of guessing.
|
|
214
215
|
- Anything estimating gas or counting transactions from "one approve = one transaction" is wrong on
|
|
215
216
|
that branch.
|
|
216
217
|
- If the second signature is rejected after the reset landed, the allowance is now zero, so the next
|
|
217
218
|
attempt is a single transaction — retrying is always safe.
|
|
218
219
|
|
|
219
|
-
On the unsigned (
|
|
220
|
-
|
|
221
|
-
`{ approveTxHash, resetTxHash? }` only once the
|
|
222
|
-
|
|
223
|
-
did not take.
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
220
|
+
On the unsigned (backend-API) paths, prefer **`useSwapsApiApproveAndBroadcast`** — or
|
|
221
|
+
**`useBridgeApiApproveAndBroadcast`** for a bridge: each asks its API for the transactions, then
|
|
222
|
+
signs, broadcasts, and waits for each, resolving with `{ approveTxHash, resetTxHash? }` only once the
|
|
223
|
+
final approval has landed. A transaction that mines but reverts rejects the mutation naming that
|
|
224
|
+
step, so the approve is never sent over a reset that did not take. Each also invalidates its own
|
|
225
|
+
allowance query (`['swapsApi','allowance']` / `['bridgeApi','allowance']`), because confirmation now
|
|
226
|
+
happens inside the hook. Pick the one matching the action you are about to take — swaps and bridge
|
|
227
|
+
approve different spenders on the hub, so an approval built by one does not satisfy the other.
|
|
228
|
+
|
|
229
|
+
Both accept an optional **`onProgress`** in their mutation vars. It reports each transaction as
|
|
230
|
+
`{ step, phase, index, total, hash?, error? }` — `step` is `'allowance-reset'` or `'approve'`, `phase`
|
|
231
|
+
walks `signing → broadcast → confirmed` (or `failed`), and `index`/`total` give "1 of 2" without the
|
|
232
|
+
caller tracking anything. Advisory: the listener is never awaited, one that throws is ignored rather
|
|
233
|
+
than aborting a broadcast, and the mutation's own result stays the source of truth. It lives in the
|
|
234
|
+
vars rather than the hook options so it is never a stale closure.
|
|
235
|
+
|
|
236
|
+
`useSwapsApiApprove` / `useBridgeApiApprove` still exist and return the API's `{ tx, resetTx? }`
|
|
237
|
+
verbatim — use them only when you need to own signing. If you do, broadcast `resetTx` **first and
|
|
238
|
+
wait for it to succeed**; the approve is not a valid state transition until the reset has landed, so
|
|
239
|
+
sending both together spends the user's gas on a certain revert. Waiting is not enough on its own —
|
|
240
|
+
check the receipt's status, because a mined-and-reverted reset leaves the allowance exactly where it
|
|
241
|
+
was.
|
|
231
242
|
|
|
232
243
|
## queryKey / mutationKey conventions (mandatory)
|
|
233
244
|
|
|
@@ -199,7 +199,7 @@ Typed React Query wrappers over the backend Swaps API v2 (`sodax.api.swaps.*`),
|
|
|
199
199
|
| Hook | Type |
|
|
200
200
|
|---|---|
|
|
201
201
|
| `useSwapsApiApprove` | Mutation; builds unsigned approval tx(s) — `{ tx, resetTx? }`, caller signs |
|
|
202
|
-
| `useSwapsApiApproveAndBroadcast` | Mutation; builds **and** signs/broadcasts/waits — preferred; `{ approveTxHash, resetTxHash? }` |
|
|
202
|
+
| `useSwapsApiApproveAndBroadcast` | Mutation; builds **and** signs/broadcasts/waits — preferred; `{ approveTxHash, resetTxHash? }`; optional `onProgress` per step |
|
|
203
203
|
| `useSwapsApiCreateIntent` | Mutation; builds `{ tx, intent, relayData }` |
|
|
204
204
|
| `useSwapsApiSubmitIntent` | Mutation; submits broadcast intent to the relay |
|
|
205
205
|
| `useSwapsApiCancelIntent` | Mutation; builds unsigned cancel tx |
|
|
@@ -219,7 +219,8 @@ Typed React Query wrappers over the backend Bridge API v2 (`sodax.api.bridge.*`)
|
|
|
219
219
|
| `useBridgeApiBridgeableAmount` | Query; `{ limit }` deposit capacity / withdrawal liquidity for a pair |
|
|
220
220
|
| `useBridgeApiIsBridgeable` | Query; `{ bridgeable }` whether a (from, to) pair is bridgeable |
|
|
221
221
|
| `useBridgeApiSubmitTxStatus` | Query (1s); requires `txHash` + `srcChainKey`; polls until `executed` / `failed` |
|
|
222
|
-
| `useBridgeApiApprove` | Mutation; builds unsigned approval tx |
|
|
222
|
+
| `useBridgeApiApprove` | Mutation; builds the unsigned approval txs — `{ tx, resetTx? }`, ordering is yours to handle |
|
|
223
|
+
| `useBridgeApiApproveAndBroadcast` | Mutation; builds **and** signs/broadcasts/waits — preferred; `{ approveTxHash, resetTxHash? }`; optional `onProgress` per step |
|
|
223
224
|
| `useBridgeApiCreateBridgeIntent` | Mutation; builds `{ tx, relayData }` (no intent) |
|
|
224
225
|
| `useBridgeApiSubmitTx` | Mutation; `request: BridgeSubmitTxRequestV2` (FULL relayData envelope) |
|
|
225
226
|
|
|
@@ -197,6 +197,7 @@ Typed wrappers over `sodax.api.bridge.*` (one per Bridge API v2 endpoint), all k
|
|
|
197
197
|
| `['bridgeApi', 'bridgeable', srcChainKey, dstChainKey, inputToken, outputToken]` | `useBridgeApiIsBridgeable` |
|
|
198
198
|
| `['bridgeApi', 'submitTx', 'status', txHash, srcChainKey]` | `useBridgeApiSubmitTxStatus` — both identifiers required |
|
|
199
199
|
| `['bridgeApi', 'approve']` | `useBridgeApiApprove` mutation |
|
|
200
|
+
| `['bridgeApi', 'approveAndBroadcast']` | `useBridgeApiApproveAndBroadcast` mutation |
|
|
200
201
|
| `['bridgeApi', 'createBridgeIntent']` | `useBridgeApiCreateBridgeIntent` mutation |
|
|
201
202
|
| `['bridgeApi', 'submitTx']` | `useBridgeApiSubmitTx` mutation |
|
|
202
203
|
|
|
@@ -50,7 +50,7 @@ For most consumers, this whole pipeline is one method call (`sodax.swaps.swap(..
|
|
|
50
50
|
|
|
51
51
|
### Supported chains
|
|
52
52
|
|
|
53
|
-
|
|
53
|
+
22 total. EVM (14): Sonic (hub), Ethereum, Arbitrum, Base, BSC, Optimism, Polygon, Avalanche, HyperEVM, Lightlink, Redbelly, Kaia, Hedera, Robinhood Chain. Non-EVM (8): Solana, Sui, Stellar, ICON, Injective, NEAR, Stacks, Bitcoin. See [`reference/`](reference/) § "Chain keys" for the full table with relay IDs and address-type mapping.
|
|
54
54
|
|
|
55
55
|
---
|
|
56
56
|
|
|
@@ -62,7 +62,7 @@ Instead, the SDK has **one** `SpokeService` instance (owned by `Sodax`) which ho
|
|
|
62
62
|
|
|
63
63
|
```
|
|
64
64
|
SpokeService
|
|
65
|
-
├── EvmSpokeService (handles all
|
|
65
|
+
├── EvmSpokeService (handles all 14 EVM chains)
|
|
66
66
|
├── SonicSpokeService (special-cased for the hub)
|
|
67
67
|
├── SolanaSpokeService
|
|
68
68
|
├── SuiSpokeService
|
|
@@ -102,10 +102,12 @@ so a token added or upgraded later is handled without a code change. Consumer im
|
|
|
102
102
|
transaction hash: the hash of the **last** transaction. Show step progress in the UI if you want,
|
|
103
103
|
but nothing breaks if you do not.
|
|
104
104
|
- **Unsigned flows (`raw: true`)** still return exactly one transaction from `approve`, which cannot
|
|
105
|
-
express a two-step plan. Use `sodax.swaps.buildApproveTxs({ params, raw: true })`
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
the reset has landed.
|
|
105
|
+
express a two-step plan. Use `sodax.swaps.buildApproveTxs({ params, raw: true })` — or
|
|
106
|
+
`sodax.bridge.buildApproveTxs` for a bridge — instead; both return `{ approveTx, resetTx? }`.
|
|
107
|
+
`resetTx` is present only for a guarded token holding a stale allowance — broadcast it and wait for
|
|
108
|
+
it to be mined first, because `approveTx` is not valid until the reset has landed. Each feature
|
|
109
|
+
resolves its own spender (a bridge on the hub approves the caller's hub wallet router, a swap the
|
|
110
|
+
solver's intents contract), so call the one matching the action you are about to take.
|
|
109
111
|
|
|
110
112
|
---
|
|
111
113
|
|
|
@@ -62,6 +62,31 @@ Bridge is **vault-backed, not solver-based**, so the surface is smaller and a fe
|
|
|
62
62
|
*also* have backend endpoints (listed above), mirrored on this client for non-SDK HTTP callers / parity.
|
|
63
63
|
The token *list* is backend-served via `getTokens` / `getTokensByChain`.
|
|
64
64
|
|
|
65
|
+
## `approve` can return two transactions
|
|
66
|
+
|
|
67
|
+
`BridgeApproveResponseV2` is `{ tx, resetTx? }`. `resetTx` appears only when the source token rejects
|
|
68
|
+
an allowance change from one non-zero value to another (the 2017 TetherToken lineage) **and** the
|
|
69
|
+
wallet already holds a stale allowance — a wallet in that state cannot approve at all until it is
|
|
70
|
+
zeroed.
|
|
71
|
+
|
|
72
|
+
Broadcast `resetTx` first and wait for it to be mined, then broadcast `tx`. The two cannot be
|
|
73
|
+
batched: the approval is only valid once the reset has landed on-chain. Submitting `tx` while a
|
|
74
|
+
non-zero stale allowance remains is a guaranteed revert.
|
|
75
|
+
|
|
76
|
+
```ts
|
|
77
|
+
const { tx, resetTx } = approveResponse;
|
|
78
|
+
|
|
79
|
+
if (resetTx) {
|
|
80
|
+
const resetHash = await sendTransaction(resetTx);
|
|
81
|
+
await waitForTransactionReceipt(resetHash);
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
await sendTransaction(tx);
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
The field is optional and absent for every other token, so ignoring it keeps existing behaviour —
|
|
88
|
+
it just cannot rescue a wallet stuck on a guarded token.
|
|
89
|
+
|
|
65
90
|
## Common call shapes
|
|
66
91
|
|
|
67
92
|
### Allowance · approve · create intent (shared body)
|
|
@@ -77,7 +102,13 @@ const body = {
|
|
|
77
102
|
|
|
78
103
|
const allowance = await sodax.api.bridge.checkAllowance(body);
|
|
79
104
|
if (allowance.ok && !allowance.value.valid) {
|
|
80
|
-
const approved = await sodax.api.bridge.approve(body);
|
|
105
|
+
const approved = await sodax.api.bridge.approve(body);
|
|
106
|
+
if (!approved.ok) return;
|
|
107
|
+
const { tx: approveTx, resetTx } = approved.value; // broadcast resetTx first when present, then tx
|
|
108
|
+
if (resetTx) {
|
|
109
|
+
await waitForTransactionReceipt(await sendTransaction(resetTx));
|
|
110
|
+
}
|
|
111
|
+
await waitForTransactionReceipt(await sendTransaction(approveTx));
|
|
81
112
|
}
|
|
82
113
|
|
|
83
114
|
const created = await sodax.api.bridge.createBridgeIntent(body);
|
|
@@ -16,6 +16,8 @@ A bridge call deposits the source token into its vault on the hub, then triggers
|
|
|
16
16
|
sodax.bridge.bridge<K>(action: BridgeParams<K, false>): Promise<Result<TxHashPair, SodaxError>>;
|
|
17
17
|
sodax.bridge.createBridgeIntent<K, Raw>(action: BridgeParams<K, Raw>): Promise<Result<IntentTxResult<K, Raw>, SodaxError>>;
|
|
18
18
|
sodax.bridge.approve<K, Raw>(args): Promise<Result<TxReturnType<K, Raw>, SodaxError>>;
|
|
19
|
+
// Unsigned callers only: returns both transactions when a stale allowance must be cleared first.
|
|
20
|
+
sodax.bridge.buildApproveTxs<K>(action: BridgeParams<K, true>): Promise<Result<ApprovalTxs<K>, SodaxError>>;
|
|
19
21
|
sodax.bridge.isAllowanceValid<K, Raw>(args): Promise<Result<boolean, SodaxError>>;
|
|
20
22
|
|
|
21
23
|
sodax.bridge.getBridgeableAmount(from: XToken, to: XToken): Promise<Result<BridgeLimit, SodaxError>>;
|
|
@@ -195,6 +197,7 @@ if (result.ok) {
|
|
|
195
197
|
| `bridge` | `TxHashPair` |
|
|
196
198
|
| `createBridgeIntent` | `IntentTxResult<K, Raw>` = `{ tx: TxReturnType<K, Raw>, relayData }` |
|
|
197
199
|
| `approve` | `TxReturnType<K, Raw>` |
|
|
200
|
+
| `buildApproveTxs` | `ApprovalTxs<K> = { approveTx, resetTx? }` |
|
|
198
201
|
| `isAllowanceValid` | `boolean` |
|
|
199
202
|
| `getBridgeableAmount` | `BridgeLimit = { amount, decimals, type }` |
|
|
200
203
|
| `getBridgeableTokens` | `XToken[]` |
|
|
@@ -205,6 +208,13 @@ approval, so the user signs twice. The returned value is unchanged — one hash,
|
|
|
205
208
|
transaction's. Detection simulates the approval, so never gate on a token list. Full note: "ERC-20
|
|
206
209
|
approval can take two transactions" in [`architecture.md`](../architecture.md).
|
|
207
210
|
|
|
211
|
+
Unsigned callers cannot get that from `approve({ raw: true })`, which returns a single transaction.
|
|
212
|
+
Use `buildApproveTxs` instead — it returns `{ approveTx, resetTx? }`, and when `resetTx` is present
|
|
213
|
+
you must broadcast it and wait for it to be mined before `approveTx`. It resolves the same spender as
|
|
214
|
+
`approve` and `isAllowanceValid` (the caller's own hub wallet router on the hub, the asset manager on
|
|
215
|
+
an EVM spoke), so do not substitute `sodax.swaps.buildApproveTxs` for a bridge — swaps approves a
|
|
216
|
+
different contract on the hub.
|
|
217
|
+
|
|
208
218
|
## Error codes
|
|
209
219
|
|
|
210
220
|
`feature: 'bridge'`. Per-method narrow unions:
|
|
@@ -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
|
|
@@ -17,6 +17,7 @@
|
|
|
17
17
|
| `REDBELLY_MAINNET` | `'redbelly'` | EVM | spoke | `0x${string}` |
|
|
18
18
|
| `KAIA_MAINNET` | `'0x2019.kaia'` | EVM | spoke | `0x${string}` |
|
|
19
19
|
| `HEDERA_MAINNET` | `'hedera'` | EVM | spoke | `0x${string}` |
|
|
20
|
+
| `ROBINHOOD_MAINNET` | `'robinhood'` | EVM | spoke | `0x${string}` |
|
|
20
21
|
| `SOLANA_MAINNET` | `'solana'` | SOLANA | spoke | base58 PublicKey string |
|
|
21
22
|
| `SUI_MAINNET` | `'sui'` | SUI | spoke | `0x${string}` (32-byte) |
|
|
22
23
|
| `STELLAR_MAINNET` | `'stellar'` | STELLAR | spoke | `G…` |
|
|
@@ -36,9 +37,9 @@
|
|
|
36
37
|
|
|
37
38
|
| Type | What it is |
|
|
38
39
|
|---|---|
|
|
39
|
-
| `ChainKey` | Union of all `ChainKeys.*` values (
|
|
40
|
-
| `SpokeChainKey` | Same union as `ChainKey` — includes Sonic (
|
|
41
|
-
| `EvmChainKey` | Subset of `ChainKey` for the
|
|
40
|
+
| `ChainKey` | Union of all `ChainKeys.*` values (22 chains). |
|
|
41
|
+
| `SpokeChainKey` | Same union as `ChainKey` — includes Sonic (22 chains). For "EVM chains excluding the hub" use `EvmSpokeOnlyChainKey`. |
|
|
42
|
+
| `EvmChainKey` | Subset of `ChainKey` for the 14 EVM chains. |
|
|
42
43
|
| `HubChainKey` | The literal `'sonic'`. |
|
|
43
44
|
|
|
44
45
|
### Chain-family helpers
|
|
@@ -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)
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: sodax-wallet-sdk-core-evm
|
|
3
|
-
description: 'Granular skill for the @sodax/wallet-sdk-core v2 EVM wallet provider only — `EvmWalletProvider` (backed by viem), one class covering all
|
|
3
|
+
description: 'Granular skill for the @sodax/wallet-sdk-core v2 EVM wallet provider only — `EvmWalletProvider` (backed by viem), one class covering all 14 SODAX EVM chains — the Sonic hub plus 13 EVM spoke chains (Ethereum, Arbitrum, Base, BSC, Optimism, Polygon, Avalanche, HyperEVM, Lightlink, Redbelly, Kaia, Hedera, Robinhood Chain). Use when a backend / Node script / CI / bot / non-React browser flow needs to instantiate an EVM provider directly and sign + broadcast — e.g. "instantiate EvmWalletProvider", "private-key EVM signing in Node", "EVM wallet provider for a bot", "sendTransaction from a script". Covers BOTH integration (write new v2 code) and migration (port v1 — almost a no-op at this surface: deep-import → barrel). Picks via Step 1. Links into the parent sodax-wallet-sdk-core knowledge tree. For React dapps use the sodax-wallet-sdk-react skill instead (get the typed provider via useWalletProvider).'
|
|
4
4
|
license: MIT
|
|
5
5
|
metadata:
|
|
6
6
|
version: '0.0.1'
|
|
@@ -9,13 +9,13 @@ metadata:
|
|
|
9
9
|
|
|
10
10
|
# EVM (`wallet-sdk-core` granular skill)
|
|
11
11
|
|
|
12
|
-
Granular skill for `EvmWalletProvider` — the low-level EVM wallet for backend / Node / non-React flows. One class covers all
|
|
12
|
+
Granular skill for `EvmWalletProvider` — the low-level EVM wallet for backend / Node / non-React flows. One class covers all 14 SODAX EVM chains — the Sonic hub plus 13 EVM spoke chains — via `getEvmViemChain()`. Source-of-truth reference lives in the parent broad skill's knowledge tree; this file is the focused workflow only.
|
|
13
13
|
|
|
14
14
|
## Step 1 — Clarify with user before coding
|
|
15
15
|
|
|
16
16
|
1. **New code or v1 → v2 port?** New → § Integration. Port v1 → § Migration (almost always a no-op here).
|
|
17
17
|
2. **Private-key or browser-extension config?** EVM discriminates by **field presence** (no `type`): PK = `{ privateKey, chainId, rpcUrl? }` (Node / CI / bots); browser-extension = `{ walletClient, publicClient }` (pre-built by wagmi / the consumer). Mutually exclusive — pick one.
|
|
18
|
-
3. **Which chain?** One `EvmWalletProvider` covers all
|
|
18
|
+
3. **Which chain?** One `EvmWalletProvider` covers all 14 EVM chains (the Sonic hub plus 13 EVM spokes) via `chainId: EvmChainKey` (`ChainKeys.SONIC_MAINNET`, …).
|
|
19
19
|
|
|
20
20
|
## Integration workflow (new v2 code)
|
|
21
21
|
|
|
@@ -18,7 +18,7 @@ It is intentionally framework-agnostic — Node ≥ 20.12, browser, edge runtime
|
|
|
18
18
|
|
|
19
19
|
| Chain family | Provider class | Underlying chain SDK |
|
|
20
20
|
|---|---|---|
|
|
21
|
-
| EVM (
|
|
21
|
+
| EVM (14 chains) | `EvmWalletProvider` | `viem` |
|
|
22
22
|
| Solana | `SolanaWalletProvider` | `@solana/web3.js` |
|
|
23
23
|
| Sui | `SuiWalletProvider` | `@mysten/sui` |
|
|
24
24
|
| Bitcoin | `BitcoinWalletProvider` | `bitcoinjs-lib` (+ `ecpair`, `secp256k1`) |
|
|
@@ -4,7 +4,7 @@ Chain families and spoke chain keys this package can sign for. Keys live in `@so
|
|
|
4
4
|
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
## EVM (one provider,
|
|
7
|
+
## EVM (one provider, 14 chains)
|
|
8
8
|
|
|
9
9
|
`EvmWalletProvider` covers every EVM spoke chain via `getEvmViemChain()`. The provider is exhaustive — adding a new `EvmChainKey` to `@sodax/types` requires updating `getEvmViemChain` (caught at compile time via a `never` assertion in the default branch).
|
|
10
10
|
|
|
@@ -23,6 +23,7 @@ Chain families and spoke chain keys this package can sign for. Keys live in `@so
|
|
|
23
23
|
| `ChainKeys.REDBELLY_MAINNET` | `redbellyMainnet` |
|
|
24
24
|
| `ChainKeys.KAIA_MAINNET` | `kaia` |
|
|
25
25
|
| `ChainKeys.HEDERA_MAINNET` | `hedera` |
|
|
26
|
+
| `ChainKeys.ROBINHOOD_MAINNET` | `robinhoodChain` (defined locally — absent from `viem/chains`) |
|
|
26
27
|
|
|
27
28
|
---
|
|
28
29
|
|
|
@@ -39,7 +40,7 @@ Chain families and spoke chain keys this package can sign for. Keys live in `@so
|
|
|
39
40
|
| NEAR | `NearWalletProvider` | `ChainKeys.NEAR_MAINNET` |
|
|
40
41
|
| Stacks | `StacksWalletProvider` | `ChainKeys.STACKS_MAINNET` |
|
|
41
42
|
|
|
42
|
-
>
|
|
43
|
+
> 22 spoke chains total = 14 EVM + 8 non-EVM. The hub chain (Sonic) is counted with EVM.
|
|
43
44
|
|
|
44
45
|
---
|
|
45
46
|
|
|
@@ -10,7 +10,7 @@ Chains supported by `@sodax/wallet-sdk-react` v2 — their `ChainType` family an
|
|
|
10
10
|
|
|
11
11
|
| ChainType | Networks (examples) | React adapter mounted |
|
|
12
12
|
|---|---|---|
|
|
13
|
-
| `EVM` | Sonic, Ethereum, Arbitrum, Base, BSC, Optimism, Polygon, Avalanche, HyperEVM, Lightlink, Redbelly, Kaia, Hedera | wagmi |
|
|
13
|
+
| `EVM` | Sonic, Ethereum, Arbitrum, Base, BSC, Optimism, Polygon, Avalanche, HyperEVM, Lightlink, Redbelly, Kaia, Hedera, Robinhood Chain | wagmi |
|
|
14
14
|
| `SOLANA` | Solana mainnet | `@solana/wallet-adapter-react` |
|
|
15
15
|
| `SUI` | Sui mainnet/testnet | `@mysten/dapp-kit-react` |
|
|
16
16
|
| `BITCOIN` | Bitcoin mainnet | (none — direct extension probes) |
|
|
@@ -56,7 +56,7 @@ ChainKeys.BITCOIN_MAINNET; // BITCOIN
|
|
|
56
56
|
// …etc
|
|
57
57
|
```
|
|
58
58
|
|
|
59
|
-
Naming pattern: `<NETWORK>_MAINNET`. EVM has
|
|
59
|
+
Naming pattern: `<NETWORK>_MAINNET`. EVM has 14 entries (Sonic, Ethereum, Arbitrum, Base, BSC, Optimism, Polygon, Avalanche, HyperEVM, Lightlink, Redbelly, Kaia, Hedera, Robinhood Chain); the other 8 families each have one. Inspect `@sodax/types` for the authoritative list.
|
|
60
60
|
|
|
61
61
|
---
|
|
62
62
|
|