@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.
Files changed (41) hide show
  1. package/AGENTS.md +6 -4
  2. package/README.md +3 -2
  3. package/package.json +1 -1
  4. package/skills/sodax-build/SKILL.md +1 -0
  5. package/skills/sodax-build/knowledge/chains-and-assets.md +1 -1
  6. package/skills/sodax-dapp-kit/auxiliary-services/SKILL.md +1 -1
  7. package/skills/sodax-dapp-kit/bridge/SKILL.md +1 -0
  8. package/skills/sodax-dapp-kit/integration/knowledge/ai-rules.md +3 -0
  9. package/skills/sodax-dapp-kit/integration/knowledge/architecture.md +7 -3
  10. package/skills/sodax-dapp-kit/integration/knowledge/features/auxiliary-services.md +8 -3
  11. package/skills/sodax-dapp-kit/integration/knowledge/quickstart.md +2 -2
  12. package/skills/sodax-dapp-kit/integration/knowledge/recipes/setup.md +1 -1
  13. package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md +1 -1
  14. package/skills/sodax-dapp-kit/leverage-yield/SKILL.md +1 -0
  15. package/skills/sodax-dapp-kit/swap/SKILL.md +1 -0
  16. package/skills/sodax-sdk/SKILL.md +2 -1
  17. package/skills/sodax-sdk/bridge/SKILL.md +1 -1
  18. package/skills/sodax-sdk/bridge-api/SKILL.md +13 -8
  19. package/skills/sodax-sdk/integration/knowledge/ai-rules.md +5 -3
  20. package/skills/sodax-sdk/integration/knowledge/architecture.md +8 -8
  21. package/skills/sodax-sdk/integration/knowledge/features/backend-api.md +1 -1
  22. package/skills/sodax-sdk/integration/knowledge/features/bridge-api.md +43 -7
  23. package/skills/sodax-sdk/integration/knowledge/features/leverage-yield-api.md +38 -3
  24. package/skills/sodax-sdk/integration/knowledge/features/money-market.md +2 -0
  25. package/skills/sodax-sdk/integration/knowledge/features/swap.md +6 -2
  26. package/skills/sodax-sdk/integration/knowledge/features/swaps-api.md +36 -4
  27. package/skills/sodax-sdk/integration/knowledge/quickstart.md +4 -4
  28. package/skills/sodax-sdk/integration/knowledge/recipes/initialize-sodax.md +13 -6
  29. package/skills/sodax-sdk/integration/knowledge/recipes/logging.md +2 -4
  30. package/skills/sodax-sdk/integration/knowledge/recipes/testing.md +2 -2
  31. package/skills/sodax-sdk/leverage-yield/SKILL.md +1 -1
  32. package/skills/sodax-sdk/leverage-yield-api/SKILL.md +12 -10
  33. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/README.md +1 -1
  34. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/architecture.md +3 -3
  35. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/checklist.md +2 -2
  36. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/money-market.md +1 -1
  37. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/recipes.md +1 -1
  38. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/reference/sodax-config.md +1 -1
  39. package/skills/sodax-sdk/swap/SKILL.md +1 -1
  40. package/skills/sodax-sdk/swaps-api/SKILL.md +11 -9
  41. 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 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"), 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?** If the user just wants "do a swap", prefer `sodax.swaps` (the `swap`
21
- skill). Use `sodax.api.swaps` when they need a single backend call (a quote, a fee, a status poll) or
22
- are building their own flow.
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 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
+ 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
- - **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
+ - **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. Intent-bearing bodies pass the `bigint` `IntentRequestV2` through unmodified (no manual `.toString()`).
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 end-to-end swap orchestrator (`sodax.swaps`) that wraps these backend calls.
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