@sodax/skills 2.1.0-rc.6 → 2.1.0-rc.7

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.
Files changed (24) hide show
  1. package/package.json +2 -2
  2. package/skills/sodax-sdk/integration/knowledge/chain-specifics.md +1 -1
  3. package/skills/sodax-wallet-sdk-core/integration/knowledge/README.md +1 -1
  4. package/skills/sodax-wallet-sdk-core/integration/knowledge/architecture.md +0 -2
  5. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/README.md +1 -1
  6. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/sui.md +18 -11
  7. package/skills/sodax-wallet-sdk-core/integration/knowledge/quickstart.md +9 -5
  8. package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/library-exports.md +0 -5
  9. package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/setup-browser-extension.md +3 -2
  10. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/chain-support.md +1 -1
  11. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/public-api.md +0 -1
  12. package/skills/sodax-wallet-sdk-core/migration-v1-to-v2/knowledge/breaking-changes/library-exports.md +0 -1
  13. package/skills/sodax-wallet-sdk-core/migration-v1-to-v2/knowledge/recipes/adopt-library-exports.md +0 -4
  14. package/skills/sodax-wallet-sdk-core/migration-v1-to-v2/knowledge/reference/added-fields.md +1 -2
  15. package/skills/sodax-wallet-sdk-core/sui/SKILL.md +9 -8
  16. package/skills/sodax-wallet-sdk-react/SKILL.md +1 -1
  17. package/skills/sodax-wallet-sdk-react/integration/knowledge/ai-rules.md +2 -2
  18. package/skills/sodax-wallet-sdk-react/integration/knowledge/architecture.md +1 -1
  19. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/setup.md +1 -1
  20. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/sign-message.md +1 -1
  21. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/chain-support.md +2 -2
  22. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/breaking-changes.md +2 -2
  23. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/reference/components.md +1 -1
  24. 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.6",
7
+ "version": "2.1.0-rc.7",
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": ">=20.0.0"
27
+ "node": ">=22.12.0"
28
28
  },
29
29
  "files": [
30
30
  ".claude-plugin",
@@ -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
 
@@ -20,7 +20,7 @@ It is intentionally framework-agnostic — Node ≥ 20.12, browser, edge runtime
20
20
  |---|---|---|
21
21
  | EVM (13 chains) | `EvmWalletProvider` | `viem` |
22
22
  | Solana | `SolanaWalletProvider` | `@solana/web3.js` |
23
- | Sui | `SuiWalletProvider` | `@mysten/sui` + `@mysten/wallet-standard` |
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` + `@mysten/wallet-standard` |
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` and `@mysten/wallet-standard`.
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`, `@mysten/wallet-standard` |
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
- rpcUrl: string;
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
- client: SuiClient; // pre-built by consumer
27
- wallet: WalletWithFeatures<Partial<SuiWalletFeatures>>;
28
- account: WalletAccount; // active account from wallet
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 | `'wallet' in config && 'account' in config` |
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: SuiClient` and `wallet: SuiWallet` are private.
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 requires THREE objects.** Many wallet adapters expose `client` + `wallet` but not the active `account`. Fetch it via `wallet.accounts[0]` or your adapter's "current account" API before constructing the provider.
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
- - **`response` options forward to the underlying SuiClient call.** In PK mode that's `signAndExecuteTransaction`; in browser-extension mode it's `executeTransactionBlock`. Same option shape (`SuiTransactionBlockResponseOptions`).
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
 
@@ -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
- rpcUrl: 'https://sui-rpc.publicnode.com',
87
+ grpcUrl: 'https://fullnode.mainnet.sui.io',
88
88
  mnemonics: 'word1 word2 … word12',
89
89
  });
90
90
 
91
- // Browser-extension — wallet-standard wallet
91
+ // Browser-extension — the provider owns the client; you supply the signer
92
92
  const suiBrowser = new SuiWalletProvider({
93
- client: mySuiClient, // SuiClient
94
- wallet: myWalletWithSuiFeatures, // WalletWithFeatures<Partial<SuiWalletFeatures>>
95
- account: myActiveWalletAccount, // WalletAccount
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,
@@ -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 | `client` (`SuiClient`) + `wallet` (`WalletWithFeatures<Partial<SuiWalletFeatures>>`) + `account` (`WalletAccount`) |
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
- | `WalletAccount is undefined` (Sui) | Adapter exposes `wallet` but not the active `account` | Read `wallet.accounts[0]` or your adapter's "current account" API before constructing. |
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
 
@@ -51,7 +51,7 @@ Run-time deps each provider pulls in. See [`../recipes/library-exports.md`](../r
51
51
  |---|---|
52
52
  | `EvmWalletProvider` | `viem` |
53
53
  | `SolanaWalletProvider` | `@solana/web3.js`, `@solana/spl-token`, `@solana/wallet-adapter-base` |
54
- | `SuiWalletProvider` | `@mysten/sui`, `@mysten/wallet-standard` |
54
+ | `SuiWalletProvider` | `@mysten/sui` |
55
55
  | `BitcoinWalletProvider` | `bitcoinjs-lib`, `ecpair`, `secp256k1`, `@bitcoinerlab/secp256k1`, `bip322-js` |
56
56
  | `StellarWalletProvider` | `@stellar/stellar-sdk` |
57
57
  | `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
  ```
@@ -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** — `SuiTransactionBlockResponseOptions`, `Transaction`, `TransactionArgument`
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 + @mysten/wallet-standard). 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 — 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).'
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 (almost always a no-op here).
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 = `{ rpcUrl, mnemonics }`; browser-extension = `{ client, wallet, account }` (all THREE required). Mutually exclusive — pick one.
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
- - **Forgetting the active `account` in browser-extension mode.** It needs all three of `client` + `wallet` + `account`; many adapters expose the first two but not the active account (fetch via `wallet.accounts[0]`).
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 at this surface**.
38
- 2. Only mechanical change: 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)).
39
- 3. Compile errors on `@sodax/sdk` / `@sodax/types` symbols → not this migration; load the `sodax-sdk` skill (migration mode).
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 all three objects.
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/SUI/ICON/NEAR use `{ rpcUrl?, defaults? }`; BITCOIN/STELLAR/INJECTIVE extend their `*RpcConfig` with `{ defaults? }`; STACKS accepts a preset name or `StacksNetworkLike & { defaults? }`.
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` |
@@ -12,7 +12,7 @@ Chains supported by `@sodax/wallet-sdk-react` v2 — their `ChainType` family an
12
12
  |---|---|---|
13
13
  | `EVM` | Sonic, Ethereum, Arbitrum, Base, BSC, Optimism, Polygon, Avalanche, HyperEVM, Lightlink, Redbelly, Kaia, Hedera | 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' \| 'devnet'` |
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 |
@@ -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`, `SUI`, `ICON`, `NEAR` | `{ rpcUrl?, defaults? }` |
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' \| 'devnet'?` | `'mainnet'` |
191
+ | `network` | `'mainnet' \| 'testnet'?` | `'mainnet'` |
191
192
 
192
193
  | v1 | v2 |
193
194
  |---|---|