@sodax/skills 2.0.0-rc.8 → 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.
Files changed (168) hide show
  1. package/.claude-plugin/plugin.json +1 -0
  2. package/AGENTS.md +123 -13
  3. package/README.md +5 -2
  4. package/package.json +1 -1
  5. package/skills/sodax-build/SKILL.md +90 -0
  6. package/skills/sodax-build/knowledge/README.md +35 -0
  7. package/skills/sodax-build/knowledge/brief-template.md +41 -0
  8. package/skills/sodax-build/knowledge/chains-and-assets.md +26 -0
  9. package/skills/sodax-build/knowledge/example-sessions.md +84 -0
  10. package/skills/sodax-build/knowledge/feature-catalog.md +51 -0
  11. package/skills/sodax-build/knowledge/glossary.md +35 -0
  12. package/skills/sodax-build/knowledge/handoff.md +60 -0
  13. package/skills/sodax-build/knowledge/interview-guide.md +66 -0
  14. package/skills/sodax-build/knowledge/monetization.md +37 -0
  15. package/skills/sodax-build/knowledge/use-case-gallery.md +32 -0
  16. package/skills/sodax-dapp-kit/SKILL.md +6 -2
  17. package/skills/sodax-dapp-kit/auxiliary-services/SKILL.md +65 -0
  18. package/skills/sodax-dapp-kit/bitcoin/SKILL.md +57 -0
  19. package/skills/sodax-dapp-kit/bridge/SKILL.md +59 -0
  20. package/skills/sodax-dapp-kit/dex/SKILL.md +60 -0
  21. package/skills/sodax-dapp-kit/integration/knowledge/README.md +1 -1
  22. package/skills/sodax-dapp-kit/integration/knowledge/features/README.md +3 -2
  23. package/skills/sodax-dapp-kit/integration/knowledge/features/auxiliary-services.md +71 -11
  24. package/skills/sodax-dapp-kit/integration/knowledge/features/bitcoin.md +10 -6
  25. package/skills/sodax-dapp-kit/integration/knowledge/features/dex.md +2 -2
  26. package/skills/sodax-dapp-kit/integration/knowledge/features/leverage-yield.md +112 -0
  27. package/skills/sodax-dapp-kit/integration/knowledge/features/migration.md +1 -1
  28. package/skills/sodax-dapp-kit/integration/knowledge/features/money-market.md +6 -1
  29. package/skills/sodax-dapp-kit/integration/knowledge/features/swap.md +1 -1
  30. package/skills/sodax-dapp-kit/integration/knowledge/quickstart.md +2 -2
  31. package/skills/sodax-dapp-kit/integration/knowledge/recipes/README.md +1 -0
  32. package/skills/sodax-dapp-kit/integration/knowledge/recipes/backend-queries.md +23 -8
  33. package/skills/sodax-dapp-kit/integration/knowledge/recipes/bitcoin.md +8 -8
  34. package/skills/sodax-dapp-kit/integration/knowledge/recipes/leverage-yield.md +168 -0
  35. package/skills/sodax-dapp-kit/integration/knowledge/recipes/migration.md +1 -1
  36. package/skills/sodax-dapp-kit/integration/knowledge/recipes/setup.md +4 -4
  37. package/skills/sodax-dapp-kit/integration/knowledge/recipes/swap.md +1 -1
  38. package/skills/sodax-dapp-kit/integration/knowledge/recipes/wallet-connectivity.md +3 -0
  39. package/skills/sodax-dapp-kit/integration/knowledge/reference/glossary.md +1 -1
  40. package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md +67 -6
  41. package/skills/sodax-dapp-kit/integration/knowledge/reference/querykey-conventions.md +49 -0
  42. package/skills/sodax-dapp-kit/leverage-yield/SKILL.md +54 -0
  43. package/skills/sodax-dapp-kit/migration/SKILL.md +64 -0
  44. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md +1 -1
  45. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md +2 -2
  46. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/checklist.md +1 -1
  47. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/README.md +1 -1
  48. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/auxiliary-services.md +19 -10
  49. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/bitcoin.md +2 -2
  50. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/bridge.md +1 -1
  51. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/dex.md +1 -1
  52. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/migration.md +1 -1
  53. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/reference/renamed-hooks.md +3 -3
  54. package/skills/sodax-dapp-kit/money-market/SKILL.md +61 -0
  55. package/skills/sodax-dapp-kit/staking/SKILL.md +60 -0
  56. package/skills/sodax-dapp-kit/swap/SKILL.md +64 -0
  57. package/skills/sodax-sdk/SKILL.md +54 -50
  58. package/skills/sodax-sdk/backend-api/SKILL.md +58 -0
  59. package/skills/sodax-sdk/bridge/SKILL.md +53 -0
  60. package/skills/sodax-sdk/dex/SKILL.md +54 -0
  61. package/skills/sodax-sdk/integration/knowledge/README.md +5 -3
  62. package/skills/sodax-sdk/integration/knowledge/ai-rules.md +1 -1
  63. package/skills/sodax-sdk/integration/knowledge/architecture.md +26 -39
  64. package/skills/sodax-sdk/integration/knowledge/chain-specifics.md +57 -10
  65. package/skills/sodax-sdk/integration/knowledge/features/README.md +6 -3
  66. package/skills/sodax-sdk/integration/knowledge/features/backend-api.md +92 -0
  67. package/skills/sodax-sdk/integration/knowledge/features/bridge.md +48 -11
  68. package/skills/sodax-sdk/integration/knowledge/features/dex.md +7 -7
  69. package/skills/sodax-sdk/integration/knowledge/features/leverage-yield.md +175 -0
  70. package/skills/sodax-sdk/integration/knowledge/features/{icx-bnusd-baln.md → migration.md} +75 -30
  71. package/skills/sodax-sdk/integration/knowledge/features/money-market.md +20 -25
  72. package/skills/sodax-sdk/integration/knowledge/features/partner.md +86 -0
  73. package/skills/sodax-sdk/integration/knowledge/features/recovery.md +51 -0
  74. package/skills/sodax-sdk/integration/knowledge/features/staking.md +8 -3
  75. package/skills/sodax-sdk/integration/knowledge/features/swap.md +106 -22
  76. package/skills/sodax-sdk/integration/knowledge/features/swaps-api.md +171 -0
  77. package/skills/sodax-sdk/integration/knowledge/quickstart.md +1 -1
  78. package/skills/sodax-sdk/integration/knowledge/recipes/README.md +1 -0
  79. package/skills/sodax-sdk/integration/knowledge/recipes/backend-server-init.md +3 -3
  80. package/skills/sodax-sdk/integration/knowledge/recipes/gas-estimation.md +8 -4
  81. package/skills/sodax-sdk/integration/knowledge/recipes/initialize-sodax.md +34 -2
  82. package/skills/sodax-sdk/integration/knowledge/recipes/logging.md +102 -0
  83. package/skills/sodax-sdk/integration/knowledge/recipes/raw-tx-flow.md +28 -4
  84. package/skills/sodax-sdk/integration/knowledge/recipes/result-and-errors.md +1 -1
  85. package/skills/sodax-sdk/integration/knowledge/recipes/testing.md +7 -11
  86. package/skills/sodax-sdk/integration/knowledge/reference/README.md +1 -1
  87. package/skills/sodax-sdk/integration/knowledge/reference/chain-keys.md +40 -4
  88. package/skills/sodax-sdk/integration/knowledge/reference/error-codes.md +32 -9
  89. package/skills/sodax-sdk/integration/knowledge/reference/glossary.md +2 -2
  90. package/skills/sodax-sdk/integration/knowledge/reference/public-api.md +37 -4
  91. package/skills/sodax-sdk/leverage-yield/SKILL.md +50 -0
  92. package/skills/sodax-sdk/migration/SKILL.md +69 -0
  93. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/README.md +1 -1
  94. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/ai-rules.md +6 -10
  95. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/architecture.md +2 -2
  96. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/result-and-errors.md +3 -3
  97. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/type-system.md +6 -5
  98. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/checklist.md +2 -2
  99. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/README.md +4 -2
  100. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/backend-api.md +92 -0
  101. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/bridge.md +5 -5
  102. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/dex.md +2 -4
  103. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/{icx-bnusd-baln.md → migration.md} +31 -29
  104. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/money-market.md +2 -2
  105. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/partner.md +64 -0
  106. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/recovery.md +35 -0
  107. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/staking.md +8 -3
  108. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/swap.md +22 -18
  109. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/reference/sodax-config.md +19 -17
  110. package/skills/sodax-sdk/money-market/SKILL.md +56 -0
  111. package/skills/sodax-sdk/partner/SKILL.md +55 -0
  112. package/skills/sodax-sdk/recovery/SKILL.md +53 -0
  113. package/skills/sodax-sdk/staking/SKILL.md +53 -0
  114. package/skills/sodax-sdk/swap/SKILL.md +72 -0
  115. package/skills/sodax-sdk/swaps-api/SKILL.md +62 -0
  116. package/skills/sodax-wallet-sdk-core/SKILL.md +7 -3
  117. package/skills/sodax-wallet-sdk-core/bitcoin/SKILL.md +54 -0
  118. package/skills/sodax-wallet-sdk-core/evm/SKILL.md +54 -0
  119. package/skills/sodax-wallet-sdk-core/icon/SKILL.md +54 -0
  120. package/skills/sodax-wallet-sdk-core/injective/SKILL.md +54 -0
  121. package/skills/sodax-wallet-sdk-core/integration/knowledge/README.md +1 -1
  122. package/skills/sodax-wallet-sdk-core/integration/knowledge/ai-rules.md +2 -2
  123. package/skills/sodax-wallet-sdk-core/integration/knowledge/architecture.md +5 -5
  124. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/bitcoin.md +2 -2
  125. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/evm.md +2 -2
  126. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/icon.md +5 -5
  127. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/injective.md +4 -2
  128. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/near.md +1 -1
  129. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/solana.md +2 -2
  130. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/stacks.md +2 -2
  131. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/stellar.md +2 -2
  132. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/sui.md +1 -1
  133. package/skills/sodax-wallet-sdk-core/integration/knowledge/quickstart.md +1 -1
  134. package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/setup-private-key.md +2 -2
  135. package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/sign-and-broadcast.md +1 -0
  136. package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/testing.md +1 -1
  137. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/chain-support.md +3 -2
  138. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/interfaces.md +7 -5
  139. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/provider-classes.md +2 -2
  140. package/skills/sodax-wallet-sdk-core/migration-v1-to-v2/knowledge/README.md +1 -1
  141. package/skills/sodax-wallet-sdk-core/near/SKILL.md +54 -0
  142. package/skills/sodax-wallet-sdk-core/solana/SKILL.md +54 -0
  143. package/skills/sodax-wallet-sdk-core/stacks/SKILL.md +53 -0
  144. package/skills/sodax-wallet-sdk-core/stellar/SKILL.md +54 -0
  145. package/skills/sodax-wallet-sdk-core/sui/SKILL.md +53 -0
  146. package/skills/sodax-wallet-sdk-react/SKILL.md +5 -3
  147. package/skills/sodax-wallet-sdk-react/bridge-to-sdk/SKILL.md +56 -0
  148. package/skills/sodax-wallet-sdk-react/connect/SKILL.md +59 -0
  149. package/skills/sodax-wallet-sdk-react/integration/knowledge/architecture.md +3 -3
  150. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/chain-detection.md +1 -1
  151. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/connect-button.md +1 -1
  152. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/sign-message.md +10 -10
  153. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/switch-chain.md +1 -1
  154. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/api-surface.md +4 -4
  155. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/chain-support.md +4 -4
  156. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/connectors.md +1 -1
  157. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/hooks.md +5 -4
  158. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/wallet-brands.md +1 -1
  159. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/ai-rules.md +1 -1
  160. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/recipes/multi-chain-modal.md +57 -31
  161. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/recipes/ssr-setup.md +24 -19
  162. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/reference/config.md +1 -1
  163. package/skills/sodax-wallet-sdk-react/sign-message/SKILL.md +51 -0
  164. package/skills/sodax-wallet-sdk-react/switch-chain/SKILL.md +51 -0
  165. package/skills/sodax-wallet-sdk-react/wallet-modal/SKILL.md +54 -0
  166. package/skills/sodax-wallet-sdk-react/walletconnect/SKILL.md +52 -0
  167. package/skills/sodax-sdk/integration/knowledge/features/auxiliary-services.md +0 -189
  168. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/auxiliary-services.md +0 -156
