@sodax/skills 2.2.0-rc.7 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (23) hide show
  1. package/AGENTS.md +4 -3
  2. package/package.json +3 -2
  3. package/skills/sodax-build/SKILL.md +2 -2
  4. package/skills/sodax-dapp-kit/SKILL.md +23 -5
  5. package/skills/sodax-dapp-kit/auxiliary-services/SKILL.md +1 -1
  6. package/skills/sodax-dapp-kit/integration/knowledge/ai-rules.md +3 -0
  7. package/skills/sodax-dapp-kit/integration/knowledge/features/auxiliary-services.md +15 -5
  8. package/skills/sodax-dapp-kit/integration/knowledge/features/leverage-yield.md +13 -1
  9. package/skills/sodax-dapp-kit/integration/knowledge/recipes/README.md +1 -0
  10. package/skills/sodax-dapp-kit/integration/knowledge/recipes/dex.md +23 -8
  11. package/skills/sodax-dapp-kit/integration/knowledge/recipes/leverage-yield-product-anatomy.md +150 -0
  12. package/skills/sodax-dapp-kit/integration/knowledge/recipes/leverage-yield.md +121 -38
  13. package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md +6 -3
  14. package/skills/sodax-dapp-kit/leverage-yield/SKILL.md +25 -8
  15. package/skills/sodax-sdk/SKILL.md +2 -1
  16. package/skills/sodax-sdk/integration/knowledge/ai-rules.md +3 -0
  17. package/skills/sodax-sdk/integration/knowledge/features/leverage-yield.md +57 -11
  18. package/skills/sodax-sdk/integration/knowledge/features/sponsoring.md +3 -1
  19. package/skills/sodax-sdk/integration/knowledge/features/swaps-api.md +5 -0
  20. package/skills/sodax-sdk/integration/knowledge/recipes/initialize-sodax.md +1 -1
  21. package/skills/sodax-sdk/leverage-yield/SKILL.md +14 -7
  22. package/skills/sodax-wallet-sdk-core/SKILL.md +20 -2
  23. package/skills/sodax-wallet-sdk-react/SKILL.md +16 -1
