@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.
- package/AGENTS.md +7 -7
- package/README.md +5 -5
- package/package.json +4 -4
- package/skills/sodax-build/SKILL.md +1 -1
- package/skills/sodax-build/knowledge/README.md +1 -1
- package/skills/sodax-build/knowledge/feature-catalog.md +4 -0
- package/skills/sodax-build/knowledge/glossary.md +1 -0
- package/skills/sodax-build/knowledge/handoff.md +3 -0
- package/skills/sodax-build/knowledge/interview-guide.md +1 -0
- package/skills/sodax-dapp-kit/auxiliary-services/SKILL.md +4 -1
- package/skills/sodax-dapp-kit/bridge/SKILL.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/architecture.md +18 -4
- package/skills/sodax-dapp-kit/integration/knowledge/features/auxiliary-services.md +23 -1
- package/skills/sodax-dapp-kit/integration/knowledge/features/bridge.md +8 -0
- package/skills/sodax-dapp-kit/integration/knowledge/features/leverage-yield.md +5 -3
- package/skills/sodax-dapp-kit/integration/knowledge/features/swap.md +24 -0
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/bridge.md +2 -0
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/leverage-yield.md +1 -0
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/swap.md +141 -1
- package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md +8 -0
- package/skills/sodax-dapp-kit/integration/knowledge/reference/public-api.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/reference/querykey-conventions.md +8 -0
- package/skills/sodax-dapp-kit/leverage-yield/SKILL.md +3 -3
- package/skills/sodax-dapp-kit/swap/SKILL.md +3 -3
- package/skills/sodax-sdk/bridge/SKILL.md +3 -1
- package/skills/sodax-sdk/integration/knowledge/architecture.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/features/bridge-api.md +5 -3
- package/skills/sodax-sdk/integration/knowledge/features/bridge.md +8 -0
- package/skills/sodax-sdk/integration/knowledge/features/leverage-yield.md +25 -2
- package/skills/sodax-sdk/integration/knowledge/features/swap.md +72 -2
- package/skills/sodax-sdk/integration/knowledge/features/swaps-api.md +56 -2
- package/skills/sodax-sdk/integration/knowledge/reference/error-codes.md +27 -1
- package/skills/sodax-sdk/integration/knowledge/reference/public-api.md +30 -1
- package/skills/sodax-sdk/leverage-yield/SKILL.md +3 -2
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/architecture.md +1 -1
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/reference/sodax-config.md +9 -1
- package/skills/sodax-sdk/swap/SKILL.md +3 -1
- package/skills/sodax-sdk/swaps-api/SKILL.md +3 -2
- package/skills/sodax-wallet-sdk-core/evm/SKILL.md +2 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/README.md +1 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/evm.md +6 -0
- package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/interfaces.md +4 -1
- package/skills/sodax-wallet-sdk-core/migration-v1-to-v2/knowledge/README.md +1 -1
- package/skills/sodax-wallet-sdk-react/SKILL.md +5 -3
- package/skills/sodax-wallet-sdk-react/integration/knowledge/README.md +2 -1
- package/skills/sodax-wallet-sdk-react/integration/knowledge/ai-rules.md +2 -0
- package/skills/sodax-wallet-sdk-react/integration/knowledge/architecture.md +10 -6
- package/skills/sodax-wallet-sdk-react/integration/knowledge/examples/05-privy-email-login.tsx +157 -0
- package/skills/sodax-wallet-sdk-react/integration/knowledge/examples/README.md +1 -0
- package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/privy-email-login.md +111 -0
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/api-surface.md +14 -0
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/chain-support.md +1 -1
- package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/README.md +1 -1
- package/skills/sodax-wallet-sdk-react/privy/SKILL.md +53 -0
- 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`.
|
|
67
|
-
|
|
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/
|
|
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
|
|
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/
|
|
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/
|
|
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/) —
|
|
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/
|
|
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}>
|
|
29
|
-
<
|
|
30
|
-
<
|
|
31
|
-
{
|
|
32
|
-
|
|
33
|
-
|
|
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
|