@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.
Files changed (163) hide show
  1. package/.claude-plugin/plugin.json +1 -9
  2. package/AGENTS.md +119 -14
  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/money-market.md +6 -1
  28. package/skills/sodax-dapp-kit/integration/knowledge/features/swap.md +1 -1
  29. package/skills/sodax-dapp-kit/integration/knowledge/quickstart.md +2 -2
  30. package/skills/sodax-dapp-kit/integration/knowledge/recipes/README.md +1 -0
  31. package/skills/sodax-dapp-kit/integration/knowledge/recipes/backend-queries.md +23 -8
  32. package/skills/sodax-dapp-kit/integration/knowledge/recipes/bitcoin.md +8 -8
  33. package/skills/sodax-dapp-kit/integration/knowledge/recipes/leverage-yield.md +168 -0
  34. package/skills/sodax-dapp-kit/integration/knowledge/recipes/migration.md +1 -1
  35. package/skills/sodax-dapp-kit/integration/knowledge/recipes/setup.md +4 -4
  36. package/skills/sodax-dapp-kit/integration/knowledge/recipes/swap.md +1 -1
  37. package/skills/sodax-dapp-kit/integration/knowledge/recipes/wallet-connectivity.md +3 -0
  38. package/skills/sodax-dapp-kit/integration/knowledge/reference/glossary.md +1 -1
  39. package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md +67 -6
  40. package/skills/sodax-dapp-kit/integration/knowledge/reference/querykey-conventions.md +49 -0
  41. package/skills/sodax-dapp-kit/leverage-yield/SKILL.md +54 -0
  42. package/skills/sodax-dapp-kit/migration/SKILL.md +64 -0
  43. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md +1 -1
  44. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md +2 -2
  45. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/checklist.md +1 -1
  46. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/README.md +1 -1
  47. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/auxiliary-services.md +19 -10
  48. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/bitcoin.md +2 -2
  49. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/bridge.md +1 -1
  50. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/dex.md +1 -1
  51. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/reference/renamed-hooks.md +3 -3
  52. package/skills/sodax-dapp-kit/money-market/SKILL.md +61 -0
  53. package/skills/sodax-dapp-kit/staking/SKILL.md +60 -0
  54. package/skills/sodax-dapp-kit/swap/SKILL.md +64 -0
  55. package/skills/sodax-sdk/SKILL.md +11 -6
  56. package/skills/sodax-sdk/backend-api/SKILL.md +21 -15
  57. package/skills/sodax-sdk/bridge/SKILL.md +4 -0
  58. package/skills/sodax-sdk/dex/SKILL.md +5 -1
  59. package/skills/sodax-sdk/integration/knowledge/README.md +1 -1
  60. package/skills/sodax-sdk/integration/knowledge/ai-rules.md +1 -1
  61. package/skills/sodax-sdk/integration/knowledge/architecture.md +24 -21
  62. package/skills/sodax-sdk/integration/knowledge/chain-specifics.md +57 -10
  63. package/skills/sodax-sdk/integration/knowledge/features/README.md +2 -1
  64. package/skills/sodax-sdk/integration/knowledge/features/backend-api.md +27 -16
  65. package/skills/sodax-sdk/integration/knowledge/features/bridge.md +15 -14
  66. package/skills/sodax-sdk/integration/knowledge/features/dex.md +7 -7
  67. package/skills/sodax-sdk/integration/knowledge/features/leverage-yield.md +175 -0
  68. package/skills/sodax-sdk/integration/knowledge/features/migration.md +73 -28
  69. package/skills/sodax-sdk/integration/knowledge/features/money-market.md +20 -25
  70. package/skills/sodax-sdk/integration/knowledge/features/partner.md +27 -4
  71. package/skills/sodax-sdk/integration/knowledge/features/recovery.md +5 -4
  72. package/skills/sodax-sdk/integration/knowledge/features/staking.md +2 -2
  73. package/skills/sodax-sdk/integration/knowledge/features/swap.md +42 -24
  74. package/skills/sodax-sdk/integration/knowledge/features/swaps-api.md +171 -0
  75. package/skills/sodax-sdk/integration/knowledge/quickstart.md +1 -1
  76. package/skills/sodax-sdk/integration/knowledge/recipes/README.md +1 -0
  77. package/skills/sodax-sdk/integration/knowledge/recipes/backend-server-init.md +3 -3
  78. package/skills/sodax-sdk/integration/knowledge/recipes/gas-estimation.md +8 -4
  79. package/skills/sodax-sdk/integration/knowledge/recipes/initialize-sodax.md +34 -2
  80. package/skills/sodax-sdk/integration/knowledge/recipes/logging.md +102 -0
  81. package/skills/sodax-sdk/integration/knowledge/recipes/raw-tx-flow.md +28 -4
  82. package/skills/sodax-sdk/integration/knowledge/recipes/result-and-errors.md +1 -1
  83. package/skills/sodax-sdk/integration/knowledge/recipes/testing.md +7 -11
  84. package/skills/sodax-sdk/integration/knowledge/reference/README.md +1 -1
  85. package/skills/sodax-sdk/integration/knowledge/reference/chain-keys.md +40 -4
  86. package/skills/sodax-sdk/integration/knowledge/reference/error-codes.md +32 -9
  87. package/skills/sodax-sdk/integration/knowledge/reference/glossary.md +2 -2
  88. package/skills/sodax-sdk/integration/knowledge/reference/public-api.md +37 -4
  89. package/skills/sodax-sdk/leverage-yield/SKILL.md +50 -0
  90. package/skills/sodax-sdk/migration/SKILL.md +5 -1
  91. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/README.md +1 -1
  92. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/ai-rules.md +1 -1
  93. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/architecture.md +2 -2
  94. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/result-and-errors.md +3 -3
  95. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/type-system.md +6 -5
  96. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/checklist.md +1 -1
  97. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/backend-api.md +23 -23
  98. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/bridge.md +5 -5
  99. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/dex.md +2 -4
  100. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/migration.md +29 -27
  101. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/money-market.md +2 -2
  102. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/partner.md +10 -5
  103. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/recovery.md +2 -2
  104. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/staking.md +2 -2
  105. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/swap.md +22 -18
  106. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/reference/sodax-config.md +18 -16
  107. package/skills/sodax-sdk/money-market/SKILL.md +7 -3
  108. package/skills/sodax-sdk/partner/SKILL.md +4 -0
  109. package/skills/sodax-sdk/recovery/SKILL.md +5 -1
  110. package/skills/sodax-sdk/staking/SKILL.md +4 -0
  111. package/skills/sodax-sdk/swap/SKILL.md +8 -3
  112. package/skills/sodax-sdk/swaps-api/SKILL.md +62 -0
  113. package/skills/sodax-wallet-sdk-core/SKILL.md +7 -3
  114. package/skills/sodax-wallet-sdk-core/bitcoin/SKILL.md +54 -0
  115. package/skills/sodax-wallet-sdk-core/evm/SKILL.md +54 -0
  116. package/skills/sodax-wallet-sdk-core/icon/SKILL.md +54 -0
  117. package/skills/sodax-wallet-sdk-core/injective/SKILL.md +54 -0
  118. package/skills/sodax-wallet-sdk-core/integration/knowledge/README.md +1 -1
  119. package/skills/sodax-wallet-sdk-core/integration/knowledge/ai-rules.md +2 -2
  120. package/skills/sodax-wallet-sdk-core/integration/knowledge/architecture.md +5 -5
  121. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/bitcoin.md +2 -2
  122. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/evm.md +2 -2
  123. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/icon.md +5 -5
  124. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/injective.md +4 -2
  125. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/near.md +1 -1
  126. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/solana.md +2 -2
  127. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/stacks.md +2 -2
  128. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/stellar.md +2 -2
  129. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/sui.md +1 -1
  130. package/skills/sodax-wallet-sdk-core/integration/knowledge/quickstart.md +1 -1
  131. package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/setup-private-key.md +2 -2
  132. package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/sign-and-broadcast.md +1 -0
  133. package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/testing.md +1 -1
  134. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/chain-support.md +3 -2
  135. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/interfaces.md +7 -5
  136. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/provider-classes.md +2 -2
  137. package/skills/sodax-wallet-sdk-core/migration-v1-to-v2/knowledge/README.md +1 -1
  138. package/skills/sodax-wallet-sdk-core/near/SKILL.md +54 -0
  139. package/skills/sodax-wallet-sdk-core/solana/SKILL.md +54 -0
  140. package/skills/sodax-wallet-sdk-core/stacks/SKILL.md +53 -0
  141. package/skills/sodax-wallet-sdk-core/stellar/SKILL.md +54 -0
  142. package/skills/sodax-wallet-sdk-core/sui/SKILL.md +53 -0
  143. package/skills/sodax-wallet-sdk-react/SKILL.md +5 -3
  144. package/skills/sodax-wallet-sdk-react/bridge-to-sdk/SKILL.md +56 -0
  145. package/skills/sodax-wallet-sdk-react/connect/SKILL.md +59 -0
  146. package/skills/sodax-wallet-sdk-react/integration/knowledge/architecture.md +3 -3
  147. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/chain-detection.md +1 -1
  148. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/connect-button.md +1 -1
  149. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/sign-message.md +10 -10
  150. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/switch-chain.md +1 -1
  151. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/api-surface.md +4 -4
  152. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/chain-support.md +4 -4
  153. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/connectors.md +1 -1
  154. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/hooks.md +5 -4
  155. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/wallet-brands.md +1 -1
  156. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/ai-rules.md +1 -1
  157. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/recipes/multi-chain-modal.md +57 -31
  158. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/recipes/ssr-setup.md +24 -19
  159. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/reference/config.md +1 -1
  160. package/skills/sodax-wallet-sdk-react/sign-message/SKILL.md +51 -0
  161. package/skills/sodax-wallet-sdk-react/switch-chain/SKILL.md +51 -0
  162. package/skills/sodax-wallet-sdk-react/wallet-modal/SKILL.md +54 -0
  163. package/skills/sodax-wallet-sdk-react/walletconnect/SKILL.md +52 -0
