@sodax/skills 2.2.0 → 2.3.0-rc.2

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 (55) hide show
  1. package/AGENTS.md +7 -7
  2. package/README.md +5 -5
  3. package/package.json +4 -4
  4. package/skills/sodax-build/SKILL.md +1 -1
  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/auxiliary-services/SKILL.md +4 -1
  11. package/skills/sodax-dapp-kit/bridge/SKILL.md +1 -1
  12. package/skills/sodax-dapp-kit/integration/knowledge/architecture.md +18 -4
  13. package/skills/sodax-dapp-kit/integration/knowledge/features/auxiliary-services.md +23 -1
  14. package/skills/sodax-dapp-kit/integration/knowledge/features/bridge.md +8 -0
  15. package/skills/sodax-dapp-kit/integration/knowledge/features/leverage-yield.md +5 -3
  16. package/skills/sodax-dapp-kit/integration/knowledge/features/swap.md +24 -0
  17. package/skills/sodax-dapp-kit/integration/knowledge/recipes/bridge.md +2 -0
  18. package/skills/sodax-dapp-kit/integration/knowledge/recipes/leverage-yield.md +1 -0
  19. package/skills/sodax-dapp-kit/integration/knowledge/recipes/swap.md +141 -1
  20. package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md +8 -0
  21. package/skills/sodax-dapp-kit/integration/knowledge/reference/public-api.md +1 -1
  22. package/skills/sodax-dapp-kit/integration/knowledge/reference/querykey-conventions.md +8 -0
  23. package/skills/sodax-dapp-kit/leverage-yield/SKILL.md +3 -3
  24. package/skills/sodax-dapp-kit/swap/SKILL.md +3 -3
  25. package/skills/sodax-sdk/bridge/SKILL.md +3 -1
  26. package/skills/sodax-sdk/integration/knowledge/architecture.md +1 -1
  27. package/skills/sodax-sdk/integration/knowledge/features/bridge-api.md +5 -3
  28. package/skills/sodax-sdk/integration/knowledge/features/bridge.md +8 -0
  29. package/skills/sodax-sdk/integration/knowledge/features/leverage-yield.md +25 -2
  30. package/skills/sodax-sdk/integration/knowledge/features/swap.md +72 -2
  31. package/skills/sodax-sdk/integration/knowledge/features/swaps-api.md +56 -2
  32. package/skills/sodax-sdk/integration/knowledge/reference/error-codes.md +27 -1
  33. package/skills/sodax-sdk/integration/knowledge/reference/public-api.md +30 -1
  34. package/skills/sodax-sdk/leverage-yield/SKILL.md +3 -2
  35. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/architecture.md +1 -1
  36. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/reference/sodax-config.md +9 -1
  37. package/skills/sodax-sdk/swap/SKILL.md +3 -1
  38. package/skills/sodax-sdk/swaps-api/SKILL.md +3 -2
  39. package/skills/sodax-wallet-sdk-core/evm/SKILL.md +2 -1
  40. package/skills/sodax-wallet-sdk-core/integration/knowledge/README.md +1 -1
  41. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/evm.md +6 -0
  42. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/interfaces.md +4 -1
  43. package/skills/sodax-wallet-sdk-core/migration-v1-to-v2/knowledge/README.md +1 -1
  44. package/skills/sodax-wallet-sdk-react/SKILL.md +5 -3
  45. package/skills/sodax-wallet-sdk-react/integration/knowledge/README.md +2 -1
  46. package/skills/sodax-wallet-sdk-react/integration/knowledge/ai-rules.md +2 -0
  47. package/skills/sodax-wallet-sdk-react/integration/knowledge/architecture.md +10 -6
  48. package/skills/sodax-wallet-sdk-react/integration/knowledge/examples/05-privy-email-login.tsx +157 -0
  49. package/skills/sodax-wallet-sdk-react/integration/knowledge/examples/README.md +1 -0
  50. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/privy-email-login.md +111 -0
  51. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/api-surface.md +14 -0
  52. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/chain-support.md +1 -1
  53. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/README.md +1 -1
  54. package/skills/sodax-wallet-sdk-react/privy/SKILL.md +53 -0
  55. package/skills/sodax-wallet-sdk-react/wallet-modal/SKILL.md +1 -0