@@ -0,0 +1,54 @@
1
+ ---
2
+ name: sodax-wallet-sdk-core-bitcoin
3
+ description: 'Granular skill for the @sodax/wallet-sdk-core v2 Bitcoin wallet provider only — `BitcoinWalletProvider` (PSBT signing via bitcoinjs-lib + ecpair + bip322-js). Use when a backend / Node script / CI / bot / non-React browser flow needs to instantiate a Bitcoin provider directly and sign PSBTs / messages — e.g. "instantiate BitcoinWalletProvider", "sign a PSBT in Node", "BIP-322 vs ECDSA message signing", "private-key Bitcoin signing". Covers BOTH integration (write new v2 code) and migration (port v1 — almost a no-op at this surface: deep-import → barrel). Picks via Step 1. Links into the parent sodax-wallet-sdk-core knowledge tree. For React dapps use the sodax-wallet-sdk-react skill instead (get the typed provider via useWalletProvider).'
4
+ license: MIT
5
+ metadata:
6
+ version: '0.0.1'
7
+ author: sodax
8
+ ---
9
+
10
+ # Bitcoin (`wallet-sdk-core` granular skill)
11
+
12
+ Granular skill for `BitcoinWalletProvider` — the low-level Bitcoin wallet for backend / Node / non-React flows. 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 (almost always a no-op here).
17
+ 2. **Private-key or browser-extension config?** Bitcoin discriminates by an **explicit uppercase `type`** (`'PRIVATE_KEY'` | `'BROWSER_EXTENSION'`) — not field presence. PK = `{ type: 'PRIVATE_KEY', privateKey, network, addressType? }`; browser-extension = `{ type: 'BROWSER_EXTENSION', walletsKit, network }`.
18
+ 3. **Which message-signing scheme?** `signBip322Message` (modern, structured) vs `signEcdsaMessage` (legacy `signmessage`) — pick based on what the verifier expects.
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/architecture.md`](../integration/knowledge/architecture.md) — `BaseWalletProvider`, dual-config discriminants, shallow `defaults` merge, library-exports.
24
+ 3. [`../integration/knowledge/features/bitcoin.md`](../integration/knowledge/features/bitcoin.md) — full config union, `BitcoinWalletDefaults`, `BitcoinWalletsKit` shape, methods (`signTransaction` / `signEcdsaMessage` / `signBip322Message` / `sendBitcoin`), gotchas.
25
+ 4. Setup recipe → [`../integration/knowledge/recipes/setup-private-key.md`](../integration/knowledge/recipes/setup-private-key.md) or [`../integration/knowledge/recipes/setup-browser-extension.md`](../integration/knowledge/recipes/setup-browser-extension.md); then [`../integration/knowledge/recipes/sign-and-broadcast.md`](../integration/knowledge/recipes/sign-and-broadcast.md), [`../integration/knowledge/recipes/defaults-and-overrides.md`](../integration/knowledge/recipes/defaults-and-overrides.md).
26
+ 5. Lookups → [`../integration/knowledge/reference/provider-classes.md`](../integration/knowledge/reference/provider-classes.md), [`interfaces.md`](../integration/knowledge/reference/interfaces.md), [`chain-support.md`](../integration/knowledge/reference/chain-support.md).
27
+
28
+ ### Bitcoin-specific anti-patterns
29
+
30
+ - **Forgetting the `type` discriminant.** Bitcoin and Stellar use an **uppercase `type` field** — every other chain uses field presence. Easy to confuse.
31
+ - **Passing PSBT as hex to `signTransaction`.** Inputs are **base64**-encoded; in browser-extension mode the same base64 is forwarded to `walletsKit.signPsbt` (whose param is misleadingly named `psbtHex`).
32
+ - **Calling `sendBitcoin` unconditionally.** It's optional on the wallet kit — guard on its presence (Xverse / Unisat implement it; others don't).
33
+ - **Assuming the `addressType` default is network-dependent.** Optional in PK mode; when omitted the provider defaults it to `P2WPKH` (a constant — same on testnet and mainnet). Set it explicitly for P2TR / P2SH / P2PKH.
34
+ - **Mixing PK + browser-extension fields.** Discriminated union — don't `as`.
35
+
36
+ ## Migration workflow (port v1 → v2)
37
+
38
+ 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**.
39
+ 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)).
40
+ 3. Compile errors on `@sodax/sdk` / `@sodax/types` symbols → not this migration; load the `sodax-sdk` skill (migration mode).
41
+
42
+ ## Verification
43
+
44
+ 1. `pnpm tsc --noEmit` exits clean.
45
+ 2. Config sets `type` and uses exactly one variant; PSBTs are base64.
46
+ 3. No v1 deep imports from `@sodax/wallet-sdk-core/wallet-providers/` (migration only).
47
+
48
+ ## Related skills (same family)
49
+
50
+ Sibling chain skills follow the same shape — evm, solana, sui, stellar, icon, injective, near, stacks. For multi-chain or undecided work, load the broad [`sodax-wallet-sdk-core` skill](../SKILL.md).
51
+
52
+ ## Passing the provider into the SDK (different package family)
53
+
54
+ This skill *builds* the provider. For the concrete handoff, see [`../integration/knowledge/recipes/bridge-to-sdk.md`](../integration/knowledge/recipes/bridge-to-sdk.md). To execute SODAX operations, **also load the `sodax-sdk` skill (integration mode)** and pass it as `{ raw: false, walletProvider }`. React dapps get the provider via `useWalletProvider(...)` — **load the `sodax-wallet-sdk-react` skill** instead.
@@ -0,0 +1,54 @@
1
+ ---
2
+ name: sodax-wallet-sdk-core-evm
3
+ description: 'Granular skill for the @sodax/wallet-sdk-core v2 EVM wallet provider only — `EvmWalletProvider` (backed by viem), one class covering all 13 SODAX EVM chains — the Sonic hub plus 12 EVM spoke chains (Ethereum, Arbitrum, Base, BSC, Optimism, Polygon, Avalanche, HyperEVM, Lightlink, Redbelly, Kaia, Hedera). Use when a backend / Node script / CI / bot / non-React browser flow needs to instantiate an EVM provider directly and sign + broadcast — e.g. "instantiate EvmWalletProvider", "private-key EVM signing in Node", "EVM wallet provider for a bot", "sendTransaction from a script". Covers BOTH integration (write new v2 code) and migration (port v1 — almost a no-op at this surface: deep-import → barrel). Picks via Step 1. Links into the parent sodax-wallet-sdk-core knowledge tree. For React dapps use the sodax-wallet-sdk-react skill instead (get the typed provider via useWalletProvider).'
4
+ license: MIT
5
+ metadata:
6
+ version: '0.0.1'
7
+ author: sodax
8
+ ---
9
+
10
+ # EVM (`wallet-sdk-core` granular skill)
11
+
12
+ Granular skill for `EvmWalletProvider` — the low-level EVM wallet for backend / Node / non-React flows. One class covers all 13 SODAX EVM chains — the Sonic hub plus 12 EVM spoke chains — via `getEvmViemChain()`. Source-of-truth reference lives in the parent broad skill's knowledge tree; this file is the focused workflow only.
13
+
14
+ ## Step 1 — Clarify with user before coding
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?** EVM discriminates by **field presence** (no `type`): PK = `{ privateKey, chainId, rpcUrl? }` (Node / CI / bots); browser-extension = `{ walletClient, publicClient }` (pre-built by wagmi / the consumer). Mutually exclusive — pick one.
18
+ 3. **Which chain?** One `EvmWalletProvider` covers all 13 EVM chains (the Sonic hub plus 12 EVM spokes) via `chainId: EvmChainKey` (`ChainKeys.SONIC_MAINNET`, …).
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/architecture.md`](../integration/knowledge/architecture.md) — `BaseWalletProvider`, dual-config discriminants, shallow `defaults` merge, library-exports.
24
+ 3. [`../integration/knowledge/features/evm.md`](../integration/knowledge/features/evm.md) — full config union, `EvmWalletDefaults`, methods (`getWalletAddress` / `sendTransaction` / `waitForTransactionReceipt`), gotchas.
25
+ 4. Setup recipe → [`../integration/knowledge/recipes/setup-private-key.md`](../integration/knowledge/recipes/setup-private-key.md) (Node) or [`../integration/knowledge/recipes/setup-browser-extension.md`](../integration/knowledge/recipes/setup-browser-extension.md); then [`../integration/knowledge/recipes/sign-and-broadcast.md`](../integration/knowledge/recipes/sign-and-broadcast.md), [`../integration/knowledge/recipes/defaults-and-overrides.md`](../integration/knowledge/recipes/defaults-and-overrides.md), [`../integration/knowledge/recipes/library-exports.md`](../integration/knowledge/recipes/library-exports.md).
26
+ 5. Lookups → [`../integration/knowledge/reference/provider-classes.md`](../integration/knowledge/reference/provider-classes.md), [`interfaces.md`](../integration/knowledge/reference/interfaces.md), [`chain-support.md`](../integration/knowledge/reference/chain-support.md).
27
+
28
+ ### EVM-specific anti-patterns
29
+
30
+ - **Mixing PK + browser-extension fields.** The config is a discriminated union — don't `as` across variants.
31
+ - **Expecting `defaults` to deep-merge.** It's shallow — top-level keys overwrite wholesale.
32
+ - **Passing `publicClient` / `walletClient` / `transport` defaults in browser-extension mode.** They're ignored (provider logs a one-time warn); supply them only in PK mode.
33
+ - **Adding `viem` as a direct dep** when `WalletClient` / `PublicClient` etc. re-export from `@sodax/wallet-sdk-core`.
34
+ - **Assuming nonce management.** There is none — fire parallel sends and you collide; set `defaults.sendTransaction.nonce` or per-call `nonce`.
35
+
36
+ ## Migration workflow (port v1 → v2)
37
+
38
+ 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** (class / config names identical).
39
+ 2. The only mechanical change is 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)) and re-imported library types ([`library-exports.md`](../migration-v1-to-v2/knowledge/breaking-changes/library-exports.md)).
40
+ 3. If compile errors mention `@sodax/sdk` / `@sodax/types` symbols, it's **not** this migration — load the `sodax-sdk` skill (migration mode).
41
+
42
+ ## Verification
43
+
44
+ 1. `pnpm tsc --noEmit` exits clean.
45
+ 2. Config uses exactly one discriminant variant (no PK + browser mixing).
46
+ 3. No deep imports from v1's flat `wallet-providers/<chain>.ts` layout (migration only): `grep -rE "from '@sodax/wallet-sdk-core/wallet-providers/" src/` is empty.
47
+
48
+ ## Related skills (same family)
49
+
50
+ Sibling chain skills follow the same shape — bitcoin, solana, sui, stellar, icon, injective, near, stacks. For multi-chain or undecided work, load the broad [`sodax-wallet-sdk-core` skill](../SKILL.md).
51
+
52
+ ## Passing the provider into the SDK (different package family)
53
+
54
+ This skill *builds* the provider. For the concrete handoff, see [`../integration/knowledge/recipes/bridge-to-sdk.md`](../integration/knowledge/recipes/bridge-to-sdk.md). To execute SODAX operations with it, **also load the `sodax-sdk` skill (integration mode)** and pass the provider in the SDK call payload (`{ raw: false, walletProvider }`). React dapps should get the provider via `useWalletProvider(...)` — **load the `sodax-wallet-sdk-react` skill** instead.
@@ -0,0 +1,54 @@
1
+ ---
2
+ name: sodax-wallet-sdk-core-icon
3
+ description: 'Granular skill for the @sodax/wallet-sdk-core v2 ICON wallet provider only — `IconWalletProvider` (backed by icon-sdk-js; browser-extension mode talks to Hana via the ICONEX `CustomEvent` relay — an in-page message bridge). Use when a backend / Node script / CI / bot / non-React browser flow needs to instantiate an ICON provider directly and sign + broadcast — e.g. "instantiate IconWalletProvider", "ICON private-key signing in Node", "send an IcxCallTransaction", "Hana wallet bridge". Covers BOTH integration (write new v2 code) and migration (port v1 — almost a no-op at this surface: deep-import → barrel). Picks via Step 1. Links into the parent sodax-wallet-sdk-core knowledge tree. For React dapps use the sodax-wallet-sdk-react skill instead (get the typed provider via useWalletProvider).'
4
+ license: MIT
5
+ metadata:
6
+ version: '0.0.1'
7
+ author: sodax
8
+ ---
9
+
10
+ # ICON (`wallet-sdk-core` granular skill)
11
+
12
+ Granular skill for `IconWalletProvider` — the low-level ICON wallet for backend / Node / non-React flows. 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 (almost always a no-op here).
17
+ 2. **Private-key or browser-extension config?** ICON discriminates by **field presence** (no `type`): PK = `{ privateKey, rpcUrl }`; browser-extension = `{ walletAddress?, rpcUrl }` (talks to Hana via the ICONEX `CustomEvent` relay). `rpcUrl` is **required in both modes** — no public-RPC fallback.
18
+ 3. **Scripted determinism?** In browser-extension mode supply `walletAddress` yourself — the consumer provides it (or resolves it via the exported `requestAddress` helper). The provider never auto-resolves it; `getWalletAddress()` throws `Error('Wallet not initialized')` if it isn't set.
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/architecture.md`](../integration/knowledge/architecture.md) — `BaseWalletProvider`, dual-config discriminants, shallow `defaults` merge, library-exports.
24
+ 3. [`../integration/knowledge/features/icon.md`](../integration/knowledge/features/icon.md) — full config union, `IconWalletDefaults`, methods (`sendTransaction` / `waitForTransactionReceipt`), gotchas.
25
+ 4. Setup recipe → [`../integration/knowledge/recipes/setup-private-key.md`](../integration/knowledge/recipes/setup-private-key.md) or [`../integration/knowledge/recipes/setup-browser-extension.md`](../integration/knowledge/recipes/setup-browser-extension.md); then [`../integration/knowledge/recipes/sign-and-broadcast.md`](../integration/knowledge/recipes/sign-and-broadcast.md), [`../integration/knowledge/recipes/defaults-and-overrides.md`](../integration/knowledge/recipes/defaults-and-overrides.md).
26
+ 5. Lookups → [`../integration/knowledge/reference/provider-classes.md`](../integration/knowledge/reference/provider-classes.md), [`interfaces.md`](../integration/knowledge/reference/interfaces.md), [`chain-support.md`](../integration/knowledge/reference/chain-support.md).
27
+
28
+ ### ICON-specific anti-patterns
29
+
30
+ - **Omitting `rpcUrl`.** Required in both modes — there is no provider-level public-RPC fallback.
31
+ - **Assuming millisecond timestamps.** `timestampProvider` returns **microseconds** (default `Date.now() * 1000`).
32
+ - **Firing many parallel browser-extension calls.** The ICONEX `CustomEvent` relay is one shared window channel; the SDK serializes requests so at most one is in flight and concurrent calls no longer cross-resolve. They run one at a time (a pending signing prompt blocks the next), and each call times out after ~5 min if the wallet never answers.
33
+ - **Treating a contract (`cx…`) as the signer.** The wallet level is EOA-only (`IconEoaAddress`, `hx…`); contracts appear in tx params, not as the signer.
34
+ - **Mixing PK + browser-extension fields.** Discriminated union — don't `as`.
35
+
36
+ ## Migration workflow (port v1 → v2)
37
+
38
+ 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**.
39
+ 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)).
40
+ 3. Compile errors on `@sodax/sdk` / `@sodax/types` symbols → not this migration; load the `sodax-sdk` skill (migration mode).
41
+
42
+ ## Verification
43
+
44
+ 1. `pnpm tsc --noEmit` exits clean.
45
+ 2. `rpcUrl` is set; config uses exactly one discriminant variant.
46
+ 3. No v1 deep imports from `@sodax/wallet-sdk-core/wallet-providers/` (migration only).
47
+
48
+ ## Related skills (same family)
49
+
50
+ Sibling chain skills follow the same shape — evm, solana, sui, bitcoin, stellar, injective, near, stacks. For multi-chain or undecided work, load the broad [`sodax-wallet-sdk-core` skill](../SKILL.md).
51
+
52
+ ## Passing the provider into the SDK (different package family)
53
+
54
+ This skill *builds* the provider. For the concrete handoff, see [`../integration/knowledge/recipes/bridge-to-sdk.md`](../integration/knowledge/recipes/bridge-to-sdk.md). To execute SODAX operations, **also load the `sodax-sdk` skill (integration mode)** and pass it as `{ raw: false, walletProvider }`. React dapps get the provider via `useWalletProvider(...)` — **load the `sodax-wallet-sdk-react` skill** instead.
@@ -0,0 +1,54 @@
1
+ ---
2
+ name: sodax-wallet-sdk-core-injective
3
+ description: 'Granular skill for the @sodax/wallet-sdk-core v2 Injective wallet provider only — `InjectiveWalletProvider` (backed by @injectivelabs/sdk-ts + @injectivelabs/wallet-core MsgBroadcaster). Use when a backend / Node script / CI / bot / non-React browser flow needs to instantiate an Injective provider directly and build + broadcast msgs — e.g. "instantiate InjectiveWalletProvider", "Injective signing from a private key or mnemonic", "getRawTransaction then execute", "MsgBroadcaster setup". Covers BOTH integration (write new v2 code) and migration (port v1 — almost a no-op at this surface: deep-import → barrel). Picks via Step 1. Links into the parent sodax-wallet-sdk-core knowledge tree. For React dapps use the sodax-wallet-sdk-react skill instead (get the typed provider via useWalletProvider).'
4
+ license: MIT
5
+ metadata:
6
+ version: '0.0.1'
7
+ author: sodax
8
+ ---
9
+
10
+ # Injective (`wallet-sdk-core` granular skill)
11
+
12
+ Granular skill for `InjectiveWalletProvider` — the low-level Injective wallet for backend / Node / non-React flows. 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 (almost always a no-op here).
17
+ 2. **Secret (key/mnemonic) or browser-extension config?** Injective discriminates by **field presence**, but the credential variant is `SecretInjectiveWalletConfig`: `{ secret: { privateKey } | { mnemonics }, chainId, network }`; browser-extension = `{ msgBroadcaster }`. The credential is **nested under `secret`** — there is no top-level `privateKey`.
18
+ 3. **Account state correct?** Override `defaults.sequence` / `defaults.accountNumber` when the on-chain account differs from the zero defaults (else broadcasting fails with "incorrect account sequence").
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/architecture.md`](../integration/knowledge/architecture.md) — `BaseWalletProvider`, dual-config discriminants, shallow `defaults` merge, library-exports.
24
+ 3. [`../integration/knowledge/features/injective.md`](../integration/knowledge/features/injective.md) — full config union, `InjectiveWalletDefaults`, methods (`getRawTransaction` / `execute`), gotchas.
25
+ 4. Setup recipe → [`../integration/knowledge/recipes/setup-private-key.md`](../integration/knowledge/recipes/setup-private-key.md) or [`../integration/knowledge/recipes/setup-browser-extension.md`](../integration/knowledge/recipes/setup-browser-extension.md); then [`../integration/knowledge/recipes/sign-and-broadcast.md`](../integration/knowledge/recipes/sign-and-broadcast.md), [`../integration/knowledge/recipes/defaults-and-overrides.md`](../integration/knowledge/recipes/defaults-and-overrides.md).
26
+ 5. Lookups → [`../integration/knowledge/reference/provider-classes.md`](../integration/knowledge/reference/provider-classes.md), [`interfaces.md`](../integration/knowledge/reference/interfaces.md), [`chain-support.md`](../integration/knowledge/reference/chain-support.md).
27
+
28
+ ### Injective-specific anti-patterns
29
+
30
+ - **Passing a top-level `privateKey`.** Not accepted — wrap it as `{ secret: { privateKey } }` (or `{ secret: { mnemonics } }`). This was always the shape, in v1 too.
31
+ - **Treating `chainId` as endpoint selection.** `chainId` is required by the config type but is never consumed for network/endpoint selection — only `network` drives endpoints. A mismatch does not itself cause a runtime RPC failure; still pass a coherent pair (`Mainnet` + `injective-1`, `Testnet` + `injective-888`).
32
+ - **Relying on the zero `sequence` / `accountNumber` defaults.** Override when the on-chain account state differs.
33
+ - **Expecting `evmOptions` to do anything.** It's reserved/unused — declared to keep the config shape stable.
34
+ - **Mixing secret + browser-extension fields.** Discriminated union — don't `as`.
35
+
36
+ ## Migration workflow (port v1 → v2)
37
+
38
+ 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**.
39
+ 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)).
40
+ 3. Compile errors on `@sodax/sdk` / `@sodax/types` symbols → not this migration; load the `sodax-sdk` skill (migration mode).
41
+
42
+ ## Verification
43
+
44
+ 1. `pnpm tsc --noEmit` exits clean.
45
+ 2. Credential is nested under `secret`; both `chainId` and `network` are present (pass a coherent pair — only `network` selects endpoints).
46
+ 3. No v1 deep imports from `@sodax/wallet-sdk-core/wallet-providers/` (migration only).
47
+
48
+ ## Related skills (same family)
49
+
50
+ Sibling chain skills follow the same shape — evm, solana, sui, bitcoin, stellar, icon, near, stacks. For multi-chain or undecided work, load the broad [`sodax-wallet-sdk-core` skill](../SKILL.md).
51
+
52
+ ## Passing the provider into the SDK (different package family)
53
+
54
+ This skill *builds* the provider. For the concrete handoff, see [`../integration/knowledge/recipes/bridge-to-sdk.md`](../integration/knowledge/recipes/bridge-to-sdk.md). To execute SODAX operations, **also load the `sodax-sdk` skill (integration mode)** and pass it as `{ raw: false, walletProvider }`. React dapps get the provider via `useWalletProvider(...)` — **load the `sodax-wallet-sdk-react` skill** instead.
@@ -18,7 +18,7 @@ It is intentionally framework-agnostic — Node ≥ 20.12, browser, edge runtime
18
18
 