@@ -0,0 +1,62 @@
1
+ ---
2
+ name: sodax-sdk-swaps-api
3
+ description: 'Granular skill for the @sodax/sdk v2 Swaps API client — `sodax.api.swaps` (class SwapsApiService), a typed HTTP client for the backend Swaps API v2 (`/swaps/*`, 21 endpoints: quote, deadline, allowance/approve, create-intent, intent submit/status/cancel/hash/packet/extra-data, limit orders, gas estimate, partner/solver fees, submit-tx + status). Every method returns Promise<Result<T>>, never throws, and validates the response. Use when the task calls the swaps backend directly (e.g. "get a swap quote from the Sodax backend", "sodax.api.swaps", "submit swap tx", "createIntent via the backend API", "poll submit-tx status", "swaps API v2", "point swaps at a custom endpoint"). For the higher-level end-to-end swap orchestrator use the `swap` skill instead. Skill links into the parent sodax-sdk knowledge tree.'
4
+ ---
5
+
6
+ # Swaps API (Core SDK granular skill)
7
+
8
+ Granular skill for `sodax.api.swaps` (class `SwapsApiService`) — the typed HTTP client for the backend
9
+ **Swaps API v2** (`/swaps/*`). `sodax.api` is an alias for `sodax.backendApi`; `.swaps` is the swaps
10
+ client. 21 endpoints, one method each; every method returns `Promise<Result<T>>` (never throws) and
11
+ validates the response. Errors carry `feature: 'backend'`, `context.api: 'swaps'`, `context.endpoint`.
12
+
13
+ > Lower-level than `sodax.swaps`: this is the raw backend HTTP surface. For the end-to-end
14
+ > create→relay→post-execution swap orchestrator, use the [`swap`](../swap/SKILL.md) skill.
15
+
16
+ ## Step 1 — Clarify with user before coding
17
+
18
+ 1. **Which endpoint(s)?** Tokens · quote/deadline · allowance/approve/create-intent · intent lifecycle
19
+ (submit/status/cancel/hash/packet/extra-data/fill/get) · limit-orders/gas/fees · submit-tx/status.
20
+ 2. **Orchestrator or raw API?** If the user just wants "do a swap", prefer `sodax.swaps` (the `swap`
21
+ skill). Use `sodax.api.swaps` when they need a single backend call (a quote, a fee, a status poll) or
22
+ are building their own flow.
23
+ 3. **Custom endpoint?** Does the swaps API live at a different host than the base backend API? If so, the
24
+ `CustomApiConfig` variant is needed (see anti-patterns + the feature doc).
25
+
26
+ ## Integration workflow
27
+
28
+ 1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT (read first).
29
+ 2. [`../integration/knowledge/features/swaps-api.md`](../integration/knowledge/features/swaps-api.md) — the full 21-endpoint client: signatures, wire shapes (bigint vs decimal string), common call shapes (quote, create-intent, submit-tx + status), per-call overrides, custom endpoint.
30
+ 3. For the end-to-end swap flow that wraps these calls → [`../integration/knowledge/features/swap.md`](../integration/knowledge/features/swap.md); for the sibling read client (`sodax.backendApi`) → [`../integration/knowledge/features/backend-api.md`](../integration/knowledge/features/backend-api.md).
31
+ 4. Errors are `Result<T, SodaxError<'EXTERNAL_API_ERROR'>>` → [`../integration/knowledge/recipes/result-and-errors.md`](../integration/knowledge/recipes/result-and-errors.md) and [`../integration/knowledge/reference/error-codes.md`](../integration/knowledge/reference/error-codes.md).
32
+
33
+ ### Swaps-API-specific anti-patterns
34
+
35
+ - **`try/catch` for failures.** Every method returns `Result<T>` — branch on `result.ok`. `catch` won't fire for HTTP/timeout/validation failures.
36
+ - **Passing the `RelayExtraData` object** to `submitTx`'s `relayData`. The field is a `string` — pass `relayData.payload`.
37
+ - **Stringifying `intent` numerics yourself.** `IntentRequestV2` fields are `bigint`; the client serializes them to decimal strings — pass the bigint intent through as-is.
38
+ - **Calling `getSubmitTxStatus` with only `txHash`.** Both `txHash` AND `srcChainKey` are required.
39
+ - **Confusing `sodax.api.swaps` with `sodax.swaps`.** The former is the backend HTTP client; the latter is the on-chain intent orchestrator.
40
+
41
+ ## Migration workflow (v1 → v2)
42
+
43
+ The typed `sodax.api.swaps` client is **v2-new** (v1 had no equivalent typed swaps client — quotes went
44
+ through the solver and submit-tx lived on `sodax.backendApi.submitSwapTx`). The relevant v1 → v2 deltas it
45
+ builds on are covered in the existing swap + backend-api migration docs:
46
+
47
+ 1. [`../migration-v1-to-v2/knowledge/features/swap.md`](../migration-v1-to-v2/knowledge/features/swap.md) — create-intent / submit-tx request-shape changes (`srcChainId` → `srcChainKey`, `relayData` object → string, bigint intent).
48
+ 2. [`../migration-v1-to-v2/knowledge/features/backend-api.md`](../migration-v1-to-v2/knowledge/features/backend-api.md) — submit-tx moved off `BackendApiService` onto `sodax.api.swaps.submitTx`, and the `Result`-wrapping contract.
49
+
50
+ ## Verification
51
+
52
+ 1. `pnpm tsc --noEmit` clean.
53
+ 2. Every `await sodax.api.swaps.<method>(...)` call site has `if (!result.ok)`.
54
+ 3. `submitTx.relayData` is `relayData.payload` (string); `getSubmitTxStatus` passes both `txHash` and `srcChainKey`.
55
+ 4. Intent-bearing bodies pass the `bigint` `IntentRequestV2` through unmodified (no manual `.toString()`).
56
+
57
+ ## Related granular skills (same family)
58
+
59
+ - [`../swap/SKILL.md`](../swap/SKILL.md) — the end-to-end swap orchestrator (`sodax.swaps`) that wraps these backend calls.
60
+ - [`../backend-api/SKILL.md`](../backend-api/SKILL.md) — the sibling `sodax.backendApi` read client (intent / orderbook / money-market reads + config).
61
+
62
+ For multi-feature tasks, load the broad [`sodax-sdk` skill](../SKILL.md).
@@ -1,6 +1,10 @@
1
1
  ---
