@sodax/skills 2.2.0-rc.4 → 2.2.0-rc.5
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/package.json +1 -1
- package/skills/sodax-sdk/integration/knowledge/architecture.md +35 -0
- package/skills/sodax-sdk/integration/knowledge/chain-specifics.md +3 -1
- package/skills/sodax-sdk/integration/knowledge/features/leverage-yield.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/features/swap.md +7 -0
- package/skills/sodax-sdk/integration/knowledge/recipes/logging.md +2 -2
package/package.json
CHANGED
|
@@ -540,3 +540,38 @@ You drop down to the relay layer only when:
|
|
|
540
540
|
- Per-feature usage: [`features/`](features/).
|
|
541
541
|
- Non-EVM chain quirks: [`chain-specifics.md`](chain-specifics.md).
|
|
542
542
|
- v1 → v2 porting context: [`README.md`](../../migration-v1-to-v2/knowledge/README.md).
|
|
543
|
+
|
|
544
|
+
### RWA classification and token logos
|
|
545
|
+
|
|
546
|
+
`XToken.isRwa === true` marks a registered tokenized stock, ETF or commodity,
|
|
547
|
+
including registered cross-chain representations. An omitted flag means no RWA
|
|
548
|
+
classification is declared; it is not a general-purpose crypto/stablecoin taxonomy.
|
|
549
|
+
Chain membership and symbol spelling do not determine RWA status.
|
|
550
|
+
|
|
551
|
+
Use `isRealWorldAsset({ chainKey, address })` to resolve metadata from the packaged
|
|
552
|
+
SDK registry when your token data comes from an API without the flag. It returns
|
|
553
|
+
false for unknown chains or addresses, ignores symbols, and compares EVM addresses
|
|
554
|
+
case-insensitively while preserving non-EVM identifier casing. It does not read
|
|
555
|
+
custom constructor config or validate swap/money-market support. New registry
|
|
556
|
+
metadata requires an SDK update; it does not automatically update backend payloads.
|
|
557
|
+
|
|
558
|
+
```typescript
|
|
559
|
+
import { ChainKeys, getSupportedSolverTokens, isRealWorldAsset, tokenLogo } from '@sodax/sdk';
|
|
560
|
+
|
|
561
|
+
const tokens = getSupportedSolverTokens(ChainKeys.ROBINHOOD_MAINNET);
|
|
562
|
+
const rwaTokens = tokens.filter(isRealWorldAsset);
|
|
563
|
+
const rows = tokens.map(token => ({
|
|
564
|
+
symbol: token.symbol,
|
|
565
|
+
isRwa: isRealWorldAsset(token),
|
|
566
|
+
logo: tokenLogo(token.symbol),
|
|
567
|
+
}));
|
|
568
|
+
```
|
|
569
|
+
|
|
570
|
+
For API responses using `xChainId`, pass it as `chainKey` alongside the token's
|
|
571
|
+
on-chain `address`. Resolve each chain/address before grouping directory rows;
|
|
572
|
+
keep feature support and UI visibility filters separate from classification.
|
|
573
|
+
|
|
574
|
+
`tokenLogo(symbol)` serves shared PNGs from the SDK repository's `main` branch.
|
|
575
|
+
Robinhood equity/ETF entries use the Robinhood mark; xStocks retain their own
|
|
576
|
+
artwork. Image replacements become available after merge, subject to caching,
|
|
577
|
+
without an SDK release. Consumers must use these URLs to receive the replacements.
|
|
@@ -100,6 +100,8 @@ const balance = await radfi.getBalance(tradingWallet.address);
|
|
|
100
100
|
const exists = await radfi.checkIfTradingWalletExists(personalAddress);
|
|
101
101
|
```
|
|
102
102
|
|
|
103
|
+
**Bound hosts.** Bound serves its API from three hosts and the SDK routes per path family: `/sodax/*` on `svc.bound.exchange`, `/auth/*` + `/wallets/*` on `auth.bound.exchange`, `/transactions/*` on `api.radfi.co`, and `/wallets/balance` + `/utxos` on `api.ums.bound.exchange`. The packaged defaults are correct, so no configuration is needed. `api.bound.exchange` is retired and **refused**: a `radfi.apiUrl`/`authUrl`/`transactionsUrl` still naming it throws at construction, naming the replacement for that field. Two things to know: `api.radfi.co` is a **different registrable domain**, so a Content-Security-Policy `connect-src` or egress allowlist written as `https://*.bound.exchange` will block BTC withdrawal and UTXO renewal; and setting `radfi.apiUrl` yourself sends the **three routed** families to that host (deliberate — it keeps a single-host or proxy setup working and makes a half-migration impossible). To keep the split while moving one family, set `radfi.authUrl` or `radfi.transactionsUrl` explicitly. UMS is not routed by `apiUrl`: `/wallets/balance` and `/utxos` always use `radfi.umsUrl`, so a proxy that must capture all Bound traffic has to override that too.
|
|
104
|
+
|
|
103
105
|
**Server-side / raw flows (no interactive sign-in).** A backend that builds raw Bitcoin intents can't run the BIP322 login, so seed a pre-provisioned Bound token instead of authenticating. `RadfiProvider` honors three injection points: `new Sodax({ ... })` with `radfi.accessToken` (and optional `refreshToken`) in the Bitcoin chain config (the constructor seeds them), `radfi.setRadfiAccessToken(token)` at runtime, or a per-action `extras.bound.accessToken` on `createIntent` (the Bitcoin-gated `bound` slot groups Bound/Radfi inputs). If an authenticated Bound call has neither a token nor a configured `apiKey`, `RadfiProvider` throws a legible `RadfiApiError` (the message names the fix: inject via `setRadfiAccessToken` or `new Sodax({ ... })` with `radfi.accessToken`) instead of sending an empty bearer and getting an opaque 403.
|
|
104
106
|
|
|
105
107
|
**Backend request signing.** Separate from the per-user token above: if Bound authenticates your service itself, pass `radfi.signRequest` to `new Sodax({ ... })`. The SDK calls it once per outbound Bound request and merges the returned headers onto it, so the credential stays in your closure and never on the SDK config:
|
|
@@ -118,7 +120,7 @@ new Sodax({
|
|
|
118
120
|
});
|
|
119
121
|
```
|
|
120
122
|
|
|
121
|
-
It receives `{ method, path }
|
|
123
|
+
It receives `{ method, path, baseUrl }` — `baseUrl` is the resolved Bound host for that call, so a signer holding a per-origin credential can branch on it. It may be async, and runs on every routed request (a timestamped signature must not be cached); UMS calls (`/wallets/balance`, `/utxos`) bypass it and go out unsigned. Its headers merge last, so do not return `Authorization` — that is the per-user token. Server-side only: never ship a credential in a browser bundle.
|
|
122
124
|
|
|
123
125
|
Other public methods on `RadfiProvider` you may need: `setRadfiAccessToken`, `refreshAccessToken`, `createTradingWallet`, `createWithdrawTransaction`, `requestRadfiSignature`, `getExpiredUtxos`, `buildRenewUtxoTransaction`, `signAndBroadcastRenewUtxo`, `withdrawToUser`, `signAndBroadcastWithdraw`, `getMaxWithdrawable`. Read `RadfiProvider` source for argument shapes — the API surface is broader than typical chain providers.
|
|
124
126
|
|
|
@@ -8,7 +8,7 @@ Access: `sodax.leverageYield`. Service class: `LeverageYieldService`. Feature ta
|
|
|
8
8
|
|
|
9
9
|
## How it works
|
|
10
10
|
|
|
11
|
-
- A vault holds `asset` (a Sodax vault token like sodaWEETH) as collateral, borrows `borrowToken` (e.g. sodaETH) from the Sodax-forked AAVE pool, swaps it back into the asset, and re-supplies — to a `targetLTV`.
|
|
11
|
+
- A vault holds `asset` (a Sodax vault token like the weETH vault, `SodaTokens.sodaWEETH`) as collateral, borrows `borrowToken` (e.g. sodaETH) from the Sodax-forked AAVE pool, swaps it back into the asset, and re-supplies — to a `targetLTV`.
|
|
12
12
|
- The ERC-4626 **share token is the vault proxy address itself** (`lsoda*`). Holding shares = holding the leveraged position.
|
|
13
13
|
- **Deposit** = swap any spoke token → `lsoda*`, delivered to the user's **hub wallet** on Sonic. **Withdraw** = swap `lsoda*` (held in the hub wallet) → any token on any chain.
|
|
14
14
|
- **Steady-state APR**: `netAprRay = supplyAprRay + leverageMultiplier × (supplyAprRay − borrowAprRay)`, where `leverageMultiplier = targetLTV / (1 − targetLTV)`. Rates are RAY (`1e27`); the multiplier is WAD (`1e18`). `netAprRay` goes **negative** when the borrow rate exceeds supply — for LSD-backed vaults the LSD's native staking yield (folded in by `getEffectiveApr`) is the real alpha.
|
|
@@ -42,6 +42,7 @@ sodax.swaps.createLimitOrderIntent<K, Raw>(/* same as createIntent shape with li
|
|
|
42
42
|
|
|
43
43
|
sodax.swaps.cancelIntent<K>(/* … */): Promise<Result<TxHashPair, SodaxError>>; // not generic over Raw (only false)
|
|
44
44
|
sodax.swaps.cancelLimitOrder<K>(/* … */): Promise<Result<TxHashPair, SodaxError>>; // TxHashPair = { srcChainTxHash, dstChainTxHash }
|
|
45
|
+
sodax.swaps.getCancelIntentRelayData(intent: Intent): Result<RelayExtraData>; // `data` for manually relaying a Solana cancel tx
|
|
45
46
|
|
|
46
47
|
sodax.swaps.approve<K, Raw>(/* … */): Promise<Result<TxReturnType<K, Raw>, SodaxError>>;
|
|
47
48
|
sodax.swaps.isAllowanceValid<K, Raw>(/* … */): Promise<Result<boolean, SodaxError>>;
|
|
@@ -317,6 +318,12 @@ await sodax.swaps.cancelIntent({
|
|
|
317
318
|
});
|
|
318
319
|
```
|
|
319
320
|
|
|
321
|
+
Relay handling is chain-aware and needs no caller input: Solana cancels submit the cancel payload with the spoke tx, Bitcoin cancels relay the signed on-demand payload. On Bitcoin `srcChainTxHash` is the relay's `od:<hash>` id, not a chain tx hash.
|
|
322
|
+
|
|
323
|
+
`params.srcAddress` (optional) overrides the wallet the cancel is sent from; it defaults to the intent's `srcAddress`, or on Bitcoin TRADING mode to `walletProvider.getWalletAddress()` (the intent stores the trading address). A raw (`raw: true`) Bitcoin TRADING-mode cancel must pass it.
|
|
324
|
+
|
|
325
|
+
Relaying a `createCancelIntent` tx yourself: on Solana pass `data: sodax.swaps.getCancelIntentRelayData(intent).value` to `submitIntent` (the create-intent extra data does not match a cancel tx); on Bitcoin the returned value is the signed on-demand payload JSON — relay it via `sodax.spoke.bitcoin.getOnDemandRelayIdentity(json)` (`srcTxHash: 'withdraw'`, `data`, `pollTxHash`).
|
|
326
|
+
|
|
320
327
|
## Return shapes
|
|
321
328
|
|
|
322
329
|
| Method | Success type |
|
|
@@ -24,8 +24,8 @@ chain config from the backend but **never** replaces the logger — the backend
|
|
|
24
24
|
it.
|
|
25
25
|
|
|
26
26
|
> Combine with the other constructor options freely — pass `logger` alongside `chains` / `api` /
|
|
27
|
-
> `solver` overrides in the same object. The
|
|
28
|
-
>
|
|
27
|
+
> `solver` overrides in the same object. The merged options land on `sodax.instanceConfig` (including the
|
|
28
|
+
> `logger` key), but the sink the services use is `sodax.config.logger`. See [`initialize-sodax.md`](initialize-sodax.md).
|
|
29
29
|
|
|
30
30
|
## Custom sink
|
|
31
31
|
|