19
19
  | Chain family | Provider class | Underlying chain SDK |
20
20
  |---|---|---|
21
- | EVM (12 chains) | `EvmWalletProvider` | `viem` |
21
+ | EVM (13 chains) | `EvmWalletProvider` | `viem` |
22
22
  | Solana | `SolanaWalletProvider` | `@solana/web3.js` |
23
23
  | Sui | `SuiWalletProvider` | `@mysten/sui` + `@mysten/wallet-standard` |
24
24
  | Bitcoin | `BitcoinWalletProvider` | `bitcoinjs-lib` (+ `ecpair`, `secp256k1`) |
@@ -14,7 +14,7 @@ Before changing anything, gather context:
14
14
  # Runtime — Node script? React dApp? Edge runtime?
15
15
  cat <user>/package.json | grep -E '"type|"main|"module'
16
16
 
17
- # Node version — must be >= 18
17
+ # Node version — must be >= 20.12
18
18
  cat <user>/.nvmrc 2>/dev/null
19
19
  node --version
20
20
 
@@ -38,7 +38,7 @@ For **each** chain the user wants to integrate, decide between:
38
38
  | **Private-key** | A Node script, CI runner, indexer, or test that legitimately possesses a raw key. | The user pastes a real-looking key in a frontend file. Never embed a private key in a browser bundle. |