@@ -63,8 +63,9 @@ applies per-call overrides that take precedence over the service config (see "Pe
63
63
  allowance change from one non-zero value to another (the 2017 TetherToken lineage) **and** the wallet
64
64
  already holds a stale allowance — a wallet in that state cannot approve at all until it is zeroed.
65
65
 
66
- Broadcast `resetTx` first and wait for it to be mined, then broadcast `tx`. The two cannot be
67
- batched: the approval is only valid once the reset has landed on-chain.
66
+ Broadcast `resetTx` first and wait for it to be mined, then broadcast `tx`. As separate transactions
67
+ they cannot go out together: the approval is only valid once the reset has landed on-chain. An
68
+ EIP-5792 atomic batch is different — it runs its calls in order, so it can carry both (next section).
68
69
 
69
70
  ```ts
70
71
  const { tx, resetTx } = approveResponse;
@@ -80,6 +81,59 @@ await sendTransaction(tx);
80
81
  The field is optional and absent for every other token, so ignoring it keeps existing behaviour —
81
82
  it just cannot rescue a wallet stuck on a guarded token.
82
83
 
84
+ ## Approve and send the intent in one signature
85
+
86
+ When `checkAllowance` says the allowance is short and the source is an EVM spoke, the approval can go
87
+ out in the same EIP-5792 atomic batch as the intent tx — one wallet prompt instead of two or three.
88
+ `/swaps/intents` only simulates on the hub, so the intent tx can be built before the approval lands.
89
+
90
+ ```ts
91
+ import {
92
+ isAtomicBatchRefusal,
93
+ isEvmSpokeOnlyChainKeyType,
94
+ isEvmWalletProviderType,
95
+ resolveApprovalStrategy,
96
+ sendApprovalBatch,
97
+ } from '@sodax/sdk';
98
+
99
+ if (
100
+ isEvmSpokeOnlyChainKeyType(srcChainKey) &&
101
+ isEvmWalletProviderType(walletProvider) &&
102
+ (await resolveApprovalStrategy({ srcChainKey, walletProvider, allowAccountUpgrade })) === 'atomic-batch'
103
+ ) {
104
+ // EVM source: approve.tx, approve.resetTx and createIntent's tx are all EvmRawTransaction.
105
+ const sent = await sendApprovalBatch({
106
+ walletProvider,
107
+ srcChainKey,
108
+ txs: [...(resetTx ? [resetTx] : []), tx, intentTx], // the intent tx last
109
+ timeoutMs: 120_000,
110
+ feature: 'swap',
111
+ onBatchSent: batchId => saveBatchId(batchId), // persist before the wait: the way back to an unconfirmed batch
112
+ });
113
+ if (sent.ok) {
114
+ // sent.value.txHash is the source tx: persist it, then submitTx({ txHash: sent.value.txHash, ... })
115
+ } else if (isAtomicBatchRefusal(sent.error)) {
116
+ // Refused before signing, nothing sent: approve separately (reset first), then create the intent again and send it.
117
+ } else {
118
+ // USER_REJECTED, 'atomic-batch-failed' (nothing landed) or ATOMIC_BATCH_UNCONFIRMED (may still land).
119
+ throw sent.error;
120
+ }
121
+ }
122
+ ```
123
+
124
+ The rules match `sodax.swaps.swapWithApproval`:
125
+
126
+ - `'sequential'` for the Sonic hub and any wallet without EIP-5792 support — approve, wait, then sign.
127
+ - Only `ATOMIC_BATCH_REFUSED` may fall back to separate transactions; the wallet signed nothing.
128
+ - `USER_REJECTED` — with `context.reason === ACCOUNT_UPGRADE_DECLINED` when the user declined the
129
+ smart-account upgrade; offer the swap again with `allowAccountUpgrade: false`.
130
+ - `TX_VERIFICATION_FAILED` with `context.reason === ATOMIC_BATCH_UNCONFIRMED` — the batch may still
131
+ land. Do not resend it, as a batch or as separate transactions: resume it later with
132
+ `confirmApprovalBatch({ walletProvider, batchId, callCount, timeoutMs, feature })`, which reads the
133
+ deposit's `txHash` once the wallet confirms it.
134
+
135
+ In React, the `sodax-dapp-kit` skill's `useSwapsApiBroadcastWithApproval` hook wraps this whole flow.
136
+
83
137
  ## Wire shapes — `bigint` vs decimal strings
84
138
 
85
139
  Request bodies that carry an `intent` struct (`cancelIntent`, `getIntentHash`,
@@ -99,10 +99,32 @@ type LookupErrorCode = 'VALIDATION_FAILED' | 'LOOKUP_FAILED' | 'UNKNOWN';
99
99
  |---|---|
100
100
  | `createIntent` | `CreateIntentErrorCode` |
101
101
  | `swap` | All of {`USER_REJECTED`, `VALIDATION_FAILED`, `INTENT_CREATION_FAILED`, `EXECUTION_FAILED`, `TX_VERIFICATION_FAILED`, `TX_SUBMIT_FAILED`, `RELAY_TIMEOUT`, `RELAY_FAILED`, `EXTERNAL_API_ERROR`, `UNKNOWN`} |
102
+ | `swapWithApproval` | `SwapWithApprovalErrorCode`: the `swap` codes plus `APPROVE_FAILED \| ALLOWANCE_CHECK_FAILED`. See [Atomic approval batches](#atomic-approval-batches-contextreason) for the batch reasons |
103
+ | `getApprovalStrategy` | `ApprovalStrategyErrorCode` (`ALLOWANCE_CHECK_FAILED` only) |
102
104
  | `postExecution` | `EXECUTION_FAILED \| EXTERNAL_API_ERROR \| UNKNOWN` (with `phase: 'postExecution'`) |
103
105
  | `createLimitOrder`, `createLimitOrderIntent` | `CreateIntentErrorCode` |
104
106
  | `cancelIntent`, `cancelLimitOrder` | `EXECUTION_FAILED \| VALIDATION_FAILED \| UNKNOWN` |
105
107
 
108
+ #### Atomic approval batches (`context.reason`)
109
+
110
+ When the approval and the deposit go out as one EIP-5792 batch (`swapWithApproval`,
111
+ `bridgeWithApproval`, `vaultSwapWithApproval`, or the shared `sendApprovalBatch` / `confirmApprovalBatch`
112
+ helpers), these codes carry a `context.reason` that changes
113
+ what the caller should do. Check it before the generic retry advice above.
114
+
115
+ | Code | `context.reason` | Meaning | Retry? |
116
+ |---|---|---|---|
117
+ | `USER_REJECTED` | `ACCOUNT_UPGRADE_DECLINED` | The user declined the smart-account upgrade, not the swap. | Offer it again with `allowAccountUpgrade: false` (two signatures). |
118
+ | `INTENT_CREATION_FAILED` | `ATOMIC_BATCH_REFUSED` | The wallet refused the batch before signing, or cannot batch. Nothing was sent. | Yes, approve separately. `swapWithApproval` does this itself; a caller of `sendApprovalBatch` does it. Test with `isAtomicBatchRefusal(error)`. |
119
+ | `INTENT_CREATION_FAILED` | `'atomic-batch-failed'` (with `batchId`, `statusCode`) | The batch was never included or fully reverted. Nothing was deposited. | Yes. |
120
+ | `TX_VERIFICATION_FAILED` | `ATOMIC_BATCH_UNCONFIRMED` (with `batchId`, `callCount`) | The wallet took the batch but it did not confirm in time. **It may still land.** | **No.** Do not let the user send it again. Resume it: call `swapWithApproval` / `bridgeWithApproval` / `vaultSwapWithApproval` again with `resumeBatchId` and `resumeBatchCallCount`, which sends nothing and finishes the flow once the batch lands; a `sendApprovalBatch` caller uses `confirmApprovalBatch`. |
121
+
122
+ `sendApprovalBatch` and `confirmApprovalBatch` return `ApprovalBatchErrorCode`
123
+ (`USER_REJECTED | INTENT_CREATION_FAILED | TX_VERIFICATION_FAILED`) on the `feature` the caller passes.
124
+ `confirmApprovalBatch` resumes a batch that came back unconfirmed, from the `batchId` that
125
+ `sendApprovalBatch` reported through `onBatchSent`. `resolveApprovalStrategy` does not fail: a wallet
126
+ whose capabilities cannot be read resolves to `'sequential'`.
127
+
106
128
  ### Money Market (`feature: 'moneyMarket'`)
107
129
 
108
130
  | Method | Narrow code union |
@@ -129,6 +151,8 @@ type LookupErrorCode = 'VALIDATION_FAILED' | 'LOOKUP_FAILED' | 'UNKNOWN';
129
151
  | Method | Narrow code union |
130
152
  |---|---|
131
153
  | `bridge` | All exec codes. |
154
+ | `bridgeWithApproval` | `BridgeWithApprovalErrorCode`: the `bridge` codes plus `APPROVE_FAILED \| ALLOWANCE_CHECK_FAILED`, with `context.action: 'bridgeWithApproval'` on the approval step. See [Atomic approval batches](#atomic-approval-batches-contextreason) for the batch reasons |
155
+ | `getApprovalStrategy` | `AllowanceCheckErrorCode` (the `isAllowanceValid` error, so invalid params stay `VALIDATION_FAILED`) |
132
156
  | `createBridgeIntent` | `CreateIntentErrorCode` |
133
157
  | `approve` | `ApproveErrorCode` |
134
158
  | `isAllowanceValid` | `AllowanceCheckErrorCode` |
@@ -166,12 +190,14 @@ Both follow the same shape: action methods get the full exec union (`'EXECUTION_
166
190
 
167
191
  ### Leverage Yield (`feature: 'leverageYield'`)
168
192
 
169
- Action discriminator on `context.action`: `'deposit' \| 'withdraw' \| 'approve' \| 'allowanceCheck' \| 'vaultSwap'`.
193
+ Action discriminator on `context.action`: `'deposit' \| 'withdraw' \| 'approve' \| 'allowanceCheck' \| 'vaultSwap' \| 'vaultSwapWithApproval'` (the last on the approval step of `vaultSwapWithApproval`).
170
194
 
171
195
  | Method | Narrow code union |
172
196
  |---|---|
173
197
  | `deposit`, `withdraw`, `createVaultIntent` | `CreateIntentErrorCode` (create-intent subset) |
174
198
  | `vaultSwap` | All exec codes: `VALIDATION_FAILED \| INTENT_CREATION_FAILED \| TX_VERIFICATION_FAILED \| TX_SUBMIT_FAILED \| RELAY_TIMEOUT \| RELAY_FAILED \| EXECUTION_FAILED \| EXTERNAL_API_ERROR \| UNKNOWN` |
199
+ | `vaultSwapWithApproval` | `VaultSwapWithApprovalErrorCode`: the `vaultSwap` codes plus `APPROVE_FAILED \| ALLOWANCE_CHECK_FAILED`. Errors after the broadcast are `vaultSwap`'s own. See [Atomic approval batches](#atomic-approval-batches-contextreason) for the batch reasons |
200
+ | `getApprovalStrategy` | `ApprovalStrategyErrorCode` (`ALLOWANCE_CHECK_FAILED` only); a hub-wallet swap resolves `'not-required'` |
175
201
  | `notifySolver` | `EXECUTION_FAILED \| EXTERNAL_API_ERROR \| UNKNOWN` (with `phase: 'postExecution'`) |
176
202
  | `approve` | `ApproveErrorCode` |
177
203
  | `isAllowanceValid` | `AllowanceCheckErrorCode` (action `'allowanceCheck'`) |
@@ -103,6 +103,35 @@ import {
103
103
  type INearWalletProvider,
104
104
  type IBitcoinWalletProvider,
105
105
 
106
+ // Approve + swap in one signature (see features/swap.md)
107
+ type SwapApprovalStrategy, // 'not-required' | 'atomic-batch' | 'sequential'
108
+ type SwapWithApprovalParams,
109
+ type SwapWithApprovalResponse,
110
+ type SwapWithApprovalErrorCode,
111
+ type ApprovalStrategyErrorCode,
112
+ ATOMIC_BATCH_UNCONFIRMED, // context.reason: the batch may still land; resume it with resumeBatchId, never resend
113
+ ACCOUNT_UPGRADE_DECLINED, // context.reason: retry with allowAccountUpgrade: false
114
+
115
+ // Approval batch helpers, for flows that build their own deposit (see features/swaps-api.md)
116
+ type ApprovalStrategy,
117
+ type ApprovalOptions,
118
+ type ApprovalBatchErrorCode,
119
+ type ApprovalBatchResult,
120
+ resolveApprovalStrategy, // 'atomic-batch' | 'sequential'; never fails
121
+ sendApprovalBatch, // [reset?, approve, deposit] as one EIP-5792 batch
122
+ confirmApprovalBatch, // resume a batch that came back unconfirmed
123
+ isAtomicBatchRefusal, // the one batch failure that may fall back to separate txs
124
+ ATOMIC_BATCH_REFUSED, // context.reason of that refusal
125
+ type ApprovalStrategyError,
126
+
127
+ // Approve + bridge / vault deposit in one signature (see features/bridge.md, features/leverage-yield.md)
128
+ type BridgeWithApprovalParams,
129
+ type BridgeWithApprovalResponse,
130
+ type BridgeWithApprovalErrorCode,
131
+ type VaultSwapWithApprovalParams,
132
+ type VaultSwapWithApprovalResponse,
133
+ type VaultSwapWithApprovalErrorCode,
134
+
106
135
  // Param types (per feature)
107
136
  type CreateIntentParams,
108
137
  type CreateLimitOrderParams,
@@ -218,7 +247,7 @@ This is a partial list — see `src/index.ts` of the published tarball for the a
218
247
  - **Import only from `@sodax/sdk` root.** No deep imports from `dist/...`.
219
248
  - **Do not depend on `@sodax/types` separately.** It's a transitive of `@sodax/sdk` (force-bundled via tsup `noExternal`); declaring it as a direct dependency invites version skew.
220
249
  - **Stable contract:** every export above is part of the public API. Anything not exported from the root barrel is internal — don't reach for it via `dist` paths.
221
- - **Tarball contents:** `dist/` (compiled JS + types). Nothing else ships. Consumer-facing AI docs (this tree) are shipped separately via [`@sodax/skills`](https://github.com/icon-project/sodax-sdks/tree/main/packages/skills).
250
+ - **Tarball contents:** `dist/` (compiled JS + types). Nothing else ships. Consumer-facing AI docs (this tree) are shipped separately via [`@sodax/skills`](https://github.com/gosodax/sodax-sdks/tree/main/packages/skills).
222
251
 
223
252
  ---
224
253
 
@@ -14,8 +14,8 @@ Granular skill for `LeverageYieldService` — `sodax.leverageYield`. Feature tag
14
14
  ## Step 1 — Clarify with user before coding
15
15
 
16
16
  0. **Vault or leverage position?** Ask this first — they share the service and nothing else. A **vault** is one pooled ERC-4626 position at a single target LTV, entered/exited as an intent swap (`deposit` / `withdraw` / `vaultSwap`). A **leverage position** is the user's own AAVE account, cloned per position, with its own eMode category and leverage tier (`openLeveragePosition` and friends). "Deposit into a leverage vault" is the first; "open a leverage position", "adjust my leverage", "close my position" is the second. If the answer is positions, jump to Step 1b.
17
- 1. **Deposit or withdraw?** Deposit = any spoke token → `lsoda*` shares (delivered to the user's hub wallet). Withdraw = `lsoda*` shares (in the hub wallet) → any token on any chain.
18
- 2. **Build vs execute.** `deposit` / `withdraw` only *build* a `LeverageYieldSwapPayload`; `vaultSwap` *executes* it end-to-end. Spread the built payload into `vaultSwap({ ...payload, walletProvider })`.
17
+ 1. **Deposit or withdraw?** Deposit = any spoke token → `lsoda*` shares (delivered to the user's hub wallet). Withdraw = `lsoda*` shares (in the hub wallet) → any token on any chain. **Except Bitcoin:** vault swaps refuse it on either side with `VALIDATION_FAILED`.
18
+ 2. **Build vs execute.** `deposit` / `withdraw` only *build* a `LeverageYieldSwapPayload`; `vaultSwap` *executes* it end-to-end. Spread the built payload into `vaultSwap({ ...payload, walletProvider })`. `vaultSwapWithApproval` does the same with the deposit's approval folded in (one EIP-5792 batch when the wallet can); `getApprovalStrategy` predicts the path.
19
19
  3. **End-to-end or manual relay?** By default `vaultSwap` creates the intent and hands it to the backend submit-tx flow, which relays and notifies the solver; on any backend non-success it falls back to verify → relay → notify client-side, and then resolves before the fill (opt out of the backend path with `leverageYield: { useBackendSubmitTx: false }`). For a fully manual flow, use `createVaultIntent`, relay yourself, and finish with the public `notifySolver`.
20
20
  4. **Which vaults?** `listVaults()` (synchronous registry: `{ name, vault, asset, borrowToken, lsdSource? }`); pass `vault` to every call.
21
21
  5. **Reads?** `getEffectiveApr` (headline, AAVE + LSD), `getApr` (AAVE-only — can be negative), `getPosition`, `getTotalAssets`, `previewRedeem`, `getMaxWithdrawForUser` / `getShareBalanceForUser` (resolve the hub wallet from a spoke address internally).
@@ -48,6 +48,7 @@ Granular skill for `LeverageYieldService` — `sodax.leverageYield`. Feature tag
48
48
  - **Quoting a vault flow through `sodax.swaps.getQuote`.** It deducts the effective *swap* fee, while the vault intent charges the effective *leverage-yield* fee (`leverageYield.partnerFee ?? fee`) — the two disagree whenever the feature fees differ. It can be made to agree by passing the leverage-yield fee explicitly (with a zero fee — `{ address, percentage: 0 }` — where that fee is `undefined`, since an explicit `undefined` falls back to the swap fee), but prefer `sodax.leverageYield.getQuote` (`token_dst` = vault for a deposit, `token_src` = vault for a withdraw).
49
49
  - **Quoting with a different `partnerFee` than the intent charges.** The fee is deducted from the input before the swap, so the quote is sized on a different net input; when the intent's fee is the larger one, the `minOutputAmount` derived from that quote can't be met and the intent never fills. Pass the same `partnerFee` to `getQuote` and to `deposit()` / `vaultSwap()`, or omit it on both.
50
50
  - **Assuming `swaps.partnerFee` monetizes vault flows.** It does not — configure `leverageYield.partnerFee` (or the global `fee`).
51
+ - **Reporting a vault swap as lost on a post-broadcast failure.** `TX_VERIFICATION_FAILED`, the relay codes and post-execution failures from `vaultSwap` carry `error.context.srcTxHash` — the vault swap may still complete, so keep polling `getDetailedStatus` with it. A failed solver notification also carries `error.context.dstTxHash`: call `notifySolver({ intent_tx_hash })` with it again first, since polling never notifies.
51
52
 
52
53
  ### Leverage-position anti-patterns
53
54
 
@@ -176,7 +176,7 @@ If you pass a config override to `new Sodax({ ... })`, put solver endpoints in `
176
176
  v1 had per-feature relay helpers (each feature module had its own `*WaitForRelay()` or `relay*Tx()` function). v2 centralises this into `IntentRelayApiService` with two public entry points:
177
177
 
178
178
  - `submitTransaction(payload, apiUrl)` — TWO positional args (`payload: IntentRelayRequest<'submit'>`, `apiUrl: HttpUrl`), not an options object. POSTs the spoke transaction to the relay submit endpoint and resolves the relay's first-stage acknowledgement.
179
- - `relayTxAndWaitPacket({ srcTxHash, data, chainKey, relayerApiEndpoint, timeout, pollTxHash? })` — `RelayAndWaitParams`: `data` is the whole `RelayExtraData` / `OnDemandRelayData` object, `chainKey` is the source `SpokeChainKey`. Runs `submitTransaction` and then polls until the destination packet reaches `executed`. Resolves with `{ srcTxHash, dstTxHash, packet }` on success.
179
+ - `relayTxAndWaitPacket({ srcTxHash, data?, chainKey, relayerApiEndpoint, timeout, pollTxHash? })` — `RelayAndWaitParams`: `data` is the whole `RelayExtraData` / `OnDemandRelayData` object (required for Solana and Bitcoin), `chainKey` is the source `SpokeChainKey`. Runs `submitTransaction` and then polls until the destination packet reaches `executed`. Resolves with `{ srcTxHash, dstTxHash, packet }` on success.
180
180
 
181
181
  Internally, every feature service now calls `relayTxAndWaitPacket` for the spoke→hub leg. Failures from this layer surface to consumers via `mapRelayFailure`.
182
182
 
@@ -52,7 +52,7 @@ All v1 fields were **optional**. v1 had **no** top-level `rpcConfig` on `SodaxCo
52
52
  | `SodaxConfig.swaps` (`SolverConfigParams` — `{ intentsContract, solverApiEndpoint, protocolIntentsContract?, partnerFee? }`) | **Split into two:** `SodaxConfig.solver: SolverConfig` (`{ intentsContract, solverApiEndpoint, protocolIntentsContract }`) and `SodaxConfig.swaps: SwapsConfig` (supported tokens per chain — new in v2). | v1 partner-fee inside `SolverConfigParams` moves to the global `SodaxOptions.fee` option or per-feature configs. |
53
53
  | `SodaxConfig.hubProviderConfig` (`EvmHubProviderConfig` — `{ hubRpcUrl, chainConfig }`) | **`SodaxConfig.hub`** (`HubConfig` — full hub addresses + native token + bnUSD + polling + RPC URL). | Field renamed `hubProviderConfig` → `hub`. Shape expanded: v1 just had RPC URL + chain config; v2 ships the full hub-contract address map. |
54
54
  | `SodaxConfig.moneyMarket` (`MoneyMarketConfigParams`) | `SodaxConfig.moneyMarket` (`MoneyMarketConfig` — required, shape changed). | Reshape, see `@sodax/types/src/common/common.ts` MoneyMarketConfig. |
55
- | `SodaxConfig.bridge` (`BridgeServiceConfig`) | `SodaxConfig.bridge` (`BridgeConfig` — `{ partnerFee }`). | Reshape; smaller. |
55
+ | `SodaxConfig.bridge` (`BridgeServiceConfig`) | `SodaxConfig.bridge` (`BridgeConfig` — `{ partnerFee }`). | Reshape; smaller. Client-side option `bridge.useBackendSubmitTx` (default **on**) selects the backend submit-tx path. |
56
56
  | `SodaxConfig.dex` (`DexServiceConfig`) | `SodaxConfig.dex` (`DexConfig`). | Reshape. |
57
57
  | `SodaxConfig.relayerApiEndpoint: HttpUrl` (string) | **`SodaxConfig.relay`** (`RelayConfig` — object with relayer URL + chain-id map). | Renamed + reshaped from string to object. |
58
58
  | `SodaxConfig.backendApiConfig` (`BackendApiConfig`) | **`SodaxConfig.api`** (`ApiConfig`). | Renamed. |
@@ -63,6 +63,14 @@ All v1 fields were **optional**. v1 had **no** top-level `rpcConfig` on `SodaxCo
63
63
  | (none in v1) | **`SodaxOptions.fee?: PartnerFee`** (new — a client-side option, NOT a `SodaxConfig` data field). | Global partner fee, set via `new Sodax({ fee })` and read back on `sodax.config.fee`. A client option like `logger` — never fetched from or overwritten by the backend. Per-feature overrides still live on `SodaxConfig` (`bridge.partnerFee`, `swaps.partnerFee`, `moneyMarket.partnerFee`). |
64
64
  | (v1 had no top-level `configService` injection slot on `SodaxConfig` — `ConfigService` was always constructed internally from `backendApiConfig` + `sharedConfig`.) | Same — `ConfigService` is internal. v2 does **not** expose a typed slot to inject a custom `IConfigApi` either. To swap the backend in tests, point `SodaxConfig.api.baseURL` at a mock server. | See Pitfall below. |
65
65
 
66
+ **Within v2, too:** `swaps.useBackendSubmitTx` / `bridge.useBackendSubmitTx` (client-side options, default **on**)
67
+ replace the earlier `swapsOptions` / `bridgeOptions` keys (`SwapsClientOptions` / `BridgeClientOptions`). The old keys
68
+ are deprecated, honoured only when the new flag is omitted, and removed in v3, where the only form is
69
+ `swaps: { partnerFee, useBackendSubmitTx }` / `bridge: { partnerFee, useBackendSubmitTx }`. Do not generate the old
70
+ keys; an explicit `false` on the new key keeps the fully client-side relay path. A `SwapService` built directly
71
+ (not through `new Sodax`) also still accepts a deprecated `useBackendSubmitTx` constructor field, which wins over the
72
+ configured value; it is removed in v3 too.
73
+
66
74
  Migration:
67
75
 
68
76
  ```diff
@@ -22,7 +22,7 @@ Swap has materially different code paths depending on the answers. Don't skip:
22
22
  - Signed → `raw: false` + `walletProvider`.
23
23
  - Unsigned → `raw: true`, you handle relay yourself.
24
24
  3. **One-shot `swap()` or step-by-step (`createIntent` → backend submit → `postExecution`)?**
25
- - One-shot is the default for frontends. Step-by-step is for backends that already have a relay/orchestration layer.
25
+ - One-shot is the default for frontends. If the token may need an approval, prefer `swapWithApproval()` — it approves only when needed, and on an EIP-5792 wallet does approve + swap in one signature (`getApprovalStrategy()` tells you which path it will take). A wallet that must first upgrade the account (`'ready'`) prompts for it; pass `allowAccountUpgrade: false` to skip that and approve separately, e.g. after a `USER_REJECTED` with `context.reason === ACCOUNT_UPGRADE_DECLINED`. Step-by-step is for backends that already have a relay/orchestration layer.
26
26
  - Step-by-step code must reproduce BOTH paths `swap()` runs internally — the backend submit-tx attempt *and* the client-side relay fallback on any non-success. The helpers behind `swap()` are package-internal, so the loop is hand-written: [`../integration/knowledge/recipes/manual-submit-tx-with-fallback.md`](../integration/knowledge/recipes/manual-submit-tx-with-fallback.md).
27
27
  4. **Market order or limit order?** Limit orders use a different params shape — `deadline` becomes optional (forced to `0n` internally), not required.
28
28
 
@@ -37,11 +37,13 @@ Read in order. Skipping `ai-rules.md` is the most common cause of agents reverti
37
37
  - Backend step-by-step → [`../integration/knowledge/recipes/raw-tx-flow.md`](../integration/knowledge/recipes/raw-tx-flow.md) + [`../integration/knowledge/recipes/backend-server-init.md`](../integration/knowledge/recipes/backend-server-init.md)
38
38
  4. Error handling for swap-specific codes (`INTENT_CREATION_FAILED`, `EXECUTION_FAILED`, `RELAY_TIMEOUT`, solver-side `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).
39
39
  5. Cross-chain destination quirks (Stellar trustline, BTC PSBT, Solana PDA) → [`../integration/knowledge/chain-specifics.md`](../integration/knowledge/chain-specifics.md).
40
+ 6. Reading swap status → [`../integration/knowledge/features/swap.md`](../integration/knowledge/features/swap.md) § Reading swap status. Default to `getDetailedStatus({ srcChainKey, srcTxHash })` (works whichever completion path ran) and collapse it with `summarizeSwapStatus`.
40
41
 
41
42
  ### Swap-specific anti-patterns
42
43
 
43
44
  - **`try { await sodax.swaps.swap(...) } catch` for SDK-level failures.** v2 returns `Result<T>` — branch on `result.ok`. `catch` only fires for thrown exceptions (e.g. missing `walletProvider`), not for `RELAY_TIMEOUT` or `EXECUTION_FAILED`.
44
45
  - **Forgetting the discriminator.** `raw: false` is required on signed swaps; without it TypeScript rejects `walletProvider`.
46
+ - **Reporting a swap as lost on a post-broadcast failure.** `TX_VERIFICATION_FAILED`, the relay codes and postExecution failures carry `error.context.srcTxHash` — the backend may still complete the swap, so keep polling `getDetailedStatus` with it. A failed solver notification also carries `error.context.dstTxHash`: call `postExecution({ intent_tx_hash })` with it again first, since polling never notifies.
45
47
  - **Calling `sodax.api.swaps.submitTx` with the full `relayData` object.** The backend expects the `payload: string` field, not the wrapper.
46
48
 
47
49
  ## Migration workflow (port v1 swap to v2)
@@ -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
 
@@ -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, EVM chain switching, WalletConnect, 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". 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.'
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'
@@ -32,6 +32,7 @@ If the task is one wallet concern, load its granular skill instead of this broad
32
32
  | EVM chain switching / wrong network | [`./switch-chain/SKILL.md`](./switch-chain/SKILL.md) | "useEvmSwitchChain", "wrong network banner" |
33
33
  | Sign an arbitrary message | [`./sign-message/SKILL.md`](./sign-message/SKILL.md) | "useXSignMessage", "prove wallet ownership", "SIWE" |
34
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" |
35
36
 
36
37
  Load this broad skill (keep reading below) for a full wallet setup, several concerns at once, or a v1 port.
37
38
 
@@ -45,6 +46,7 @@ Pick this mode when the consumer is a React dapp that needs SODAX wallet connect
45
46
  - "Multi-chain modal UI" — `useWalletModal`, `useChainGroups`, `useConnectedChains`.
46
47
  - "Pass the connected wallet to a `@sodax/sdk` swap" — `useWalletProvider({ xChainId })`.
47
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`.
48
50
  - "SSR with Next.js" — `ssr: true` flag on the EVM slot.
49
51
 
50
52
  ### Workflow
@@ -52,8 +54,8 @@ Pick this mode when the consumer is a React dapp that needs SODAX wallet connect
52
54
  1. Read [`integration/knowledge/ai-rules.md`](./integration/knowledge/ai-rules.md) — DO / DON'T + workflow.
53
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`.
54
56
  3. Read [`integration/knowledge/architecture.md`](./integration/knowledge/architecture.md) — provider mount tree, frozen config, EVM single-connection model, `xChainType` vs `xChainId`.
55
- 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`.
56
- 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`).
57
59
  6. Lookups → [`integration/knowledge/reference/`](./integration/knowledge/reference/) — hooks, connectors, chain-support, wallet-brands, api-surface.
58
60
 
59
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