@sodax/skills 2.2.0-rc.8 → 2.3.0-rc.1

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 (63) hide show
  1. package/AGENTS.md +11 -10
  2. package/README.md +5 -5
  3. package/package.json +6 -5
  4. package/skills/sodax-build/SKILL.md +3 -3
  5. package/skills/sodax-build/knowledge/README.md +1 -1
  6. package/skills/sodax-build/knowledge/feature-catalog.md +4 -0
  7. package/skills/sodax-build/knowledge/glossary.md +1 -0
  8. package/skills/sodax-build/knowledge/handoff.md +3 -0
  9. package/skills/sodax-build/knowledge/interview-guide.md +1 -0
  10. package/skills/sodax-dapp-kit/SKILL.md +23 -5
  11. package/skills/sodax-dapp-kit/auxiliary-services/SKILL.md +4 -1
  12. package/skills/sodax-dapp-kit/bridge/SKILL.md +1 -1
  13. package/skills/sodax-dapp-kit/integration/knowledge/ai-rules.md +3 -0
  14. package/skills/sodax-dapp-kit/integration/knowledge/architecture.md +18 -4
  15. package/skills/sodax-dapp-kit/integration/knowledge/features/auxiliary-services.md +31 -1
  16. package/skills/sodax-dapp-kit/integration/knowledge/features/bridge.md +8 -0
  17. package/skills/sodax-dapp-kit/integration/knowledge/features/leverage-yield.md +17 -3
  18. package/skills/sodax-dapp-kit/integration/knowledge/features/swap.md +24 -0
  19. package/skills/sodax-dapp-kit/integration/knowledge/recipes/README.md +1 -0
  20. package/skills/sodax-dapp-kit/integration/knowledge/recipes/bridge.md +2 -0
  21. package/skills/sodax-dapp-kit/integration/knowledge/recipes/dex.md +23 -8
  22. package/skills/sodax-dapp-kit/integration/knowledge/recipes/leverage-yield-product-anatomy.md +150 -0
  23. package/skills/sodax-dapp-kit/integration/knowledge/recipes/leverage-yield.md +122 -38
  24. package/skills/sodax-dapp-kit/integration/knowledge/recipes/swap.md +141 -1
  25. package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md +14 -3
  26. package/skills/sodax-dapp-kit/integration/knowledge/reference/public-api.md +1 -1
  27. package/skills/sodax-dapp-kit/integration/knowledge/reference/querykey-conventions.md +8 -0
  28. package/skills/sodax-dapp-kit/leverage-yield/SKILL.md +27 -10
  29. package/skills/sodax-dapp-kit/swap/SKILL.md +3 -3
  30. package/skills/sodax-sdk/SKILL.md +2 -1
  31. package/skills/sodax-sdk/bridge/SKILL.md +3 -1
  32. package/skills/sodax-sdk/integration/knowledge/ai-rules.md +3 -0
  33. package/skills/sodax-sdk/integration/knowledge/architecture.md +1 -1
  34. package/skills/sodax-sdk/integration/knowledge/features/bridge-api.md +5 -3
  35. package/skills/sodax-sdk/integration/knowledge/features/bridge.md +8 -0
  36. package/skills/sodax-sdk/integration/knowledge/features/leverage-yield.md +81 -12
  37. package/skills/sodax-sdk/integration/knowledge/features/swap.md +68 -2
  38. package/skills/sodax-sdk/integration/knowledge/features/swaps-api.md +56 -2
  39. package/skills/sodax-sdk/integration/knowledge/reference/error-codes.md +27 -1
  40. package/skills/sodax-sdk/integration/knowledge/reference/public-api.md +30 -1
  41. package/skills/sodax-sdk/leverage-yield/SKILL.md +16 -8
  42. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/architecture.md +1 -1
  43. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/reference/sodax-config.md +9 -1
  44. package/skills/sodax-sdk/swap/SKILL.md +3 -1
  45. package/skills/sodax-sdk/swaps-api/SKILL.md +3 -2
  46. package/skills/sodax-wallet-sdk-core/SKILL.md +20 -2
  47. package/skills/sodax-wallet-sdk-core/evm/SKILL.md +2 -1
  48. package/skills/sodax-wallet-sdk-core/integration/knowledge/README.md +1 -1
  49. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/evm.md +6 -0
  50. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/interfaces.md +4 -1
  51. package/skills/sodax-wallet-sdk-core/migration-v1-to-v2/knowledge/README.md +1 -1
  52. package/skills/sodax-wallet-sdk-react/SKILL.md +20 -3
  53. package/skills/sodax-wallet-sdk-react/integration/knowledge/README.md +2 -1
  54. package/skills/sodax-wallet-sdk-react/integration/knowledge/ai-rules.md +2 -0
  55. package/skills/sodax-wallet-sdk-react/integration/knowledge/architecture.md +10 -6
  56. package/skills/sodax-wallet-sdk-react/integration/knowledge/examples/05-privy-email-login.tsx +157 -0
  57. package/skills/sodax-wallet-sdk-react/integration/knowledge/examples/README.md +1 -0
  58. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/privy-email-login.md +111 -0
  59. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/api-surface.md +14 -0
  60. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/chain-support.md +1 -1
  61. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/README.md +1 -1
  62. package/skills/sodax-wallet-sdk-react/privy/SKILL.md +53 -0
  63. package/skills/sodax-wallet-sdk-react/wallet-modal/SKILL.md +1 -0
@@ -1,6 +1,6 @@
1
1
  ---