2
2
  name: sodax-wallet-sdk-core
3
- description: 'INTEGRATION (write NEW code) — @sodax/wallet-sdk-core is the low-level multi-chain wallet layer (one provider class per chain family across 9 chain types: EVM, Solana, Sui, Bitcoin, Stellar, ICON, Injective, NEAR, Stacks). Each class accepts either a private-key config (Node scripts, CI, bots, indexers) or a browser-extension config (custom non-React browser flows) and signs + broadcasts transactions. Use whenever a backend, script, test, or non-React browser flow needs to instantiate a wallet provider directly — `EvmWalletProvider`, `SolanaWalletProvider`, etc. Triggers on "instantiate EvmWalletProvider", "sign a tx from a Node script", "wallet provider for backend", "private-key signing", "wallet-sdk-core setup", any `*WalletProvider` class name. For React dapps prefer `sodax-wallet-sdk-react` instead — most React consumers never touch this package directly and get a typed `IXxxWalletProvider` via `useWalletProvider(...)`. MIGRATION (port v1 → v2) — v1 → v2 changes are additive (same class names, same config-type names, same config shapes). The only mechanical migration is replacing deep imports from v1''s flat `wallet-providers/<chain>.ts` layout with barrel imports, plus optionally adopting the new `defaults` field and re-imported library types. Triggers on imports from `@sodax/wallet-sdk-core/wallet-providers/…`, bumping from an older RC, or adopting new additive `defaults` / `*WalletDefaults` / `*Policy` fields. Most projects don''t need a wallet-sdk-core migration — the real migration target is usually `@sodax/sdk` or `@sodax/types`. Load this skill if EITHER applies; the body gates by mode.'
3
+ description: 'Sign and broadcast SODAX transactions from a backend, script, CI, bot, or non-React app with @sodax/wallet-sdk-core — one wallet-provider class per chain family (EVM, Solana, Sui, Bitcoin, Stellar, ICON, Injective, NEAR, Stacks). INTEGRATION (write NEW code) — the low-level multi-chain wallet layer (one provider class per chain family across 9 chain types). Each class accepts either a private-key config (Node scripts, CI, bots, indexers) or a browser-extension config (custom non-React browser flows) and signs + broadcasts transactions. Use whenever a backend, script, test, or non-React browser flow needs to instantiate a wallet provider directly — `EvmWalletProvider`, `SolanaWalletProvider`, etc. Triggers on "instantiate EvmWalletProvider", "sign a tx from a Node script", "wallet provider for backend", "private-key signing", "wallet-sdk-core setup", any `*WalletProvider` class name. For React dapps prefer `sodax-wallet-sdk-react` instead — most React consumers never touch this package directly and get a typed `IXxxWalletProvider` via `useWalletProvider(...)`. MIGRATION (port v1 → v2) — v1 → v2 changes are additive (same class names, same config-type names, same config shapes). The only mechanical migration is replacing deep imports from v1''s flat `wallet-providers/<chain>.ts` layout with barrel imports, plus optionally adopting the new `defaults` field and re-imported library types. Triggers on imports from `@sodax/wallet-sdk-core/wallet-providers/…`, bumping from an older RC, or adopting new additive `defaults` / `*WalletDefaults` / `*Policy` fields. Most projects don''t need a wallet-sdk-core migration — the real migration target is usually `@sodax/sdk` or `@sodax/types`. Load this skill if EITHER applies; the body gates by mode.'
4
+ license: MIT
5
+ metadata:
6
+ version: '0.0.1'
7
+ author: sodax
4
8
  ---