@@ -16,8 +16,9 @@ Granular skill for `LeverageYieldService` — `sodax.leverageYield`. Feature tag
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
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
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 })`.
19
- 3. **End-to-end or manual relay?** `vaultSwap` does create → verify → relay → notify. For backend submit-tx, use `createVaultIntent` then relay yourself and finish with the public `notifySolver`.
20
- 4. **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).
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
+ 4. **Which vaults?** `listVaults()` (synchronous registry: `{ name, vault, asset, borrowToken, lsdSource? }`); pass `vault` to every call.
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).
21
22
 
22
23
  ### Step 1b — leverage positions
23
24
 
@@ -41,6 +42,9 @@ Granular skill for `LeverageYieldService` — `sodax.leverageYield`. Feature tag
41
42
  - **Using `getApr` as the headline number.** For LSD-backed vaults the AAVE-only spread is often negative; `getEffectiveApr` folds in the LSD staking yield (the real source of return).
42
43
  - **Passing a spoke address to `getShareBalance` / `getMaxWithdraw`.** Those take a hub address. Use the `*ForUser(vault, srcChainKey, srcAddress)` variants to resolve the hub wallet first.
43
44
  - **Gating withdraw on `approve` / `isAllowanceValid`.** Those are Sonic-direct allowance helpers for the vault's underlying asset; the swap-style withdraw authorises the share spend via a hub-wallet `Connection.sendMessage` (`hubWalletSwap: true`).
45
+ - **Sending `minOutputAmount: 0n`.** Derive it from `sodax.leverageYield.getQuote`'s `quoted_amount` minus a slippage tolerance in basis points. The SDK does not reject zero, and a zero minimum accepts any fill.
46
+ - **Adding a `partnerFee` nobody asked for.** It is optional and opt-in; leave it out unless the integrator gave you their own receiver. Never copy a fee address from a SODAX demo or doc.
47
+ - **Reading `leverageMultiplierWad` as total exposure.** It is the borrowed multiple, `targetLTV / (1 − targetLTV)`; exposure is `1 + multiplier`. `targetLtvBps` and `getPosition().ltv` are basis points.
44
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).
45
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.
46
50
  - **Assuming `swaps.partnerFee` monetizes vault flows.** It does not — configure `leverageYield.partnerFee` (or the global `fee`).
@@ -63,14 +67,17 @@ Granular skill for `LeverageYieldService` — `sodax.leverageYield`. Feature tag
63
67
 
64
68
  1. `pnpm tsc --noEmit` clean.
65
69
  2. Every `await sodax.leverageYield.<method>(...)` has `if (!result.ok)`.
66
- 3. Deposit/withdraw build a payload that is then run through `vaultSwap` (or `createVaultIntent` + relay + `notifySolver`).
67
- 4. APR display uses `getEffectiveApr`; share/withdraw sizing from a spoke address uses the `*ForUser` reads.
68
- 5. Positions: every `borrowAmount` / `minCollateralOut` traces back to `sizeLeverageBorrow` + `projectLeverageLeg` (never oracle parity), `exceedsMaxLtv` is checked before posting, and `notified` is read on every open / leverage change.
69
- 6. Positions: leverage changes go through `submitLeveragePositionIntent`, not `runLeveragePositionOperation`; `notifySolver` is given `dstChainTxHash`; exits are sized from `getPositionCollateralBalance` and charge the fee from `getPositionInfo`.
70
+ 3. Every `minOutputAmount` comes from `sodax.leverageYield.getQuote` minus slippage; no `0n`, no unrequested `partnerFee`.
71
+ 4. Deposit/withdraw build a payload that is then run through `vaultSwap` (or `createVaultIntent` + relay + `notifySolver`).
72
+ 5. APR display uses `getEffectiveApr`; share/withdraw sizing from a spoke address uses the `*ForUser` reads.
73
+ 6. Positions: every `borrowAmount` / `minCollateralOut` traces back to `sizeLeverageBorrow` + `projectLeverageLeg` (never oracle parity), `exceedsMaxLtv` is checked before posting, and `notified` is read on every open / leverage change.
74
+ 7. Positions: leverage changes go through `submitLeveragePositionIntent`, not `runLeveragePositionOperation`; `notifySolver` is given `dstChainTxHash`; exits are sized from `getPositionCollateralBalance` and charge the fee from `getPositionInfo`.
70
75
 
71
76
  ## Related granular skills (same family)
72
77
 
73
- - [`../swap/SKILL.md`](../swap/SKILL.md) — `vaultSwap` is a leverage-yield copy of the swap intent flow; quote `minOutputAmount` via the solver quote there.
78
+ - [`../swap/SKILL.md`](../swap/SKILL.md) — `vaultSwap` is a leverage-yield copy of the swap intent flow. Quote `minOutputAmount` with `sodax.leverageYield.getQuote`, not the swap skill's `getQuote`.
74
79
  - [`../recovery/SKILL.md`](../recovery/SKILL.md) — recover stuck hub-wallet assets (including `lsoda*` shares) back to a spoke chain.
75
80
 
76
81
  For multi-feature tasks, load the broad [`sodax-sdk` skill](../SKILL.md).
82
+
83
+ Building a user-facing React vault screen? Load the `sodax-dapp-kit` skill's leverage-yield granular skill: its product anatomy covers the journey, the states, USD prices, derived values and the units table.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: sodax-wallet-sdk-core
3
- description: 'Sign and broadcast SODAX transactions from a backend, script, CI, bot, or non-React app with @sodax/wallet-sdk-core — one wallet-provider class per chain family (EVM, Solana, Sui, Bitcoin, Stellar, ICON, Injective, NEAR, Stacks). INTEGRATION (write NEW code) — the low-level multi-chain wallet layer (one provider class per chain family across 9 chain types). Each class accepts either a private-key config (Node scripts, CI, bots, indexers) or a browser-extension config (custom non-React browser flows) and signs + broadcasts transactions. Use whenever a backend, script, test, or non-React browser flow needs to instantiate a wallet provider directly — `EvmWalletProvider`, `SolanaWalletProvider`, etc. Triggers on "instantiate EvmWalletProvider", "sign a tx from a Node script", "wallet provider for backend", "private-key signing", "wallet-sdk-core setup", any `*WalletProvider` class name. For React dapps prefer `sodax-wallet-sdk-react` instead — most React consumers never touch this package directly and get a typed `IXxxWalletProvider` via `useWalletProvider(...)`. MIGRATION (port v1 → v2) — v1 → v2 changes are additive (same class names, same config-type names, same config shapes). The only mechanical migration is replacing deep imports from v1''s flat `wallet-providers/<chain>.ts` layout with barrel imports, plus optionally adopting the new `defaults` field and re-imported library types. Triggers on imports from `@sodax/wallet-sdk-core/wallet-providers/…`, bumping from an older RC, or adopting new additive `defaults` / `*WalletDefaults` / `*Policy` fields. Most projects don''t need a wallet-sdk-core migration — the real migration target is usually `@sodax/sdk` or `@sodax/types`. Load this skill if EITHER applies; the body gates by mode.'
3
+ description: 'Sign and broadcast SODAX transactions from a backend, script, CI, bot, or non-React app with @sodax/wallet-sdk-core — one wallet-provider class per chain family (EVM, Solana, Sui, Bitcoin, Stellar, ICON, Injective, NEAR, Stacks). INTEGRATION (write NEW code) — each class accepts a private-key config (Node scripts, CI, bots, indexers) or a browser-extension config (custom non-React browser flows). Use whenever non-React code must instantiate a wallet provider directly. Triggers on "instantiate EvmWalletProvider", "sign a tx from a Node script", "wallet provider for backend", "private-key signing", "wallet-sdk-core setup", any `*WalletProvider` class name. For React dapps prefer `sodax-wallet-sdk-react` — React consumers get a typed `IXxxWalletProvider` via `useWalletProvider(...)`. MIGRATION (port v1 → v2) — changes are additive (same class, config-type and config-shape names). The only mechanical step is replacing deep imports from v1''s flat `wallet-providers/<chain>.ts` layout with barrel imports, plus optionally adopting the new `defaults` field and re-imported library types. Triggers on imports from `@sodax/wallet-sdk-core/wallet-providers/…`, bumping from an older RC, or adopting `defaults` / `*WalletDefaults` / `*Policy` fields. Most projects need no wallet-sdk-core migration — the real target is usually `@sodax/sdk` or `@sodax/types`. Load this skill if EITHER applies; the body gates by mode.'
4
4
  license: MIT
5
5
  metadata:
6
6
  version: '0.0.1'
@@ -18,6 +18,24 @@ AGENTS.md routes you here when you're working with `@sodax/wallet-sdk-core` v2
18
18
 
19
19
  For React consumers → use `sodax-wallet-sdk-react` (they get the typed wallet provider via `useWalletProvider(...)` and pass it to `@sodax/sdk` calls).
20
20
 
21
+ ## Prefer a granular skill if the chain is known
22
+
23
+ If the task targets one chain family, load its granular skill instead of this broad one. It covers that provider's config, methods and gotchas, for both integration and migration.
24
+
25
+ | Chain family | Granular skill | Trigger phrases |
26
+ |---|---|---|
27
+ | EVM (Sonic hub + every EVM spoke) | [`./evm/SKILL.md`](./evm/SKILL.md) | "instantiate EvmWalletProvider", "viem wallet for Sonic / Base / Arbitrum" |
28
+ | Solana | [`./solana/SKILL.md`](./solana/SKILL.md) | "SolanaWalletProvider", "sign a Solana tx from Node" |
29
+ | Sui | [`./sui/SKILL.md`](./sui/SKILL.md) | "SuiWalletProvider", "Sui signing from a script" |
30
+ | Bitcoin (PSBT) | [`./bitcoin/SKILL.md`](./bitcoin/SKILL.md) | "BitcoinWalletProvider", "sign a PSBT" |
31
+ | Stellar | [`./stellar/SKILL.md`](./stellar/SKILL.md) | "StellarWalletProvider", "Stellar signing from a backend" |
32
+ | ICON | [`./icon/SKILL.md`](./icon/SKILL.md) | "IconWalletProvider", "Hana wallet relay" |
33
+ | Injective | [`./injective/SKILL.md`](./injective/SKILL.md) | "InjectiveWalletProvider", "Injective MsgBroadcaster" |
34
+ | NEAR | [`./near/SKILL.md`](./near/SKILL.md) | "NearWalletProvider", "NEAR signing from Node" |
35
+ | Stacks | [`./stacks/SKILL.md`](./stacks/SKILL.md) | "StacksWalletProvider", "Stacks signing from a script" |
36
+
37
+ Load this broad skill (keep reading below) when the task spans several chain families or the chain is undecided.
38
+
21
39
  ---
22
40
 
23
41
  ## Integration mode (writing new v2 code)
@@ -33,7 +51,7 @@ Direct usage of `@sodax/wallet-sdk-core` is the right choice for:
33
51
  1. Read [`integration/knowledge/ai-rules.md`](./integration/knowledge/ai-rules.md) — DO / DON'T + workflow + stop conditions.
34
52
  2. Read [`integration/knowledge/architecture.md`](./integration/knowledge/architecture.md) — mental model: `BaseWalletProvider`, dual-config discriminants (Bitcoin/Stellar via an explicit `type` field, every other chain via field presence), shallow `defaults` merge, library-exports.
35
53
  3. Read [`integration/knowledge/quickstart.md`](./integration/knowledge/quickstart.md) — copy-paste minimal example for the chain you need.
36
- 4. For your chain, read [`integration/knowledge/features/`](./integration/knowledge/features/) — per-chain config table + methods + gotchas (one file per chain family).
54
+ 4. For your chain, read [`integration/knowledge/features/`](./integration/knowledge/features/) — per-chain config table + methods + gotchas, one file per chain family: `evm.md`, `solana.md`, `sui.md`, `bitcoin.md`, `stellar.md`, `icon.md`, `injective.md`, `near.md`, `stacks.md`.
37
55
  5. Task-specific recipes → [`integration/knowledge/recipes/`](./integration/knowledge/recipes/) — `setup-private-key.md`, `setup-browser-extension.md`, `sign-and-broadcast.md`, `defaults-and-overrides.md`, `library-exports.md`, `bridge-to-sdk.md` (pass provider to `@sodax/sdk`).
38
56
  6. Lookups → [`integration/knowledge/reference/`](./integration/knowledge/reference/) — public API, provider classes, interfaces (`IXxxWalletProvider`), chain support, glossary.
39
57
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: sodax-wallet-sdk-react
3
- description: 'Add SODAX multi-chain wallet connectivity to a React dapp with @sodax/wallet-sdk-react — connect/disconnect, account & signing hooks, a headless wallet modal, WalletConnect, and bridging the connected wallet into @sodax/sdk. INTEGRATION (write NEW code) — the React wallet connectivity layer for multi-chain dapps. Covers `SodaxWalletProvider` setup, hook-based connect/disconnect/account/signing UX across 9 chain types (EVM, Solana, Sui, Bitcoin, Stellar, ICON, Injective, NEAR, Stacks), headless wallet-modal primitives, WalletConnect for non-injected wallets (Fireblocks/Ledger/mobile), and `useWalletProvider` for bridging the connected wallet into `@sodax/sdk` calls. Use whenever a React dapp needs SODAX wallet connectivity. Triggers on "add wallet connect", "set up SodaxWalletProvider", "useXConnect", "useXAccount", "useWalletProvider", "useWalletModal", "wallet modal", "connect button", "multi-chain wallet UI", "WalletConnect for Fireblocks". Peer deps: `react >= 19`, `@tanstack/react-query 5.x`. MIGRATION (port v1 → v2) — the v2 reshape removed `useXWagmiStore` from the public API (each selector must be replaced with a public hook like `useXServices` / `useXService({ xChainType })` / `useXConnections` / `useXConnection({ xChainType })`; do NOT rename to `useXWalletStore` — the v2 barrel does not export it), unified hook signatures to single-object params, reshaped `SodaxWalletProvider` props (removed `rpcConfig` / `options` / `initialState` in favor of `config: SodaxWalletConfig`), and flattened the chain-slot wrapper (`chains: { EVM, SOLANA, ... }` → top-level slots on `SodaxWalletConfig`). Triggers on "useXWagmiStore is gone", "SodaxWalletProvider props broke", "old wallet-sdk-react hooks", "upgrade @sodax/wallet-sdk-react". Load this skill if EITHER applies; the body gates by mode.'
3
+ description: 'Add SODAX multi-chain wallet connectivity to a React dapp with @sodax/wallet-sdk-react — connect/disconnect, account & signing hooks, a headless wallet modal, EVM chain switching, WalletConnect, 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.'
4
4
  license: MIT
5
5
  metadata:
6
6
  version: '0.0.1'
@@ -20,6 +20,21 @@ AGENTS.md routes you here when you're working with `@sodax/wallet-sdk-react` v2
20
20
  For backend / non-React → use `sodax-wallet-sdk-core` instead.
21
21
  For React dapps with hooks wrapping the SDK → also load `sodax-dapp-kit`.
22
22
 
23
+ ## Prefer a granular skill if the concern is known
24
+
25
+ If the task is one wallet concern, load its granular skill instead of this broad one. Each links straight to its recipe, for both integration and migration.
26
+
27
+ | Concern | Granular skill | Trigger phrases |
28
+ |---|---|---|
29
+ | Connect / disconnect, account and connection state | [`./connect/SKILL.md`](./connect/SKILL.md) | "useXConnect", "useXAccount", "connect button" |
30
+ | Headless wallet modal and multi-chain UI | [`./wallet-modal/SKILL.md`](./wallet-modal/SKILL.md) | "useWalletModal", "wallet modal", "connect several chains" |
31
+ | Connected wallet → SDK signer | [`./bridge-to-sdk/SKILL.md`](./bridge-to-sdk/SKILL.md) | "useWalletProvider", "pass the wallet to @sodax/sdk" |
32
+ | EVM chain switching / wrong network | [`./switch-chain/SKILL.md`](./switch-chain/SKILL.md) | "useEvmSwitchChain", "wrong network banner" |
33
+ | Sign an arbitrary message | [`./sign-message/SKILL.md`](./sign-message/SKILL.md) | "useXSignMessage", "prove wallet ownership", "SIWE" |
34
+ | WalletConnect / enterprise custody | [`./walletconnect/SKILL.md`](./walletconnect/SKILL.md) | "WalletConnect", "Fireblocks", "Ledger", "mobile-only wallet" |
35
+
36
+ Load this broad skill (keep reading below) for a full wallet setup, several concerns at once, or a v1 port.
37
+
23
38
  ---
24
39
 
25
40
  ## Integration mode (writing new v2 code)