2
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 (`/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.'
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 (`/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", "approve and send the swap in one signature"). For the higher-level end-to-end swap orchestrator use the `swap` skill instead. Skill links into the parent sodax-sdk knowledge tree.'
4
4
  ---
5
5
 
6
6
  # Swaps API (Core SDK granular skill)
@@ -26,7 +26,7 @@ validates the response. Errors carry `feature: 'backend'`, `context.api: 'swaps'
26
26
  ## Integration workflow
27
27
 
28
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.
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, and sending the approval and the intent tx in one EIP-5792 signature.
30
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
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
32
 
@@ -36,6 +36,7 @@ validates the response. Errors carry `feature: 'backend'`, `context.api: 'swaps'
36
36
  - **`try/catch` for failures.** Every method returns `Result<T>` — branch on `result.ok`. `catch` won't fire for HTTP/timeout/validation failures.
37
37
  - **Passing the `RelayExtraData` object** to `submitTx`'s `relayData`. The field is a `string` — pass `relayData.payload`.
38
38
  - **Stringifying `intent` numerics yourself.** `IntentRequestV2` fields are `bigint`; the client serializes them to decimal strings — pass the bigint intent through as-is.
39
+ - **Approving, waiting, then signing the intent tx on an EVM source.** Where the wallet supports EIP-5792, `sendApprovalBatch` sends `[resetTx?, tx, intentTx]` as one batch (one signature): `features/swaps-api.md` § "Approve and send the intent in one signature". Never re-send a batch that returned `ATOMIC_BATCH_UNCONFIRMED`; resume it with `confirmApprovalBatch`.
39
40
  - **Calling `getSubmitTxStatus` with only `txHash`.** Both `txHash` AND `srcChainKey` are required.
40
41
  - **Confusing `sodax.api.swaps` with `sodax.swaps`.** The former is the backend HTTP client; the latter is the on-chain intent orchestrator.
41
42
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: sodax-wallet-sdk-core
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.'
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) — each class accepts a private-key config (Node scripts, CI, bots, indexers) or a browser-extension config (custom non-React browser flows). Use whenever non-React code must instantiate a wallet provider directly. 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` — React consumers get a typed `IXxxWalletProvider` via `useWalletProvider(...)`. MIGRATION (port v1 → v2) — changes are additive (same class, config-type and config-shape names). The only mechanical step 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 `defaults` / `*WalletDefaults` / `*Policy` fields. Most projects need no wallet-sdk-core migration — the real target is usually `@sodax/sdk` or `@sodax/types`. Load this skill if EITHER applies; the body gates by mode.'
4
4
  license: MIT
5
5
  metadata:
6
6
  version: '0.0.1'
@@ -18,6 +18,24 @@ AGENTS.md routes you here when you're working with `@sodax/wallet-sdk-core` v2
18
18
 
19
19
  For React consumers → use `sodax-wallet-sdk-react` (they get the typed wallet provider via `useWalletProvider(...)` and pass it to `@sodax/sdk` calls).
20
20
 
21
+ ## Prefer a granular skill if the chain is known
22
+
23
+ If the task targets one chain family, load its granular skill instead of this broad one. It covers that provider's config, methods and gotchas, for both integration and migration.
24
+
25
+ | Chain family | Granular skill | Trigger phrases |
26
+ |---|---|---|
27
+ | EVM (Sonic hub + every EVM spoke) | [`./evm/SKILL.md`](./evm/SKILL.md) | "instantiate EvmWalletProvider", "viem wallet for Sonic / Base / Arbitrum" |
28
+ | Solana | [`./solana/SKILL.md`](./solana/SKILL.md) | "SolanaWalletProvider", "sign a Solana tx from Node" |
29
+ | Sui | [`./sui/SKILL.md`](./sui/SKILL.md) | "SuiWalletProvider", "Sui signing from a script" |
30
+ | Bitcoin (PSBT) | [`./bitcoin/SKILL.md`](./bitcoin/SKILL.md) | "BitcoinWalletProvider", "sign a PSBT" |
31
+ | Stellar | [`./stellar/SKILL.md`](./stellar/SKILL.md) | "StellarWalletProvider", "Stellar signing from a backend" |
32
+ | ICON | [`./icon/SKILL.md`](./icon/SKILL.md) | "IconWalletProvider", "Hana wallet relay" |
33
+ | Injective | [`./injective/SKILL.md`](./injective/SKILL.md) | "InjectiveWalletProvider", "Injective MsgBroadcaster" |
34
+ | NEAR | [`./near/SKILL.md`](./near/SKILL.md) | "NearWalletProvider", "NEAR signing from Node" |
35
+ | Stacks | [`./stacks/SKILL.md`](./stacks/SKILL.md) | "StacksWalletProvider", "Stacks signing from a script" |
36
+
37
+ Load this broad skill (keep reading below) when the task spans several chain families or the chain is undecided.
38
+
21
39
  ---
22
40
 
23
41
  ## Integration mode (writing new v2 code)
@@ -33,7 +51,7 @@ Direct usage of `@sodax/wallet-sdk-core` is the right choice for:
33
51
  1. Read [`integration/knowledge/ai-rules.md`](./integration/knowledge/ai-rules.md) — DO / DON'T + workflow + stop conditions.
34
52
  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.
35
53
  3. Read [`integration/knowledge/quickstart.md`](./integration/knowledge/quickstart.md) — copy-paste minimal example for the chain you need.
36
- 4. For your chain, read [`integration/knowledge/features/`](./integration/knowledge/features/) — per-chain config table + methods + gotchas (one file per chain family).
54
+ 4. For your chain, read [`integration/knowledge/features/`](./integration/knowledge/features/) — per-chain config table + methods + gotchas, one file per chain family: `evm.md`, `solana.md`, `sui.md`, `bitcoin.md`, `stellar.md`, `icon.md`, `injective.md`, `near.md`, `stacks.md`.
37
55
  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`).
38
56
  6. Lookups → [`integration/knowledge/reference/`](./integration/knowledge/reference/) — public API, provider classes, interfaces (`IXxxWalletProvider`), chain support, glossary.
39
57
 
@@ -21,7 +21,7 @@ Granular skill for `EvmWalletProvider` — the low-level EVM wallet for backend
21
21
 
22
22
  1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DON'T (read first).
23
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.
24
+ 3. [`../integration/knowledge/features/evm.md`](../integration/knowledge/features/evm.md) — full config union, `EvmWalletDefaults`, methods (`getWalletAddress` / `sendTransaction` / `waitForTransactionReceipt`, plus the EIP-5792 batch trio `getAtomicBatchSupport` / `sendAtomicBatch` / `waitForBatch`), gotchas.
25
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
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
27
 
@@ -32,6 +32,7 @@ Granular skill for `EvmWalletProvider` — the low-level EVM wallet for backend
32
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
33
  - **Adding `viem` as a direct dep** when `WalletClient` / `PublicClient` etc. re-export from `@sodax/wallet-sdk-core`.
34
34
  - **Assuming nonce management.** There is none — fire parallel sends and you collide; set `defaults.sendTransaction.nonce` or per-call `nonce`.
35
+ - **Expecting EIP-5792 batches from a private-key provider.** `getAtomicBatchSupport` is always `'unsupported'` there and `sendAtomicBatch` throws — batching needs a connected wallet (browser-extension mode).
35
36
  - **Skipping `expectedChainId` on chain-specific sends.** Without it the tx goes to whatever chain the wallet is on; with it a mismatch throws and nothing is sent.
36
37
 
37
38
  ## Migration workflow (port v1 → v2)
@@ -105,4 +105,4 @@ In a React dApp you usually consume this package **indirectly** — `useWalletPr
105
105
  ## Getting help
106
106
 
107
107
  - API surface lookup: [`reference/`](./reference/).
108
- - Bug or missing feature: [open an issue](https://github.com/icon-project/sodax-sdks/issues).
108
+ - Bug or missing feature: [open an issue](https://github.com/gosodax/sodax-sdks/issues).
@@ -49,6 +49,7 @@ type EvmWalletDefaults = {
49
49
  transport?: HttpTransportConfig;
50
50
  sendTransaction?: EvmSendTransactionPolicy; // Omit<Partial<SendTransactionParameters>, keyof EvmRawTransaction>
51
51
  waitForTransactionReceipt?: EvmWaitForTransactionReceiptPolicy; // Partial<Omit<WaitForTransactionReceiptParameters, 'hash'>>
52
+ waitForCallsStatus?: EvmWaitForCallsStatusPolicy; // Partial<Omit<WaitForCallsStatusParameters, 'id' | 'status'>>
52
53
  };
53
54
  ```