5
9
 
6
10
  # When to use this skill
@@ -27,7 +31,7 @@ Direct usage of `@sodax/wallet-sdk-core` is the right choice for:
27
31
  ### Workflow
28
32
 
29
33
  1. Read [`integration/knowledge/ai-rules.md`](./integration/knowledge/ai-rules.md) — DO / DON'T + workflow + stop conditions.
30
- 2. Read [`integration/knowledge/architecture.md`](./integration/knowledge/architecture.md) — mental model: `BaseWalletProvider`, dual-config discriminants (`{ type: 'PRIVATE_KEY', … }` vs `{ type: 'BROWSER_EXTENSION', … }`), shallow `defaults` merge, library-exports.
34
+ 2. Read [`integration/knowledge/architecture.md`](./integration/knowledge/architecture.md) — mental model: `BaseWalletProvider`, dual-config discriminants (Bitcoin/Stellar via an explicit `type` field, every other chain via field presence), shallow `defaults` merge, library-exports.
31
35
  3. Read [`integration/knowledge/quickstart.md`](./integration/knowledge/quickstart.md) — copy-paste minimal example for the chain you need.
32
36
  4. For your chain, read [`integration/knowledge/features/`](./integration/knowledge/features/) — per-chain config table + methods + gotchas (one file per chain family).