39
39
  | **Browser-extension** | A dApp where a wallet extension (MetaMask, Phantom, Xverse, Hana, Freighter, Leather, …) provides the signing primitives. | The user has neither a key nor a wallet adapter on hand. They probably want `@sodax/wallet-sdk-react` instead. |
40
40
 
41
- Ask the user which mode applies **before** writing code. Default to **private-key** for `apps/node`-style scripts and **browser-extension** for `apps/web`-style dApps.
41
+ Ask the user which mode applies **before** writing code. Default to **private-key** for Node scripts / CI / bots and **browser-extension** for browser dApps.
42
42
 
43
43
  ### 3. Apply the matching recipe
44
44
 
@@ -147,10 +147,10 @@ export type { MsgBroadcaster } from '@injectivelabs/wallet-core';
147
147
  export { Networks } from '@stellar/stellar-sdk';
148
148
 
149
149
  // Stacks (also re-exports the `PostConditionMode` enum)
150
- export { PostConditionMode } from '@stacks/transactions';
151
- export type { ClarityValue, PostConditionModeName } from '@stacks/transactions';
152
- export type { StacksNetwork } from '@stacks/network';
153
- export type { StacksProvider } from '@stacks/connect';
150
+ export { PostConditionMode } from '@sodax/libs/stacks/core';
151
+ export type { ClarityValue, PostConditionModeName } from '@sodax/libs/stacks/core';
152
+ export type { StacksNetwork } from '@sodax/libs/stacks/core';
153
+ export type { StacksProvider } from '@sodax/libs/stacks/connect';
154
154
 
