@sodax/skills 2.3.0-rc.2 → 2.3.0-rc.3
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 +6 -4
- package/README.md +3 -2
- package/package.json +1 -1
- package/skills/sodax-build/SKILL.md +1 -0
- package/skills/sodax-build/knowledge/chains-and-assets.md +1 -1
- package/skills/sodax-dapp-kit/auxiliary-services/SKILL.md +1 -1
- package/skills/sodax-dapp-kit/bridge/SKILL.md +1 -0
- package/skills/sodax-dapp-kit/integration/knowledge/ai-rules.md +3 -0
- package/skills/sodax-dapp-kit/integration/knowledge/architecture.md +7 -3
- package/skills/sodax-dapp-kit/integration/knowledge/features/auxiliary-services.md +8 -3
- package/skills/sodax-dapp-kit/integration/knowledge/quickstart.md +2 -2
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/setup.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md +1 -1
- package/skills/sodax-dapp-kit/leverage-yield/SKILL.md +1 -0
- package/skills/sodax-dapp-kit/swap/SKILL.md +1 -0
- package/skills/sodax-sdk/SKILL.md +2 -1
- package/skills/sodax-sdk/bridge/SKILL.md +1 -1
- package/skills/sodax-sdk/bridge-api/SKILL.md +13 -8
- package/skills/sodax-sdk/integration/knowledge/ai-rules.md +5 -3
- package/skills/sodax-sdk/integration/knowledge/architecture.md +8 -8
- package/skills/sodax-sdk/integration/knowledge/features/backend-api.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/features/bridge-api.md +43 -7
- package/skills/sodax-sdk/integration/knowledge/features/leverage-yield-api.md +38 -3
- package/skills/sodax-sdk/integration/knowledge/features/money-market.md +2 -0
- package/skills/sodax-sdk/integration/knowledge/features/swap.md +6 -2
- package/skills/sodax-sdk/integration/knowledge/features/swaps-api.md +36 -4
- package/skills/sodax-sdk/integration/knowledge/quickstart.md +4 -4
- package/skills/sodax-sdk/integration/knowledge/recipes/initialize-sodax.md +13 -6
- package/skills/sodax-sdk/integration/knowledge/recipes/logging.md +2 -4
- package/skills/sodax-sdk/integration/knowledge/recipes/testing.md +2 -2
- package/skills/sodax-sdk/leverage-yield/SKILL.md +1 -1
- package/skills/sodax-sdk/leverage-yield-api/SKILL.md +12 -10
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/README.md +1 -1
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/architecture.md +3 -3
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/checklist.md +2 -2
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/money-market.md +1 -1
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/recipes.md +1 -1
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/reference/sodax-config.md +1 -1
- package/skills/sodax-sdk/swap/SKILL.md +1 -1
- package/skills/sodax-sdk/swaps-api/SKILL.md +11 -9
- package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/interfaces.md +3 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: sodax-sdk-swaps-api
|
|
3
|
-
description: 'Granular skill for the @sodax/sdk v2 Swaps API client — `sodax.api.swaps` (class SwapsApiService), a typed HTTP client for the backend Swaps API (`/swaps/*`, 21 endpoints: quote, deadline, allowance/approve, create-intent, intent submit/status/cancel/hash/packet/extra-data, limit orders, gas estimate, partner/solver fees, submit-tx + status). Every method returns Promise<Result<T>>, never throws, and validates the response. Use when the task calls the swaps backend directly (e.g. "get a swap quote from the Sodax backend", "sodax.api.swaps", "submit swap tx", "createIntent via the backend API", "poll submit-tx status", "swaps API v2", "point swaps at a custom endpoint", "approve and send the swap in one signature"). For the higher-level
|
|
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"), or must swap tokens the installed SDK does not bundle ("unsupported token_src", "backend token list without upgrading the SDK"). For the higher-level swap orchestrator, which accepts only bundled tokens, 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)
|
|
@@ -17,9 +17,10 @@ validates the response. Errors carry `feature: 'backend'`, `context.api: 'swaps'
|
|
|
17
17
|
|
|
18
18
|
1. **Which endpoint(s)?** Tokens · quote/deadline · allowance/approve/create-intent · intent lifecycle
|
|
19
19
|
(submit/status/cancel/hash/packet/extra-data/fill/get) · limit-orders/gas/fees · submit-tx/status.
|
|
20
|
-
2. **Orchestrator or raw API?**
|
|
21
|
-
|
|
22
|
-
|
|
20
|
+
2. **Orchestrator or raw API?** `sodax.swaps` (the `swap` skill) accepts only tokens bundled with the
|
|
21
|
+
installed `@sodax/sdk` (`unsupported token_src` / `token_dst` otherwise). Use `sodax.api.swaps` end to
|
|
22
|
+
end for tokens newer than the installed SDK, where the backend validates, or for a single backend call
|
|
23
|
+
(a quote, a fee, a status poll). Otherwise prefer `sodax.swaps` for "do a swap".
|
|
23
24
|
3. **Custom endpoint?** Does the swaps API live at a different host than the base backend API? If so, the
|
|
24
25
|
`CustomApiConfig` variant is needed (see anti-patterns + the feature doc).
|
|
25
26
|
|
|
@@ -27,7 +28,7 @@ validates the response. Errors carry `feature: 'backend'`, `context.api: 'swaps'
|
|
|
27
28
|
|
|
28
29
|
1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT (read first).
|
|
29
30
|
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
|
-
3. For the
|
|
31
|
+
3. For the SDK swap flow (local token checks; only its submit-tx leg calls this API) → [`../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
32
|
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
33
|
|
|
33
34
|
### Swaps-API-specific anti-patterns
|
|
@@ -35,8 +36,8 @@ validates the response. Errors carry `feature: 'backend'`, `context.api: 'swaps'
|
|
|
35
36
|
- **Omitting `partnerFee` on `getQuote` / `createIntent`.** Optional on the type only — no backend/SDK default. Ask for a real fee receiver; never invent one or use the zero address.
|
|
36
37
|
- **`try/catch` for failures.** Every method returns `Result<T>` — branch on `result.ok`. `catch` won't fire for HTTP/timeout/validation failures.
|
|
37
38
|
- **Passing the `RelayExtraData` object** to `submitTx`'s `relayData`. The field is a `string` — pass `relayData.payload`.
|
|
38
|
-
- **
|
|
39
|
-
- **Approving, waiting, then signing the intent tx on an EVM source.** Where the wallet supports EIP-5792,
|
|
39
|
+
- **Passing `createIntent`'s `intent` straight to `submitTx`.** It is `IntentResponseV2` (decimal strings); `submitTx` takes `IntentRequestV2` (bigint). Convert it with `toIntentRequest` ([`features/swaps-api.md`](../integration/knowledge/features/swaps-api.md) § "Submit tx + poll status"); don't stringify bigints yourself.
|
|
40
|
+
- **Approving, waiting, then signing the intent tx on an EVM source.** Where your SDK has `sendApprovalBatch` and the wallet supports EIP-5792, it 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`.
|
|
40
41
|
- **Calling `getSubmitTxStatus` with only `txHash`.** Both `txHash` AND `srcChainKey` are required.
|
|
41
42
|
- **Confusing `sodax.api.swaps` with `sodax.swaps`.** The former is the backend HTTP client; the latter is the on-chain intent orchestrator.
|
|
42
43
|
|
|
@@ -55,11 +56,12 @@ builds on are covered in the existing swap + backend-api migration docs:
|
|
|
55
56
|
2. Every `await sodax.api.swaps.<method>(...)` call site has `if (!result.ok)`.
|
|
56
57
|
3. `submitTx.relayData` is `relayData.payload` (string); `getSubmitTxStatus` passes both `txHash` and `srcChainKey`.
|
|
57
58
|
4. Every `getQuote` / `createIntent` body carries the same `partnerFee` (real receiver), or the user said they are not monetizing.
|
|
58
|
-
5.
|
|
59
|
+
5. The `intent` given to `submitTx` is an `IntentRequestV2` (bigint) converted from `createIntent`'s `IntentResponseV2`; no manual `.toString()`.
|
|
60
|
+
6. Tokens offered to users come from `getTokens()`, not from `sodax.config` or `getSupportedSolverTokens`, when the flow must accept tokens newer than the installed SDK.
|
|
59
61
|
|
|
60
62
|
## Related granular skills (same family)
|
|
61
63
|
|
|
62
|
-
- [`../swap/SKILL.md`](../swap/SKILL.md) — the
|
|
64
|
+
- [`../swap/SKILL.md`](../swap/SKILL.md) — the swap orchestrator (`sodax.swaps`): it validates tokens locally and uses this API only for submit-tx.
|
|
63
65
|
- [`../backend-api/SKILL.md`](../backend-api/SKILL.md) — the sibling `sodax.backendApi` read client (intent / orderbook / money-market reads + config).
|
|
64
66
|
|
|
65
67
|
For multi-feature tasks, load the broad [`sodax-sdk` skill](../SKILL.md).
|
|
@@ -34,6 +34,7 @@ Plus public field: `publicClient: PublicClient`. The three EIP-5792 methods are
|
|
|
34
34
|
| `getAssociatedTokenAddress` | `(mint) => Promise<SolanaBase58PublicKey>` |
|
|
35
35
|
| `getBalance` | `(publicKey) => Promise<number>` |
|
|
36
36
|
| `getTokenAccountBalance` | `(publicKey) => Promise<RpcResponseAndContext<TokenAmount>>` |
|
|
37
|
+
| `signAndSendTransaction?` | `(tx: SolanaRawTransaction) => Promise<TransactionSignature>` — signs and sends a transaction the Swaps / Bridge / Leverage Yield API built |
|
|
37
38
|
|
|
38
39
|
Plus public field: `connection: Connection`.
|
|
39
40
|
|
|
@@ -72,6 +73,7 @@ Plus public field: `connection: Connection`.
|
|
|
72
73
|
| `getWalletAddress` | `() => Promise<string>` |
|
|
73
74
|
| `signTransaction` | `(tx: XDR) => Promise<XDR>` |
|
|
74
75
|
| `waitForTransactionReceipt` | `(hash: string, opts?: Pick<StellarWalletDefaults, 'pollInterval' | 'pollTimeout'>) => Promise<…>` |
|
|
76
|
+
| `signAndSendTransaction?` | `(tx: StellarRawTransaction) => Promise<string>` — signs and sends a transaction the Swaps / Bridge / Leverage Yield API built |
|
|
75
77
|
|
|
76
78
|
---
|
|
77
79
|
|
|
@@ -123,6 +125,7 @@ Plus public fields (PK mode only): `account?: Account`, `rpcProvider?: JsonRpcPr
|
|
|
123
125
|
| `sendTransaction` | `(params: StacksTransactionParams) => Promise<…>` |
|
|
124
126
|
| `readContract` | `(params: StacksTransactionParams) => Promise<ClarityValue>` |
|
|
125
127
|
| `getBalance` | `(address: string) => Promise<bigint>` |
|
|
128
|
+
| `signAndSendTransaction?` | `(tx: StacksRawTransaction) => Promise<string>` — signs and sends a transaction the Swaps / Bridge / Leverage Yield API built |
|
|
126
129
|
|
|
127
130
|
---
|
|
128
131
|
|