33
37
  5. Task-specific recipes → [`integration/knowledge/recipes/`](./integration/knowledge/recipes/) — `setup-private-key.md`, `setup-browser-extension.md`, `sign-and-broadcast.md`, `defaults-and-overrides.md`, `library-exports.md`, `bridge-to-sdk.md` (pass provider to `@sodax/sdk`).
@@ -35,7 +39,7 @@ Direct usage of `@sodax/wallet-sdk-core` is the right choice for:
35
39
 
36
40
  ### Conventions to follow (integration)
37
41
 
38
- - **Dual-config discriminant.** Every chain's provider config has a `type` discriminator: `'PRIVATE_KEY'` (Node / scripts) or `'BROWSER_EXTENSION'` (consumer dApps). Pick one — don't merge them.
42
+ - **Dual-config discriminant.** **Bitcoin and Stellar** configs carry an explicit `type` discriminator (`'PRIVATE_KEY'` for Node / scripts or `'BROWSER_EXTENSION'` for consumer dApps); **every other chain** (EVM, Solana, Sui, ICON, Injective, NEAR, Stacks) discriminates by field presence (e.g. `privateKey` vs `walletClient`/`wallet`). Either way, pick ONE variant — don't merge them.
39
43
  - **`defaults` is a shallow merge.** Each provider accepts a `defaults` field for per-method overrides (e.g. `waitForTransactionReceipt`, `gasPrice`). The merge into the per-call options is **shallow**, not deep. Top-level keys overwrite wholesale.
40
44
  - **Use barrel imports**, not deep imports. Import classes from `@sodax/wallet-sdk-core`, not from `@sodax/wallet-sdk-core/wallet-providers/<chain>.ts`.
41
45
  - **Re-import chain SDK types from the barrel.** `@sodax/wallet-sdk-core` re-exports the types you need (e.g. `WalletClient` from viem, `SuiClient` from `@mysten/sui`). Don't add the underlying SDK as a direct dep — risks version skew.
@@ -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',