155
155
  // Near
156
156
  export type { KeyPairString } from 'near-api-js';
@@ -207,6 +207,6 @@ For the full interface signatures, see [`reference/interfaces.md`](./reference/i
207
207
  - **`getEvmViemChain(key)` is exhaustively typed.** The default branch is a `never`-assertion — if `@sodax/types` adds a new `EvmChainKey` value, this function fails to typecheck until the case is added. That's by design.
208
208
  - **Sui browser-extension mode requires THREE objects** — `client`, `wallet`, and `account`. Many wallet adapters expose the first two but not the third. See [`features/sui.md`](./features/sui.md).
209
209
  - **Stellar requires `rpcUrl` in both modes** (technically optional, but defaults to a public RPC). Use a private RPC for production.
210
- - **Bitcoin in private-key mode also takes an optional `addressType`** (P2WPKH / P2TR / …). Browser-extension mode infers it from the wallet kit.
210
+ - **Bitcoin in private-key mode also takes an optional `addressType`** (P2WPKH / P2TR / …), defaulting to the `P2WPKH` constant when omitted. Browser-extension mode has no `addressType` field — the address returned by the wallet kit already has whatever type the wallet uses.
211
211
 
212
212
  Everything else is covered by [`features/`](./features/) on a per-chain basis.
@@ -20,7 +20,7 @@ type PrivateKeyBitcoinWalletConfig = {
20
20
  type: 'PRIVATE_KEY';
21
21
  privateKey: Hex; // `0x…` from @sodax/types
22
22
  network: 'TESTNET' | 'MAINNET';
23
- addressType?: BtcAddressType; // P2WPKH / P2TR / P2SH / P2PKH — default chosen by lib
23
+ addressType?: BtcAddressType; // P2WPKH / P2TR / P2SH / P2PKH — defaults to P2WPKH (constant, same on testnet/mainnet)
24
24
  defaults?: BitcoinWalletDefaults;
25
25
  };
26
26
 
@@ -89,7 +89,7 @@ Read directly via `this.defaults.defaultFinalize` — no `mergePolicy` / `mergeD
89
89
  ## Gotchas
90
90
 
91
91
  - **The discriminant is `type`, uppercase.** Bitcoin and Stellar use this style — every other chain uses field presence. Easy to confuse.
92
- - **`addressType` is optional in PK mode.** If you omit it, bitcoinjs picks a default (typically P2WPKH on mainnet). Browser-extension mode infers it from the wallet kit.
92
+ - **`addressType` is optional in PK mode.** If you omit it, the provider defaults it to `P2WPKH` (a constant — the same on testnet and mainnet, not network-dependent); set it explicitly for P2TR / P2SH / P2PKH. Browser-extension mode has no `addressType` field — the provider just uses the address `walletsKit.getAccounts()` returns, which carries whatever type the wallet uses.
93
93
  - **PSBT inputs are base64-encoded** when passed to `signTransaction`. In browser-extension mode the same base64 string is forwarded to `walletsKit.signPsbt`; the kit's parameter is misleadingly named `psbtHex` but receives base64. The kit returns a signed PSBT which the provider parses as hex when finalising.
94
94
  - **`sendBitcoin` is optional on the wallet kit.** Some browser-extension wallets (Xverse / Unisat) implement it; others don't. Guard on its presence.
95
95
  - **`signEcdsaMessage` vs `signBip322Message`** — choose based on what your verifier expects. BIP-322 is the more modern, structured signature spec; ECDSA is the legacy `signmessage` RPC behavior.
@@ -1,6 +1,6 @@
1
1
  # EVM — `EvmWalletProvider`
2
2
 
3
- Backed by [viem](https://viem.sh). One class covers all **12** SODAX EVM spoke chains via `getEvmViemChain()`.
3
+ Backed by [viem](https://viem.sh). One class covers **every** SODAX EVM spoke chain via `getEvmViemChain()` (see the table below).
4
4
 
5
5
  | | |
6
6
  |---|---|
@@ -8,7 +8,7 @@ Backed by [viem](https://viem.sh). One class covers all **12** SODAX EVM spoke c
8
8
  | Interface | `IEvmWalletProvider` (from `@sodax/types`) |
9
9
  | Discriminant style | **Field presence** (no `type` field) |
10
10
  | Underlying SDK | `viem` |
11
- | Supported chains | Sonic (hub), Ethereum, Arbitrum, Base, BSC, Optimism, Polygon, Avalanche, HyperEVM, Lightlink, Redbelly, Kaia |
11
+ | Supported chains | Sonic (hub), Ethereum, Arbitrum, Base, BSC, Optimism, Polygon, Avalanche, HyperEVM, Lightlink, Redbelly, Kaia, Hedera |
12
12
 
13
13
  ---
14
14
 
@@ -1,6 +1,6 @@
1
1
  # ICON — `IconWalletProvider`
2
2
 
3
- Backed by `icon-sdk-js`. Browser-extension mode targets the Hana wallet's `postMessage` JSON-RPC bridge.
3
+ Backed by `icon-sdk-js`. Browser-extension mode talks to the Hana wallet over the ICONEX relay — an in-page message bridge built on `window.dispatchEvent(new CustomEvent('ICONEX_RELAY_REQUEST', …))` + `window.addEventListener('ICONEX_RELAY_RESPONSE', …)`.
4
4
 
5
5
  | | |
6
6
  |---|---|
@@ -23,7 +23,7 @@ type PrivateKeyIconWalletConfig = {
23
23
  };
24
24
 
25
25
  type BrowserExtensionIconWalletConfig = {
26
- walletAddress?: IconEoaAddress; // `hx…` — optional; resolved at first sign call if omitted
26
+ walletAddress?: IconEoaAddress; // `hx…` — supplied by the consumer (the provider never auto-resolves it)
27
27
  rpcUrl: `http${string}`;
28
28
  defaults?: IconWalletDefaults;
29
29
  };
@@ -32,7 +32,7 @@ type BrowserExtensionIconWalletConfig = {
32
32
  | Mode discriminant | How to detect |
33
33
  |---|---|
34
34
  | Private-key | `'privateKey' in config` |
35
- | Browser-extension | `'walletAddress' in config` OR `!('privateKey' in config)` (defaults to browser-extension when key absent) |
35
+ | Browser-extension | `'walletAddress' in config` |
36
36
 
37
37
  > `rpcUrl` is **required in both modes** — ICON has no public-RPC fallback in the provider.
38
38
 
@@ -74,8 +74,8 @@ type IconWalletDefaults = {
74
74
 
75
75
  ## Gotchas
76
76
 
77
- - **Browser-extension mode talks to Hana via `window.postMessage`.** Events use a request-ID — collisions can occur if you fire many parallel calls; tune `defaults.jsonRpcId` if you control the consumer.
78
- - **`walletAddress` is optional in browser-extension mode.** When omitted, the provider issues a `REQUEST_ADDRESS` event on first use to resolve it. For deterministic behavior in scripts, pass it explicitly.
77
+ - **Browser-extension mode talks to Hana via the ICONEX relay** — `window.dispatchEvent(new CustomEvent('ICONEX_RELAY_REQUEST', …))` + `window.addEventListener('ICONEX_RELAY_RESPONSE', …)`, not `window.postMessage`. The relay is one shared window channel; the SDK serializes requests so at most one is in flight and concurrent calls no longer cross-resolve. They run one at a time, and each call times out after ~5 min if the wallet never answers.
78
+ - **`walletAddress` is optional in browser-extension mode, but the provider never auto-resolves it.** The consumer must supply it (or resolve it themselves via the exported `requestAddress` helper, which performs the ICONEX `REQUEST_ADDRESS` round-trip). If the wallet isn't set, `getWalletAddress()` throws `Error('Wallet not initialized')`.
79
79
  - **Address type is branded — `IconEoaAddress` (`hx…`) vs `IconAddress` (`hx… | cx…`).** EOA only at the wallet level; contracts (`cx…`) appear inside tx params, not as the signer.
80
80
  - **Timestamps are microseconds.** `timestampProvider` returns microseconds, not milliseconds — the default is `Date.now() * 1000`.
81
81
 
@@ -59,9 +59,11 @@ type InjectiveWalletDefaults = {
59
59
  | Method | Signature | Returns |
60
60
  |---|---|---|
61
61
  | `getWalletAddress` | `() => Promise<InjectiveEoaAddress>` | `inj1…` address |
62
- | `getWalletPubKey` | `() => Promise<string>` | hex pubkey |
62
+ | `getWalletPubKey` | `() => Promise<string>` | pubkey string |
63
63
  | `getRawTransaction` | `(…) => Promise<…>` | unsigned tx — useful for inspection / external signing |
64
64
  | `execute` | `(…) => Promise<…>` | broadcast result |
65
+ | `sendTransaction` | `(signedTxRaw: Uint8Array) => Promise<string>` | tx hash — broadcasts an already-signed proto-encoded Cosmos `TxRaw` |
66
+ | `signAndSendTransaction` | `(tx: InjectiveRawTransaction) => Promise<string>` | tx hash — signs + broadcasts an unsigned raw tx (the Swaps-API / SDK-handoff path) |
65
67
 
66
68
  `getRawTransaction` and `execute` merge `defaults.defaultFunds`, `defaults.defaultMemo`, `defaults.sequence`, `defaults.accountNumber` into the produced tx where the caller omits them.
67
69
 
@@ -80,7 +82,7 @@ type InjectiveWalletDefaults = {
80
82
 
81
83
  - **`secret` is mandatory in the PK variant.** A top-level `privateKey` field is **not** accepted — wrap in `{ secret: { privateKey } }`. Same shape in v1 and v2; if you see top-level `privateKey` in user code, it was always wrong.
82
84
  - **`evmOptions` is reserved.** It is declared in the type but **not currently read** by the provider. It exists to keep the config shape stable while EVM sidecar support on Injective is in development.
83
- - **`chainId` and `network` must agree.** Pass `Mainnet` + `injective-1` for mainnet, `Testnet` + `injective-888` for testnet. Mismatched pairs cause broadcasting errors that look like RPC failures.
85
+ - **`chainId` is required by the `SecretInjectiveWalletConfig` type, but only `network` drives endpoint selection.** The constructor reads `config.network` (`getNetworkEndpoints(config.network)`, `MsgBroadcasterWithPk({ network })`) — `config.chainId` is checked by the type guard but never consumed for network/endpoint selection, so a `chainId`/`network` mismatch does not itself produce a runtime RPC failure. Still pass a coherent pair (e.g. `Mainnet` + `injective-1`).
84
86
  - **`sequence` / `accountNumber` defaults are zero.** Override via `defaults` or per call when the on-chain account state differs (otherwise broadcasting fails with "incorrect account sequence").
85
87
 
86
88
  ---
@@ -60,7 +60,7 @@ type NearTxExecutionStatus =
60
60
  | `getRawTransaction` | `(params: CallContractParams) => Promise<NearRawTransaction>` | unsigned tx — useful for inspection |
61
61
  | `signAndSubmitTxn` | `(transaction: NearRawTransaction, options?: NearWalletDefaults) => Promise<string>` | tx hash |
62
62
 
63
- `signAndSubmitTxn` merges `defaults` (flat) over per-call `options`.
63
+ `signAndSubmitTxn` merges per-call `options` over `defaults` (flat, shallow).
64
64
 
65
65
  ---
66
66
 
@@ -63,7 +63,7 @@ type SolanaWalletDefaults = {
63
63
  | `getWalletAddress` | `() => Promise<string>` | base58 public key |
64
64
  | `getWalletBase58PublicKey` | `() => SolanaBase58PublicKey` | synchronous public key |
65
65
  | `sendTransaction` | `(rawTx: SolanaSerializedTransaction, options?: SendOptions) => Promise<string>` | signature |
66
- | `sendTransactionWithConfirmation` | `(rawTx, sendOptions?, confirmCommitment?) => Promise<string>` | signature, after confirmation |
66
+ | `sendTransactionWithConfirmation` | `(rawTx, optionsOrCommitment?: Commitment \| { send?: SendOptions; commitment?: Commitment }) => Promise<string>` | signature, after confirmation |
67
67
  | `waitForConfirmation` | `(signature, commitment?) => Promise<…>` | confirmation status |
68
68
  | `buildV0Txn` | `(rawInstructions: SolanaRawTransactionInstruction[]) => Promise<SolanaSerializedTransaction>` | serialised v0 transaction |
69
69
  | `getAssociatedTokenAddress` | `(mint) => Promise<SolanaBase58PublicKey>` | derived ATA |
@@ -72,7 +72,7 @@ type SolanaWalletDefaults = {
72
72
 
73
73
  Default slice merging:
74
74
  - `defaults.sendOptions` → merged into `sendTransaction(_, options)`.
75
- - `defaults.confirmCommitment` → falls back when `sendTransactionWithConfirmation(_, _, commit)` is undefined.
75
+ - `defaults.confirmCommitment` → falls back when the commitment resolved from `sendTransactionWithConfirmation`'s 2nd arg (the object's `commitment`, or a bare `Commitment`) is undefined.
76
76
  - `defaults.connectionCommitment` / `defaults.connectionConfig` → used at construction time only.
77
77
 
78
78
  ---
@@ -55,8 +55,8 @@ type StacksWalletDefaults = {
55
55
  | Method | Signature | Returns |
56
56
  |---|---|---|
57
57
  | `getWalletAddress` | `() => Promise<string>` | Stacks address (`SP…` / `ST…`) |
58
- | `getPublicKey` | `() => Promise<string>` | hex pubkey |
59
- | `sendTransaction` | `(params: StacksTransactionParams) => Promise<…>` | tx response |
58
+ | `getPublicKey` | `() => Promise<string>` | hex pubkey — **PK-mode only**; throws `'getPublicKey is only supported for private key wallet configuration'` for browser-extension configs |
59
+ | `sendTransaction` | `(params: StacksTransactionParams) => Promise<string>` | broadcast txid |
60
60
  | `readContract` | `(txParams: StacksTransactionParams) => Promise<ClarityValue>` | read-only call result |
61
61
  | `getBalance` | `(address: string) => Promise<bigint>` | STX micro-balance |
62
62
 
@@ -1,6 +1,6 @@
1
1
  # Stellar — `StellarWalletProvider`
2
2
 
3
- Backed by `@stellar/stellar-sdk` (`Horizon.Server` + Soroban primitives).
3
+ Backed by `@stellar/stellar-sdk` (`Horizon.Server` only — classic `Transaction` signing + Horizon polling; no Soroban surface).
4
4
 
5
5
  | | |
6
6
  |---|---|
@@ -65,7 +65,7 @@ Merge strategy: flat (`mergeDefaults`).
65
65
  |---|---|---|
66
66
  | `getWalletAddress` | `() => Promise<string>` | Stellar address |
67
67
  | `signTransaction` | `(tx: XDR) => Promise<XDR>` | signed XDR |
68
- | `waitForTransactionReceipt` | `(hash: string, options?: Partial<StellarWalletDefaults>) => Promise<…>` | tx result; respects `pollInterval` / `pollTimeout` |
68
+ | `waitForTransactionReceipt` | `(hash: string, options?: Pick<StellarWalletDefaults, 'pollInterval' \| 'pollTimeout'>) => Promise<…>` | tx result; respects `pollInterval` / `pollTimeout` (`networkPassphrase` is NOT accepted per-call) |
69
69
 
70
70
  ---
71
71
 
@@ -33,7 +33,7 @@ type BrowserExtensionSuiWalletConfig = {
33
33
  | Mode discriminant | How to detect |
34
34
  |---|---|
35
35
  | Private-key | `'mnemonics' in config` |
36
- | Browser-extension | `'client' in config` (also requires `wallet` + `account`) |
36
+ | Browser-extension | `'wallet' in config && 'account' in config` |
37
37
 
38
38
  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
39
 
@@ -20,7 +20,7 @@ pnpm add @sodax/sdk
20
20
 
21
21
  ---
22
22
 
23
- ## EVM (12 chains)
23
+ ## EVM (13 chains)
24
24
 
25
25
  ```ts
26
26
  import { EvmWalletProvider } from '@sodax/wallet-sdk-core';
@@ -101,10 +101,10 @@ grep -rn "from '@sodax/wallet-sdk-core" <script-dir>
101
101
 
102
102
  | Error | Cause | Fix |
103
103
  |---|---|---|
104
- | `Invalid EVM wallet config` | Mixed PK and browser-extension fields in one object | Pick **one** variant. Don't pass both `privateKey` and `walletClient`. |
104
+ | `Invalid EVM wallet config` | Config matches neither variant — no valid `privateKey` (`0x…`) and not both `walletClient` + `publicClient` | Supply exactly one valid variant. (Note: if you DO pass a valid `privateKey`, PK mode wins even if browser fields are also present — no throw.) |
105
105
  | TS2322: `'string'` is not assignable to `` `0x${string}` `` | Missing hex prefix or wrong type | Read from env with `as \`0x${string}\`` after a runtime check. |
106
106
  | TS: `Property 'secret' is missing` (Injective) | Used `privateKey` at top level | Wrap in `{ secret: { privateKey } }` or `{ secret: { mnemonics } }`. See [`../features/injective.md`](../features/injective.md). |
107
- | `Cannot find module 'viem/chains'` for unknown chain | Passed an EVM chain key not in `getEvmViemChain` | Use a `ChainKeys.*_MAINNET` constant — the function is exhaustive. |
107
+ | `Unsupported EVM chain key: <key>` | Passed an EVM chain key not handled by `getEvmViemChain` | Use a `ChainKeys.*_MAINNET` constant — `chainId` is typed `EvmChainKey` and the switch is exhaustive, so this is normally a compile-time error. |
108
108
 
109
109
  ---
110
110
 
@@ -14,6 +14,7 @@ For SDK-mediated flows (deposit, swap, bridge, lend, stake) see [`bridge-to-sdk.
14
14
  import type { EvmRawTransaction } from '@sodax/types';
15
15
 
16
16
  const tx: EvmRawTransaction = {
17
+ from: '0x…', // required — the sender (your wallet address)
17
18
  to: '0x…',
18
19
  value: 1_000_000_000_000_000n, // 0.001 ETH
19
20
  data: '0x',
@@ -129,7 +129,7 @@ describe.skipIf(!PK)('e2e — EVM testnet', () => {
129
129
  });
130
130
  ```
131
131
 
132
- `apps/node/src/tests/` in this repo follows this pattern — see those test files for live examples.
132
+ Apply the same pattern in your own test suite — construct the provider with a deterministic private key, then assert on the returned address / tx hash.
133
133
 
134
134
  ---
135
135
 
@@ -4,7 +4,7 @@ Chain families and spoke chain keys this package can sign for. Keys live in `@so
4
4
 
5
5
  ---
6
6
 
7
- ## EVM (one provider, 12 chains)
7
+ ## EVM (one provider, 13 chains)
8
8
 
9
9
  `EvmWalletProvider` covers every EVM spoke chain via `getEvmViemChain()`. The provider is exhaustive — adding a new `EvmChainKey` to `@sodax/types` requires updating `getEvmViemChain` (caught at compile time via a `never` assertion in the default branch).
10
10
 
@@ -22,6 +22,7 @@ Chain families and spoke chain keys this package can sign for. Keys live in `@so
22
22
  | `ChainKeys.LIGHTLINK_MAINNET` | `lightlinkPhoenix` |
23
23
  | `ChainKeys.REDBELLY_MAINNET` | `redbellyMainnet` |
24
24
  | `ChainKeys.KAIA_MAINNET` | `kaia` |
25
+ | `ChainKeys.HEDERA_MAINNET` | `hedera` |
25
26
 
26
27
  ---
27
28
 
@@ -38,7 +39,7 @@ Chain families and spoke chain keys this package can sign for. Keys live in `@so
38
39
  | NEAR | `NearWalletProvider` | `ChainKeys.NEAR_MAINNET` |
39
40
  | Stacks | `StacksWalletProvider` | `ChainKeys.STACKS_MAINNET` |
40
41
 
41
- > 20 spoke chains total = 12 EVM + 8 non-EVM. The hub chain (Sonic) is counted with EVM.
42
+ > 21 spoke chains total = 13 EVM + 8 non-EVM. The hub chain (Sonic) is counted with EVM.
42
43
 
43
44
  ---
44
45
 
@@ -68,7 +68,7 @@ Plus public field: `connection: Connection`.
68
68
  |---|---|
69
69
  | `getWalletAddress` | `() => Promise<string>` |
70
70
  | `signTransaction` | `(tx: XDR) => Promise<XDR>` |
71
- | `waitForTransactionReceipt` | `(hash: string, opts?: Partial<StellarWalletDefaults>) => Promise<…>` |
71
+ | `waitForTransactionReceipt` | `(hash: string, opts?: Pick<StellarWalletDefaults, 'pollInterval' | 'pollTimeout'>) => Promise<…>` |
72
72
 
73
73
  ---
74
74
 
@@ -89,9 +89,11 @@ Plus public field: `iconService: IconService`.
89
89
  | Method | Signature (abridged) |
90
90
  |---|---|
91
91
  | `getWalletAddress` | `() => Promise<InjectiveEoaAddress>` |
92
- | `getWalletPubKey` | `() => Promise<string>` |
93
- | `getRawTransaction` | `(…) => Promise<…>` |
94
- | `execute` | `(…) => Promise<…>` |
92
+ | `execute` | `(…) => Promise<InjectiveExecuteResponse>` |
93
+ | `sendTransaction?` | `(signedTxRaw: Uint8Array) => Promise<string>` |
94
+ | `signAndSendTransaction?` | `(tx: InjectiveRawTransaction) => Promise<string>` — the SDK / Swaps-API handoff path |
95
+ | `getWalletPubKey` *(class-only, not on interface)* | `() => Promise<string>` |
96
+ | `getRawTransaction` *(class-only, not on interface)* | `(…) => Promise<InjectiveRawTransaction>` |
95
97
 
96
98
  Plus public field: `wallet: InjectiveWallet`.
97
99
 
@@ -103,7 +105,7 @@ Plus public field: `wallet: InjectiveWallet`.
103
105
  |---|---|
104
106
  | `getWalletAddress` | `() => Promise<string>` |
105
107
  | `getRawTransaction` | `(params: CallContractParams) => Promise<NearRawTransaction>` |
106
- | `signAndSubmitTxn` | `(tx: NearRawTransaction, opts?: NearWalletDefaults) => Promise<string>` |
108
+ | `signAndSubmitTxn` | `(tx: NearRawTransaction) => Promise<string>` *(the concrete class adds an optional `opts?: NearWalletDefaults`)* |
107
109
 
108
110
  Plus public fields (PK mode only): `account?: Account`, `rpcProvider?: JsonRpcProvider`.
109
111
 
@@ -5,7 +5,7 @@ One row per chain. Use this when you know the chain and need to look up everythi
5
5
  | Chain | Class | Config union | Interface (`@sodax/types`) | Default merge helper | Discriminant |
6
6
  |---|---|---|---|---|---|
7
7
  | EVM | `EvmWalletProvider` | `EvmWalletConfig` | `IEvmWalletProvider` | `mergePolicy` (per-method) | Field presence (no `type`) |
8
- | Solana | `SolanaWalletProvider` | `SolanaWalletConfig` | `ISolanaWalletProvider` | `mergePolicy` (per-method) | Field presence (no `type`) |
8
+ | Solana | `SolanaWalletProvider` | `SolanaWalletConfig` | `ISolanaWalletProvider` | flat (read directly) | Field presence (no `type`) |
9
9
  | Sui | `SuiWalletProvider` | `SuiWalletConfig` | `ISuiWalletProvider` | `mergePolicy` (per-method) | Field presence — uses `mnemonics` |
10
10
  | Bitcoin | `BitcoinWalletProvider` | `BitcoinWalletConfig` | `IBitcoinWalletProvider` | `mergeDefaults` (flat) | **`type` field** (`'PRIVATE_KEY' \| 'BROWSER_EXTENSION'`) |
11
11
  | Stellar | `StellarWalletProvider` | `StellarWalletConfig` | `IStellarWalletProvider` | `mergeDefaults` (flat) | **`type` field** |
@@ -14,7 +14,7 @@ One row per chain. Use this when you know the chain and need to look up everythi
14
14
  | NEAR | `NearWalletProvider` | `NearWalletConfig` | `INearWalletProvider` | `mergeDefaults` (flat) | Field presence (no `type`) |
15
15
  | Stacks | `StacksWalletProvider` | `StacksWalletConfig` | `IStacksWalletProvider` | `mergeDefaults` (flat) | Field presence (no `type`) |
16
16
 
17
- > EVM, Solana, and Sui group their `defaults` per method (e.g. `defaults.sendTransaction`, `defaults.signAndExecuteTxn`). Every other chain has a flat `defaults` object. See [`../architecture.md`](../architecture.md) § `BaseWalletProvider`.
17
+ > EVM and Sui group their `defaults` per method (e.g. `defaults.sendTransaction`, `defaults.signAndExecuteTxn`) via `mergePolicy`. Every other chain (incl. Solana) has a flat `defaults` object. See [`../architecture.md`](../architecture.md) § `BaseWalletProvider`.
18
18
 
19
19
  ---
20
20
 
@@ -65,7 +65,7 @@ pnpm exec tsc --noEmit | grep -iE "wallet-sdk-core|WalletProvider|WalletConfig"
65
65
 
66
66
  ## Tip: typecheck-driven verification
67
67
 
68
- The repo includes `apps/node/` (Node scripts) and `apps/demo_v1/` (React demo). Running `pnpm exec tsc --noEmit` from either reveals breaking changes — but for wallet-sdk-core specifically, **none of those errors come from this package**. If you see `wallet-sdk-core` in the error output, it's most likely:
68
+ Running `pnpm exec tsc --noEmit` across your codebase reveals breaking changes — but for wallet-sdk-core specifically, **none of those errors come from this package**. If you see `wallet-sdk-core` in the error output, it's most likely:
69
69
 
70
70
  - A deep import from `src/...` (never supported; the v2 source layout differs).
71
71
  - Indirect — a broken `@sodax/sdk` / `@sodax/types` signature that includes a wallet-provider type.