@sodax/skills 2.1.0-rc.6 → 2.1.0-rc.8
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 +2 -2
- 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/chain-specifics.md +1 -1
- 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/reference/chain-keys.md +4 -3
- package/skills/sodax-wallet-sdk-core/evm/SKILL.md +3 -3
- package/skills/sodax-wallet-sdk-core/integration/knowledge/README.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/architecture.md +0 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/README.md +1 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/sui.md +18 -11
- package/skills/sodax-wallet-sdk-core/integration/knowledge/quickstart.md +10 -6
- package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/library-exports.md +0 -5
- package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/setup-browser-extension.md +3 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/chain-support.md +4 -3
- package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/public-api.md +0 -1
- package/skills/sodax-wallet-sdk-core/migration-v1-to-v2/knowledge/breaking-changes/library-exports.md +0 -1
- package/skills/sodax-wallet-sdk-core/migration-v1-to-v2/knowledge/recipes/adopt-library-exports.md +0 -4
- package/skills/sodax-wallet-sdk-core/migration-v1-to-v2/knowledge/reference/added-fields.md +1 -2
- package/skills/sodax-wallet-sdk-core/sui/SKILL.md +9 -8
- package/skills/sodax-wallet-sdk-react/SKILL.md +1 -1
- package/skills/sodax-wallet-sdk-react/integration/knowledge/ai-rules.md +2 -2
- package/skills/sodax-wallet-sdk-react/integration/knowledge/architecture.md +1 -1
- package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/setup.md +1 -1
- package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/sign-message.md +1 -1
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/chain-support.md +4 -4
- package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/breaking-changes.md +2 -2
- package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/reference/components.md +1 -1
- package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/reference/config.md +3 -2
package/package.json
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
"publishConfig": {
|
|
5
5
|
"access": "public"
|
|
6
6
|
},
|
|
7
|
-
"version": "2.1.0-rc.
|
|
7
|
+
"version": "2.1.0-rc.8",
|
|
8
8
|
"license": "MIT",
|
|
9
9
|
"description": "AI-agent skills and knowledge for consumers of @sodax/* SDKs (Claude Code, Codex, Cursor, …)",
|
|
10
10
|
"keywords": [
|
|
@@ -24,7 +24,7 @@
|
|
|
24
24
|
},
|
|
25
25
|
"type": "module",
|
|
26
26
|
"engines": {
|
|
27
|
-
"node": ">=
|
|
27
|
+
"node": ">=22.12.0"
|
|
28
28
|
},
|
|
29
29
|
"files": [
|
|
30
30
|
".claude-plugin",
|
|
@@ -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
|
|
|
@@ -239,7 +239,7 @@ Deposits **from** NEAR (`deposit()` / `fillIntent()` on the NEAR spoke service)
|
|
|
239
239
|
|
|
240
240
|
| Chain | Notes |
|
|
241
241
|
|---|---|
|
|
242
|
-
| **Sui** (`SUI_MAINNET`) | Address: 32-byte `0x…` (different from EVM addresses despite the prefix). Wallet provider `ISuiWalletProvider` uses `@mysten/sui` under the hood. |
|
|
242
|
+
| **Sui** (`SUI_MAINNET`) | Address: 32-byte `0x…` (different from EVM addresses despite the prefix). Wallet provider `ISuiWalletProvider` uses `@mysten/sui` under the hood. Reads and submission go over gRPC-web (`grpc_url`, default `https://fullnode.mainnet.sui.io`; `rpc_url` remains a deprecated alias that wins when set) — Mysten's public fullnodes stopped serving JSON-RPC in July 2026, and `sui-node` drops it in October 2026. |
|
|
243
243
|
| **Stacks** (`STACKS_MAINNET`) | Address: `SP…` (mainnet) / `ST…` (testnet). Uses `@stacks/transactions` for tx construction. |
|
|
244
244
|
| **Injective** (`INJECTIVE_MAINNET`) | Cosmos-ecosystem chain. Address: `inj1…`. Wallet provider uses `@injectivelabs/sdk-ts`. |
|
|
245
245
|
|
|
@@ -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:
|
|
@@ -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
|
|
@@ -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,9 +18,9 @@ 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
|
-
| Sui | `SuiWalletProvider` | `@mysten/sui`
|
|
23
|
+
| Sui | `SuiWalletProvider` | `@mysten/sui` |
|
|
24
24
|
| Bitcoin | `BitcoinWalletProvider` | `bitcoinjs-lib` (+ `ecpair`, `secp256k1`) |
|
|
25
25
|
| Stellar | `StellarWalletProvider` | `@stellar/stellar-sdk` |
|
|
26
26
|
| ICON | `IconWalletProvider` | `icon-sdk-js` |
|
|
@@ -131,9 +131,7 @@ export type { Account, Address, Chain, Transport, PublicClient, WalletClient,
|
|
|
131
131
|
TransactionReceipt } from 'viem';
|
|
132
132
|
|
|
133
133
|
// Sui types
|
|
134
|
-
export type { SuiTransactionBlockResponseOptions } from '@mysten/sui/client';
|
|
135
134
|
export type { Transaction, TransactionArgument } from '@mysten/sui/transactions';
|
|
136
|
-
export type { SuiWalletFeatures, WalletAccount, WalletWithFeatures } from '@mysten/wallet-standard';
|
|
137
135
|
|
|
138
136
|
// Solana types
|
|
139
137
|
export type { Commitment, ConnectionConfig, SendOptions } from '@solana/web3.js';
|
|
@@ -11,7 +11,7 @@ One file per chain family. Each file documents:
|
|
|
11
11
|
|---|---|---|---|
|
|
12
12
|
| [EVM](./evm.md) | `EvmWalletProvider` | Field presence (no `type`) | `viem` |
|
|
13
13
|
| [Solana](./solana.md) | `SolanaWalletProvider` | Field presence | `@solana/web3.js` |
|
|
14
|
-
| [Sui](./sui.md) | `SuiWalletProvider` | Field presence (uses `mnemonics`) | `@mysten/sui`
|
|
14
|
+
| [Sui](./sui.md) | `SuiWalletProvider` | Field presence (uses `mnemonics`) | `@mysten/sui` |
|
|
15
15
|
| [Bitcoin](./bitcoin.md) | `BitcoinWalletProvider` | Explicit `type` | `bitcoinjs-lib`, `ecpair`, `secp256k1` |
|
|
16
16
|
| [Stellar](./stellar.md) | `StellarWalletProvider` | Explicit `type` | `@stellar/stellar-sdk` |
|
|
17
17
|
| [ICON](./icon.md) | `IconWalletProvider` | Field presence | `icon-sdk-js` |
|
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
# Sui — `SuiWalletProvider`
|
|
2
2
|
|
|
3
|
-
Backed by `@mysten/sui`
|
|
3
|
+
Backed by `@mysten/sui` (gRPC transport).
|
|
4
4
|
|
|
5
5
|
| | |
|
|
6
6
|
|---|---|
|
|
7
7
|
| Class | `SuiWalletProvider` |
|
|
8
8
|
| Interface | `ISuiWalletProvider` (from `@sodax/types`) |
|
|
9
9
|
| Discriminant style | **Field presence** (no `type` field) — but uses `mnemonics`, not `privateKey` |
|
|
10
|
-
| Underlying SDK | `@mysten/sui
|
|
10
|
+
| Underlying SDK | `@mysten/sui` (gRPC transport) |
|
|
11
11
|
|
|
12
12
|
---
|
|
13
13
|
|
|
@@ -17,15 +17,16 @@ Backed by `@mysten/sui` and `@mysten/wallet-standard`.
|
|
|
17
17
|
type SuiWalletConfig = PrivateKeySuiWalletConfig | BrowserExtensionSuiWalletConfig;
|
|
18
18
|
|
|
19
19
|
type PrivateKeySuiWalletConfig = {
|
|
20
|
-
|
|
20
|
+
grpcUrl?: string; // gRPC-web endpoint, e.g. https://fullnode.mainnet.sui.io
|
|
21
|
+
rpcUrl?: string; // deprecated alias — pass this OR grpcUrl, never both
|
|
21
22
|
mnemonics: string; // BIP-39 mnemonic — NOT a raw private key
|
|
22
23
|
defaults?: SuiWalletDefaults;
|
|
23
24
|
};
|
|
24
25
|
|
|
25
26
|
type BrowserExtensionSuiWalletConfig = {
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
27
|
+
grpcUrl: string;
|
|
28
|
+
address: string; // active account address
|
|
29
|
+
signTransaction: (txn: SuiTransaction) => Promise<{ bytes: string; signature: string }>;
|
|
29
30
|
defaults?: SuiWalletDefaults;
|
|
30
31
|
};
|
|
31
32
|
```
|
|
@@ -33,7 +34,7 @@ type BrowserExtensionSuiWalletConfig = {
|
|
|
33
34
|
| Mode discriminant | How to detect |
|
|
34
35
|
|---|---|
|
|
35
36
|
| Private-key | `'mnemonics' in config` |
|
|
36
|
-
| Browser-extension | `'
|
|
37
|
+
| Browser-extension | `'signTransaction' in config && 'address' in config` |
|
|
37
38
|
|
|
38
39
|
Note the name — `PrivateKeySuiWalletConfig` is still called "PrivateKey" for consistency, even though the credential is a mnemonic. The library derives an Ed25519 keypair from the mnemonic phrase.
|
|
39
40
|
|
|
@@ -45,7 +46,6 @@ Note the name — `PrivateKeySuiWalletConfig` is still called "PrivateKey" for c
|
|
|
45
46
|
type SuiWalletDefaults = {
|
|
46
47
|
signAndExecuteTxn?: {
|
|
47
48
|
dryRun?: { enabled?: boolean }; // default: enabled = true
|
|
48
|
-
response?: SuiTransactionBlockResponseOptions;
|
|
49
49
|
};
|
|
50
50
|
getCoins?: { limit?: number };
|
|
51
51
|
};
|
|
@@ -76,16 +76,23 @@ await provider.signAndExecuteTxn(tx, { dryRun: { enabled: false } });
|
|
|
76
76
|
|---|---|---|
|
|
77
77
|
| `chainType` | `'SUI'` (literal) | Discriminant. |
|
|
78
78
|
|
|
79
|
-
The internal `client:
|
|
79
|
+
The internal `client: SuiGrpcClient` and `wallet: SuiWallet` are private.
|
|
80
80
|
|
|
81
81
|
---
|
|
82
82
|
|
|
83
83
|
## Gotchas
|
|
84
84
|
|
|
85
|
-
- **Browser-extension mode
|
|
85
|
+
- **Browser-extension mode takes a signer callback, not a wallet object.** The provider builds its own gRPC client and only asks you to sign.
|
|
86
|
+
- **The callback takes the transaction positionally — wrap, don't assign.** `dAppKit.signTransaction` from `@mysten/dapp-kit-react` takes `{ transaction, account?, network? }`, and wallet-standard's `signTransaction` feature takes `{ transaction, account, chain }`; neither is assignable to `(txn) => …`. Name the account explicitly — left out, dApp Kit signs with whichever account is currently connected, which need not be the `address` you passed. The provider builds and dry-runs the transaction against its own client before calling you, so the adapter only has to serialize it (`account` is dApp Kit's `UiWalletAccount`).
|
|
87
|
+
|
|
88
|
+
```ts
|
|
89
|
+
// @ai-snippets-skip
|
|
90
|
+
signTransaction: async txn => dAppKit.signTransaction({ transaction: await txn.toJSON(), account }),
|
|
91
|
+
```
|
|
86
92
|
- **Mnemonic is the only private-key option.** There is no raw-secret-key constructor. If you have a 32-byte key bytes you must convert it to a mnemonic upstream (or fork the provider).
|
|
87
93
|
- **Dry-run is on by default for safety.** Production scripts almost never want to disable it.
|
|
88
|
-
-
|
|
94
|
+
- **Sui speaks gRPC only.** Mysten's public fullnodes stopped serving JSON-RPC in July 2026, and `sui-node` drops it in October 2026, so the endpoint must serve gRPC-web. `https://fullnode.mainnet.sui.io` does, free and without an API key. The old `rpcUrl` name still resolves. Exactly one of the two must be set: neither throws, and so does both.
|
|
95
|
+
- **The public fullnode is rate-limited per IP.** Bursts past roughly 150 concurrent calls, or sustained load past roughly 20-25 req/s, return `RESOURCE_EXHAUSTED`; it recovers within seconds. Fine for a user's browser session. A server-side integration sharing one egress IP should pass its own node or a paid provider.
|
|
89
96
|
|
|
90
97
|
---
|
|
91
98
|
|
|
@@ -20,7 +20,7 @@ pnpm add @sodax/sdk
|
|
|
20
20
|
|
|
21
21
|
---
|
|
22
22
|
|
|
23
|
-
## EVM (
|
|
23
|
+
## EVM (14 chains)
|
|
24
24
|
|
|
25
25
|
```ts
|
|
26
26
|
import { EvmWalletProvider } from '@sodax/wallet-sdk-core';
|
|
@@ -84,15 +84,19 @@ import { SuiWalletProvider } from '@sodax/wallet-sdk-core';
|
|
|
84
84
|
|
|
85
85
|
// Private-key — DERIVED FROM MNEMONIC, not a raw key
|
|
86
86
|
const suiPk = new SuiWalletProvider({
|
|
87
|
-
|
|
87
|
+
grpcUrl: 'https://fullnode.mainnet.sui.io',
|
|
88
88
|
mnemonics: 'word1 word2 … word12',
|
|
89
89
|
});
|
|
90
90
|
|
|
91
|
-
// Browser-extension —
|
|
91
|
+
// Browser-extension — the provider owns the client; you supply the signer
|
|
92
92
|
const suiBrowser = new SuiWalletProvider({
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
93
|
+
grpcUrl: 'https://fullnode.mainnet.sui.io',
|
|
94
|
+
address: myActiveWalletAccount.address, // string — from dApp Kit's UiWalletAccount
|
|
95
|
+
// `signTransaction` takes the transaction positionally; dApp Kit's is options-shaped,
|
|
96
|
+
// so wrap it. Name the account — otherwise dApp Kit signs with whichever one happens
|
|
97
|
+
// to be connected.
|
|
98
|
+
signTransaction: async txn =>
|
|
99
|
+
dAppKit.signTransaction({ transaction: await txn.toJSON(), account: myActiveWalletAccount }),
|
|
96
100
|
});
|
|
97
101
|
```
|
|
98
102
|
|
|
@@ -15,9 +15,7 @@ Source file: `src/types/library-exports.ts`. The export name is the same as upst
|
|
|
15
15
|
| Chain SDK | Re-exported types |
|
|
16
16
|
|---|---|
|
|
17
17
|
| `viem` | `Account`, `Address`, `Chain`, `Transport`, `PublicClient`, `WalletClient`, `HttpTransportConfig`, `PublicClientConfig`, `WalletClientConfig`, `SendTransactionParameters`, `WaitForTransactionReceiptParameters`, `TransactionReceipt` |
|
|
18
|
-
| `@mysten/sui/client` | `SuiTransactionBlockResponseOptions` |
|
|
19
18
|
| `@mysten/sui/transactions` | `Transaction`, `TransactionArgument` |
|
|
20
|
-
| `@mysten/wallet-standard` | `SuiWalletFeatures`, `WalletAccount`, `WalletWithFeatures` |
|
|
21
19
|
| `@solana/web3.js` | `Commitment`, `ConnectionConfig`, `SendOptions` |
|
|
22
20
|
| `@injectivelabs/networks` | `Network` |
|
|
23
21
|
| `@injectivelabs/ts-types` | `ChainId`, `EvmChainId` |
|
|
@@ -48,9 +46,6 @@ import type {
|
|
|
48
46
|
WalletClient,
|
|
49
47
|
PublicClient,
|
|
50
48
|
TransactionReceipt,
|
|
51
|
-
SuiWalletFeatures,
|
|
52
|
-
WalletAccount,
|
|
53
|
-
WalletWithFeatures,
|
|
54
49
|
ConnectionConfig,
|
|
55
50
|
Network,
|
|
56
51
|
ChainId,
|
package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/setup-browser-extension.md
CHANGED
|
@@ -14,7 +14,7 @@ Each chain has its own browser-extension variant. See [`../features/<chain>.md`]
|
|
|
14
14
|
|---|---|
|
|
15
15
|
| EVM | `walletClient` (viem `WalletClient<Transport, Chain, Account>`) + `publicClient` (viem `PublicClient`) |
|
|
16
16
|
| Solana | `wallet: { publicKey, signTransaction }` + `endpoint` |
|
|
17
|
-
| Sui | `
|
|
17
|
+
| Sui | `grpcUrl` + `address` + `signTransaction` (returns `{ bytes, signature }`) |
|
|
18
18
|
| Bitcoin | `type: 'BROWSER_EXTENSION'`, `walletsKit` (consumer-supplied adapter), `network` |
|
|
19
19
|
| Stellar | `type: 'BROWSER_EXTENSION'`, `walletsKit`, `network` |
|
|
20
20
|
| ICON | `walletAddress` (optional `hx…`) + `rpcUrl` |
|
|
@@ -124,7 +124,8 @@ grep -rn "@sodax/wallet-sdk-core/" <user-src> | grep -v "from '@sodax/wallet-sdk
|
|
|
124
124
|
| Error | Cause | Fix |
|
|
125
125
|
|---|---|---|
|
|
126
126
|
| `signTransaction is not a function` (Solana) | Wallet adapter didn't provide a signer for the connected wallet | Gate construction on `signTransaction != null`. |
|
|
127
|
-
| `
|
|
127
|
+
| `Cannot read properties of undefined` inside the Sui signer, or a type error on `signTransaction` | `dAppKit.signTransaction` assigned directly | Wrap it — the config's callback takes the transaction positionally, dApp Kit's takes `{ transaction, … }`. |
|
|
128
|
+
| Sui wallet signs with the wrong account | `account` omitted from the wrapped `dAppKit.signTransaction` call | Pass it explicitly; dApp Kit defaults to whichever account is connected, not the `address` you configured. |
|
|
128
129
|
| `[EvmWalletProvider] defaults.{transport,publicClient,walletClient} ignored…` | Mixed PK-mode defaults with browser-extension config | Move those defaults out — they only apply in private-key mode. |
|
|
129
130
|
| Mode picked the wrong variant (TypeScript narrowing fails) | Mixed PK and browser fields | Pick **one** discriminated union variant. Don't pass both. |
|
|
130
131
|
|
|
@@ -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
|
|
|
@@ -51,7 +52,7 @@ Run-time deps each provider pulls in. See [`../recipes/library-exports.md`](../r
|
|
|
51
52
|
|---|---|
|
|
52
53
|
| `EvmWalletProvider` | `viem` |
|
|
53
54
|
| `SolanaWalletProvider` | `@solana/web3.js`, `@solana/spl-token`, `@solana/wallet-adapter-base` |
|
|
54
|
-
| `SuiWalletProvider` | `@mysten/sui
|
|
55
|
+
| `SuiWalletProvider` | `@mysten/sui` |
|
|
55
56
|
| `BitcoinWalletProvider` | `bitcoinjs-lib`, `ecpair`, `secp256k1`, `@bitcoinerlab/secp256k1`, `bip322-js` |
|
|
56
57
|
| `StellarWalletProvider` | `@stellar/stellar-sdk` |
|
|
57
58
|
| `IconWalletProvider` | `icon-sdk-js` |
|
|
@@ -99,7 +99,6 @@ Type-only (selected examples):
|
|
|
99
99
|
```ts
|
|
100
100
|
import type {
|
|
101
101
|
WalletClient, PublicClient, TransactionReceipt, // from viem
|
|
102
|
-
SuiTransactionBlockResponseOptions, // from @mysten/sui
|
|
103
102
|
Commitment, ConnectionConfig, SendOptions, // from @solana/web3.js
|
|
104
103
|
Network, ChainId, EvmChainId, MsgBroadcaster, // from @injectivelabs/*
|
|
105
104
|
ClarityValue, PostConditionModeName, // from @stacks/transactions
|
|
@@ -28,7 +28,6 @@ Consumer apps previously had to list every chain SDK explicitly in `package.json
|
|
|
28
28
|
"viem": "^2.x", // for WalletClient, PublicClient
|
|
29
29
|
"@stellar/stellar-sdk": "^11.x", // for Networks
|
|
30
30
|
"@stacks/transactions": "^6.x", // for PostConditionMode
|
|
31
|
-
"@mysten/wallet-standard": "^0.x" // for WalletAccount, WalletWithFeatures
|
|
32
31
|
}
|
|
33
32
|
}
|
|
34
33
|
```
|
package/skills/sodax-wallet-sdk-core/migration-v1-to-v2/knowledge/recipes/adopt-library-exports.md
CHANGED
|
@@ -14,7 +14,6 @@ For the full list of re-exported types, see [`recipes/library-exports.md`](../..
|
|
|
14
14
|
import type { WalletClient, PublicClient, TransactionReceipt } from 'viem';
|
|
15
15
|
import { Networks } from '@stellar/stellar-sdk';
|
|
16
16
|
import { PostConditionMode } from '@stacks/transactions';
|
|
17
|
-
import type { WalletAccount, WalletWithFeatures, SuiWalletFeatures } from '@mysten/wallet-standard';
|
|
18
17
|
import type { Commitment, ConnectionConfig, SendOptions } from '@solana/web3.js';
|
|
19
18
|
```
|
|
20
19
|
|
|
@@ -25,9 +24,6 @@ import type {
|
|
|
25
24
|
WalletClient,
|
|
26
25
|
PublicClient,
|
|
27
26
|
TransactionReceipt,
|
|
28
|
-
WalletAccount,
|
|
29
|
-
WalletWithFeatures,
|
|
30
|
-
SuiWalletFeatures,
|
|
31
27
|
Commitment,
|
|
32
28
|
ConnectionConfig,
|
|
33
29
|
SendOptions,
|
|
@@ -58,8 +58,7 @@ See [`recipes/library-exports.md`](../../../integration/knowledge/recipes/librar
|
|
|
58
58
|
Summary:
|
|
59
59
|
|
|
60
60
|
- **viem** — `Account`, `Address`, `Chain`, `Transport`, `PublicClient`, `WalletClient`, `HttpTransportConfig`, `PublicClientConfig`, `WalletClientConfig`, `SendTransactionParameters`, `WaitForTransactionReceiptParameters`, `TransactionReceipt`
|
|
61
|
-
- **@mysten/sui** — `
|
|
62
|
-
- **@mysten/wallet-standard** — `SuiWalletFeatures`, `WalletAccount`, `WalletWithFeatures`
|
|
61
|
+
- **@mysten/sui** — `Transaction`, `TransactionArgument`
|
|
63
62
|
- **@solana/web3.js** — `Commitment`, `ConnectionConfig`, `SendOptions`
|
|
64
63
|
- **@injectivelabs/*** — `Network`, `ChainId`, `EvmChainId`, `MsgBroadcaster`
|
|
65
64
|
- **@stellar/stellar-sdk** — `Networks` (runtime value)
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: sodax-wallet-sdk-core-sui
|
|
3
|
-
description: 'Granular skill for the @sodax/wallet-sdk-core v2 Sui wallet provider only — `SuiWalletProvider` (backed by @mysten/sui
|
|
3
|
+
description: 'Granular skill for the @sodax/wallet-sdk-core v2 Sui wallet provider only — `SuiWalletProvider` (backed by @mysten/sui over gRPC). Use when a backend / Node script / CI / bot / non-React browser flow needs to instantiate a Sui provider directly and sign + execute — e.g. "instantiate SuiWalletProvider", "Sui signing from a mnemonic in Node", "signAndExecuteTxn with dry-run". Covers BOTH integration (write new v2 code) and migration (port v1 — private-key mode is near mechanical, but browser-extension mode is a hard break: `{client, wallet, account}` becomes `{grpcUrl, address, signTransaction}`). 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'
|
|
@@ -13,8 +13,8 @@ Granular skill for `SuiWalletProvider` — the low-level Sui wallet for backend
|
|
|
13
13
|
|
|
14
14
|
## Step 1 — Clarify with user before coding
|
|
15
15
|
|
|
16
|
-
1. **New code or v1 → v2 port?** New → § Integration. Port v1 → § Migration (
|
|
17
|
-
2. **Private-key or browser-extension config?** Sui discriminates by **field presence** (no `type`) but the PK credential is a **`mnemonics`** string (BIP-39), not a raw key: PK = `{
|
|
16
|
+
1. **New code or v1 → v2 port?** New → § Integration. Port v1 → § Migration (mechanical for private-key mode; browser-extension mode must be rewritten).
|
|
17
|
+
2. **Private-key or browser-extension config?** Sui discriminates by **field presence** (no `type`) but the PK credential is a **`mnemonics`** string (BIP-39), not a raw key: PK = `{ grpcUrl, mnemonics }`; browser-extension = `{ grpcUrl, address, signTransaction }`. Mutually exclusive — pick one. `rpcUrl` is still accepted as a deprecated alias for `grpcUrl`. Exactly one of the two must be present — passing both throws.
|
|
18
18
|
3. **Dry-run?** `signAndExecuteTxn` runs a pre-flight dry-run **on by default**; disable only when paying gas for a doomed tx is acceptable.
|
|
19
19
|
|
|
20
20
|
## Integration workflow (new v2 code)
|
|
@@ -28,20 +28,21 @@ Granular skill for `SuiWalletProvider` — the low-level Sui wallet for backend
|
|
|
28
28
|
### Sui-specific anti-patterns
|
|
29
29
|
|
|
30
30
|
- **Passing a raw private key.** The PK variant accepts only a `mnemonics` phrase — the library derives the Ed25519 keypair. There is no raw-secret-key constructor.
|
|
31
|
-
- **
|
|
31
|
+
- **Assigning `dAppKit.signTransaction` straight to `signTransaction`.** The config's callback takes the transaction positionally; dApp Kit's and wallet-standard's signers are options-shaped. Wrap it, and name the account — otherwise it signs with whichever one is connected, not the `address` you passed.
|
|
32
32
|
- **Disabling dry-run by default.** It's on for safety — production scripts almost never want `{ dryRun: { enabled: false } }`.
|
|
33
33
|
- **Mixing PK + browser-extension fields.** Discriminated union — don't `as`.
|
|
34
34
|
|
|
35
35
|
## Migration workflow (port v1 → v2)
|
|
36
36
|
|
|
37
|
-
1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md) — headline: **v1 code drops in unchanged
|
|
38
|
-
2.
|
|
39
|
-
3.
|
|
37
|
+
1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md) — headline: **private-key v1 code drops in nearly unchanged; browser-extension code does not**.
|
|
38
|
+
2. **Browser-extension mode must be rewritten**: `{ client, wallet, account }` → `{ grpcUrl, address, signTransaction }`, and the endpoint must speak gRPC-web. `rpcUrl` survives as a deprecated alias for `grpcUrl`; `SuiSignAndExecutePolicy.response` is gone. See [`../integration/knowledge/features/sui.md`](../integration/knowledge/features/sui.md) for the new config and the signer wrapper.
|
|
39
|
+
3. Otherwise mechanical: deep-import → barrel ([`../migration-v1-to-v2/knowledge/breaking-changes/folder-layout.md`](../migration-v1-to-v2/knowledge/breaking-changes/folder-layout.md)). Optionally adopt `defaults` ([`defaults-config.md`](../migration-v1-to-v2/knowledge/breaking-changes/defaults-config.md)) / re-imported library types ([`library-exports.md`](../migration-v1-to-v2/knowledge/breaking-changes/library-exports.md)).
|
|
40
|
+
4. Compile errors on `@sodax/sdk` / `@sodax/types` symbols → not this migration; load the `sodax-sdk` skill (migration mode).
|
|
40
41
|
|
|
41
42
|
## Verification
|
|
42
43
|
|
|
43
44
|
1. `pnpm tsc --noEmit` exits clean.
|
|
44
|
-
2. Config uses exactly one discriminant variant; browser-extension passes
|
|
45
|
+
2. Config uses exactly one discriminant variant; browser-extension passes `grpcUrl` + `address` + a wrapped `signTransaction`.
|
|
45
46
|
3. No v1 deep imports from `@sodax/wallet-sdk-core/wallet-providers/` (migration only).
|
|
46
47
|
|
|
47
48
|
## Related skills (same family)
|
|
@@ -112,7 +112,7 @@ If a project has both v1 patterns AND a request for new features: **migration fi
|
|
|
112
112
|
1. **`useXWagmiStore` removed from the public API.** v2 does **not** export the store hook at all — neither `useXWagmiStore` nor `useXWalletStore` is available from the package barrel. Replace each `useXWagmiStore(state => state.X)` selector with the matching public hook (`useXServices`, `useXService({ xChainType })`, `useXConnections`, `useXConnection({ xChainType })`, etc.). See [`migration-v1-to-v2/knowledge/reference/imports.md`](./migration-v1-to-v2/knowledge/reference/imports.md) § "Store hook removed from the public API" for the full field-to-hook map and a STOP decision tree for selectors hitting v2-internal fields. The localStorage persistence key `'xwagmi-store'` is unchanged, so user connections survive the upgrade.
|
|
113
113
|
2. **Hook args unified to a single object.** v1 hooks took positional args; v2 hooks take `{ xChainType }` or `{ xChainId }` (mutually exclusive on `useXAccount` / `useWalletProvider`).
|
|
114
114
|
3. **`SodaxWalletProvider` props.** v1's `rpcConfig`, `options`, `initialState` props are removed. v2 takes one `config: SodaxWalletConfig` prop where top-level keys are `ChainType` slots (`EVM`, `SOLANA`, `SUI`, …). The old `chains: { EVM, SOLANA, ... }` wrapper is also gone — chain-type slots are now top-level.
|
|
115
|
-
4. **Per-chain entry shape varies.** EVM/SOLANA/
|
|
115
|
+
4. **Per-chain entry shape varies.** EVM/SOLANA/ICON/NEAR use `{ rpcUrl?, defaults? }`; SUI uses `{ grpcUrl?, defaults? }` (`rpcUrl` is a deprecated alias, and the two are mutually exclusive); BITCOIN/STELLAR/INJECTIVE extend their `*RpcConfig` with `{ defaults? }`; STACKS accepts a preset name or `StacksNetworkLike & { defaults? }`.
|
|
116
116
|
|
|
117
117
|
### Stop conditions (defer to user)
|
|
118
118
|
|
|
@@ -21,12 +21,12 @@ cat <user>/package.json | grep '"react"'
|
|
|
21
21
|
cat <user>/package.json | grep '"@tanstack/react-query'
|
|
22
22
|
|
|
23
23
|
# Existing wallet libraries that may conflict
|
|
24
|
-
grep -l "wagmi\|@solana/wallet-adapter\|@mysten/dapp-kit" <user>/package.json
|
|
24
|
+
grep -l "wagmi\|@solana/wallet-adapter\|@mysten/dapp-kit-react" <user>/package.json
|
|
25
25
|
```
|
|
26
26
|
|
|
27
27
|
**If React < 19**, stop and tell the user — this package requires React 19.
|
|
28
28
|
|
|
29
|
-
**If wagmi / @solana/wallet-adapter / @mysten/dapp-kit are already direct dependencies**, stop and ask the user — this package mounts those internally; running both will cause duplicate provider context errors.
|
|
29
|
+
**If wagmi / @solana/wallet-adapter / @mysten/dapp-kit-react are already direct dependencies**, stop and ask the user — this package mounts those internally; running both will cause duplicate provider context errors.
|
|
30
30
|
|
|
31
31
|
### 2. Always start with `setup.md`
|
|
32
32
|
|
|
@@ -8,7 +8,7 @@ If you are looking for "how do I do X", go to [`recipes/`](./recipes/). This fil
|
|
|
8
8
|
|
|
9
9
|
## The shape of the package
|
|
10
10
|
|
|
11
|
-
`@sodax/wallet-sdk-react` is a **uniform React layer over heterogeneous chain wallet libraries**. Each chain family ships a different React adapter (wagmi, `@solana/wallet-adapter-react`, `@mysten/dapp-kit`) or no React adapter at all (Bitcoin, Stellar, ICON, Injective, NEAR, Stacks). The package wraps all nine families behind one set of hooks so consumer code does not branch on chain family.
|
|
11
|
+
`@sodax/wallet-sdk-react` is a **uniform React layer over heterogeneous chain wallet libraries**. Each chain family ships a different React adapter (wagmi, `@solana/wallet-adapter-react`, `@mysten/dapp-kit-react`) or no React adapter at all (Bitcoin, Stellar, ICON, Injective, NEAR, Stacks). The package wraps all nine families behind one set of hooks so consumer code does not branch on chain family.
|
|
12
12
|
|
|
13
13
|
Two abstractions make this work:
|
|
14
14
|
|
|
@@ -81,7 +81,7 @@ For wagmi cookie hydration in App Router, also see [`recipes/ssr-setup.md`](../.
|
|
|
81
81
|
|---|---|---|
|
|
82
82
|
| `EVM` | ✅ wagmi | One connection across every configured EVM chain. WalletConnect opt-in via `EVM.walletConnect.projectId`. |
|
|
83
83
|
| `SOLANA` | ✅ `@solana/wallet-adapter-react` | `autoConnect` defaults to `true`. |
|
|
84
|
-
| `SUI` | ✅ `@mysten/dapp-kit` | `network` defaults to `'mainnet'`. |
|
|
84
|
+
| `SUI` | ✅ `@mysten/dapp-kit-react` | `network` defaults to `'mainnet'`. |
|
|
85
85
|
| `BITCOIN` / `STELLAR` / `ICON` / `INJECTIVE` / `NEAR` / `STACKS` | ❌ no React adapter | Service auto-registered at mount. Connector list shipped per chain. |
|
|
86
86
|
|
|
87
87
|
For chain key constants and per-chain entry shapes, see [`../reference/chain-support.md`](../reference/chain-support.md).
|
|
@@ -37,7 +37,7 @@ Return type is the discriminated union `` `0x${string}` | Uint8Array | string |
|
|
|
37
37
|
|-------|----------------|-----------------|
|
|
38
38
|
| EVM | `signMessageAsync` from wagmi → personal_sign | `` `0x${string}` `` |
|
|
39
39
|
| Solana | `signMessage` from `@solana/wallet-adapter` | `string` (base64) |
|
|
40
|
-
| Sui | `signPersonalMessage` from `@mysten/dapp-kit` | `string` (base64 signature) |
|
|
40
|
+
| Sui | `signPersonalMessage` from `@mysten/dapp-kit-react` | `string` (base64 signature) |
|
|
41
41
|
| Bitcoin | Auto-detect: BIP-322 (P2WPKH/P2TR) or ECDSA (P2SH/P2PKH) | `string` |
|
|
42
42
|
| Stellar | `walletsKit.signMessage` from `@creit.tech/stellar-wallets-kit` | `string` (base64) |
|
|
43
43
|
| Injective | `walletStrategy.signArbitrary` from `@injectivelabs/wallet-base` | `string` |
|
|
@@ -10,9 +10,9 @@ 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
|
-
| `SUI` | Sui mainnet/testnet | `@mysten/dapp-kit` |
|
|
15
|
+
| `SUI` | Sui mainnet/testnet | `@mysten/dapp-kit-react` |
|
|
16
16
|
| `BITCOIN` | Bitcoin mainnet | (none — direct extension probes) |
|
|
17
17
|
| `STELLAR` | Stellar mainnet | (none) |
|
|
18
18
|
| `ICON` | ICON mainnet | (none) |
|
|
@@ -30,7 +30,7 @@ EVM is the only family with multiple networks under one connection — wagmi mai
|
|
|
30
30
|
|---|---|---|
|
|
31
31
|
| `EVM` | `ssr?, reconnectOnMount?, initialState?, walletConnect?, connectors?, chains` | `chains` keyed by `ChainKey` → `{ rpcUrl?, defaults? }` |
|
|
32
32
|
| `SOLANA` | `autoConnect?, connectors?, chains` | `chains` keyed by `ChainKey` → `{ rpcUrl?, defaults? }` |
|
|
33
|
-
| `SUI` | `network?, connectors?, chains?` | `network: 'mainnet' \| 'testnet'
|
|
33
|
+
| `SUI` | `network?, connectors?, chains?` | `network: 'mainnet' \| 'testnet'` |
|
|
34
34
|
| `BITCOIN` | extends `BitcoinRpcConfig` + `{ defaults?, connectors? }` | Pass `{}` for SDK defaults |
|
|
35
35
|
| `STELLAR` | extends `StellarRpcConfig` + `{ defaults?, connectors? }` | Pass `{}` for SDK defaults |
|
|
36
36
|
| `INJECTIVE` | extends `InjectiveRpcConfig` + `{ defaults?, connectors? }` | Pass `{}` for SDK defaults |
|
|
@@ -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
|
|
|
@@ -27,7 +27,7 @@ What did NOT change → [bottom of file](#what-did-not-change).
|
|
|
27
27
|
|
|
28
28
|
v1 spread chain configuration across **three separate props**: `rpcConfig` (per-chain RPC URLs), `options` (per-adapter options like `wagmi.ssr`, `solana.autoConnect`, `sui.autoConnect`), and `initialState` (wagmi state for SSR hydration).
|
|
29
29
|
|
|
30
|
-
v2 collapses all three into a **single `config` prop** of type `SodaxWalletConfig`. The new shape uses **chain-type slots** (`EVM`, `SOLANA`, `SUI`, `BITCOIN`, `STELLAR`, `ICON`, `INJECTIVE`, `NEAR`, `STACKS`) at the top level. Each slot is `ChainTypeConfig<T>` — adapter options merged with `{ chains?, connectors? }` where `chains` is keyed by `ChainKey` and holds per-chain `{ rpcUrl?, defaults? }
|
|
30
|
+
v2 collapses all three into a **single `config` prop** of type `SodaxWalletConfig`. The new shape uses **chain-type slots** (`EVM`, `SOLANA`, `SUI`, `BITCOIN`, `STELLAR`, `ICON`, `INJECTIVE`, `NEAR`, `STACKS`) at the top level. Each slot is `ChainTypeConfig<T>` — adapter options merged with `{ chains?, connectors? }` where `chains` is keyed by `ChainKey` and holds per-chain `{ rpcUrl?, defaults? }` — except `SUI`, whose entry is `{ grpcUrl?, defaults? }` with `rpcUrl` kept as a deprecated alias.
|
|
31
31
|
|
|
32
32
|
### Why
|
|
33
33
|
|
|
@@ -140,7 +140,7 @@ See [`reference/imports.md`](./reference/imports.md) for the sub-path map per ch
|
|
|
140
140
|
|
|
141
141
|
### What changed
|
|
142
142
|
|
|
143
|
-
v1 mounted **every** chain adapter (wagmi, `@solana/wallet-adapter`, `@mysten/dapp-kit`) and registered services for every chain regardless of whether the consumer used them.
|
|
143
|
+
v1 mounted **every** chain adapter (wagmi, `@solana/wallet-adapter`, `@mysten/dapp-kit-react`) and registered services for every chain regardless of whether the consumer used them.
|
|
144
144
|
|
|
145
145
|
v2 mounts only the slots present in `walletConfig`. An app that only needs EVM + Sui passes `{ EVM: {...}, SUI: {...} }` and ships **none** of the Solana / Bitcoin / NEAR adapter code in the React tree.
|
|
146
146
|
|
|
@@ -57,7 +57,7 @@ These are mounted **inside** `SodaxWalletProvider` and are not part of the publi
|
|
|
57
57
|
| Component | v1 | v2 | Note |
|
|
58
58
|
|---|---|---|---|
|
|
59
59
|
| `Hydrate` | exported (file `Hydrate.ts`) | replaced by per-chain `EvmHydrator`, `SolanaHydrator`, `SuiHydrator` (internal) | If you imported `Hydrate` from v1, **remove the import** — v2 does not export an equivalent. State hydration is automatic. |
|
|
60
|
-
| `WagmiProvider`, `SuiClientProvider`, `SolanaWalletProvider` (re-exports) | not re-exported | not re-exported | Use the original packages (`wagmi`, `@mysten/dapp-kit`, `@solana/wallet-adapter-react`) only if you need direct access — most apps should not. |
|
|
60
|
+
| `WagmiProvider`, `SuiClientProvider`, `SolanaWalletProvider` (re-exports) | not re-exported | not re-exported | Use the original packages (`wagmi`, `@mysten/dapp-kit-react`, `@solana/wallet-adapter-react`) only if you need direct access — most apps should not. |
|
|
61
61
|
|
|
62
62
|
---
|
|
63
63
|
|
|
@@ -98,7 +98,8 @@ const walletConfig: SodaxWalletConfig = {
|
|
|
98
98
|
|
|
99
99
|
| Slot | Per-chain entry |
|
|
100
100
|
|---|---|
|
|
101
|
-
| `EVM`, `SOLANA`, `
|
|
101
|
+
| `EVM`, `SOLANA`, `ICON`, `NEAR` | `{ rpcUrl?, defaults? }` |
|
|
102
|
+
| `SUI` | `{ grpcUrl?, defaults? }` — `rpcUrl` is a deprecated alias; pass one or the other, never both |
|
|
102
103
|
| `BITCOIN`, `STELLAR`, `INJECTIVE` | extends their `*RpcConfig` type with `{ defaults? }` |
|
|
103
104
|
| `STACKS` | preset name (string) **or** `StacksNetworkLike & { defaults? }` |
|
|
104
105
|
|
|
@@ -187,7 +188,7 @@ SUI: {
|
|
|
187
188
|
| Field | Type | Default |
|
|
188
189
|
|---|---|---|
|
|
189
190
|
| `autoConnect` | `boolean?` | `true` |
|
|
190
|
-
| `network` | `'mainnet' \| 'testnet'
|
|
191
|
+
| `network` | `'mainnet' \| 'testnet'?` | `'mainnet'` |
|
|
191
192
|
|
|
192
193
|
| v1 | v2 |
|
|
193
194
|
|---|---|
|