@sodax/skills 2.0.0-rc.9 → 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -9
- package/AGENTS.md +119 -14
- package/README.md +5 -2
- package/package.json +1 -1
- package/skills/sodax-build/SKILL.md +90 -0
- package/skills/sodax-build/knowledge/README.md +35 -0
- package/skills/sodax-build/knowledge/brief-template.md +41 -0
- package/skills/sodax-build/knowledge/chains-and-assets.md +26 -0
- package/skills/sodax-build/knowledge/example-sessions.md +84 -0
- package/skills/sodax-build/knowledge/feature-catalog.md +51 -0
- package/skills/sodax-build/knowledge/glossary.md +35 -0
- package/skills/sodax-build/knowledge/handoff.md +60 -0
- package/skills/sodax-build/knowledge/interview-guide.md +66 -0
- package/skills/sodax-build/knowledge/monetization.md +37 -0
- package/skills/sodax-build/knowledge/use-case-gallery.md +32 -0
- package/skills/sodax-dapp-kit/SKILL.md +6 -2
- package/skills/sodax-dapp-kit/auxiliary-services/SKILL.md +65 -0
- package/skills/sodax-dapp-kit/bitcoin/SKILL.md +57 -0
- package/skills/sodax-dapp-kit/bridge/SKILL.md +59 -0
- package/skills/sodax-dapp-kit/dex/SKILL.md +60 -0
- package/skills/sodax-dapp-kit/integration/knowledge/README.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/features/README.md +3 -2
- package/skills/sodax-dapp-kit/integration/knowledge/features/auxiliary-services.md +71 -11
- package/skills/sodax-dapp-kit/integration/knowledge/features/bitcoin.md +10 -6
- package/skills/sodax-dapp-kit/integration/knowledge/features/dex.md +2 -2
- package/skills/sodax-dapp-kit/integration/knowledge/features/leverage-yield.md +112 -0
- package/skills/sodax-dapp-kit/integration/knowledge/features/money-market.md +6 -1
- package/skills/sodax-dapp-kit/integration/knowledge/features/swap.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/quickstart.md +2 -2
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/README.md +1 -0
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/backend-queries.md +23 -8
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/bitcoin.md +8 -8
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/leverage-yield.md +168 -0
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/migration.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/setup.md +4 -4
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/swap.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/wallet-connectivity.md +3 -0
- package/skills/sodax-dapp-kit/integration/knowledge/reference/glossary.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md +67 -6
- package/skills/sodax-dapp-kit/integration/knowledge/reference/querykey-conventions.md +49 -0
- package/skills/sodax-dapp-kit/leverage-yield/SKILL.md +54 -0
- package/skills/sodax-dapp-kit/migration/SKILL.md +64 -0
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md +1 -1
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md +2 -2
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/checklist.md +1 -1
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/README.md +1 -1
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/auxiliary-services.md +19 -10
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/bitcoin.md +2 -2
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/bridge.md +1 -1
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/dex.md +1 -1
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/reference/renamed-hooks.md +3 -3
- package/skills/sodax-dapp-kit/money-market/SKILL.md +61 -0
- package/skills/sodax-dapp-kit/staking/SKILL.md +60 -0
- package/skills/sodax-dapp-kit/swap/SKILL.md +64 -0
- package/skills/sodax-sdk/SKILL.md +11 -6
- package/skills/sodax-sdk/backend-api/SKILL.md +21 -15
- package/skills/sodax-sdk/bridge/SKILL.md +4 -0
- package/skills/sodax-sdk/dex/SKILL.md +5 -1
- package/skills/sodax-sdk/integration/knowledge/README.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/ai-rules.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/architecture.md +24 -21
- package/skills/sodax-sdk/integration/knowledge/chain-specifics.md +57 -10
- package/skills/sodax-sdk/integration/knowledge/features/README.md +2 -1
- package/skills/sodax-sdk/integration/knowledge/features/backend-api.md +27 -16
- package/skills/sodax-sdk/integration/knowledge/features/bridge.md +15 -14
- package/skills/sodax-sdk/integration/knowledge/features/dex.md +7 -7
- package/skills/sodax-sdk/integration/knowledge/features/leverage-yield.md +175 -0
- package/skills/sodax-sdk/integration/knowledge/features/migration.md +73 -28
- package/skills/sodax-sdk/integration/knowledge/features/money-market.md +20 -25
- package/skills/sodax-sdk/integration/knowledge/features/partner.md +27 -4
- package/skills/sodax-sdk/integration/knowledge/features/recovery.md +5 -4
- package/skills/sodax-sdk/integration/knowledge/features/staking.md +2 -2
- package/skills/sodax-sdk/integration/knowledge/features/swap.md +42 -24
- package/skills/sodax-sdk/integration/knowledge/features/swaps-api.md +171 -0
- package/skills/sodax-sdk/integration/knowledge/quickstart.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/recipes/README.md +1 -0
- package/skills/sodax-sdk/integration/knowledge/recipes/backend-server-init.md +3 -3
- package/skills/sodax-sdk/integration/knowledge/recipes/gas-estimation.md +8 -4
- package/skills/sodax-sdk/integration/knowledge/recipes/initialize-sodax.md +34 -2
- package/skills/sodax-sdk/integration/knowledge/recipes/logging.md +102 -0
- package/skills/sodax-sdk/integration/knowledge/recipes/raw-tx-flow.md +28 -4
- package/skills/sodax-sdk/integration/knowledge/recipes/result-and-errors.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/recipes/testing.md +7 -11
- package/skills/sodax-sdk/integration/knowledge/reference/README.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/reference/chain-keys.md +40 -4
- package/skills/sodax-sdk/integration/knowledge/reference/error-codes.md +32 -9
- package/skills/sodax-sdk/integration/knowledge/reference/glossary.md +2 -2
- package/skills/sodax-sdk/integration/knowledge/reference/public-api.md +37 -4
- package/skills/sodax-sdk/leverage-yield/SKILL.md +50 -0
- package/skills/sodax-sdk/migration/SKILL.md +5 -1
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/README.md +1 -1
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/ai-rules.md +1 -1
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/architecture.md +2 -2
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/result-and-errors.md +3 -3
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/type-system.md +6 -5
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/checklist.md +1 -1
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/backend-api.md +23 -23
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/bridge.md +5 -5
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/dex.md +2 -4
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/migration.md +29 -27
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/money-market.md +2 -2
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/partner.md +10 -5
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/recovery.md +2 -2
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/staking.md +2 -2
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/swap.md +22 -18
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/reference/sodax-config.md +18 -16
- package/skills/sodax-sdk/money-market/SKILL.md +7 -3
- package/skills/sodax-sdk/partner/SKILL.md +4 -0
- package/skills/sodax-sdk/recovery/SKILL.md +5 -1
- package/skills/sodax-sdk/staking/SKILL.md +4 -0
- package/skills/sodax-sdk/swap/SKILL.md +8 -3
- package/skills/sodax-sdk/swaps-api/SKILL.md +62 -0
- package/skills/sodax-wallet-sdk-core/SKILL.md +7 -3
- package/skills/sodax-wallet-sdk-core/bitcoin/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/evm/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/icon/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/injective/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/integration/knowledge/README.md +1 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/ai-rules.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/architecture.md +5 -5
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/bitcoin.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/evm.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/icon.md +5 -5
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/injective.md +4 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/near.md +1 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/solana.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/stacks.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/stellar.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/sui.md +1 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/quickstart.md +1 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/setup-private-key.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/sign-and-broadcast.md +1 -0
- package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/testing.md +1 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/chain-support.md +3 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/interfaces.md +7 -5
- package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/provider-classes.md +2 -2
- package/skills/sodax-wallet-sdk-core/migration-v1-to-v2/knowledge/README.md +1 -1
- package/skills/sodax-wallet-sdk-core/near/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/solana/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/stacks/SKILL.md +53 -0
- package/skills/sodax-wallet-sdk-core/stellar/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/sui/SKILL.md +53 -0
- package/skills/sodax-wallet-sdk-react/SKILL.md +5 -3
- package/skills/sodax-wallet-sdk-react/bridge-to-sdk/SKILL.md +56 -0
- package/skills/sodax-wallet-sdk-react/connect/SKILL.md +59 -0
- package/skills/sodax-wallet-sdk-react/integration/knowledge/architecture.md +3 -3
- package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/chain-detection.md +1 -1
- package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/connect-button.md +1 -1
- package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/sign-message.md +10 -10
- package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/switch-chain.md +1 -1
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/api-surface.md +4 -4
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/chain-support.md +4 -4
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/connectors.md +1 -1
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/hooks.md +5 -4
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/wallet-brands.md +1 -1
- package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/ai-rules.md +1 -1
- package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/recipes/multi-chain-modal.md +57 -31
- package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/recipes/ssr-setup.md +24 -19
- package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/reference/config.md +1 -1
- package/skills/sodax-wallet-sdk-react/sign-message/SKILL.md +51 -0
- package/skills/sodax-wallet-sdk-react/switch-chain/SKILL.md +51 -0
- package/skills/sodax-wallet-sdk-react/wallet-modal/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-react/walletconnect/SKILL.md +52 -0
|
@@ -25,9 +25,9 @@ const signature = await sign.mutateAsync({
|
|
|
25
25
|
| `xChainType` | `ChainType` | Which chain to sign with (`'EVM'`, `'BITCOIN'`, …) |
|
|
26
26
|
| `message` | `string` | Plain UTF-8; per-chain wrappers handle encoding |
|
|
27
27
|
|
|
28
|
-
Return type is the discriminated union `` `0x${string}` | Uint8Array | string | undefined `` because each chain returns its native signature shape (hex for EVM, base64 for Stellar
|
|
28
|
+
Return type is the discriminated union `` `0x${string}` | Uint8Array | string | undefined `` because each chain returns its native signature shape (hex for EVM, base64 for Stellar and Solana, etc.). Cast or branch on `xChainType` when consuming.
|
|
29
29
|
|
|
30
|
-
`undefined` is returned (not thrown) when the chain doesn't implement `signMessage` —
|
|
30
|
+
`undefined` is returned (not thrown) when the chain doesn't implement `signMessage` — ICON, NEAR, and Stacks. A one-time `console.warn` accompanies the `undefined`.
|
|
31
31
|
|
|
32
32
|
---
|
|
33
33
|
|
|
@@ -36,13 +36,13 @@ Return type is the discriminated union `` `0x${string}` | Uint8Array | string |
|
|
|
36
36
|
| Chain | Implementation | Signature shape |
|
|
37
37
|
|-------|----------------|-----------------|
|
|
38
38
|
| EVM | `signMessageAsync` from wagmi → personal_sign | `` `0x${string}` `` |
|
|
39
|
-
| Solana | `signMessage` from `@solana/wallet-adapter` | `
|
|
40
|
-
| Sui | `signPersonalMessage` from `@mysten/dapp-kit` | `string` (base64 signature
|
|
39
|
+
| Solana | `signMessage` from `@solana/wallet-adapter` | `string` (base64) |
|
|
40
|
+
| Sui | `signPersonalMessage` from `@mysten/dapp-kit` | `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` |
|
|
44
|
-
| NEAR |
|
|
45
|
-
| Stacks | `signMessage`
|
|
44
|
+
| **NEAR** | **Not supported** — registers no `signMessage` action | `undefined` |
|
|
45
|
+
| **Stacks** | **Not supported** — registers no `signMessage` action | `undefined` |
|
|
46
46
|
| **ICON** | **Not supported** — Hana wallet does not expose a signing API | `undefined` |
|
|
47
47
|
|
|
48
48
|
---
|
|
@@ -53,10 +53,10 @@ Bitcoin's signing flow inspects the connected address and picks the right method
|
|
|
53
53
|
|
|
54
54
|
| Address type | Signing method | Connectors that support it |
|
|
55
55
|
|--------------|----------------|----------------------------|
|
|
56
|
-
| P2WPKH (native segwit, `bc1q…`) | BIP-322 | Unisat, Xverse, OKX |
|
|
57
|
-
| P2TR (taproot, `bc1p…`) | BIP-322 | Unisat, Xverse, OKX |
|
|
58
|
-
| P2SH (legacy multi-sig, `3…`) | ECDSA | Unisat, Xverse, OKX |
|
|
59
|
-
| P2PKH (legacy, `1…`) | ECDSA | Unisat, Xverse, OKX |
|
|
56
|
+
| P2WPKH (native segwit, `bc1q…`) | BIP-322 | Unisat, Xverse, OKX, Hana |
|
|
57
|
+
| P2TR (taproot, `bc1p…`) | BIP-322 | Unisat, Xverse, OKX, Hana |
|
|
58
|
+
| P2SH (legacy multi-sig, `3…`) | ECDSA | Unisat, Xverse, OKX, Hana |
|
|
59
|
+
| P2PKH (legacy, `1…`) | ECDSA | Unisat, Xverse, OKX, Hana |
|
|
60
60
|
|
|
61
61
|
If a custom connector implements only one of the two methods, calling `signMessage` from a wrongly-typed address surfaces the error inline.
|
|
62
62
|
|
|
@@ -121,7 +121,7 @@ Keplr and Leap on Injective don't have this constraint — `isWrongChain` is `fa
|
|
|
121
121
|
|
|
122
122
|
## Safe to call when EVM is disabled
|
|
123
123
|
|
|
124
|
-
`useEvmSwitchChain` checks `
|
|
124
|
+
`useEvmSwitchChain` checks `useIsChainEnabled('EVM')` and returns a no-op result `{ isWrongChain: false, handleSwitchChain: () => {} }` when the EVM slot isn't mounted in `SodaxWalletProvider` config. Calling wagmi's hooks outside a `WagmiProvider` would throw — the early-return lets components opt-in to a "switch chain" CTA without checking EVM-enabled themselves at every call site.
|
|
125
125
|
|
|
126
126
|
---
|
|
127
127
|
|
|
@@ -112,7 +112,7 @@ Concrete chain classes live behind sub-paths. Default to barrel imports; opt int
|
|
|
112
112
|
|
|
113
113
|
### Default pattern (most chains)
|
|
114
114
|
|
|
115
|
-
`/xchains/{bitcoin, evm, icon, injective, near, solana, stacks, sui}` re-export the chain's `XService` + `XConnector` classes — `EvmXService`/`EvmXConnector`, `SolanaXService`/`SolanaXConnector`, `BitcoinXService`/`BitcoinXConnector`, `StacksXService`/`StacksXConnector`, etc. Icon also exports `IconHanaXConnector` (the connector for the Hana wallet).
|
|
115
|
+
`/xchains/{bitcoin, evm, icon, injective, near, solana, stacks, stellar, sui}` re-export the chain's `XService` + `XConnector` classes — `EvmXService`/`EvmXConnector`, `SolanaXService`/`SolanaXConnector`, `BitcoinXService`/`BitcoinXConnector`, `StacksXService`/`StacksXConnector`, `StellarXService`/`StellarWalletsKitXConnector`, etc. Icon also exports `IconHanaXConnector` (the connector for the Hana wallet).
|
|
116
116
|
|
|
117
117
|
```ts
|
|
118
118
|
// @ai-snippets-skip
|
|
@@ -124,8 +124,8 @@ import { IconHanaXConnector } from '@sodax/wallet-sdk-react/xchains/icon';
|
|
|
124
124
|
|
|
125
125
|
| Sub-path | Beyond `XService`/`XConnector` |
|
|
126
126
|
|---|---|
|
|
127
|
-
| `/xchains/bitcoin` | `XverseXConnector`, `UnisatXConnector`, `OKXXConnector` (
|
|
128
|
-
| `/xchains/evm` | `createWagmiConfig` (function — also exported as alias `createWagmi`) |
|
|
127
|
+
| `/xchains/bitcoin` | `XverseXConnector`, `UnisatXConnector`, `OKXXConnector`, `BitcoinHanaXConnector` (4 wallet connectors), hook `useBitcoinXConnectors`, type `BtcWalletAddressType` |
|
|
128
|
+
| `/xchains/evm` | `createWagmiConfig` (function — also exported as alias `createWagmi`); `tryCookieToInitialState` (wraps wagmi's `cookieToInitialState` so a malformed SSR cookie yields `undefined` instead of throwing) |
|
|
129
129
|
| `/xchains/icon` | `CHAIN_INFO` (value), `SupportedChainId` (enum) |
|
|
130
130
|
| `/xchains/stacks` | `STACKS_PROVIDERS` (value), hook `useStacksXConnectors`, type `StacksProviderConfig` |
|
|
131
131
|
|
|
@@ -133,7 +133,7 @@ import { IconHanaXConnector } from '@sodax/wallet-sdk-react/xchains/icon';
|
|
|
133
133
|
|
|
134
134
|
| Sub-path | Notes |
|
|
135
135
|
|---|---|
|
|
136
|
-
| `/xchains/stellar` |
|
|
136
|
+
| `/xchains/stellar` | Re-exports `StellarXService` + `StellarWalletsKitXConnector` (the concrete connector wrapping `@creit.tech/stellar-wallets-kit`). |
|
|
137
137
|
|
|
138
138
|
If unsure what a sub-path exports, check the published `dist/`:
|
|
139
139
|
|
|
@@ -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 | wagmi |
|
|
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
15
|
| `SUI` | Sui mainnet/testnet | `@mysten/dapp-kit` |
|
|
16
16
|
| `BITCOIN` | Bitcoin mainnet | (none — direct extension probes) |
|
|
@@ -28,9 +28,9 @@ EVM is the only family with multiple networks under one connection — wagmi mai
|
|
|
28
28
|
|
|
29
29
|
| Slot | Config fields | Notes |
|
|
30
30
|
|---|---|---|
|
|
31
|
-
| `EVM` | `ssr?, walletConnect?, connectors?, chains` | `chains` keyed by `ChainKey` → `{ rpcUrl?, defaults? }` |
|
|
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' \| 'devnet'` |
|
|
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 13 entries (Sonic, Ethereum, Arbitrum, Base, BSC, Optimism, Polygon, Avalanche, HyperEVM, Lightlink, Redbelly, Kaia, Hedera); the other 8 families each have one. Inspect `@sodax/types` for the authoritative list.
|
|
60
60
|
|
|
61
61
|
---
|
|
62
62
|
|
|
@@ -37,7 +37,7 @@ const connectors = useXConnectors({ xChainType: 'EVM' });
|
|
|
37
37
|
// IXConnector[] — already filtered to enabled chain
|
|
38
38
|
```
|
|
39
39
|
|
|
40
|
-
For the per-chain class names (only needed for `instanceof` or custom-connector-list use cases), see [`api-surface.md`](./api-surface.md) § "Sub-path exports" and the worked example in [`../recipes/sub-path-imports.md`](../recipes/sub-path-imports.md). Bitcoin's `BitcoinXConnector` is the only abstract base — its concrete subclasses (Unisat, Xverse, OKX) override per-wallet signing methods (see [`sign-message.md`](../recipes/sign-message.md)).
|
|
40
|
+
For the per-chain class names (only needed for `instanceof` or custom-connector-list use cases), see [`api-surface.md`](./api-surface.md) § "Sub-path exports" and the worked example in [`../recipes/sub-path-imports.md`](../recipes/sub-path-imports.md). Bitcoin's `BitcoinXConnector` is the only abstract base — its concrete subclasses (Unisat, Xverse, OKX, Hana) override per-wallet signing methods (see [`sign-message.md`](../recipes/sign-message.md)).
|
|
41
41
|
|
|
42
42
|
---
|
|
43
43
|
|
|
@@ -21,9 +21,10 @@ Hooks do **not** throw when their chain isn't enabled — each picks its own no-
|
|
|
21
21
|
| `useEvmSwitchChain` | Returns `{ isWrongChain: false, handleSwitchChain: () => {} }` (no-op) |
|
|
22
22
|
| `useEnabledChains` | Returns the list of slots actually present (does not include the disabled one) |
|
|
23
23
|
| `useChainGroups`, `useConnectedChains` | Excludes the chain from output |
|
|
24
|
-
| `useXConnect
|
|
24
|
+
| `useXConnect` | Mutation rejects (throws) when invoked with an unsupported `xChainType` |
|
|
25
|
+
| `useXDisconnect`, `useXSignMessage` | Resolve (to `void` / `undefined`) with a `console.warn` — they do **not** reject |
|
|
25
26
|
|
|
26
|
-
Rule of thumb: read-hooks degrade silently
|
|
27
|
+
Rule of thumb: read-hooks and `useXDisconnect`/`useXSignMessage` degrade silently (empty / `undefined` + warning); only `useXConnect` rejects. All are safe to call unconditionally.
|
|
27
28
|
|
|
28
29
|
---
|
|
29
30
|
|
|
@@ -161,8 +162,8 @@ if (isWrongChain) handleSwitchChain();
|
|
|
161
162
|
|
|
162
163
|
| Hook | Signature | Returns |
|
|
163
164
|
|---|---|---|
|
|
164
|
-
| `useXService` | `useXService({ xChainType })` | `
|
|
165
|
-
| `useXServices` | `useXServices()` | `Partial<Record<ChainType,
|
|
165
|
+
| `useXService` | `useXService({ xChainType })` | `XService \| undefined` |
|
|
166
|
+
| `useXServices` | `useXServices()` | `Partial<Record<ChainType, XService>>` |
|
|
166
167
|
| `useEnabledChains` | `useEnabledChains()` | `ChainType[]` |
|
|
167
168
|
| `useInitChainServices` | (internal — handled by `SodaxWalletProvider`) | — |
|
|
168
169
|
|
|
@@ -10,7 +10,7 @@ The identifiers are **open**: any string works. The table below lists every bran
|
|
|
10
10
|
|
|
11
11
|
| Identifier | Chains it matches | Underlying connector id / name |
|
|
12
12
|
|---|---|---|
|
|
13
|
-
| `'hana'` | EVM, ICON, Sui, Stellar | EVM via EIP-6963 RDNS (e.g. `io.havah.hana`); ICON id `hana`; Sui/Stellar — connector names containing "Hana" |
|
|
13
|
+
| `'hana'` | EVM, ICON, Sui, Stellar, Bitcoin | EVM via EIP-6963 RDNS (e.g. `io.havah.hana`); ICON id `hana`; Bitcoin id `hana-bitcoin`; Sui/Stellar — connector names containing "Hana" |
|
|
14
14
|
| `'phantom'` | EVM, Solana | EVM RDNS `app.phantom`; Solana adapter name `Phantom` |
|
|
15
15
|
| `'metamask'` | EVM, Injective | EVM RDNS `io.metamask`; Injective `Wallet.Metamask` strategy |
|
|
16
16
|
| `'xverse'` | Bitcoin, Stacks | Bitcoin id `xverse`; Stacks id `XverseProviders.BitcoinProvider` |
|
|
@@ -99,7 +99,7 @@ Stop and ask the user before continuing if you encounter any of the following. T
|
|
|
99
99
|
| User reads from `useXWagmiStore` with a selector touching `setXConnection`, `unsetXConnection`, or any v2-internal field (`enabledChains`, `walletProviders`, `chainActions`, …) | These are not part of the v2 public API. Agent must replace direct store reads with public hooks (`useXServices`, `useXConnections`, etc. — see [`reference/imports.md`](./reference/imports.md) § "Store hook removed"). For mutations the user must adopt `useXConnect` / `useXDisconnect` — confirm before substituting. |
|
|
100
100
|
| User passes `rpcConfig`, `options`, or `initialState` to the v1 provider | These are removed in v2. Migration target is the new `config` object. Verify what behavior the user wants preserved. |
|
|
101
101
|
| Test files that mock `XService` or `XConnector` | Mock surface differs. Tests must be updated by hand with the user's intent in mind. |
|
|
102
|
-
|
|
|
102
|
+
| Code references internal SODAX example / scaffolding (not a published `@sodax/*` export) | Not part of the public API — don't port or depend on it. |
|
|
103
103
|
| User explicitly says "don't change behavior X" | Some v2 changes are intentional behavior shifts (e.g. EVM = single connection across all networks). Confirm before forcing v1 behavior back. |
|
|
104
104
|
|
|
105
105
|
When stopping, **quote the file/line** of the offending code and present the user with concrete options.
|
package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/recipes/multi-chain-modal.md
CHANGED
|
@@ -113,8 +113,11 @@ v2 ships these primitives so the consumer focuses only on UI rendering.
|
|
|
113
113
|
import {
|
|
114
114
|
useWalletModal,
|
|
115
115
|
useChainGroups,
|
|
116
|
+
useXConnectors,
|
|
116
117
|
sortConnectors,
|
|
118
|
+
type IXConnector,
|
|
117
119
|
} from '@sodax/wallet-sdk-react';
|
|
120
|
+
import type { ChainType } from '@sodax/types';
|
|
118
121
|
|
|
119
122
|
export function WalletModal({ open, onClose }: { open: boolean; onClose: () => void }) {
|
|
120
123
|
const modal = useWalletModal({
|
|
@@ -132,40 +135,27 @@ export function WalletModal({ open, onClose }: { open: boolean; onClose: () => v
|
|
|
132
135
|
<h2>Select a chain</h2>
|
|
133
136
|
{chainGroups.map((group) => (
|
|
134
137
|
<button
|
|
135
|
-
key={group.
|
|
136
|
-
onClick={() => modal.
|
|
138
|
+
key={group.chainType}
|
|
139
|
+
onClick={() => modal.selectChain(group.chainType)}
|
|
137
140
|
>
|
|
138
|
-
{group.
|
|
141
|
+
{group.displayName}
|
|
139
142
|
</button>
|
|
140
143
|
))}
|
|
141
144
|
</Dialog>
|
|
142
145
|
);
|
|
143
146
|
|
|
144
|
-
case 'walletSelect':
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
147
|
+
case 'walletSelect':
|
|
148
|
+
// The wallet list is NOT on modal.state — pull it from useXConnectors for
|
|
149
|
+
// the chosen chain. A hook can't be called inside a switch case, so render
|
|
150
|
+
// a child component keyed off modal.state.chainType.
|
|
148
151
|
return (
|
|
149
|
-
<
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
{
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
disabled={!connector.isInstalled}
|
|
156
|
-
onClick={() => modal.connect(connector)}
|
|
157
|
-
>
|
|
158
|
-
{connector.name}
|
|
159
|
-
{!connector.isInstalled && (
|
|
160
|
-
<a href={connector.installUrl} target="_blank" rel="noreferrer">
|
|
161
|
-
Install
|
|
162
|
-
</a>
|
|
163
|
-
)}
|
|
164
|
-
</button>
|
|
165
|
-
))}
|
|
166
|
-
</Dialog>
|
|
152
|
+
<WalletPicker
|
|
153
|
+
chainType={modal.state.chainType}
|
|
154
|
+
onPick={modal.selectWallet}
|
|
155
|
+
onBack={modal.back}
|
|
156
|
+
onClose={onClose}
|
|
157
|
+
/>
|
|
167
158
|
);
|
|
168
|
-
}
|
|
169
159
|
|
|
170
160
|
case 'connecting':
|
|
171
161
|
return (
|
|
@@ -189,6 +179,42 @@ export function WalletModal({ open, onClose }: { open: boolean; onClose: () => v
|
|
|
189
179
|
return null;
|
|
190
180
|
}
|
|
191
181
|
}
|
|
182
|
+
|
|
183
|
+
function WalletPicker({
|
|
184
|
+
chainType,
|
|
185
|
+
onPick,
|
|
186
|
+
onBack,
|
|
187
|
+
onClose,
|
|
188
|
+
}: {
|
|
189
|
+
chainType: ChainType;
|
|
190
|
+
onPick: (c: IXConnector) => void;
|
|
191
|
+
onBack: () => void;
|
|
192
|
+
onClose: () => void;
|
|
193
|
+
}) {
|
|
194
|
+
const connectors = sortConnectors(useXConnectors({ xChainType: chainType }), {
|
|
195
|
+
preferred: ['metamask', 'phantom'],
|
|
196
|
+
});
|
|
197
|
+
return (
|
|
198
|
+
<Dialog onClose={onClose}>
|
|
199
|
+
<button onClick={onBack}>← back</button>
|
|
200
|
+
<h2>Connect to {chainType}</h2>
|
|
201
|
+
{connectors.map((connector) => (
|
|
202
|
+
<button
|
|
203
|
+
key={connector.id}
|
|
204
|
+
disabled={!connector.isInstalled}
|
|
205
|
+
onClick={() => onPick(connector)}
|
|
206
|
+
>
|
|
207
|
+
{connector.name}
|
|
208
|
+
{!connector.isInstalled && (
|
|
209
|
+
<a href={connector.installUrl} target="_blank" rel="noreferrer">
|
|
210
|
+
Install
|
|
211
|
+
</a>
|
|
212
|
+
)}
|
|
213
|
+
</button>
|
|
214
|
+
))}
|
|
215
|
+
</Dialog>
|
|
216
|
+
);
|
|
217
|
+
}
|
|
192
218
|
```
|
|
193
219
|
|
|
194
220
|
---
|
|
@@ -199,7 +225,7 @@ export function WalletModal({ open, onClose }: { open: boolean; onClose: () => v
|
|
|
199
225
|
|---|---|---|
|
|
200
226
|
| Track which chain is picked | `useState<ChainType \| null>` | `useWalletModal().state.kind === 'walletSelect'` |
|
|
201
227
|
| List enabled chains | hardcoded `SUPPORTED_CHAINS` | `useChainGroups()` (driven by `walletConfig`) |
|
|
202
|
-
| List connectors per chain | one `useXConnectors` per chain | `modal.state.
|
|
228
|
+
| List connectors per chain | one `useXConnectors` per chain | one `useXConnectors({ xChainType: modal.state.chainType })` in the `walletSelect` branch |
|
|
203
229
|
| Connecting / error state | `useState` for `connectingId`, `error` | `modal.state.kind` with discriminated union |
|
|
204
230
|
| Retry on error | re-trigger click manually | `modal.retry()` |
|
|
205
231
|
| Filter to installed wallets | n/a | `connector.isInstalled` + `connector.installUrl` |
|
|
@@ -213,9 +239,9 @@ export function WalletModal({ open, onClose }: { open: boolean; onClose: () => v
|
|
|
213
239
|
|
|
214
240
|
1. **Find the v1 modal file.** Search for `useState<ChainType` or multiple `useXConnectors` calls in the same component.
|
|
215
241
|
2. **Replace state-tracking with `useWalletModal`.** Remove `useState` for picked chain, connectingId, error.
|
|
216
|
-
3. **Replace hardcoded chain list with `useChainGroups`.** Use the `
|
|
242
|
+
3. **Replace hardcoded chain list with `useChainGroups`.** Use the `chainType` field on each group entry (pass it to `modal.selectChain`); render `displayName` for the label.
|
|
217
243
|
4. **Switch on `modal.state.kind`.** Render branches: `'closed'` / `'chainSelect'` / `'walletSelect'` / `'connecting'` / `'error'` / `'success'`.
|
|
218
|
-
5. **
|
|
244
|
+
5. **Render the wallet list from `useXConnectors`, not the modal.** In the `'walletSelect'` branch, read `modal.state.chainType` and call `useXConnectors({ xChainType })` (in a child component, since hooks can't run inside a `switch`). Connect with `modal.selectWallet(connector)`. Use `connector.isInstalled` / `connector.installUrl` for the install CTA and `sortConnectors` to rank installed wallets first.
|
|
219
245
|
6. **Keep your existing `<Dialog>` primitive.** v2 is **headless** — bring your own UI components.
|
|
220
246
|
|
|
221
247
|
---
|
|
@@ -238,8 +264,8 @@ grep -nE "useState.*connectingId|useState.*pickedChain" <user-modal-file>
|
|
|
238
264
|
|
|
239
265
|
## Edge cases
|
|
240
266
|
|
|
241
|
-
- **Modal opens on a specific chain (skip chain select).** Call `modal.
|
|
242
|
-
- **App needs to know which chain the user picked even before connecting.** Read `modal.state.
|
|
267
|
+
- **Modal opens on a specific chain (skip chain select).** Call `modal.selectChain('EVM')` directly in your trigger button instead of going through chain select. The state machine starts at `'walletSelect'` for that chain.
|
|
268
|
+
- **App needs to know which chain the user picked even before connecting.** Read `modal.state.chainType` inside the `'walletSelect'` / `'connecting'` branches.
|
|
243
269
|
- **Multiple modal trigger buttons (e.g. chain-specific CTAs).** Reuse one `useWalletModal` instance — do not create one per button.
|
|
244
270
|
|
|
245
271
|
For a full integration walkthrough (without v1 baggage), see [`recipes/multi-chain-modal.md`](../../../integration/knowledge/recipes/multi-chain-modal.md).
|
|
@@ -62,34 +62,39 @@ If the project is **not** Next.js (Vite, CRA), only the prop-shape rewrite appli
|
|
|
62
62
|
// @ai-snippets-skip
|
|
63
63
|
// app/layout.tsx — v2 ✅
|
|
64
64
|
import { headers } from 'next/headers';
|
|
65
|
-
import { cookieToInitialState } from 'wagmi';
|
|
66
65
|
import { ChainKeys } from '@sodax/types';
|
|
67
66
|
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
|
|
68
67
|
import { SodaxWalletProvider, type SodaxWalletConfig } from '@sodax/wallet-sdk-react';
|
|
69
|
-
import { createWagmiConfig } from '@sodax/wallet-sdk-react/xchains/evm';
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
68
|
+
import { createWagmiConfig, tryCookieToInitialState } from '@sodax/wallet-sdk-react/xchains/evm';
|
|
69
|
+
|
|
70
|
+
// Single source of truth for the EVM slot. Server and client MUST build from the SAME values
|
|
71
|
+
// (chains, ssr, persistKey) — otherwise the SSR cookie read uses a different key/config and the
|
|
72
|
+
// first render flashes disconnected.
|
|
73
|
+
const evmConfig: NonNullable<SodaxWalletConfig['EVM']> = {
|
|
74
|
+
ssr: true,
|
|
75
|
+
reconnectOnMount: true,
|
|
76
|
+
// persistKey: 'my-app', // optional; default 'sodax' (cookie 'sodax.store'). Set the SAME value used on the client.
|
|
77
|
+
chains: {
|
|
78
|
+
[ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://rpc.soniclabs.com' },
|
|
79
|
+
[ChainKeys.ETHEREUM_MAINNET]: { rpcUrl: 'https://ethereum-rpc.publicnode.com' },
|
|
79
80
|
},
|
|
80
|
-
// Add other chain slots as needed
|
|
81
81
|
};
|
|
82
82
|
|
|
83
|
+
const walletConfig: SodaxWalletConfig = { EVM: evmConfig /* + other chain slots */ };
|
|
83
84
|
const queryClient = new QueryClient();
|
|
84
85
|
|
|
85
86
|
export default async function RootLayout({ children }: { children: React.ReactNode }) {
|
|
86
87
|
const cookie = (await headers()).get('cookie');
|
|
87
|
-
//
|
|
88
|
-
|
|
89
|
-
const
|
|
88
|
+
// Build the SSR wagmi config from the SAME evmConfig (chains + options), then re-derive
|
|
89
|
+
// initialState. `tryCookieToInitialState` swallows a malformed cookie (→ undefined) so SSR can't throw.
|
|
90
|
+
const wagmiConfig = createWagmiConfig(evmConfig.chains, {
|
|
91
|
+
ssr: evmConfig.ssr,
|
|
92
|
+
reconnectOnMount: evmConfig.reconnectOnMount,
|
|
93
|
+
persistKey: evmConfig.persistKey,
|
|
94
|
+
});
|
|
95
|
+
const initialState = tryCookieToInitialState(wagmiConfig, cookie);
|
|
90
96
|
|
|
91
|
-
const
|
|
92
|
-
const config: SodaxWalletConfig = { ...walletConfig, EVM: evmConfig };
|
|
97
|
+
const config: SodaxWalletConfig = { ...walletConfig, EVM: { ...evmConfig, initialState } };
|
|
93
98
|
|
|
94
99
|
return (
|
|
95
100
|
<html>
|
|
@@ -114,7 +119,7 @@ If you don't need to avoid the first-render disconnect flash, drop the cookie /
|
|
|
114
119
|
| `rpcConfig` flat dict | top-level prop | nested under `EVM.chains[<ChainKey>].rpcUrl` |
|
|
115
120
|
| `options.wagmi.ssr` | nested under `options.wagmi` | `EVM.ssr: true` |
|
|
116
121
|
| `options.wagmi.reconnectOnMount` | nested under `options.wagmi` | `EVM.reconnectOnMount` (still supported, default `false`) |
|
|
117
|
-
| `initialState` | top-level prop | `EVM.initialState` (still supported — pass `
|
|
122
|
+
| `initialState` | top-level prop | `EVM.initialState` (still supported — pass `tryCookieToInitialState(...)` from `@sodax/wallet-sdk-react/xchains/evm` for Next.js cookie hydration) |
|
|
118
123
|
| `QueryClient` | created internally by `SodaxWalletProvider` | created by caller, wrapped with `QueryClientProvider` |
|
|
119
124
|
|
|
120
125
|
---
|
|
@@ -123,7 +128,7 @@ If you don't need to avoid the first-render disconnect flash, drop the cookie /
|
|
|
123
128
|
|
|
124
129
|
1. **Move per-chain RPC URLs.** Move `rpcConfig['sonic']` etc. into `EVM.chains[ChainKeys.SONIC_MAINNET].rpcUrl`. Use `ChainKeys` constants from `@sodax/types`.
|
|
125
130
|
2. **Collapse `options.wagmi.*` into `EVM.*`.** `options.wagmi.ssr` → `EVM.ssr`, `options.wagmi.reconnectOnMount` → `EVM.reconnectOnMount`.
|
|
126
|
-
3. **Move `initialState` into `EVM.initialState`.** v2 still accepts wagmi cookie state; the prop name and location changed, not the feature.
|
|
131
|
+
3. **Move `initialState` into `EVM.initialState`.** v2 still accepts wagmi cookie state; the prop name and location changed, not the feature. Derive it with `tryCookieToInitialState(config, cookie)` (swallows a malformed cookie so SSR can't throw) and build the server's `createWagmiConfig` from the **same** `chains`/`persistKey` the client uses.
|
|
127
132
|
4. **Add `QueryClientProvider`.** Create a `QueryClient` (top-level module constant — singleton across renders) and wrap `SodaxWalletProvider` with `<QueryClientProvider>`.
|
|
128
133
|
5. **Make sure `@tanstack/react-query` is a direct dep.** Add it if missing:
|
|
129
134
|
```bash
|
|
@@ -215,7 +215,7 @@ v1 accepted a top-level `initialState` prop (`WagmiState`) for SSR hydration. v2
|
|
|
215
215
|
}}>
|
|
216
216
|
```
|
|
217
217
|
|
|
218
|
-
If you previously derived `initialState` via `cookieToInitialState(...)` in a server component,
|
|
218
|
+
If you previously derived `initialState` via wagmi's `cookieToInitialState(...)` in a server component, switch to `tryCookieToInitialState(...)` (from `@sodax/wallet-sdk-react/xchains/evm`, so a malformed cookie can't throw during SSR) and pass the result into `EVM.initialState` instead of the top-level prop. Build the server's `createWagmiConfig` from the **same** `chains`/`persistKey` as the client, or the SSR read hits the wrong cookie. See [`../recipes/ssr-setup.md`](../recipes/ssr-setup.md) for a full Next.js example.
|
|
219
219
|
|
|
220
220
|
---
|
|
221
221
|
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: sodax-wallet-sdk-react-sign-message
|
|
3
|
+
description: 'Granular skill for the @sodax/wallet-sdk-react v2 message-signing surface only — useXSignMessage, a React Query mutation that signs an arbitrary message with the connected wallet across chain types (Bitcoin auto-detects BIP-322 vs ECDSA). Use when a React dapp needs to prove wallet ownership or sign a login/SIWE-style challenge — e.g. "useXSignMessage", "sign a message in React", "wallet signature for auth", "per-chain message signing". Covers BOTH integration (write new v2 code) and migration (port v1 — single-object params). Picks via Step 1. Links into the parent sodax-wallet-sdk-react knowledge tree. For signing actual SODAX transactions use the bridge-to-sdk skill (useWalletProvider) instead.'
|
|
4
|
+
license: MIT
|
|
5
|
+
metadata:
|
|
6
|
+
version: '0.0.1'
|
|
7
|
+
author: sodax
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Sign message (`wallet-sdk-react` granular skill)
|
|
11
|
+
|
|
12
|
+
Granular skill for `useXSignMessage` — arbitrary message signing with the connected wallet. Source-of-truth reference lives in the parent broad skill's knowledge tree; this file is the focused workflow only.
|
|
13
|
+
|
|
14
|
+
## Step 1 — Clarify with user before coding
|
|
15
|
+
|
|
16
|
+
1. **New code or v1 → v2 port?** New → § Integration. Port v1 → § Migration.
|
|
17
|
+
2. **Message signing, not transaction signing?** `useXSignMessage` signs an arbitrary message (auth / proof-of-ownership). To sign a SODAX *transaction*, use `useWalletProvider` (the bridge-to-sdk skill) instead.
|
|
18
|
+
3. **Which chain?** The return type varies by family — see the per-chain matrix in the recipe.
|
|
19
|
+
|
|
20
|
+
## Integration workflow (new v2 code)
|
|
21
|
+
|
|
22
|
+
1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DON'T (read first).
|
|
23
|
+
2. [`../integration/knowledge/recipes/setup.md`](../integration/knowledge/recipes/setup.md) — prerequisite: provider mounted, chain slot enabled.
|
|
24
|
+
3. [`../integration/knowledge/recipes/sign-message.md`](../integration/knowledge/recipes/sign-message.md) — usage + per-chain signature matrix.
|
|
25
|
+
4. Lookups → [`../integration/knowledge/reference/hooks.md`](../integration/knowledge/reference/hooks.md) (sign-message section).
|
|
26
|
+
|
|
27
|
+
### Sign-message-specific anti-patterns
|
|
28
|
+
|
|
29
|
+
- **Treating `useXSignMessage` as a plain function.** It's a React Query mutation — call `mutateAsync({ xChainType, message })`.
|
|
30
|
+
- **Assuming a single return type.** The result is a union — `` `0x${string}` | Uint8Array | string | undefined `` — depending on chain; handle accordingly.
|
|
31
|
+
- **Expecting one Bitcoin scheme.** Bitcoin signing auto-detects BIP-322 vs ECDSA — don't hard-code one.
|
|
32
|
+
- **Calling it with a disabled or unsupported chain.** The mutation does *not* reject — it resolves `undefined` (with a one-time `console.warn`) for chains that don't implement `signMessage` or aren't in `walletConfig`. Branch on the `undefined` result; don't rely on a thrown error.
|
|
33
|
+
|
|
34
|
+
## Migration workflow (port v1 → v2)
|
|
35
|
+
|
|
36
|
+
1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md) — DO / DON'T (read first).
|
|
37
|
+
2. [`../migration-v1-to-v2/knowledge/breaking-changes.md`](../migration-v1-to-v2/knowledge/breaking-changes.md) — single-object hook params.
|
|
38
|
+
3. Symbol lookups → [`../migration-v1-to-v2/knowledge/reference/hooks.md`](../migration-v1-to-v2/knowledge/reference/hooks.md).
|
|
39
|
+
|
|
40
|
+
## Verification
|
|
41
|
+
|
|
42
|
+
1. `pnpm tsc --noEmit` exits clean.
|
|
43
|
+
2. The signature union is handled (not assumed to be a string).
|
|
44
|
+
3. `mutateAsync({ xChainType, message })` shape (single object), not positional args (migration only).
|
|
45
|
+
|
|
46
|
+
## Related skills (same family)
|
|
47
|
+
|
|
48
|
+
- [`../bridge-to-sdk/SKILL.md`](../bridge-to-sdk/SKILL.md) — for signing SODAX transactions (not arbitrary messages).
|
|
49
|
+
- [`../connect/SKILL.md`](../connect/SKILL.md) — connect the wallet first.
|
|
50
|
+
|
|
51
|
+
For multi-feature work, load the broad [`sodax-wallet-sdk-react` skill](../SKILL.md).
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: sodax-wallet-sdk-react-switch-chain
|
|
3
|
+
description: 'Granular skill for the @sodax/wallet-sdk-react v2 EVM chain-switching surface only — useEvmSwitchChain, which compares the connected EVM network to a target xChainId and exposes wrong-network state + a switch handler (also covers the Injective + MetaMask auto-switch to Ethereum). Use when a React dapp needs to detect a wallet on the wrong EVM network and prompt a switch before a signed action — e.g. "useEvmSwitchChain", "wrong network banner", "switch EVM chain before swap", "isWrongChain". Covers BOTH integration (write new v2 code) and migration (port v1 — note there is no top-level useEthereumChainId in v2). Picks via Step 1. Links into the parent sodax-wallet-sdk-react knowledge tree. EVM-only — non-EVM chains have no switch concept here.'
|
|
4
|
+
license: MIT
|
|
5
|
+
metadata:
|
|
6
|
+
version: '0.0.1'
|
|
7
|
+
author: sodax
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Switch chain (`wallet-sdk-react` granular skill)
|
|
11
|
+
|
|
12
|
+
Granular skill for `useEvmSwitchChain` — EVM wrong-network detection + switching. EVM-only. Source-of-truth reference lives in the parent broad skill's knowledge tree; this file is the focused workflow only.
|
|
13
|
+
|
|
14
|
+
## Step 1 — Clarify with user before coding
|
|
15
|
+
|
|
16
|
+
1. **New code or v1 → v2 port?** New → § Integration. Port v1 → § Migration.
|
|
17
|
+
2. **Target chain is EVM?** This hook only covers EVM networks (and the Injective + MetaMask Ethereum-mainnet auto-switch). Non-EVM chains have no switch concept.
|
|
18
|
+
3. **Gate a signed action?** Typical flow: `const { isWrongChain, handleSwitchChain } = useEvmSwitchChain({ xChainId })`; block the action and show a switch CTA while `isWrongChain`.
|
|
19
|
+
|
|
20
|
+
## Integration workflow (new v2 code)
|
|
21
|
+
|
|
22
|
+
1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DON'T (read first).
|
|
23
|
+
2. [`../integration/knowledge/recipes/setup.md`](../integration/knowledge/recipes/setup.md) — prerequisite: provider mounted with the `EVM` slot.
|
|
24
|
+
3. [`../integration/knowledge/recipes/switch-chain.md`](../integration/knowledge/recipes/switch-chain.md) — the full wrong-network → switch pattern.
|
|
25
|
+
4. Lookups → [`../integration/knowledge/reference/hooks.md`](../integration/knowledge/reference/hooks.md) (EVM-specific section).
|
|
26
|
+
|
|
27
|
+
### Switch-chain-specific anti-patterns
|
|
28
|
+
|
|
29
|
+
- **Reaching for a top-level `useEthereumChainId`.** It doesn't exist in v2 — read the raw EVM chain id via wagmi's `useAccount().chainId`; the wrong-network UX is folded into `useEvmSwitchChain`.
|
|
30
|
+
- **Expecting it to switch non-EVM chains.** EVM-only. It also handles the Injective + MetaMask case (auto-switch to Ethereum mainnet).
|
|
31
|
+
- **Ignoring the no-op return when `EVM` is absent.** With no `EVM` slot in `walletConfig` it returns `{ isWrongChain: false, handleSwitchChain: () => {} }` — safe to call, but it won't do anything.
|
|
32
|
+
- **Calling `handleSwitchChain` unconditionally.** Gate it on `isWrongChain`.
|
|
33
|
+
|
|
34
|
+
## Migration workflow (port v1 → v2)
|
|
35
|
+
|
|
36
|
+
1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md) — DO / DON'T (read first).
|
|
37
|
+
2. [`../migration-v1-to-v2/knowledge/breaking-changes.md`](../migration-v1-to-v2/knowledge/breaking-changes.md) — single-object hook params; the removed top-level `useEthereumChainId`.
|
|
38
|
+
3. Symbol lookups → [`../migration-v1-to-v2/knowledge/reference/hooks.md`](../migration-v1-to-v2/knowledge/reference/hooks.md).
|
|
39
|
+
|
|
40
|
+
## Verification
|
|
41
|
+
|
|
42
|
+
1. `pnpm tsc --noEmit` exits clean.
|
|
43
|
+
2. `handleSwitchChain` is only invoked when `isWrongChain` is true.
|
|
44
|
+
3. No reference to a top-level `useEthereumChainId` (migration only).
|
|
45
|
+
|
|
46
|
+
## Related skills (same family)
|
|
47
|
+
|
|
48
|
+
- [`../bridge-to-sdk/SKILL.md`](../bridge-to-sdk/SKILL.md) — switch the chain, then pass the provider into the SDK call.
|
|
49
|
+
- [`../connect/SKILL.md`](../connect/SKILL.md) — connect the EVM wallet first.
|
|
50
|
+
|
|
51
|
+
For multi-feature work, load the broad [`sodax-wallet-sdk-react` skill](../SKILL.md).
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: sodax-wallet-sdk-react-wallet-modal
|
|
3
|
+
description: 'Granular skill for the @sodax/wallet-sdk-react v2 headless wallet-modal + multi-chain UI primitives only — useWalletModal (chainSelect → walletSelect → connecting → success | error state machine), useConnectionFlow (connect without a modal), useChainGroups, useConnectedChains, useBatchConnect / useBatchDisconnect, and the sortConnectors utility. Use when a React dapp needs a multi-chain wallet picker modal, an inline connection flow, batch connect/disconnect across chains, or chain/connector list rendering — e.g. "build a wallet modal", "useWalletModal", "multi-chain connect UI", "connect all chains with one wallet", "useBatchConnect". Covers BOTH integration (write new v2 code) and migration (port v1). Picks via Step 1. Links into the parent sodax-wallet-sdk-react knowledge tree. For a plain connect button use the sibling connect skill.'
|
|
4
|
+
license: MIT
|
|
5
|
+
metadata:
|
|
6
|
+
version: '0.0.1'
|
|
7
|
+
author: sodax
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Wallet modal (`wallet-sdk-react` granular skill)
|
|
11
|
+
|
|
12
|
+
Granular skill for the headless multi-chain modal + connection-flow + batch hooks of `@sodax/wallet-sdk-react` v2 — render-agnostic, wallet-agnostic building blocks. Source-of-truth reference lives in the parent broad skill's knowledge tree; this file is the focused workflow only.
|
|
13
|
+
|
|
14
|
+
## Step 1 — Clarify with user before coding
|
|
15
|
+
|
|
16
|
+
1. **New code or v1 → v2 port?** New → § Integration. Port v1 → § Migration.
|
|
17
|
+
2. **Which primitive?** Full modal state machine (`useWalletModal`), modal-less inline flow (`useConnectionFlow`), chain/connection lists (`useChainGroups` / `useConnectedChains`), or bulk ops (`useBatchConnect` / `useBatchDisconnect`).
|
|
18
|
+
3. **Need a render?** These hooks are render-agnostic — you own the JSX (the hooks supply state + actions; you map them to your components).
|
|
19
|
+
|
|
20
|
+
## Integration workflow (new v2 code)
|
|
21
|
+
|
|
22
|
+
1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DON'T (read first).
|
|
23
|
+
2. [`../integration/knowledge/recipes/setup.md`](../integration/knowledge/recipes/setup.md) — prerequisite: mount `SodaxWalletProvider`, declare chain-type slots, wire React Query.
|
|
24
|
+
3. [`../integration/knowledge/architecture.md`](../integration/knowledge/architecture.md) — frozen config, EVM single-connection model, persist hydration gate.
|
|
25
|
+
4. [`../integration/knowledge/recipes/multi-chain-modal.md`](../integration/knowledge/recipes/multi-chain-modal.md) and [`../integration/knowledge/recipes/batch-operations.md`](../integration/knowledge/recipes/batch-operations.md).
|
|
26
|
+
5. Lookups → [`../integration/knowledge/reference/hooks.md`](../integration/knowledge/reference/hooks.md) (modal / multi-chain section), [`connectors.md`](../integration/knowledge/reference/connectors.md), [`wallet-brands.md`](../integration/knowledge/reference/wallet-brands.md).
|
|
27
|
+
|
|
28
|
+
### Modal-specific anti-patterns
|
|
29
|
+
|
|
30
|
+
- **Rendering UI before persist hydration.** Gate on `useConnectedChains().status === 'ready'` — render too early and you get flicker / stale state.
|
|
31
|
+
- **Expecting per-network EVM rows.** `useChainGroups` collapses every configured EVM network into a single `EVM` group (one wagmi connection covers all).
|
|
32
|
+
- **Ignoring the batch result buckets.** Both `useBatchConnect` and `useBatchDisconnect` return `successful` / `failed` (with per-chain error). Only `useBatchConnect` adds a `skipped` bucket (when `skipConnected: true`) — `BatchDisconnectResult` has no `skipped`. Surface every bucket the operation exposes.
|
|
33
|
+
- **Treating `useWalletModal` as connection state.** It's a UI state machine (`closed → chainSelect → walletSelect → connecting → success | error`); the connection itself comes from `useXAccount` / `useConnectedChains`.
|
|
34
|
+
|
|
35
|
+
## Migration workflow (port v1 → v2)
|
|
36
|
+
|
|
37
|
+
1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md) — DO / DON'T (read first).
|
|
38
|
+
2. [`../migration-v1-to-v2/knowledge/breaking-changes.md`](../migration-v1-to-v2/knowledge/breaking-changes.md) — `useXWagmiStore` removed; single-object hook params; reshaped `SodaxWalletProvider` props.
|
|
39
|
+
3. [`../migration-v1-to-v2/knowledge/recipes/multi-chain-modal.md`](../migration-v1-to-v2/knowledge/recipes/multi-chain-modal.md) — v1 modal → v2 primitives.
|
|
40
|
+
4. Symbol lookups → [`../migration-v1-to-v2/knowledge/reference/hooks.md`](../migration-v1-to-v2/knowledge/reference/hooks.md).
|
|
41
|
+
|
|
42
|
+
## Verification
|
|
43
|
+
|
|
44
|
+
1. `pnpm tsc --noEmit` exits clean.
|
|
45
|
+
2. UI is gated on `useConnectedChains().status === 'ready'`.
|
|
46
|
+
3. Batch flows surface `failed` (and `skipped`) buckets, not just `successful`.
|
|
47
|
+
4. `grep -rE 'useXWagmiStore|useXWalletStore' src/` is empty (migration only).
|
|
48
|
+
|
|
49
|
+
## Related skills (same family)
|
|
50
|
+
|
|
51
|
+
- [`../connect/SKILL.md`](../connect/SKILL.md) — a plain connect/disconnect button + account reads (no modal).
|
|
52
|
+
- [`../walletconnect/SKILL.md`](../walletconnect/SKILL.md) — add Fireblocks / Ledger / mobile wallets to the modal.
|
|
53
|
+
|
|
54
|
+
For multi-feature work, load the broad [`sodax-wallet-sdk-react` skill](../SKILL.md).
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: sodax-wallet-sdk-react-walletconnect
|
|
3
|
+
description: 'Granular skill for the @sodax/wallet-sdk-react v2 WalletConnect / enterprise-custody setup only — the walletConnect field on the EVM slot of SodaxWalletConfig, which adds non-injected wallets (Fireblocks, Ledger, mobile-only) beyond the default EIP-6963 browser-extension discovery. Use when a React dapp needs enterprise custody or mobile wallets on EVM — e.g. "add WalletConnect", "Fireblocks wallet support", "Ledger via WalletConnect", "mobile wallet connect", "projectId for WalletConnect". Covers BOTH integration (write new v2 config) and migration (port v1 WalletConnect setup). Picks via Step 1. Links into the parent sodax-wallet-sdk-react knowledge tree. WalletConnect is EVM-slot-only; for the connect UI itself use the connect / wallet-modal skills.'
|
|
4
|
+
license: MIT
|
|
5
|
+
metadata:
|
|
6
|
+
version: '0.0.1'
|
|
7
|
+
author: sodax
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# WalletConnect (`wallet-sdk-react` granular skill)
|
|
11
|
+
|
|
12
|
+
Granular skill for the `walletConnect` enterprise-custody setup on the `EVM` slot of `SodaxWalletConfig`. Source-of-truth reference lives in the parent broad skill's knowledge tree; this file is the focused workflow only.
|
|
13
|
+
|
|
14
|
+
## Step 1 — Clarify with user before coding
|
|
15
|
+
|
|
16
|
+
1. **New code or v1 → v2 port?** New → § Integration. Port v1 → § Migration.
|
|
17
|
+
2. **Which wallets?** Default EVM discovery is **EIP-6963 (browser extensions only)**. WalletConnect is needed for Fireblocks / Ledger / mobile-only wallets.
|
|
18
|
+
3. **Have a WalletConnect `projectId`?** It's required — from WalletConnect Cloud.
|
|
19
|
+
|
|
20
|
+
## Integration workflow (new v2 code)
|
|
21
|
+
|
|
22
|
+
1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DON'T (read first).
|
|
23
|
+
2. [`../integration/knowledge/recipes/setup.md`](../integration/knowledge/recipes/setup.md) — prerequisite: provider mounted with the `EVM` slot.
|
|
24
|
+
3. [`../integration/knowledge/recipes/walletconnect-setup.md`](../integration/knowledge/recipes/walletconnect-setup.md) — add `walletConnect: { projectId: '…' }` to the EVM slot.
|
|
25
|
+
4. Lookups → [`../integration/knowledge/reference/wallet-brands.md`](../integration/knowledge/reference/wallet-brands.md), [`hooks.md`](../integration/knowledge/reference/hooks.md).
|
|
26
|
+
|
|
27
|
+
### WalletConnect-specific anti-patterns
|
|
28
|
+
|
|
29
|
+
- **Expecting Fireblocks / Ledger / mobile to appear without WalletConnect.** Default EIP-6963 discovery surfaces browser extensions only — those need the `walletConnect` field.
|
|
30
|
+
- **Putting `walletConnect` on a non-EVM slot.** It's an **EVM-slot-only** field (`WalletConnectParameters`: `projectId`, `qrModalOptions`, …).
|
|
31
|
+
- **Omitting `projectId`.** Required — WalletConnect won't initialize without it.
|
|
32
|
+
- **Forgetting SSR timing.** On Next.js, the EVM slot's `ssr` flag governs wagmi hydration — see the migration `ssr-setup` recipe if you hit hydration mismatches.
|
|
33
|
+
|
|
34
|
+
## Migration workflow (port v1 → v2)
|
|
35
|
+
|
|
36
|
+
1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md) — DO / DON'T (read first).
|
|
37
|
+
2. [`../migration-v1-to-v2/knowledge/breaking-changes.md`](../migration-v1-to-v2/knowledge/breaking-changes.md) — reshaped `SodaxWalletProvider` props (`config` object; chain-type slots are top-level).
|
|
38
|
+
3. [`../migration-v1-to-v2/knowledge/recipes/walletconnect-migration.md`](../migration-v1-to-v2/knowledge/recipes/walletconnect-migration.md) — move WalletConnect config onto the EVM slot. SSR setup → [`ssr-setup.md`](../migration-v1-to-v2/knowledge/recipes/ssr-setup.md).
|
|
39
|
+
4. Symbol lookups → [`../migration-v1-to-v2/knowledge/reference/config.md`](../migration-v1-to-v2/knowledge/reference/config.md).
|
|
40
|
+
|
|
41
|
+
## Verification
|
|
42
|
+
|
|
43
|
+
1. `pnpm tsc --noEmit` exits clean.
|
|
44
|
+
2. `walletConnect: { projectId }` sits on the `EVM` slot of `SodaxWalletConfig` (not elsewhere).
|
|
45
|
+
3. A non-injected wallet (mobile / Fireblocks / Ledger) appears in the connector list.
|
|
46
|
+
|
|
47
|
+
## Related skills (same family)
|
|
48
|
+
|
|
49
|
+
- [`../wallet-modal/SKILL.md`](../wallet-modal/SKILL.md) — surface the WalletConnect wallets in the multi-chain modal.
|
|
50
|
+
- [`../connect/SKILL.md`](../connect/SKILL.md) — the connect button / connector discovery hooks.
|
|
51
|
+
|
|
52
|
+
For multi-feature work, load the broad [`sodax-wallet-sdk-react` skill](../SKILL.md).
|