54
55
 
@@ -57,6 +58,7 @@ type EvmWalletDefaults = {
57
58
  | `publicClient`, `walletClient`, `transport` | constructor | Private-key mode |
58
59
  | `sendTransaction` | `sendTransaction()` | Both modes |
59
60
  | `waitForTransactionReceipt` | `waitForTransactionReceipt()` | Both modes |
61
+ | `waitForCallsStatus` | `waitForBatch()` | Browser-extension mode (batches need a connected wallet) |
60
62
 
61
63
  > In browser-extension mode, `publicClient` / `walletClient` / `transport` defaults are **ignored** — the provider logs a one-time `console.warn`. Pass them only in private-key mode.
62
64
 
@@ -69,6 +71,9 @@ type EvmWalletDefaults = {
69
71
  | `getWalletAddress` | `() => Promise<Address>` | viem `Address` (`` `0x${string}` ``) | — |
70
72
  | `sendTransaction` | `(txData: EvmRawTransaction, options?: EvmSendTransactionPolicy & EvmSendTransactionOptions) => Promise<Hash>` | viem `Hash` | `defaults.sendTransaction` |
71
73
  | `waitForTransactionReceipt` | `(txHash: Hash, options?: EvmWaitForTransactionReceiptPolicy) => Promise<EvmRawTransactionReceipt>` | bigint-stringified receipt | `defaults.waitForTransactionReceipt` |
74
+ | `getAtomicBatchSupport` | `(chainId: number) => Promise<EvmAtomicBatchSupport>` | `'supported' \| 'ready' \| 'unsupported'` (EIP-5792 `atomic` capability) | — |
75
+ | `sendAtomicBatch` | `(txs: readonly EvmRawTransaction[], options: EvmSendBatchOptions) => Promise<string>` | EIP-5792 batch id (not a tx hash) | — |
76
+ | `waitForBatch` | `(batchId: string, options?: EvmWaitForCallsStatusPolicy) => Promise<EvmBatchResult>` | terminal status + receipts; a failed status read is retried within the timeout (three reads at most) | `defaults.waitForCallsStatus` |
72
77
 
73
78
  The serialised receipt converts all `bigint` fields to `string` so it can be `JSON.stringify`'d safely. This is enforced at the type level — `EvmRawTransactionReceipt` (from `@sodax/types`) is the stringified shape.
74
79
 
@@ -92,6 +97,7 @@ The serialised receipt converts all `bigint` fields to `string` so it can be `JS
92
97
  - **`rpcUrl` falls back to the viem chain's first public RPC.** Fine for testing — replace with a private RPC for production.
93
98
  - **Chain binding is opt-in.** Pass `options.expectedChainId` (`getEvmViemChain(chainKey).id`) and the provider refuses to send when the wallet's active chain differs. The SDK passes it on every signed send it owns: spoke/hub deposits and messages, signed ERC-20 approvals (reset leg included), and the hub-scoped vault, partner, BALN, `Permit2Service` and `Erc4626Service` sends — the last two are bound to Sonic, so calling them with a wallet on another EVM network now throws instead of broadcasting there.
94
99
  - **The chain check fails closed.** `eth_chainId` is normalised to a plain `number` before a strict compare; a mismatch or malformed wallet response throws and nothing is sent.
100
+ - **EIP-5792 batches need a connected wallet.** `getAtomicBatchSupport` reports `'unsupported'` for a private-key account, and `sendAtomicBatch` throws for one — a plain RPC endpoint has no `wallet_sendCalls`. `'ready'` means the wallet asks the user to upgrade the account (MetaMask: EIP-7702 smart account) on the first batch. `sendAtomicBatch` always requests atomic execution and refuses unless both the wallet's active chain and the wallet client's chain equal `expectedChainId`; read the tx hash from `waitForBatch(...).receipts` (it throws on timeout — the batch may still land). Most apps never call these directly — `swapWithApproval`, `bridgeWithApproval` and `vaultSwapWithApproval` do.
95
101
  - **No nonce management.** The provider does not auto-increment / serialise sends. If you fire multiple txs in parallel from the same account, manage nonces yourself via `defaults.sendTransaction.nonce` or per-call `options.nonce`.
96
102
 
97
103
  ---
@@ -13,8 +13,11 @@ The tables below summarise the methods each provider exposes. For full type-leve
13
13
  | `getWalletAddress` | `() => Promise<Address>` |
14
14
  | `sendTransaction` | `(tx: EvmRawTransaction, opts?: EvmSendTransactionPolicy) => Promise<Hash>` |
15
15
  | `waitForTransactionReceipt` | `(hash: Hash, opts?: EvmWaitForTransactionReceiptPolicy) => Promise<EvmRawTransactionReceipt>` |
16
+ | `getAtomicBatchSupport?` | `(chainId: number) => Promise<EvmAtomicBatchSupport>` — optional (EIP-5792) |
17
+ | `sendAtomicBatch?` | `(txs: readonly EvmRawTransaction[], opts: EvmSendBatchOptions) => Promise<string>` — optional, returns a batch id |
18
+ | `waitForBatch?` | `(batchId: string, opts?: EvmWaitForBatchOptions) => Promise<EvmBatchResult>` — optional; throws on timeout |
16
19
 
17
- Plus public field: `publicClient: PublicClient`.
20
+ Plus public field: `publicClient: PublicClient`. The three EIP-5792 methods are optional on the interface; a custom provider that omits them still works — the SDK falls back to separate transactions.
18
21
 
19
22
  ---
20
23
 
@@ -81,4 +81,4 @@ That filtered output is your work list. In a typical project the list is empty.
81
81
 
82
82
  ## Getting help
83
83
 
84
- If you do hit a v1 pattern that doesn't compile against v2, [open an issue](https://github.com/icon-project/sodax-sdks/issues) with the source snippet — that means we missed a backwards-compat case and the migration scope needs to grow.
84
+ If you do hit a v1 pattern that doesn't compile against v2, [open an issue](https://github.com/gosodax/sodax-sdks/issues) with the source snippet — that means we missed a backwards-compat case and the migration scope needs to grow.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: sodax-wallet-sdk-react
3
- description: 'Add SODAX multi-chain wallet connectivity to a React dapp with @sodax/wallet-sdk-react — connect/disconnect, account & signing hooks, a headless wallet modal, WalletConnect, and bridging the connected wallet into @sodax/sdk. INTEGRATION (write NEW code) — the React wallet connectivity layer for multi-chain dapps. Covers `SodaxWalletProvider` setup, hook-based connect/disconnect/account/signing UX across 9 chain types (EVM, Solana, Sui, Bitcoin, Stellar, ICON, Injective, NEAR, Stacks), headless wallet-modal primitives, WalletConnect for non-injected wallets (Fireblocks/Ledger/mobile), and `useWalletProvider` for bridging the connected wallet into `@sodax/sdk` calls. Use whenever a React dapp needs SODAX wallet connectivity. Triggers on "add wallet connect", "set up SodaxWalletProvider", "useXConnect", "useXAccount", "useWalletProvider", "useWalletModal", "wallet modal", "connect button", "multi-chain wallet UI", "WalletConnect for Fireblocks". Peer deps: `react >= 19`, `@tanstack/react-query 5.x`. MIGRATION (port v1 → v2) — the v2 reshape removed `useXWagmiStore` from the public API (each selector must be replaced with a public hook like `useXServices` / `useXService({ xChainType })` / `useXConnections` / `useXConnection({ xChainType })`; do NOT rename to `useXWalletStore` — the v2 barrel does not export it), unified hook signatures to single-object params, reshaped `SodaxWalletProvider` props (removed `rpcConfig` / `options` / `initialState` in favor of `config: SodaxWalletConfig`), and flattened the chain-slot wrapper (`chains: { EVM, SOLANA, ... }` → top-level slots on `SodaxWalletConfig`). Triggers on "useXWagmiStore is gone", "SodaxWalletProvider props broke", "old wallet-sdk-react hooks", "upgrade @sodax/wallet-sdk-react". Load this skill if EITHER applies; the body gates by mode.'
3
+ description: 'Add SODAX multi-chain wallet connectivity to a React dapp with @sodax/wallet-sdk-react — connect/disconnect, account & signing hooks, a headless wallet modal, EVM chain switching, WalletConnect, Privy email login, and bridging the connected wallet into @sodax/sdk. INTEGRATION (write NEW code) — `SodaxWalletProvider` setup and hook-based UX across EVM, Solana, Sui, Bitcoin, Stellar, ICON, Injective, NEAR and Stacks; WalletConnect for non-injected wallets (Fireblocks/Ledger/mobile); `useWalletProvider` for signing SODAX calls. Triggers on "add wallet connect", "set up SodaxWalletProvider", "useXConnect", "useXAccount", "useWalletProvider", "useWalletModal", "wallet modal", "connect button", "multi-chain wallet UI", "WalletConnect for Fireblocks", "email login with Privy". Peer deps: `react >= 19`, `@tanstack/react-query 5.x`. MIGRATION (port v1 → v2) — `useXWagmiStore` left the public API (replace each selector with `useXServices` / `useXService({ xChainType })` / `useXConnections` / `useXConnection({ xChainType })`; do NOT rename to `useXWalletStore`, which is not exported), hooks take single-object params, `SodaxWalletProvider` takes `config: SodaxWalletConfig` (no `rpcConfig` / `options` / `initialState`), and chain slots are top-level on `SodaxWalletConfig` (no `chains: { EVM, … }` wrapper). Triggers on "useXWagmiStore is gone", "SodaxWalletProvider props broke", "old wallet-sdk-react hooks", "upgrade @sodax/wallet-sdk-react". Load this skill if EITHER applies; the body gates by mode.'
4
4
  license: MIT
5
5
  metadata:
6
6
  version: '0.0.1'
@@ -20,6 +20,22 @@ AGENTS.md routes you here when you're working with `@sodax/wallet-sdk-react` v2
20
20
  For backend / non-React → use `sodax-wallet-sdk-core` instead.
21
21
  For React dapps with hooks wrapping the SDK → also load `sodax-dapp-kit`.
22
22
 
23
+ ## Prefer a granular skill if the concern is known
24
+
25
+ If the task is one wallet concern, load its granular skill instead of this broad one. Each links straight to its recipe, for both integration and migration.
26
+
27
+ | Concern | Granular skill | Trigger phrases |
28
+ |---|---|---|
29
+ | Connect / disconnect, account and connection state | [`./connect/SKILL.md`](./connect/SKILL.md) | "useXConnect", "useXAccount", "connect button" |
30
+ | Headless wallet modal and multi-chain UI | [`./wallet-modal/SKILL.md`](./wallet-modal/SKILL.md) | "useWalletModal", "wallet modal", "connect several chains" |
31
+ | Connected wallet → SDK signer | [`./bridge-to-sdk/SKILL.md`](./bridge-to-sdk/SKILL.md) | "useWalletProvider", "pass the wallet to @sodax/sdk" |
32
+ | EVM chain switching / wrong network | [`./switch-chain/SKILL.md`](./switch-chain/SKILL.md) | "useEvmSwitchChain", "wrong network banner" |
33
+ | Sign an arbitrary message | [`./sign-message/SKILL.md`](./sign-message/SKILL.md) | "useXSignMessage", "prove wallet ownership", "SIWE" |
34
+ | WalletConnect / enterprise custody | [`./walletconnect/SKILL.md`](./walletconnect/SKILL.md) | "WalletConnect", "Fireblocks", "Ledger", "mobile-only wallet" |
35
+ | Email login (Privy embedded wallet) | [`./privy/SKILL.md`](./privy/SKILL.md) | "add email login", "Privy", "embedded wallet" |
36
+
37
+ Load this broad skill (keep reading below) for a full wallet setup, several concerns at once, or a v1 port.
38
+
23
39
  ---
24
40
 
25
41
  ## Integration mode (writing new v2 code)
@@ -30,6 +46,7 @@ Pick this mode when the consumer is a React dapp that needs SODAX wallet connect
30
46
  - "Multi-chain modal UI" — `useWalletModal`, `useChainGroups`, `useConnectedChains`.
31
47
  - "Pass the connected wallet to a `@sodax/sdk` swap" — `useWalletProvider({ xChainId })`.
32
48
  - "Add WalletConnect for enterprise custody (Fireblocks, mobile)" — `walletConnect` field on `SodaxWalletConfig.EVM`.
49
+ - "Let users log in with email" / "Privy" — `privy` field on `SodaxWalletConfig.EVM`, built with `privy()` from `@sodax/wallet-sdk-react/privy`.
33
50
  - "SSR with Next.js" — `ssr: true` flag on the EVM slot.
34
51
 
35
52
  ### Workflow
@@ -37,8 +54,8 @@ Pick this mode when the consumer is a React dapp that needs SODAX wallet connect
37
54
  1. Read [`integration/knowledge/ai-rules.md`](./integration/knowledge/ai-rules.md) — DO / DON'T + workflow.
38
55
  2. **Always start with setup** → [`integration/knowledge/recipes/setup.md`](./integration/knowledge/recipes/setup.md). Mount `SodaxWalletProvider`, declare chain-type slots, wire `@tanstack/react-query`.
39
56
  3. Read [`integration/knowledge/architecture.md`](./integration/knowledge/architecture.md) — provider mount tree, frozen config, EVM single-connection model, `xChainType` vs `xChainId`.
40
- 4. Task-specific recipes → [`integration/knowledge/recipes/`](./integration/knowledge/recipes/) — `connect-button.md`, `multi-chain-modal.md`, `walletconnect-setup.md`, `bridge-to-sdk.md`, `sign-message.md`, `switch-chain.md`, `batch-operations.md`, `chain-detection.md`, `sub-path-imports.md`.
41
- 5. Working examples → [`integration/knowledge/examples/`](./integration/knowledge/examples/) — 4 working `.tsx` app shells (`01-minimal-evm`, `02-multi-chain-modal`, `03-nextjs-app-router`, `04-walletconnect-setup`).
57
+ 4. Task-specific recipes → [`integration/knowledge/recipes/`](./integration/knowledge/recipes/) — `connect-button.md`, `multi-chain-modal.md`, `walletconnect-setup.md`, `privy-email-login.md`, `bridge-to-sdk.md`, `sign-message.md`, `switch-chain.md`, `batch-operations.md`, `chain-detection.md`, `sub-path-imports.md`.
58
+ 5. Working examples → [`integration/knowledge/examples/`](./integration/knowledge/examples/) — 5 working `.tsx` app shells (`01-minimal-evm`, `02-multi-chain-modal`, `03-nextjs-app-router`, `04-walletconnect-setup`, `05-privy-email-login`).
42
59
  6. Lookups → [`integration/knowledge/reference/`](./integration/knowledge/reference/) — hooks, connectors, chain-support, wallet-brands, api-surface.
43
60
 
44
61
  ### Conventions to follow (integration)
@@ -31,6 +31,7 @@ If this is your first time using the package:
31
31
  6. [`recipes/chain-detection.md`](./recipes/chain-detection.md) — list enabled chains, render connected list with hydration gate, install detection.
32
32
  7. Add advanced features as needed:
33
33
  - [`recipes/walletconnect-setup.md`](./recipes/walletconnect-setup.md) — enable WalletConnect for enterprise-custody / mobile-only wallets.
34
+ - [`recipes/privy-email-login.md`](./recipes/privy-email-login.md) — add "Email (Privy)" email login with an embedded wallet (`EVM.privy`).
34
35
  - [`recipes/batch-operations.md`](./recipes/batch-operations.md) — batch connect / disconnect across multiple chains.
35
36
  - [`recipes/sub-path-imports.md`](./recipes/sub-path-imports.md) — deep imports from `xchains/<chain>` for `instanceof` checks or custom connector lists.
36
37
  8. Reference docs (lookup as needed):
@@ -99,5 +100,5 @@ If you are using all three, mount providers in this order at the app root:
99
100
  ## Getting help
100
101
 
101
102
  - API surface lookup: [`reference/`](./reference/).
102
- - Bug or missing feature: [open an issue](https://github.com/icon-project/sodax-sdks/issues).
103
+ - Bug or missing feature: [open an issue](https://github.com/gosodax/sodax-sdks/issues).
103
104
  - Internal architecture (only relevant for SODAX maintainers): `../CLAUDE.md` in the package root.
@@ -50,6 +50,7 @@ Only after the connect UX works should you add:
50
50
  - Switch active EVM network ([`recipes/switch-chain.md`](./recipes/switch-chain.md))
51
51
  - Chain & wallet detection patterns ([`recipes/chain-detection.md`](./recipes/chain-detection.md))
52
52
  - WalletConnect ([`recipes/walletconnect-setup.md`](./recipes/walletconnect-setup.md))
53
+ - Email login with Privy ([`recipes/privy-email-login.md`](./recipes/privy-email-login.md))
53
54
  - Batch connect / disconnect ([`recipes/batch-operations.md`](./recipes/batch-operations.md))
54
55
 
55
56
  Each is independent — apply only what the user asked for.
@@ -62,6 +63,7 @@ If the user wants a full working starter file rather than narrative steps, point
62
63
  - `02-multi-chain-modal.tsx` — full headless modal
63
64
  - `03-nextjs-app-router.tsx` — Next.js 15 SSR setup
64
65
  - `04-walletconnect-setup.tsx` — WalletConnect setup (optional single-wallet filter)
66
+ - `05-privy-email-login.tsx` — Privy email login (`EVM.privy`) with the modal and dialog guards
65
67
 
66
68
  Always combine with the narrative recipe — examples are skeletons, recipes explain why each piece exists.
67
69
 
@@ -25,12 +25,14 @@ Hooks always operate on `XService` / `XConnector` — never directly on a chain
25
25
 
26
26
  ```
27
27
  <WalletConfigProvider value={frozenConfig}>
28
- <EvmProvider config={config.EVM}> ← only if EVM slot present (mounts wagmi.WagmiProvider)
29
- <SuiProvider config={config.SUI}> ← only if SUI slot present (mounts dapp-kit providers)
30
- <SolanaProvider config={config.SOLANA}> ← only if SOLANA slot present (mounts solana-wallet-adapter)
31
- {children}
32
- </SolanaProvider>
33
- </SuiProvider>
28
+ <EvmProvider config={config.EVM}> ← only if EVM slot present (mounts wagmi.WagmiProvider)
29
+ <PrivyHost> ← only if config.EVM.privy is set (mounts PrivyProvider inside wagmi)
30
+ <SuiProvider config={config.SUI}> ← only if SUI slot present (mounts dapp-kit providers)
31
+ <SolanaProvider config={config.SOLANA}> ← only if SOLANA slot present (mounts solana-wallet-adapter)
32
+ {children}
33
+ </SolanaProvider>
34
+ </SuiProvider>
35
+ </PrivyHost>
34
36
  </EvmProvider>
35
37
  </WalletConfigProvider>
36
38
  ```
@@ -168,6 +170,8 @@ src/
168
170
  ├── utils/ # sortConnectors, walletRpcConfig, isNativeToken
169
171
  ├── types/ # Public types — config, interfaces, chainActions
170
172
  ├── providers/ # Per-chain-type React provider implementations
173
+ ├── privy/ # Privy email login; sub-path import: '@sodax/wallet-sdk-react/privy'
174
+ │ # The only code that imports the optional peer @privy-io/react-auth
171
175
  └── xchains/<chain>/ # Per-chain XService + XConnector implementations
172
176
  │ # Sub-path import: '@sodax/wallet-sdk-react/xchains/<chain>'
173
177
  └── ... # Auto-discovered by tsup; not re-exported from barrel
@@ -0,0 +1,157 @@
1
+ 'use client';
2
+
3
+ /**
4
+ * Email login with Privy — adds "Email (Privy)" (connector id `privy`) to the EVM wallet list.
5
+ * The user types an email, enters Privy's one-time code and gets an embedded EVM wallet that signs
6
+ * like any other wallet.
7
+ *
8
+ * Before running:
9
+ * - `pnpm add @privy-io/react-auth` (3.40 or newer) — an optional peer of `@sodax/wallet-sdk-react`.
10
+ * - Create an app at https://dashboard.privy.io: enable Email login and Ethereum embedded wallets,
11
+ * and allow this origin (`http://localhost:<port>` plus every deployed and preview URL).
12
+ *
13
+ * Next.js App Router: keep this whole file client-side (`'use client'` above). React refuses to pass
14
+ * `privy()`'s value from a Server Component.
15
+ *
16
+ * For Privy-only data (the user's email, key export) use Privy's own hooks such as `usePrivy()`
17
+ * below `SodaxWalletProvider` — see `../recipes/privy-email-login.md`.
18
+ */
19
+
20
+ import { type ReactNode, useEffect, useRef, useState } from 'react';
21
+ import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
22
+ import {
23
+ SodaxWalletProvider,
24
+ type SodaxWalletConfig,
25
+ useWalletModal,
26
+ useXAccount,
27
+ useXConnection,
28
+ useXConnectors,
29
+ useXDisconnect,
30
+ useXSignMessage,
31
+ } from '@sodax/wallet-sdk-react';
32
+ import { PRIVY_CONNECTOR_ID, privy } from '@sodax/wallet-sdk-react/privy';
33
+ import { ChainKeys } from '@sodax/types';
34
+
35
+ const queryClient = new QueryClient();
36
+
37
+ const walletConfig: SodaxWalletConfig = {
38
+ EVM: {
39
+ ssr: true,
40
+ chains: {
41
+ [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://rpc.soniclabs.com' },
42
+ [ChainKeys.BASE_MAINNET]: { rpcUrl: 'https://mainnet.base.org' },
43
+ },
44
+ // The App ID is public. An unset env var only warns and leaves "Email (Privy)" out; privy() never throws.
45
+ privy: privy({ appId: process.env.NEXT_PUBLIC_PRIVY_APP_ID ?? '' }),
46
+ },
47
+ };
48
+
49
+ export function App() {
50
+ return (
51
+ <QueryClientProvider client={queryClient}>
52
+ <SodaxWalletProvider config={walletConfig}>
53
+ <EmailLogin />
54
+ </SodaxWalletProvider>
55
+ </QueryClientProvider>
56
+ );
57
+ }
58
+
59
+ function EmailLogin() {
60
+ const modal = useWalletModal();
61
+ const connectors = useXConnectors({ xChainType: 'EVM' });
62
+ const account = useXAccount({ xChainType: 'EVM' });
63
+ const connection = useXConnection({ xChainType: 'EVM' });
64
+ const disconnect = useXDisconnect();
65
+
66
+ const privyConnector = connectors.find(c => c.id === PRIVY_CONNECTOR_ID);
67
+
68
+ // Privy's own login dialog owns the screen while it is connecting
69
+ if (modal.state.kind === 'connecting' && modal.state.connector.id === PRIVY_CONNECTOR_ID) {
70
+ return null;
71
+ }
72
+
73
+ if (account.address) {
74
+ return (
75
+ <div>
76
+ <code>{account.address}</code>
77
+ {connection?.xConnectorId === PRIVY_CONNECTOR_ID && <span> (email wallet)</span>}
78
+ <button type="button" onClick={() => disconnect({ xChainType: 'EVM' })}>
79
+ Disconnect
80
+ </button>
81
+ <SignInDialog />
82
+ </div>
83
+ );
84
+ }
85
+
86
+ if (!privyConnector) {
87
+ return <p>Email login not configured — set NEXT_PUBLIC_PRIVY_APP_ID</p>;
88
+ }
89
+
90
+ return (
91
+ <div>
92
+ <button type="button" onClick={() => modal.selectWallet(privyConnector)}>
93
+ Log in with email
94
+ </button>
95
+ {/* Closing Privy's dialog lands here with a user-rejection error */}
96
+ {modal.state.kind === 'error' && <p>Login failed: {modal.state.error.message}</p>}
97
+ </div>
98
+ );
99
+ }
100
+
101
+ /** A dialog of your own that signs while open: Privy's confirmation screen appears on top of it. */
102
+ function SignInDialog() {
103
+ const [open, setOpen] = useState(false);
104
+ const signMessage = useXSignMessage();
105
+
106
+ if (!open) {
107
+ return (
108
+ <button type="button" onClick={() => setOpen(true)}>
109
+ Sign in to the app
110
+ </button>
111
+ );
112
+ }
113
+
114
+ return (
115
+ <OutsideClickDialog onClose={() => setOpen(false)}>
116
+ <p>Sign a message to prove you own this wallet.</p>
117
+ <button
118
+ type="button"
119
+ disabled={signMessage.isPending}
120
+ onClick={() => signMessage.mutate({ xChainType: 'EVM', message: 'Sign in to my SODAX app' })}
121
+ >
122
+ Sign
123
+ </button>
124
+ {signMessage.data && <code>{String(signMessage.data)}</code>}
125
+ </OutsideClickDialog>
126
+ );
127
+ }
128
+
129
+ /** True for events inside Privy's screens (login, confirmations, MFA), which render outside your components. */
130
+ function isInPrivyDialog(target: EventTarget | null): boolean {
131
+ return target instanceof Element && target.closest('#privy-dialog') !== null;
132
+ }
133
+
134
+ /**
135
+ * Closes on a click outside itself — except a click on Privy's screens, which would otherwise close it
136
+ * mid-signature. Radix / shadcn equivalent on `DialogContent` or `SheetContent`:
137
+ * `onInteractOutside={event => { if (isInPrivyDialog(event.target)) event.preventDefault(); }}`
138
+ */
139
+ function OutsideClickDialog({ onClose, children }: { onClose: () => void; children: ReactNode }) {
140
+ const ref = useRef<HTMLDivElement>(null);
141
+
142
+ useEffect(() => {
143
+ const onPointerDown = (event: PointerEvent) => {
144
+ const target = event.target;
145
+ if (!(target instanceof Node) || ref.current?.contains(target) || isInPrivyDialog(target)) return;
146
+ onClose();
147
+ };
148
+ document.addEventListener('pointerdown', onPointerDown);
149
+ return () => document.removeEventListener('pointerdown', onPointerDown);
150
+ }, [onClose]);
151
+
152
+ return (
153
+ <div ref={ref} role="dialog" aria-modal="true">
154
+ {children}
155
+ </div>
156
+ );
157
+ }
@@ -10,6 +10,7 @@ For narrative + step-by-step explanation, see [`../recipes/`](../recipes/). Exam
10
10
  | [`02-multi-chain-modal.tsx`](./02-multi-chain-modal.tsx) | Headless wallet modal with chain → connector → connecting flow | ~120 |
11
11
  | [`03-nextjs-app-router.tsx`](./03-nextjs-app-router.tsx) | Next.js 15 App Router setup (SSR + `'use client'`) | ~60 |
12
12
  | [`04-walletconnect-setup.tsx`](./04-walletconnect-setup.tsx) | WalletConnect connector setup (with optional single-wallet filter) | ~50 |
13
+ | [`05-privy-email-login.tsx`](./05-privy-email-login.tsx) | Privy email login (`EVM.privy`), hiding the modal during Privy's login, a dialog that survives Privy's screens. Also needs `@privy-io/react-auth` 3.40+ | ~150 |
13
14
 
14
15
  ## Conventions
15
16
 
@@ -0,0 +1,111 @@
1
+ # Recipe: Email Login with Privy (EVM only)
2
+
3
+ Add an **"Email (Privy)"** entry to the EVM wallet list: the user logs in with an email one-time code and gets a Privy embedded wallet that signs like any other EVM wallet. Opt-in, behind the `@sodax/wallet-sdk-react/privy` sub-path.
4
+
5
+ **Depends on:** [`setup.md`](./setup.md) · **Full file:** [`examples/05-privy-email-login.tsx`](../examples/05-privy-email-login.tsx)
6
+
7
+ You write the code. The user owns the Privy app and receives the email code, so step 0 asks them first and the [Verification](#verification) hands them the login test.
8
+
9
+ ---
10
+
11
+ ## 0. Ask the user before coding
12
+
13
+ 1. **Trade-offs.** Tell them (full text in the [package guide](https://github.com/gosodax/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/WALLET_PRIVY.md)): Privy custodies access, so no signing is possible while Privy is unreachable; addresses belong to their Privy app; a user who loses their email loses the wallet; their Privy app is billed per signature.
14
+ 2. **Their Privy App ID.** If they have none, give them this checklist for dashboard.privy.io:
15
+ - Create an app and copy its App ID.
16
+ - Enable **Email** login and **Ethereum embedded wallets**. The SDK shows email login only.
17
+ - Allow every origin the app runs on: `http://localhost:<port>`, production, and each preview URL. Wildcards such as `https://*.vercel.app` are refused, and Privy requires https except on `localhost` / `127.0.0.1` — a dev server opened by LAN IP fails with "Embedded wallet is only available over HTTPS".
18
+ - To test without an inbox, enable test accounts (`test-XXXX@privy.io` with a fixed code).
19
+ 3. **Privy's confirmation screens (`showWalletUIs`).** With them on, Privy confirms every signature and transaction, and a transaction's hash arrives only after Privy has waited for the receipt and the user has closed its success screen. `false` returns the hash right after broadcast and leaves the app's own review step as the only confirmation. Unset follows the dashboard.
20
+ 4. **Shared devices (`disconnectBehavior`).** `'logout'` (default) signs the user out of Privy on disconnect, so the next connect needs a new code; `'detach'` keeps the Privy session for anyone using that browser.
21
+ 5. **App already on Privy?** If it mounts its own `PrivyProvider` only for email login and the embedded wallet, remove that provider, pass the same `appId` to `privy()` and skip the install (its `@privy-io/react-auth` must be 3.40 or newer). If it needs its own Privy configuration — other login methods, other chains, or a Privy session that must outlive a wallet disconnect — do not add `EVM.privy`: the SDK cannot use a provider the app mounts, and Privy allows only one.
22
+
23
+ ---
24
+
25
+ ## 1. Install the peer and store the App ID
26
+
27
+ ```bash
28
+ pnpm add @privy-io/react-auth
29
+ ```
30
+
31
+ - `@privy-io/react-auth` is an optional peer of `@sodax/wallet-sdk-react` — it is not installed automatically. It must be 3.40 or newer.
32
+ - **The App ID is public:** it ships in the browser bundle. Keep it in a public env var (`NEXT_PUBLIC_PRIVY_APP_ID` on Next.js, `VITE_PRIVY_APP_ID` on Vite). Unlike a SODAX API key, it needs no backend proxy.
33
+ - **npm / yarn:** Privy needs the app's top-level `viem` at 2.44 or newer; an older one fails at import with `does not provide an export named 'tempoModerato'`. pnpm is not affected.
34
+ - **Monorepo:** make the app and the SDK resolve one copy of `@privy-io/react-auth` (Vite: `resolve.dedupe: ['@privy-io/react-auth']`), or `usePrivy()` reads a different context than the provider the SDK mounts.
35
+ - **Content-Security-Policy:** if the site sends one, allow `https://auth.privy.io` in `connect-src`, `frame-src` and `child-src`.
36
+ - webpack warnings about `@farcaster/mini-app-solana` and a "Critical dependency" in `ox` are harmless for EVM-only use.
37
+
38
+ ---
39
+
40
+ ## 2. Pass `privy()` as `EVM.privy`
41
+
42
+ ```typescript
43
+ 'use client'; // Next.js App Router: privy()'s value cannot cross from a Server Component
44
+
45
+ import { type SodaxWalletConfig } from '@sodax/wallet-sdk-react';
46
+ import { privy } from '@sodax/wallet-sdk-react/privy';
47
+ import { ChainKeys } from '@sodax/types';
48
+
49
+ const walletConfig: SodaxWalletConfig = {
50
+ EVM: {
51
+ chains: { [ChainKeys.BASE_MAINNET]: { rpcUrl: 'https://mainnet.base.org' } },
52
+ // An unset env var only logs a warning and leaves "Email (Privy)" out; privy() never throws.
53
+ privy: privy({ appId: process.env.NEXT_PUBLIC_PRIVY_APP_ID ?? '' }),
54
+ },
55
+ };
56
+ ```
57
+
58
+ `useXConnectors({ xChainType: 'EVM' })` now includes a connector with `id === 'privy'` (`PRIVY_CONNECTOR_ID`). **No UI changes required.** Options: `appId` (required), `clientId` (a Privy app client, for per-environment settings), `defaultChain` (an EVM `ChainKey`, default Sonic), `showWalletUIs` and `disconnectBehavior` (the user's answers from step 0), `appearance`, `legal`. If Privy cannot start (plain-http origin other than localhost, malformed app id, a second `PrivyProvider`), the app keeps running and picking "Email (Privy)" fails with the cause.
59
+
60
+ ---
61
+
62
+ ## 3. Read the Privy user (optional)
63
+
64
+ The SDK mounts `PrivyProvider` around the app, so Privy's own hooks work in child components. Render them only while the EVM wallet is the Privy one:
65
+
66
+ ```tsx
67
+ // @ai-snippets-skip — imports the optional peer @privy-io/react-auth, which this package does not install
68
+ import { usePrivy } from '@privy-io/react-auth';
69
+ import { useXConnection } from '@sodax/wallet-sdk-react';
70
+
71
+ export function PrivyEmail() {
72
+ const connection = useXConnection({ xChainType: 'EVM' });
73
+ return connection?.xConnectorId === 'privy' ? <Email /> : null;
74
+ }
75
+
76
+ function Email() {
77
+ const { user } = usePrivy();
78
+ return <span>{user?.email?.address}</span>;
79
+ }
80
+ ```
81
+
82
+ ---
83
+
84
+ ## Anti-patterns
85
+
86
+ - **Writing `privy: { appId }`.** The value must come from `privy()` — the import is what adds Privy's code to the bundle; a plain object is skipped with a warning.
87
+ - **Importing `privy` from `@sodax/wallet-sdk-react`.** It lives only on the `/privy` sub-path.
88
+ - **Calling `privy()` in a Server Component.** Its value belongs to the browser's copy of the SDK and React refuses to serialize it; build the config in a `'use client'` file.
89
+ - **Mounting a second `PrivyProvider`.** Privy allows one; for an app that already has one, see *App already on Privy?* above.
90
+ - **Adding `@privy-io/wagmi`.** Not used — it replaces wagmi's connector list and would remove MetaMask and WalletConnect.
91
+ - **Custom modal stacking.** While Privy's login dialog is open, `useWalletModal` is `connecting`; render nothing when `state.connector.id === 'privy'`, as for `'walletConnect'`.
92
+ - **Letting a modal dialog close on Privy's screens.** Privy renders login, confirmation and MFA screens in `#privy-dialog`, outside the app's components; an open modal dialog (confirm-swap, wallet sheet) treats a click there as an outside click and closes mid-transaction. Ignore outside interactions whose target is inside `#privy-dialog` (Radix: `onInteractOutside` → `event.preventDefault()`).
93
+ - **Promising the same address across apps.** An address belongs to the Privy app: another `appId` gives the same email a different wallet. Sharing needs the same `appId` with both origins allowed; Privy's Global Wallets are not supported.
94
+
95
+ ---
96
+
97
+ ## Verification
98
+
99
+ ```bash
100
+ # 1. Type check and the production build (a missing peer fails the build with "Module not found")
101
+ pnpm tsc --noEmit && pnpm build
102
+
103
+ # 2. privy() comes from the sub-path and sits on the EVM slot
104
+ grep -rn "@sodax/wallet-sdk-react/privy" <user-src>
105
+ grep -rn "privy: privy(" <user-src>
106
+
107
+ # 3. Nothing the SDK already provides — expect no matches
108
+ grep -rn "@privy-io/wagmi\|<PrivyProvider" <user-src>
109
+ ```
110
+
111
+ 4. **Hand to the user** (you cannot receive the email code): run the app on an allowed origin, pick "Email (Privy)" in the wallet list, sign in with a test account, and check that the address appears and is still connected after a reload. Then run one small SODAX action — a quote, then a swap of about $1 — which signs through `useWalletProvider` like MetaMask, with no Privy-specific call.
@@ -99,6 +99,7 @@ Adapter-field types (only chains with React adapters):
99
99
  | `EvmAdapterFields` | type |
100
100
  | `SolanaAdapterFields` | type |
101
101
  | `SuiAdapterFields` | type |
102
+ | `PrivySource` | type — opaque value of `EvmAdapterFields.privy`; only `privy()` from the `/privy` sub-path creates one |
102
103
 
103
104
  ### Hook option / result types
104
105
 
@@ -135,6 +136,18 @@ import { IconHanaXConnector } from '@sodax/wallet-sdk-react/xchains/icon';
135
136
  |---|---|
136
137
  | `/xchains/stellar` | Re-exports `StellarXService` + `StellarWalletsKitXConnector` (the concrete connector wrapping `@creit.tech/stellar-wallets-kit`). |
137
138
 
139
+ ---
140
+
141
+ ## Privy email login — `import { X } from '@sodax/wallet-sdk-react/privy'`
142
+
143
+ Opt-in; the only entry that loads the optional peer `@privy-io/react-auth` (3.40+). See [`recipes/privy-email-login.md`](../recipes/privy-email-login.md).
144
+
145
+ | Symbol | Kind | Notes |
146
+ |---|---|---|
147
+ | `privy` | function `(options: PrivyOptions) => PrivySource` | Value for `EVM.privy`. Never throws: bad input warns and leaves the entry out |
148
+ | `PrivyOptions` | type | `appId` (required), `clientId?`, `defaultChain?` (EVM `ChainKey`, default Sonic), `showWalletUIs?`, `disconnectBehavior?` (`'logout'` \| `'detach'`, default `'logout'`), `appearance?`, `legal?` |
149
+ | `PRIVY_CONNECTOR_ID` | value `'privy'` | The connector id / `xConnectorId` of "Email (Privy)" |
150
+
138
151
  If unsure what a sub-path exports, check the published `dist/`:
139
152
 
140
153
  ```bash
@@ -149,6 +162,7 @@ grep -E '^export' node_modules/@sodax/wallet-sdk-react/dist/xchains/<chain>/inde
149
162
  |---|---|
150
163
  | `react` | `>= 19` |
151
164
  | `@tanstack/react-query` | `5.x` |
165
+ | `@privy-io/react-auth` | optional — only with `EVM.privy`; 3.40 or newer (older versions are left out with a warning) |
152
166
 
153
167
  `@tanstack/react-query` is required at runtime — `<QueryClientProvider>` must wrap `<SodaxWalletProvider>`. v1 mounted one internally; v2 does not.
154
168
 
@@ -28,7 +28,7 @@ EVM is the only family with multiple networks under one connection — wagmi mai
28
28
 
29
29
  | Slot | Config fields | Notes |
30
30
  |---|---|---|
31
- | `EVM` | `ssr?, reconnectOnMount?, initialState?, walletConnect?, connectors?, chains` | `chains` keyed by `ChainKey` → `{ rpcUrl?, defaults? }` |
31
+ | `EVM` | `ssr?, reconnectOnMount?, initialState?, persistKey?, walletConnect?, privy?, connectors?, chains` | `chains` keyed by `ChainKey` → `{ rpcUrl?, defaults? }` |
32
32
  | `SOLANA` | `autoConnect?, connectors?, chains` | `chains` keyed by `ChainKey` → `{ rpcUrl?, defaults? }` |
33
33
  | `SUI` | `network?, connectors?, chains?` | `network: 'mainnet' \| 'testnet'` |
34
34
  | `BITCOIN` | extends `BitcoinRpcConfig` + `{ defaults?, connectors? }` | Pass `{}` for SDK defaults |
@@ -44,6 +44,6 @@ If you are letting a coding agent drive the migration, point it at [`ai-rules.md
44
44
 
45
45
  ## Getting help
46
46
 
47
- If you hit a v1 pattern not covered in `reference/` or `recipes/`, please [open an issue](https://github.com/icon-project/sodax-sdks/issues) with the v1 code snippet — we'll add it to the docs.
47
+ If you hit a v1 pattern not covered in `reference/` or `recipes/`, please [open an issue](https://github.com/gosodax/sodax-sdks/issues) with the v1 code snippet — we'll add it to the docs.
48
48
 
49
49
  For internal SODAX maintainers: see `../CLAUDE.md` for architecture context.