@sodax/skills 2.2.0 → 2.3.0-rc.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- 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 +4 -2
- 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 +2 -2
- 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 +24 -1
- package/skills/sodax-sdk/integration/knowledge/features/swap.md +68 -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 +2 -1
- 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
package/AGENTS.md
CHANGED
|
@@ -12,10 +12,10 @@ This package ships **mode-gated broad SDK skills** (`skills/<name>/SKILL.md`, on
|
|
|
12
12
|
|---|---|---|
|
|
13
13
|
| `@sodax/sdk` | `sodax-sdk` | `sodax-sdk/swap`, `sodax-sdk/money-market`, `sodax-sdk/bridge`, `sodax-sdk/staking`, `sodax-sdk/dex`, `sodax-sdk/leverage-yield`, `sodax-sdk/migration`, `sodax-sdk/partner`, `sodax-sdk/recovery`, `sodax-sdk/sponsoring`, `sodax-sdk/backend-api`, `sodax-sdk/swaps-api`, `sodax-sdk/leverage-yield-api` |
|
|
14
14
|
| `@sodax/wallet-sdk-core` | `sodax-wallet-sdk-core` | `sodax-wallet-sdk-core/evm`, `sodax-wallet-sdk-core/solana`, `sodax-wallet-sdk-core/sui`, `sodax-wallet-sdk-core/bitcoin`, `sodax-wallet-sdk-core/stellar`, `sodax-wallet-sdk-core/icon`, `sodax-wallet-sdk-core/injective`, `sodax-wallet-sdk-core/near`, `sodax-wallet-sdk-core/stacks` |
|
|
15
|
-
| `@sodax/wallet-sdk-react` | `sodax-wallet-sdk-react` | `sodax-wallet-sdk-react/connect`, `sodax-wallet-sdk-react/wallet-modal`, `sodax-wallet-sdk-react/bridge-to-sdk`, `sodax-wallet-sdk-react/switch-chain`, `sodax-wallet-sdk-react/sign-message`, `sodax-wallet-sdk-react/walletconnect` |
|
|
15
|
+
| `@sodax/wallet-sdk-react` | `sodax-wallet-sdk-react` | `sodax-wallet-sdk-react/connect`, `sodax-wallet-sdk-react/wallet-modal`, `sodax-wallet-sdk-react/bridge-to-sdk`, `sodax-wallet-sdk-react/switch-chain`, `sodax-wallet-sdk-react/sign-message`, `sodax-wallet-sdk-react/walletconnect`, `sodax-wallet-sdk-react/privy` |
|
|
16
16
|
| `@sodax/dapp-kit` | `sodax-dapp-kit` | `sodax-dapp-kit/swap`, `sodax-dapp-kit/money-market`, `sodax-dapp-kit/staking`, `sodax-dapp-kit/bridge`, `sodax-dapp-kit/dex`, `sodax-dapp-kit/leverage-yield`, `sodax-dapp-kit/migration`, `sodax-dapp-kit/bitcoin`, `sodax-dapp-kit/auxiliary-services` |
|
|
17
17
|
|
|
18
|
-
**When to prefer a granular skill:** if the consumer has already picked a sub-domain (e.g. *"swap with Sodax"*, *"supply on money market"*, *"useSwap hook"*, *"instantiate EvmWalletProvider"*, *"add a connect button"*), load the matching granular skill — it's ~3 KB vs the broad skill's ~13 KB and points at exactly the knowledge files needed. For a React dapp that has settled on one feature, load `sodax-dapp-kit/<feature>`; for raw SDK / backend work, load `sodax-sdk/<feature>`; for a known chain in a backend/Node wallet flow, load `sodax-wallet-sdk-core/<chain>`; for a known React wallet concern (connect, wallet-modal, bridge-to-sdk, switch-chain, sign-message, walletconnect), load `sodax-wallet-sdk-react/<concern>`. Load the broad skill when the sub-domain is undecided, the task spans several, or the consumer is porting a full v1 codebase.
|
|
18
|
+
**When to prefer a granular skill:** if the consumer has already picked a sub-domain (e.g. *"swap with Sodax"*, *"supply on money market"*, *"useSwap hook"*, *"instantiate EvmWalletProvider"*, *"add a connect button"*), load the matching granular skill — it's ~3 KB vs the broad skill's ~13 KB and points at exactly the knowledge files needed. For a React dapp that has settled on one feature, load `sodax-dapp-kit/<feature>`; for raw SDK / backend work, load `sodax-sdk/<feature>`; for a known chain in a backend/Node wallet flow, load `sodax-wallet-sdk-core/<chain>`; for a known React wallet concern (connect, wallet-modal, bridge-to-sdk, switch-chain, sign-message, walletconnect, privy), load `sodax-wallet-sdk-react/<concern>`. Load the broad skill when the sub-domain is undecided, the task spans several, or the consumer is porting a full v1 codebase.
|
|
19
19
|
|
|
20
20
|
> **What about `@sodax/types`?** No skill. The package has no consumer-facing surface — it's pure TypeScript types, re-exported through `@sodax/sdk`. Importing `@sodax/types` directly invites version skew. The SDK skills cover all `@sodax/types` symbols you need.
|
|
21
21
|
|
|
@@ -29,7 +29,7 @@ Pick the consumer's situation, load the listed skills in order. Each entry names
|
|
|
29
29
|
| **Scaffolding ONE specific Core SDK feature** (swap, money-market, bridge, staking, dex, leverage-yield, migration, partner, recovery, sponsoring, backend-api, swaps-api, leverage-yield-api) | `sodax-sdk/<feature>` (granular, covers both modes via internal links). Add `sodax-wallet-sdk-core` (integration) if it signs and lives outside React. Skip the broad `sodax-sdk` skill |
|
|
30
30
|
| **Scaffolding ONE specific dapp-kit feature in React** (swap, money-market, staking, bridge, dex, leverage-yield, migration, bitcoin, auxiliary-services) | `sodax-wallet-sdk-react` (integration) → `sodax-dapp-kit/<feature>` (granular, covers both modes via internal links). Skip the broad `sodax-dapp-kit` skill. If the wallet concern is also settled (just a connect button, modal, bridge, etc.), narrow to `sodax-wallet-sdk-react/<concern>` too |
|
|
31
31
|
| **Scaffolding ONE chain's wallet provider** (backend/Node/non-React: evm, solana, sui, bitcoin, stellar, icon, injective, near, stacks) | `sodax-wallet-sdk-core/<chain>` (granular, covers both modes) → `sodax-sdk/<feature>` for the operation it signs. Skip the broad `sodax-wallet-sdk-core` skill |
|
|
32
|
-
| **Scaffolding ONE React wallet concern** (connect, wallet-modal, bridge-to-sdk, switch-chain, sign-message, walletconnect) | `sodax-wallet-sdk-react/<concern>` (granular, covers both modes). Skip the broad `sodax-wallet-sdk-react` skill |
|
|
32
|
+
| **Scaffolding ONE React wallet concern** (connect, wallet-modal, bridge-to-sdk, switch-chain, sign-message, walletconnect, privy) | `sodax-wallet-sdk-react/<concern>` (granular, covers both modes). Skip the broad `sodax-wallet-sdk-react` skill |
|
|
33
33
|
| **Building a NEW React dapp** | `sodax-wallet-sdk-react` (integration) → `sodax-dapp-kit` (integration) → (`sodax-sdk` (integration) only if dropping below dapp-kit) |
|
|
34
34
|
| **Building a NEW React app, no dapp-kit** (calling the SDK directly) | `sodax-wallet-sdk-react` (integration) → `sodax-sdk` (integration) |
|
|
35
35
|
| **Building a NEW Node / backend service or script** | `sodax-sdk` (integration) → `sodax-wallet-sdk-core` (integration; only if it signs) |
|
|
@@ -71,7 +71,7 @@ packages/skills/
|
|
|
71
71
|
├── sodax-wallet-sdk-react/ {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/
|
|
72
72
|
│ (incl. .tsx example apps under integration/knowledge/examples/),
|
|
73
73
|
│ <concern>/SKILL.md children — connect, wallet-modal, bridge-to-sdk,
|
|
74
|
-
│ switch-chain, sign-message, walletconnect}
|
|
74
|
+
│ switch-chain, sign-message, walletconnect, privy}
|
|
75
75
|
└── sodax-dapp-kit/ {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/,
|
|
76
76
|
<feature>/SKILL.md children — swap, money-market, staking, bridge, dex,
|
|
77
77
|
leverage-yield, migration, bitcoin, auxiliary-services}
|
|
@@ -95,7 +95,7 @@ If the user is doing **DeFi work but explicitly NOT with SODAX** (e.g. "use Unis
|
|
|
95
95
|
|
|
96
96
|
## Feedback
|
|
97
97
|
|
|
98
|
-
If an agent generates wrong code despite following a skill, that's a doc bug — file an issue at https://github.com/
|
|
98
|
+
If an agent generates wrong code despite following a skill, that's a doc bug — file an issue at https://github.com/gosodax/sodax-sdks/issues with the prompt and the incorrect output. The package is structurally CI-guarded (frontmatter + link resolution); prose-level claims benefit from real-world feedback.
|
|
99
99
|
|
|
100
100
|
## Maintaining this package
|
|
101
101
|
|
|
@@ -182,11 +182,11 @@ Run individually for faster feedback: `pnpm run check:ai-imports`, `pnpm run che
|
|
|
182
182
|
|
|
183
183
|
Two paths:
|
|
184
184
|
|
|
185
|
-
1. **GitHub-based via the [`skills` CLI](https://github.com/vercel-labs/skills)** (primary): `npx skills@latest add
|
|
185
|
+
1. **GitHub-based via the [`skills` CLI](https://github.com/vercel-labs/skills)** (primary): `npx skills@latest add gosodax/sodax-sdks/packages/skills`. Drops skills into the consumer's repo through the CLI-supported agent targets.
|
|
186
186
|
2. **npm** (fallback for web chats / unsupported tools): `pnpm add -D @sodax/skills`. Consumers point their agent at `node_modules/@sodax/skills/AGENTS.md`.
|
|
187
187
|
|
|
188
188
|
The `files` field in `package.json` controls the npm-shipped surface (`.claude-plugin`, `skills`, `AGENTS.md`, `README.md`). Knowledge ships inside each skill, so it travels with `skills/`.
|
|
189
189
|
|
|
190
190
|
### Release
|
|
191
191
|
|
|
192
|
-
Published
|
|
192
|
+
Published by `.github/workflows/sdks-publish.yml`, with every other `@sodax/*` package on an `@sdks@x.y.z` tag, or alone on an `@sodax/skills@x.y.z` tag.
|
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
AI-agent skills and knowledge for building on the **SODAX** cross-chain DeFi platform. Drop this into your repo and your AI coding agent writes v2-correct `@sodax/*` SDK code on the first try.
|
|
4
4
|
|
|
5
|
-
**Full setup** (skills CLI, npm, monorepo/local install, wiring agents to `AGENTS.md`): [docs/ai-integration-guide.md](https://github.com/
|
|
5
|
+
**Full setup** (skills CLI, npm, monorepo/local install, wiring agents to `AGENTS.md`): [docs/ai-integration-guide.md](https://github.com/gosodax/sodax-sdks/blob/main/docs/ai-integration-guide.md).
|
|
6
6
|
|
|
7
7
|
## Install
|
|
8
8
|
|
|
@@ -10,12 +10,12 @@ Using the [`skills` CLI](https://github.com/vercel-labs/skills) from Vercel Labs
|
|
|
10
10
|
|
|
11
11
|
```bash
|
|
12
12
|
# From the root of your consumer repo
|
|
13
|
-
npx skills@latest add
|
|
13
|
+
npx skills@latest add gosodax/sodax-sdks/packages/skills
|
|
14
14
|
```
|
|
15
15
|
|
|
16
16
|
The five installable skills listed in `.claude-plugin/plugin.json` land in your repo — the `sodax-build` front-door / ideation skill plus the four mode-gated per-SDK-package skills (each with two knowledge subtrees: `integration/` for new v2 code, `migration-v1-to-v2/` for v1→v2 porting). The CLI does **not** copy the package-level `AGENTS.md`; agents auto-discover each skill from its `SKILL.md` frontmatter. Re-running the command picks up the latest content.
|
|
17
17
|
|
|
18
|
-
> **npm fallback** (web chats or when you prefer a devDependency): `pnpm add -D @sodax/skills`, then point your agent at `node_modules/@sodax/skills/AGENTS.md`. See the [integration guide](https://github.com/
|
|
18
|
+
> **npm fallback** (web chats or when you prefer a devDependency): `pnpm add -D @sodax/skills`, then point your agent at `node_modules/@sodax/skills/AGENTS.md`. See the [integration guide](https://github.com/gosodax/sodax-sdks/blob/main/docs/ai-integration-guide.md#wire-your-agent).
|
|
19
19
|
|
|
20
20
|
## What you get
|
|
21
21
|
|
|
@@ -23,7 +23,7 @@ The five installable skills listed in `.claude-plugin/plugin.json` land in your
|
|
|
23
23
|
|---|---|
|
|
24
24
|
| **Front-door skill** at `skills/sodax-build/SKILL.md` | A cross-cutting ideation skill for when you don't know what to build yet. It interviews you, turns the idea into a product brief, and hands off to the right developer skill(s). Writes no app code; flat `knowledge/` tree (no integration/migration split). |
|
|
25
25
|
| **Mode-gated per-SDK-package skills** under `skills/sodax-<pkg>/SKILL.md` | One skill per SODAX SDK package. `<pkg>` ∈ `sdk`, `wallet-sdk-core`, `wallet-sdk-react`, `dapp-kit`. Each SKILL.md gates by mode (integration vs migration) at the top of the body. |
|
|
26
|
-
| **Granular skills** bundled inside each broad skill at `skills/sodax-<pkg>/<sub-domain>/SKILL.md` | Every broad skill ships focused single-domain children: `sodax-sdk` / `sodax-dapp-kit` per feature (swap, money-market, bridge, staking, dex, …); `sodax-wallet-sdk-core` per chain (evm, solana, sui, bitcoin, stellar, icon, injective, near, stacks); `sodax-wallet-sdk-react` per connectivity concern (connect, wallet-modal, bridge-to-sdk, switch-chain, sign-message, walletconnect). They install **with** their parent broad skill (not as separate packages); once installed, load one when the task is already scoped to a single sub-domain — it points at exactly the knowledge files for it instead of the whole broad skill. |
|
|
26
|
+
| **Granular skills** bundled inside each broad skill at `skills/sodax-<pkg>/<sub-domain>/SKILL.md` | Every broad skill ships focused single-domain children: `sodax-sdk` / `sodax-dapp-kit` per feature (swap, money-market, bridge, staking, dex, …); `sodax-wallet-sdk-core` per chain (evm, solana, sui, bitcoin, stellar, icon, injective, near, stacks); `sodax-wallet-sdk-react` per connectivity concern (connect, wallet-modal, bridge-to-sdk, switch-chain, sign-message, walletconnect, privy). They install **with** their parent broad skill (not as separate packages); once installed, load one when the task is already scoped to a single sub-domain — it points at exactly the knowledge files for it instead of the whole broad skill. |
|
|
27
27
|
| **Knowledge** under `skills/sodax-<pkg>/{integration,migration-v1-to-v2}/knowledge/` | Long-form supporting docs — features, recipes, reference tables, breaking-change writeups, code examples. Each skill ships both mode subtrees so `npx skills add` copies the full reference together. |
|
|
28
28
|
| **`AGENTS.md`** at the package root | Tool-neutral router: maps the consumer's stated task to the right skill + mode. Ships on npm, so it is the entry point for the `pnpm add -D @sodax/skills` and `file:` installs — the skills CLI does not copy it. |
|
|
29
29
|
|
|
@@ -49,4 +49,4 @@ LLM training data drifts: snippets from chat often use stale method names, resha
|
|
|
49
49
|
|
|
50
50
|
## Feedback
|
|
51
51
|
|
|
52
|
-
If your agent generates wrong code despite reading the docs, that's a doc bug — please open an issue on the [SODAX SDKs repo](https://github.com/
|
|
52
|
+
If your agent generates wrong code despite reading the docs, that's a doc bug — please open an issue on the [SODAX SDKs repo](https://github.com/gosodax/sodax-sdks/issues) with the prompt and the incorrect output. The per-skill `knowledge/` subtrees are structurally CI-guarded (frontmatter, link resolution); prose claims benefit from real-world feedback.
|
package/package.json
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
"publishConfig": {
|
|
5
5
|
"access": "public"
|
|
6
6
|
},
|
|
7
|
-
"version": "2.
|
|
7
|
+
"version": "2.3.0-rc.1",
|
|
8
8
|
"license": "MIT",
|
|
9
9
|
"description": "AI-agent skills and knowledge for consumers of @sodax/* SDKs (Claude Code, Codex, Cursor, …)",
|
|
10
10
|
"keywords": [
|
|
@@ -14,13 +14,13 @@
|
|
|
14
14
|
"claude-code",
|
|
15
15
|
"agents"
|
|
16
16
|
],
|
|
17
|
-
"homepage": "https://github.com/
|
|
17
|
+
"homepage": "https://github.com/gosodax/sodax-sdks/tree/main/packages/skills",
|
|
18
18
|
"bugs": {
|
|
19
|
-
"url": "https://github.com/
|
|
19
|
+
"url": "https://github.com/gosodax/sodax-sdks/issues"
|
|
20
20
|
},
|
|
21
21
|
"repository": {
|
|
22
22
|
"type": "git",
|
|
23
|
-
"url": "https://github.com/
|
|
23
|
+
"url": "https://github.com/gosodax/sodax-sdks"
|
|
24
24
|
},
|
|
25
25
|
"type": "module",
|
|
26
26
|
"engines": {
|
|
@@ -24,7 +24,7 @@ SODAX is **cross-chain DeFi** on a hub-and-spoke model (Sonic is the hub). **Its
|
|
|
24
24
|
| `useSwap`, `useXxx` hook, `@sodax/dapp-kit`, "React dapp + dapp-kit" | `sodax-dapp-kit` (+ `sodax-wallet-sdk-react`) |
|
|
25
25
|
| `Sodax`, `ChainKeys`, `Result<T>`, `SodaxError`, "backend / bot / script with @sodax/sdk" | `sodax-sdk` |
|
|
26
26
|
| `walletProvider`, `IEvmWalletProvider`, "sign on <chain>", a specific chain provider | `sodax-wallet-sdk-core` |
|
|
27
|
-
| "connect button", "wallet modal", "switch chain", WalletConnect | `sodax-wallet-sdk-react` |
|
|
27
|
+
| "connect button", "wallet modal", "switch chain", WalletConnect, "email login", Privy | `sodax-wallet-sdk-react` |
|
|
28
28
|
| A named feature already chosen (swap / money market / staking / bridge / dex / leverage yield / migration / partner / recovery) **with** an SDK in mind | the matching dev skill above |
|
|
29
29
|
|
|
30
30
|
When in doubt about whether the *what* is decided, ask **one** question: *"Do you already know which SODAX feature you want, or are we still figuring that out?"* — decided → route; not decided → interview.
|
|
@@ -26,7 +26,7 @@ This skill is **self-contained** — it needs no network to run the interview. B
|
|
|
26
26
|
- Chains, tokens, and config → the **`@sodax/types`** package source.
|
|
27
27
|
- Fees, and which feature services exist → the **`@sodax/sdk`** package source.
|
|
28
28
|
|
|
29
|
-
Repo: `https://github.com/
|
|
29
|
+
Repo: `https://github.com/gosodax/sodax-sdks` (the `@sodax/*` packages live under `packages/`). Other files here point back to this policy rather than repeating paths.
|
|
30
30
|
|
|
31
31
|
## Honesty rules
|
|
32
32
|
|
|
@@ -46,6 +46,10 @@ If assets end up stranded in a user's hub wallet, recovery withdraws them back t
|
|
|
46
46
|
|
|
47
47
|
Leveraged-yield vaults on the hub that loop supply → borrow → swap to build a leveraged position. **Advanced and risk-heavy** — only surface it when a semi-technical+ user explicitly wants leverage, and keep risk framing separate from product design. Net yield can be negative. Never present it to a Tier A user as "savings".
|
|
48
48
|
|
|
49
|
+
## Email login — users without a crypto wallet
|
|
50
|
+
|
|
51
|
+
Not a DeFi feature but an onboarding choice: an opt-in "log in with email" entry next to the usual wallets. The user types an email, enters a one-time code, and gets a wallet created for them (a Privy embedded wallet) that signs like MetaMask. EVM chains only, React apps only. Use it when the audience has no wallet yet ("my users are not crypto people"). Be honest about the trade-offs in the brief: Privy holds access, so nobody can sign while Privy is down; the builder needs their own Privy account and pays per signature; a user who loses their email loses that wallet.
|
|
52
|
+
|
|
49
53
|
---
|
|
50
54
|
|
|
51
55
|
**Mapping back to the interview:** the goal → feature table lives in [`interview-guide.md`](./interview-guide.md); worked product combinations are in [`use-case-gallery.md`](./use-case-gallery.md).
|
|
@@ -23,6 +23,7 @@ For glossing terms during the interview. Apply **by tier** (see [`interview-guid
|
|
|
23
23
|
| **Liquidity / LP** | "Put two coins into a shared pool so others can trade, and earn fees." | Concentrated-liquidity DEX. |
|
|
24
24
|
| **Allowance / approval** | "A one-time permission so the app can move a specific token for you." | ERC-20 approve step. |
|
|
25
25
|
| **Wallet** | "The app that holds your coins and signs actions (e.g. MetaMask)." | Per-chain provider in the SDK. |
|
|
26
|
+
| **Embedded wallet / email login** | "A wallet created for you when you log in with your email — no app to install." | Privy-held; EVM only. See [`feature-catalog.md`](./feature-catalog.md#email-login--users-without-a-crypto-wallet). |
|
|
26
27
|
| **Partner fee** | "The cut the app you built takes on each transaction." | See [`monetization.md`](./monetization.md). |
|
|
27
28
|
| **Gas** | "The small network fee paid to process a transaction." | Paid in the chain's native coin; not a SODAX fee. |
|
|
28
29
|
| **Token migration** | "Move an older ICON-era coin (ICX/BALN/bnUSD) into the new system." | Specific tokens only. |
|
|
@@ -19,6 +19,8 @@ The last step. Map the brief's build shape to the exact developer skill(s) the u
|
|
|
19
19
|
|
|
20
20
|
**Non-EVM chains:** if the product touches **any non-EVM chain**, add the matching chain in `sodax-wallet-sdk-core` to the handoff — each non-EVM chain needs its own wallet provider.
|
|
21
21
|
|
|
22
|
+
**Email login:** if the brief chose it, name the privy concern of `sodax-wallet-sdk-react` in the handoff (EVM only, React only). The builder must create a Privy app before the dev skill can finish.
|
|
23
|
+
|
|
22
24
|
## How to choose mode
|
|
23
25
|
|
|
24
26
|
- **Integration** (write new v2 code) — the default for a brand-new product.
|
|
@@ -53,6 +55,7 @@ handoff:
|
|
|
53
55
|
mode: integration # or "migration" (port v1 first), then integration
|
|
54
56
|
partner_fee: true # if true, also load the sodax-sdk partner feature (+ sodax-dapp-kit in React)
|
|
55
57
|
non_evm_chains: [] # each entry adds a sodax-wallet-sdk-core/<chain> provider
|
|
58
|
+
email_login: false # if true, also load sodax-wallet-sdk-react/privy (EVM, React only)
|
|
56
59
|
starter_app: apps/demo
|
|
57
60
|
phase1_goal: "one working cross-chain transfer in the safest supported environment"
|
|
58
61
|
```
|
|
@@ -52,6 +52,7 @@ See [`feature-catalog.md`](./feature-catalog.md) for the plain-English descripti
|
|
|
52
52
|
|
|
53
53
|
- **Who uses it** and **on which chains**. Tier A gets a recommended default to confirm (e.g. "start with a small number of EVM chains — one major chain plus one lower-fee chain"). Confirm against [`chains-and-assets.md`](./chains-and-assets.md).
|
|
54
54
|
- **Honesty-gate** any unsupported chain.
|
|
55
|
+
- **Do the users already have a crypto wallet?** If not (Tier A audiences often do not), offer email login as the onboarding default — EVM only, with the trade-offs in [`feature-catalog.md`](./feature-catalog.md#email-login--users-without-a-crypto-wallet). It changes the handoff.
|
|
55
56
|
- **Flag non-EVM assets**: if the product touches **any non-EVM chain**, note that it pulls in a chain-specific wallet provider — this changes the handoff (a matching chain skill in `sodax-wallet-sdk-core`). Confirm which chains are non-EVM against live source if it matters.
|
|
56
57
|
|
|
57
58
|
## Stage 4 — Monetization detail (only if not "free")
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: sodax-dapp-kit-auxiliary-services
|
|
3
|
-
description: 'Granular skill for the @sodax/dapp-kit v2 auxiliary surfaces — partner fee claiming (useFeeClaimSwap, useApproveToken, useSetSwapPreference, useGetAutoSwapPreferences, useIsTokenApproved), recovery (useHubAssetBalances, useWithdrawHubAsset), read-only backend queries (useBackendIntentByTxHash, useBackendUserIntents, useBackendOrderbook, useBackendMoneyMarketPosition), the backend API client hooks (Swaps: useSwapsApiQuote, useSwapsApiSubmitTx, useSwapsApiStatus; Bridge: useBridgeApi*; Leverage Yield: useLeverageYieldApi*, e.g. useLeverageYieldApiVaults, useLeverageYieldApiSubmitTxStatus), sponsored Stellar account activation (useStellarGate, useStellarAccountActive, useStellarAccountStatus, useSponsorConfig, useActivateStellarAccount), and shared utilities (useSodaxContext, useHubProvider, useBalances, useXBalances, useDeriveUserWalletAddress, useEstimateGas, useStellarTrustlineCheck, useEstablishTrustline). Use when a React dapp task is partner fees, recovering stuck hub assets, backend data reads (intent tracking / orderbook / MM data, no wallet), activating a Stellar account for a user who holds no XLM, or cross-cutting utilities (token balances, gas estimation, Stellar trustlines). Covers BOTH integration and migration. Links into the parent sodax-dapp-kit knowledge tree.'
|
|
3
|
+
description: 'Granular skill for the @sodax/dapp-kit v2 auxiliary surfaces — partner fee claiming (useFeeClaimSwap, useApproveToken, useSetSwapPreference, useGetAutoSwapPreferences, useIsTokenApproved), recovery (useHubAssetBalances, useWithdrawHubAsset), read-only backend queries (useBackendIntentByTxHash, useBackendUserIntents, useBackendOrderbook, useBackendMoneyMarketPosition), the backend API client hooks (Swaps: useSwapsApiQuote, useSwapsApiSubmitTx, useSwapsApiStatus, useSwapsApiApproveAndBroadcast, useSwapsApiBroadcastWithApproval; Bridge: useBridgeApi*; Leverage Yield: useLeverageYieldApi*, e.g. useLeverageYieldApiVaults, useLeverageYieldApiSubmitTxStatus), sponsored Stellar account activation (useStellarGate, useStellarAccountActive, useStellarAccountStatus, useSponsorConfig, useActivateStellarAccount), and shared utilities (useSodaxContext, useHubProvider, useBalances, useXBalances, useDeriveUserWalletAddress, useEstimateGas, useStellarTrustlineCheck, useEstablishTrustline). Use when a React dapp task is partner fees, recovering stuck hub assets, backend data reads (intent tracking / orderbook / MM data, no wallet), swapping through the backend Swaps API (approve, sign, submit-tx; one EIP-5792 signature where the wallet can batch), activating a Stellar account for a user who holds no XLM, or cross-cutting utilities (token balances, gas estimation, Stellar trustlines). Covers BOTH integration and migration. Links into the parent sodax-dapp-kit knowledge tree.'
|
|
4
4
|
license: MIT
|
|
5
5
|
metadata:
|
|
6
6
|
version: '0.0.1'
|
|
@@ -18,6 +18,7 @@ Granular skill for the smaller `@sodax/dapp-kit` v2 surfaces grouped together: *
|
|
|
18
18
|
- **Partner fees:** `useIsTokenApproved` → `useApproveToken` → `useSetSwapPreference` → `useFeeClaimSwap` (returns `IntentAutoSwapResult`, NOT `SwapResponse`); `useGetAutoSwapPreferences`, `useFetchAssetsBalances` for reads.
|
|
19
19
|
- **Recovery:** `useHubAssetBalances` (list stuck hub assets) → `useWithdrawHubAsset` (withdraw one back to a spoke). Follows a *known* failed cross-chain op — investigate the failure first.
|
|
20
20
|
- **Backend reads (no wallet):** intent tracking (`useBackendIntentByTxHash` polls 1s, `useBackendIntentByHash`, `useBackendUserIntents`), orderbook (`useBackendOrderbook` — `pagination` nests under `params`), MM data (`useBackendMoneyMarketPosition` etc.), and the Swaps API client (`useSwapsApi*` — e.g. `useSwapsApiSubmitTx`, `useSwapsApiSubmitTxStatus`, `useSwapsApiQuote`).
|
|
21
|
+
- **Swaps API swap with a wallet:** `useSwapsApiAllowance` first. Short allowance on an EVM source → `useSwapsApiBroadcastWithApproval` (the approval and the `/swaps/intents` tx in one EIP-5792 signature where the wallet can batch; a refusal means approve with `useSwapsApiApproveAndBroadcast`, create the intent again, sign it); otherwise sign the intent tx yourself. Then `useSwapsApiSubmitTx` with the `txHash`. Persist the batch id `onBatchSent` reports: a batch that comes back `ATOMIC_BATCH_UNCONFIRMED` may still land.
|
|
21
22
|
- **Stellar prerequisites:** `useStellarGate` sequences the ordered prerequisites — the account must EXIST (sponsored activation, free to the user), must TRUST the token, and only then must be able to PAY for the trustline it needs. A freshly activated account holds zero XLM. An account that already holds the trustline needs no XLM at all, which is why affordability is checked last. A failed check sets `checkFailed` with `error`/`retry` — render it, or the fail-closed gate becomes an unexplained dead button. Lower-level: `useStellarAccountStatus`, `useStellarAccountActive`, `useSponsorConfig`, `useActivateStellarAccount`.
|
|
22
23
|
- **Shared utilities:** `useSodaxContext`, `useHubProvider`, `useBalances` (SDK-backed — no `xService`, reads via `SodaxProvider`) / `useXBalances` (needs `xService` from wallet-sdk-react), `useDeriveUserWalletAddress` / `useGetUserHubWalletAddress`, `useEstimateGas`, `useStellarTrustlineCheck` / `useEstablishTrustline`.
|
|
23
24
|
|
|
@@ -37,6 +38,8 @@ Granular skill for the smaller `@sodax/dapp-kit` v2 surfaces grouped together: *
|
|
|
37
38
|
- **Passing top-level `pagination` to `useBackendOrderbook` / `useBackendAllMoneyMarketBorrowers`.** It nests under `params`; without it those queries are disabled.
|
|
38
39
|
- **Calling `useXBalances` without `xService`.** Supply `xService` from `@sodax/wallet-sdk-react`'s `useXService`; the request-side key is `xChainId` (the cross-chain abstraction), distinct from the token-side `chainKey`.
|
|
39
40
|
- **Pairing `useStellarTrustlineCheck` with `useEstablishTrustline` by hand.** Use `useStellarGate`: `hasSufficientTrustline` THROWS for an account that does not exist, so a `!data` test offers a trustline button on a missing account. `useEstablishTrustline` is a canonical mutation hook — vars are `{ token, amount, srcChainKey, walletProvider }` (NOT `account`/`asset`). `useRequestTrustline` is its deprecated 2.0.0-shape wrapper; don't write new code against it.
|
|
41
|
+
- **`useSwapsApiApproveAndBroadcast`, then signing the intent tx, on an EVM source.** Two prompts where `useSwapsApiBroadcastWithApproval` needs one when the wallet can batch; keep that path for its refusal.
|
|
42
|
+
- **Re-sending a swap whose batch came back `ATOMIC_BATCH_UNCONFIRMED`.** It may still land. Resume it with `confirmApprovalBatch` and the persisted batch id; never sign it again.
|
|
40
43
|
- **Running recovery on successful flows.** Recovery is a workaround for *failed* ops — `useHubAssetBalances` first, then withdraw the specific entry; investigate the original failure.
|
|
41
44
|
- **Leaving `useBackendIntentByTxHash` polling (1s) running after the intent resolves.**
|
|
42
45
|
|
|
@@ -15,7 +15,7 @@ Granular skill for the bridge hooks of `@sodax/dapp-kit` v2. queryKey/mutationKe
|
|
|
15
15
|
|
|
16
16
|
1. **New code or v1 → v2 port?**
|
|
17
17
|
2. **Need a bridgeable precheck?** `useGetBridgeableAmount` (vault deposit/withdrawal cap, returns a `BridgeLimit`) and `useGetBridgeableTokens` (enumerate compatible destinations).
|
|
18
|
-
3. **Allowance gating?** `useBridgeAllowance` + `useBridgeApprove` before `useBridge`.
|
|
18
|
+
3. **Allowance gating?** `useBridgeWithApproval` folds the approval in (one EIP-5792 batch when the wallet can), labelled with `useBridgeApprovalStrategy`. The two-step alternative is `useBridgeAllowance` + `useBridgeApprove` before `useBridge`.
|
|
19
19
|
4. **Source/destination chains + recipient format** — confirm both are supported spokes and the `recipient` matches the destination chain encoding.
|
|
20
20
|
|
|
21
21
|
## Integration workflow (new v2 code)
|
|
@@ -230,7 +230,20 @@ take — each API builds its approval for its own hub spender, so an approval bu
|
|
|
230
230
|
satisfy the other. Only a leverage-yield **deposit** needs one; a withdraw spends `lsoda*` from the
|
|
231
231
|
hub wallet and never approves.
|
|
232
232
|
|
|
233
|
-
|
|
233
|
+
For a swap from an EVM source whose allowance is short (`/swaps/allowance/check` says so — the hook
|
|
234
|
+
always approves), **`useSwapsApiBroadcastWithApproval`** goes one step further: given the
|
|
235
|
+
create-intent `body` and the unsigned `intentTx`, it sends the approval and `intentTx` as one EIP-5792
|
|
236
|
+
atomic batch — one signature — when the wallet supports it. It resolves with `{ txHash, approvalStrategy,
|
|
237
|
+
approval? }` and stops there: persist `txHash`, then call `useSwapsApiSubmitTx`. Persist the `batchId` its
|
|
238
|
+
`onBatchSent` reports too: a `TX_VERIFICATION_FAILED` with `context.reason === ATOMIC_BATCH_UNCONFIRMED`
|
|
239
|
+
means the batch may still land, so never let the user sign that swap again — resume it with
|
|
240
|
+
`confirmApprovalBatch` instead. A wallet that cannot batch (the Sonic hub never does), or refuses the batch
|
|
241
|
+
before signing, rejects with an `isAtomicBatchRefusal` error and nothing sent: approve with
|
|
242
|
+
`useSwapsApiApproveAndBroadcast`, create the intent again — a fresh deadline — and sign that. Pass
|
|
243
|
+
`fallbackOnRefusal: true` to have the hook approve and then send the `intentTx` it was given; that intent was
|
|
244
|
+
built before the approval, so its deadline has to outlast the approval's wait.
|
|
245
|
+
|
|
246
|
+
All three, and `useSwapsApiBroadcastWithApproval` for its separate approval, accept an optional **`onProgress`** in their mutation vars. It reports each transaction as
|
|
234
247
|
`{ step, phase, index, total, hash?, error? }` — `step` is `'allowance-reset'` or `'approve'`, `phase`
|
|
235
248
|
walks `signing → broadcast → confirmed` (or `failed`), and `index`/`total` give "1 of 2" without the
|
|
236
249
|
caller tracking anything. Advisory: the listener is never awaited, one that throws is ignored rather
|
|
@@ -240,8 +253,8 @@ vars rather than the hook options so it is never a stale closure.
|
|
|
240
253
|
`useSwapsApiApprove` / `useBridgeApiApprove` / `useLeverageYieldApiApprove` still exist and return
|
|
241
254
|
the API's `{ tx, resetTx? }` verbatim — use them only when you need to own signing. If you do,
|
|
242
255
|
broadcast `resetTx` **first and wait for it to succeed**; the approve is not a valid state
|
|
243
|
-
transition until the reset has landed, so sending both
|
|
244
|
-
revert. Waiting is not enough on its own —
|
|
256
|
+
transition until the reset has landed, so sending both as separate transactions at once spends the
|
|
257
|
+
user's gas on a certain revert (an EIP-5792 atomic batch runs them in order, so it can carry both). Waiting is not enough on its own —
|
|
245
258
|
check the receipt's status, because a mined-and-reverted reset leaves the allowance exactly where it
|
|
246
259
|
was.
|
|
247
260
|
|
|
@@ -296,7 +309,8 @@ hooks/
|
|
|
296
309
|
│ # useBalances, useXBalances, invalidateBalances,
|
|
297
310
|
│ # useStellarTrustlineCheck, useEstablishTrustline (+ deprecated useRequestTrustline)
|
|
298
311
|
├── provider/ # useHubProvider
|
|
299
|
-
├── swap/ #
|
|
312
|
+
├── swap/ # useSwapLifecycle, useSwapWithApproval, useSwapApprovalStrategy,
|
|
313
|
+
│ # useQuote, useSwap, useDetailedStatus, useStatus, useSwapAllowance, useSwapApprove,
|
|
300
314
|
│ # useCancelSwap, useCreateLimitOrder, useCancelLimitOrder
|
|
301
315
|
├── mm/ # useSupply, useWithdraw, useBorrow, useRepay, useMMAllowance, useMMApprove,
|
|
302
316
|
│ # reserves data hooks
|
|
@@ -84,6 +84,27 @@ useSwapsApiSubmitTx({ mutationOptions }); // mutation → sodax.ap
|
|
|
84
84
|
useSwapsApiSubmitTxStatus({ params, queryOptions }); // query → sodax.api.swaps.getSubmitTxStatus
|
|
85
85
|
```
|
|
86
86
|
|
|
87
|
+
**Approving and sending with a wallet.** `useSwapsApiApproveAndBroadcast` builds, signs and confirms the
|
|
88
|
+
`/swaps/approve` plan, reset first when there is one. For an EVM source whose allowance is short,
|
|
89
|
+
`useSwapsApiBroadcastWithApproval` sends the approval and the `/swaps/intents` tx as one EIP-5792 batch
|
|
90
|
+
(one signature) when the wallet can. When it cannot, the hook rejects with an `isAtomicBatchRefusal` error
|
|
91
|
+
and sends nothing: approve with `useSwapsApiApproveAndBroadcast`, create the intent again and sign that. It
|
|
92
|
+
always approves, so check `useSwapsApiAllowance` first, and it stops at the broadcast: persist `txHash`,
|
|
93
|
+
then submit it. Its errors, the unconfirmed-batch rule and `fallbackOnRefusal` are in
|
|
94
|
+
[architecture.md](../architecture.md#approve-hooks-can-prompt-the-wallet-twice).
|
|
95
|
+
|
|
96
|
+
```ts
|
|
97
|
+
// @ai-snippets-skip
|
|
98
|
+
const { mutateAsync: broadcastWithApproval } = useSwapsApiBroadcastWithApproval();
|
|
99
|
+
const { txHash } = await broadcastWithApproval({
|
|
100
|
+
body, // the create-intent body
|
|
101
|
+
intentTx: created.tx, // the unsigned tx /swaps/intents returned for it
|
|
102
|
+
walletProvider, // the source chain's IEvmWalletProvider
|
|
103
|
+
onBatchSent: (batchId, callCount) => saveBatch(batchId, callCount), // persist before the wait
|
|
104
|
+
});
|
|
105
|
+
await submitSwapTx({ request: { txHash, ...submission } });
|
|
106
|
+
```
|
|
107
|
+
|
|
87
108
|
These hooks forward the body verbatim, so `partnerFee` has no default (SDK fee config does not
|
|
88
109
|
apply). Put the same value on quote and create-intent:
|
|
89
110
|
|
|
@@ -357,7 +378,7 @@ if (isRegistered === false) {
|
|
|
357
378
|
}
|
|
358
379
|
```
|
|
359
380
|
|
|
360
|
-
For the common UI path, `useNearStorageGate` returns `{ isNear, needsRegistration, blocksAction, isChecking, isRegistering, registerStorage }`.
|
|
381
|
+
For the common UI path, `useNearStorageGate` returns `{ isNear, needsRegistration, blocksAction, isChecking, checkFailed, retry, isRegistering, registerStorage }`. `blocksAction` stays `false` when the check errors, so read `checkFailed` too and offer `retry` rather than letting the action through: whether the recipient can receive is unknown until the check succeeds. `useSwapLifecycle` does this as the `nearStorageCheckFailed` setup reason.
|
|
361
382
|
|
|
362
383
|
Derive UI gate flags with the unwrapped `resolveNearStorageGate` util (no hook) when you need custom check/register composition:
|
|
363
384
|
|
|
@@ -450,6 +471,7 @@ and origin gating are the real controls. Proxy through your own backend if that
|
|
|
450
471
|
| `useBackendOracleCandles` | none | `staleTime: 10s` — matches the ~10s server-side cache |
|
|
451
472
|
| `useExpiredUtxos` (bitcoin) | 60s | refetchInterval |
|
|
452
473
|
| `useQuote` (swap) | 3s | refetchInterval |
|
|
474
|
+
| `useDetailedStatus` (swap) | 3s | stops on the answering source's terminal state, on a rejected API key, and after 40 consecutive ambiguous reads |
|
|
453
475
|
| `useStatus` (swap) | 3s | stops on status `3`/`4`, and after 40 consecutive NOT_FOUND fetches |
|
|
454
476
|
| `useSwapAllowance` (swap) | 2s | refetchInterval |
|
|
455
477
|
| `useMMAllowance` (mm) | 5s | refetchInterval; `enabled: false` for borrow/withdraw actions |
|
|
@@ -11,12 +11,18 @@ Pair: [`features/bridge.md`](../../../migration-v1-to-v2/knowledge/features/brid
|
|
|
11
11
|
// Mutation
|
|
12
12
|
useBridge({ mutationOptions });
|
|
13
13
|
useBridgeApprove({ mutationOptions });
|
|
14
|
+
// bridge with the approval folded in: one EIP-5792 batch (one signature) when the wallet can
|
|
15
|
+
useBridgeWithApproval({ mutationOptions });
|
|
14
16
|
|
|
15
17
|
// Queries
|
|
16
18
|
// useBridgeAllowance nests payload + walletProvider under params (NOT at top level)
|
|
17
19
|
useBridgeAllowance({ params: { payload: CreateBridgeIntentParams<K>, walletProvider }, queryOptions });
|
|
20
|
+
// 'not-required' | 'atomic-batch' | 'sequential' — the path useBridgeWithApproval would take; not polled
|
|
21
|
+
useBridgeApprovalStrategy({ params: { payload, walletProvider, allowAccountUpgrade? }, queryOptions });
|
|
18
22
|
// Polls 3s from the source tx; stops on a terminal source, a rejected API key, or 40 consecutive
|
|
19
23
|
// ambiguous reads. Result-wrapped — narrow `data.value.source` ('backend' | 'relay').
|
|
24
|
+
// Feed it `srcChainTxHash` on success, or `error.context.srcTxHash` / `srcChainKey` when the bridge
|
|
25
|
+
// failed after broadcast (verify / relay codes) — the deposit may still deliver.
|
|
20
26
|
useBridgeDetailedStatus({ params: { srcChainKey, srcTxHash, apiConfig? }, queryOptions });
|
|
21
27
|
useGetBridgeableAmount({ params: { from: XToken, to: XToken }, queryOptions });
|
|
22
28
|
useGetBridgeableTokens({ params: { from: SpokeChainKey, to: SpokeChainKey, token: string }, queryOptions });
|
|
@@ -81,6 +87,8 @@ type UseGetBridgeableTokensParams = ReadHookParams<XToken[], {
|
|
|
81
87
|
|---|---|
|
|
82
88
|
| `useBridge` | `SafeUseMutationResult<TxHashPair, Error, ...>` (`{ srcChainTxHash, dstChainTxHash }`) |
|
|
83
89
|
| `useBridgeApprove` | `SafeUseMutationResult<TxReturnType<K, false>, Error, UseBridgeApproveVars<K>>` — chain-keyed receipt union (EVM/Stellar/Sui differ) |
|
|
90
|
+
| `useBridgeWithApproval` | `SafeUseMutationResult<BridgeWithApprovalResponse, Error, ...>` — `TxHashPair` plus `approvalStrategy`. A `TX_VERIFICATION_FAILED` with `context.reason === ATOMIC_BATCH_UNCONFIRMED` may still land: never bridge it again — mutate again with `resumeBatchId` / `resumeBatchCallCount` from its `context`, which sends nothing |
|
|
91
|
+
| `useBridgeApprovalStrategy` | `UseQueryResult<ApprovalStrategy, Error>` |
|
|
84
92
|
| `useBridgeAllowance` | `UseQueryResult<boolean, Error>` — already unwrapped; on SDK `!ok` the queryFn returns `false` (does NOT throw), so `isError` stays clean |
|
|
85
93
|
| `useGetBridgeableAmount` | `UseQueryResult<BridgeLimit, Error>` (richer than v1's bare `bigint`) |
|
|
86
94
|
| `useGetBridgeableTokens` | `UseQueryResult<XToken[], Error>` |
|
|
@@ -14,10 +14,12 @@ Leveraged-yield ERC-4626 vaults on the Sonic hub. Deposit any token → `lsoda*`
|
|
|
14
14
|
useLeverageYieldDeposit({ mutationOptions }); // build a deposit payload (any token → lsoda*)
|
|
15
15
|
useLeverageYieldWithdraw({ mutationOptions }); // build a withdraw payload (lsoda* → any token; hubWalletSwap)
|
|
16
16
|
useLeverageYieldVaultSwap({ mutationOptions }); // EXECUTE the built payload end-to-end
|
|
17
|
+
useLeverageYieldVaultSwapWithApproval({ mutationOptions }); // same, with a deposit's approval folded in (one EIP-5792 signature)
|
|
17
18
|
useLeverageYieldNotifySolver({ mutationOptions }); // manual-flow: notify the solver after a self-driven relay
|
|
18
19
|
|
|
19
20
|
// Reads
|
|
20
21
|
useLeverageYieldDetailedStatus({ params, queryOptions }); // track a vault swap from its SOURCE tx (3s)
|
|
22
|
+
useLeverageYieldApprovalStrategy({ params: { payload, walletProvider, allowAccountUpgrade? }, queryOptions }); // label the deposit button
|
|
21
23
|
useLeverageYieldQuote({ params, queryOptions }); // vault deposit/withdraw quote (3s) — NOT useQuote
|
|
22
24
|
useLeverageYieldEffectiveApr({ params, queryOptions }); // AAVE + LSD effective net APR (60s)
|
|
23
25
|
useLeverageYieldPosition({ params, queryOptions }); // collateral/debt/ltv/healthFactor/idle (30s)
|
|
@@ -32,7 +34,7 @@ const vaults = useMemo(() => sodax.leverageYield.listVaults(), [sodax]); // { na
|
|
|
32
34
|
|
|
33
35
|
Every read and builder takes the vault's `vault` field (the `lsoda*` proxy address). `useLeverageYieldApiVaults` is the backend REST equivalent of `listVaults()`. For symbols, logos, USD prices and a single units table, see [`../recipes/leverage-yield-product-anatomy.md`](../recipes/leverage-yield-product-anatomy.md).
|
|
34
36
|
|
|
35
|
-
`deposit` / `withdraw` are **builders** — they assemble a `LeverageYieldSwapPayload`, they do NOT broadcast. Spread the built payload into `useLeverageYieldVaultSwap`'s `mutate`, adding the `walletProvider`. `vaultSwap` takes the **backend submit-tx** path by default and falls back to the client-side relay on any non-success, so track the result with `useLeverageYieldDetailedStatus` — it keys on the source tx and answers for whichever path completed. Pass `extras.apiKey` in `mutate` to key the backend leg per action. There is no dedicated leverage-yield approve hook: the swap-style deposit approves the spoke-side asset manager, so reuse `useSwapApprove` / `useSwapAllowance` (see Approval pattern).
|
|
37
|
+
`deposit` / `withdraw` are **builders** — they assemble a `LeverageYieldSwapPayload`, they do NOT broadcast. Spread the built payload into `useLeverageYieldVaultSwap`'s `mutate`, adding the `walletProvider`. `vaultSwap` takes the **backend submit-tx** path by default and falls back to the client-side relay on any non-success, so track the result with `useLeverageYieldDetailedStatus` — it keys on the source tx and answers for whichever path completed. A post-broadcast failure (verify, relay or post-execution codes) still hands you that tx as `error.context.srcTxHash` / `srcChainKey`, so keep tracking it rather than reporting the vault swap as lost. Pass `extras.apiKey` in `mutate` to key the backend leg per action. There is no dedicated leverage-yield approve hook: the swap-style deposit approves the spoke-side asset manager, so reuse `useSwapApprove` / `useSwapAllowance` (see Approval pattern).
|
|
36
38
|
|
|
37
39
|
`use*Approve` is unchanged and still resolves to one transaction hash, but the SDK may send **two**
|
|
38
40
|
transactions on a token that rejects a non-zero to non-zero allowance change (Ethereum USDT today) —
|
|
@@ -94,7 +96,7 @@ useLeverageYieldShareBalances({ params: { vault, holders } })
|
|
|
94
96
|
|
|
95
97
|
## Approval pattern
|
|
96
98
|
|
|
97
|
-
|
|
99
|
+
`useLeverageYieldVaultSwapWithApproval` approves and deposits in one call — one signature on an EIP-5792 wallet — and needs none of the hooks below. A `TX_VERIFICATION_FAILED` with `context.reason === ATOMIC_BATCH_UNCONFIRMED` may still land: never deposit it again — mutate again with `resumeBatchId` / `resumeBatchCallCount` from its `context`, which sends nothing. For the two-step flow, leverage-yield has **no dedicated approve hook**. A deposit is a swap-style intent that bridges `inputToken` from the spoke chain, so it approves the spoke-side asset manager exactly like a swap — reuse the swap hooks. A withdraw needs no spoke-side approval: the payload carries `hubWalletSwap: true` and `vaultSwap` authorises the hub wallet to spend the `lsoda*` shares via a `Connection.sendMessage` the user signs on `srcChainKey`.
|
|
98
100
|
|
|
99
101
|
| Flow | Token approved | Hook |
|
|
100
102
|
|---|---|---|
|
|
@@ -15,10 +15,19 @@ useSwapAllowance({ params: { payload, srcChainKey, walletProvider }, queryOption
|
|
|
15
15
|
useStatus({ params: { intentTxHash }, queryOptions }); // Intent execution status (3s)
|
|
16
16
|
// Polls 3s; stops on a terminal source, a rejected API key, or 40 consecutive ambiguous reads.
|
|
17
17
|
useDetailedStatus({ params: { srcChainKey, srcTxHash }, queryOptions }); // Swap status by source tx (3s)
|
|
18
|
+
useSwapApprovalStrategy({ params: { payload, walletProvider }, queryOptions }); // 'not-required' | 'atomic-batch' | 'sequential' (no polling)
|
|
18
19
|
|
|
19
20
|
// Mutations — domain inputs flow through mutate(vars), see Mutation params below
|
|
20
21
|
useSwap({ mutationOptions });
|
|
21
22
|
useSwapApprove({ mutationOptions });
|
|
23
|
+
useSwapWithApproval({ mutationOptions }); // useSwap + approval; one EIP-5792 signature when the wallet can batch
|
|
24
|
+
|
|
25
|
+
// Composite — the whole form as one state machine; see recipes/swap.md § One Hook for the Whole Form
|
|
26
|
+
useSwapLifecycle({ intentParams, srcWalletProvider, dstWalletProvider, chainSwitch?, externalBlocked?, extras?, timeout?, mutationOptions? });
|
|
27
|
+
// → { state, error, next, reset, approvalStrategy, swap, status, stellar, nearStorage }
|
|
28
|
+
// the Stellar and NEAR gates check intentParams.dstAddress; dstWalletProvider must control it for the setup actions
|
|
29
|
+
// state.kind: idle | checking | needsChainSwitch | needsSetup(reason) | ready(approvalStrategy) | submitting
|
|
30
|
+
// | pending (error? after a post-broadcast failure) | unconfirmed (batch may still land — next() re-checks it, never re-sends) | settled | failed
|
|
22
31
|
useCancelSwap({ mutationOptions }); // TVars are FLAT: { srcChainKey, intent, walletProvider }
|
|
23
32
|
useCreateLimitOrder({ mutationOptions }); // No deadline; cancel manually
|
|
24
33
|
useCancelLimitOrder({ mutationOptions }); // TVars are FLAT: { srcChainKey, intent, walletProvider }
|
|
@@ -126,8 +135,23 @@ if (data?.ok) {
|
|
|
126
135
|
}
|
|
127
136
|
```
|
|
128
137
|
|
|
138
|
+
To render it without switching on `source`, collapse it with `summarizeSwapStatus` (from `@sodax/sdk`, re-exported here) — `{ state: 'pending' | 'solved' | 'failed'; hubTxHash?; fillTxHash? }`. `fillTxHash` may be absent even when solved.
|
|
139
|
+
|
|
140
|
+
**Default to `useDetailedStatus`.** It is the only swap status read that answers for every completion path, and it takes the identifiers `swap()` hands back on success (`intentDeliveryInfo.srcChainKey` / `srcTxHash`) and on a post-broadcast failure (`error.context.srcChainKey` / `srcTxHash`).
|
|
141
|
+
|
|
129
142
|
That is what distinguishes it from `useSwapsApiSubmitTxStatus`, which reads the backend record directly — 404 when none exists, and a stale or abandoned record for a swap the client-side fallback completed. A swap whose relay packet has not landed has no hub tx hash and reads as `LOOKUP_FAILED`; that spends the same 40-read budget as a solver `NOT_FOUND`, so a swap nothing can resolve stops instead of polling forever. A dependency outage does **not** spend the budget — it keeps polling so the read recovers on its own.
|
|
130
143
|
|
|
144
|
+
### `useSwapWithApproval` — approve and swap in one signature
|
|
145
|
+
|
|
146
|
+
Same vars as `useSwap`. It calls `sodax.swaps.swapWithApproval`: no approval when the allowance suffices; on an EVM
|
|
147
|
+
spoke whose wallet reports EIP-5792 atomic support, approve + swap as **one batch, one signature**; otherwise approve,
|
|
148
|
+
wait for it to confirm, then swap. `data.approvalStrategy` says which ran. Pair it with `useSwapApprovalStrategy` to
|
|
149
|
+
label the button up front (e.g. "Approve & Swap" vs "Approve, then Swap"), instead of the
|
|
150
|
+
`useSwapAllowance` + `useSwapApprove` + `useSwap` trio. A rejected batch — or a declined account upgrade on a
|
|
151
|
+
`'ready'` wallet — is `USER_REJECTED` and is **not** retried as two transactions. A declined upgrade carries
|
|
152
|
+
`context.reason === ACCOUNT_UPGRADE_DECLINED`; pass `allowAccountUpgrade: false` (in the mutation vars and to
|
|
153
|
+
`useSwapApprovalStrategy`) to swap without the upgrade. dapp-kit never stores that choice — the app decides.
|
|
154
|
+
|
|
131
155
|
## Gotchas
|
|
132
156
|
|
|
133
157
|
1. **`Intent.srcChain` and `Intent.dstChain` keep their v1 names.** Even though request-side params use `srcChainKey`/`dstChainKey`, the read-side `Intent` type didn't rename. Don't blanket-replace these names.
|
|
@@ -11,6 +11,8 @@ Cross-chain token transfers via the hub-and-spoke vault architecture.
|
|
|
11
11
|
| `useBridge` | Mutation | Execute a cross-chain bridge transfer |
|
|
12
12
|
| `useBridgeAllowance` | Query | Check if token approval is needed |
|
|
13
13
|
| `useBridgeApprove` | Mutation | Approve tokens for bridge |
|
|
14
|
+
| `useBridgeWithApproval` | Mutation | Bridge with the approval folded in — one signature on an EIP-5792 wallet |
|
|
15
|
+
| `useBridgeApprovalStrategy` | Query | Which approval path `useBridgeWithApproval` would take, for the button label |
|
|
14
16
|
| `useGetBridgeableAmount` | Query | Available bridgeable amount between two tokens |
|
|
15
17
|
| `useGetBridgeableTokens` | Query | Tokens bridgeable to a destination chain |
|
|
16
18
|
|
|
@@ -15,6 +15,7 @@ Leveraged-yield ERC-4626 vaults on Sonic. Deposit any token → `lsoda*` shares,
|
|
|
15
15
|
| `useLeverageYieldDeposit` | Build a deposit payload (any token → `lsoda*`) |
|
|
16
16
|
| `useLeverageYieldWithdraw` | Build a withdraw payload (`lsoda*` → any token) |
|
|
17
17
|
| `useLeverageYieldVaultSwap` | Execute a built payload end-to-end (backend submit-tx by default, client-side relay as fallback) |
|
|
18
|
+
| `useLeverageYieldVaultSwapWithApproval` | `useLeverageYieldVaultSwap` with the deposit's approval folded in — one signature on an EIP-5792 wallet |
|
|
18
19
|
| `useSwapApprove` | Approve the spoke `inputToken` (deposit only — swap-domain hook) |
|
|
19
20
|
|
|
20
21
|
### Queries
|