@kasufinance/kasu-sdk 2.13.1 → 2.15.0

package/README.md

@@ -116,7 +116,7 @@ You can also pass a whole `ChainConfigEntry` instead of a chain key.
 
 | Facade            | Methods                                                                                                                 | Purpose                         |
 | ----------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
-| `kasu.strategies` | `getAll()`, `getVisible()`, `getById()`, `getPlatformStats()`, `getPerformanceFeePercent()`, `calculateDepositLimits()`, `getRiskPerformance(poolId)`, `getOriginator(poolId)`, `getPoolTvlHistory(poolId)` | Browse pools, APY, capacity, risk, originator, TVL history |
+| `kasu.strategies` | `getAll()`, `getVisible()`, `getById()`, `getPlatformStats()`, `getPerformanceFeePercent()`, `calculateDepositLimits()`, `getRiskPerformance(poolId)`, `getOriginator(poolId)`, `getOriginatorHistory(poolId)`, `getRiskManagementGroups(poolId)`, `getPoolTvlHistory(poolId)`, `getPoolTvlHistoryWindow(poolId)` | Browse pools, APY, capacity, risk, originator, TVL history |
 | `kasu.deposits`   | `deposit()`, `withdraw()`, `withdrawMax()`, `buildKycParams()`, `isClearingPending()`                                   | Submit transactions             |
 | `kasu.portfolio`  | `getPositions()`, `getYieldHistory()`, `getTransactionHistory()`, `getRequestStates()`                                  | Lender balances, yield, per-cycle earnings (net, in the chain's own stable token), history |
 | `kasu.flows`      | `deposit(ports)`, `withdraw(ports?)`                                                                                    | Headless transaction pipelines  |
@@ -167,6 +167,44 @@ instance, so a second call reads only what is new. `timeoutMs` (default
 30 s) and `signal` bound the call and reject with
 `PoolTvlHistoryTimeoutError` / `PoolTvlHistoryAbortedError`.
 
+A strategy can run on more than one deployment (Tax Pay lends on Base and on
+XDC AUDD), and its total lent is the sum of its pools. `strategyDeployments`
+names the pools and `combineTvlHistories` adds their histories in USD at the
+rates you pass. The SDK fetches no exchange rate:
+
+```ts
+import { CHAIN_CONFIGS, combineTvlHistories, strategyDeployments } from '@kasufinance/kasu-sdk';
+
+// Your rates, keyed by ISO-4217 code — never a guess. No rate, no total.
+const usdPer: Record<string, number> = { USD: 1, AUD: audToUsd };
+
+const legs = strategyDeployments(strategy.id, 'base');
+// [{ chain: 'base', poolId: '0x…' }, { chain: 'xdc', poolId: '0x…' }]
+
+const histories = await Promise.all(
+    legs.map(async ({ chain, poolId }) => ({
+        // { entries, opening } — `opening`: what the pool held just before the window
+        ...(await sdks[chain].strategies.getPoolTvlHistoryWindow(poolId, { count: 52 })),
+        usdRate: usdPer[CHAIN_CONFIGS[chain].stableAsset.currencyCode],
+    })),
+);
+const points = combineTvlHistories(histories); // { timestamp, tvlUsd, kind }[]
+```
+
+`strategyDeployments(poolId, chain)` takes the deployment the id was read on
+(required: an address alone does not name its chain) and returns the same set
+from either side of the mapping; an unmapped id is a strategy of one on its
+own chain, and an id the mapping places on another deployment throws
+`StrategyDeploymentInputError`. `combineTvlHistories` is a step merge by time:
+at every clearing on any leg, each leg's latest point, times its rate, summed;
+a leg's `opening` (the clearing just before its window, read like every
+other point) is one more step, from its own time until the first entry, and
+a pool that started inside the window has none and counts 0 until then, so
+windows cut at different times on each chain draw no false step. It ends with one `current` point, the sum of
+the legs' current values. A missing rate, an empty leg or a bad entry throws
+`TvlHistoryInputError`, so the series never holds `NaN` and never passes off
+one chain's figure as the total.
+
 ## Domain helpers
 
 Pure functions shared by every Kasu frontend. They return **numbers and codes,
@@ -185,14 +223,16 @@ application formats them in its own design system and language.
 | Batch proof          | `validateDepositBatchCalls`, `proveDepositInReceipt`, `DepositBatchMismatchError`, `ENTRY_POINT_V07`                                                                                                   |
 | Tranche display name | `getTrancheDisplayName`, `UPPER_MEZZANINE`                                                                                                                                                               |
 | Strategy summary     | `pickShortDescription` — the CMS short blurb as one line of plain text, or `undefined` (also on every `Strategy` as `summary`)                                                                            |
+| Strategy details     | `readCmsStartDate`, `splitBusinessTypes`, `parseFacility`, `splitNumberedClauses`, `groupRiskManagementItems`, `RISK_GROUP_ORDER`, `securityStructureOf`, `strategyTotalsUsd`, `StrategyTotalsInputError` — the Details-screen fields as kasu-ui reads them (also on `Strategy` and the two strategy getters above) |
 | Requests             | `deriveRequestState`, `submissionEvents`, `countSubmissions`, `firstSubmissionTimestamp`, `isCycleClosed`                                                                                                |
 | Settlement           | `computeSettlementWindow`, `nextCycleBoundary`, `deriveCycleDates`, `CLEARING_WINDOW_SECONDS`                                                                                                            |
-| Loan contract        | `encodeDepositData`, `buildContractVersionType`, `buildLoanAgreementSignMessage`, `buildLegacyContractRequestMessage`, `buildFullNameRequestMessage`, `formatSignTimestampUtc`, `parseFormattedMessage`, `asContractType` |
+| Loan contract        | `encodeDepositData`, `buildContractVersionType`, `buildLoanAgreementSignMessage`, `buildLegacyContractRequestMessage` (deprecated), `buildFullNameRequestMessage`, `formatSignTimestampUtc`, `parseFormattedMessage`, `asContractType` |
 | Wallet errors        | `isUserRejected`, `isUnpredictableGas`, `classifyWalletFailure`                                                                                                                                          |
+| Pool TVL             | `poolTvl`, `combineTvlHistories`, `TvlHistoryInputError` — one strategy's history summed across deployments, in USD at the caller's rates |
 | Revert errors        | `decodeRevert`, `extractRevertData` — the bytes a reverted call came back with, read as the custom error the contract named                                                                              |
 | AU minimum           | `auMinimumRemaining`, `isAustralianKyc`, `auThresholdFor`, `isAuMinimumExempt`, `parseMinorUnits`, `AU_ALPHA3`, `AU_MIN_CUMULATIVE_BY_STABLE`                                                            |
 
-Three rules worth knowing:
+Rules worth knowing:
 
 - **Protocol strings are the exception to "never copy".** The messages
   `loan-contract` builds are reconstructed byte-for-byte by the Kasu backend to
@@ -213,6 +253,29 @@ Three rules worth knowing:
   `liteDescription` and `description` stay the raw CMS values. It is NOT
   sanitised: HTML tags and link syntax pass through unchanged, so render it
   as text, never as HTML or markdown.
+- **The Details-screen fields omit, never stub.** `Strategy.strategyHistory`,
+  `Strategy.endBorrowers`, `Strategy.securityStructure`,
+  `getOriginatorHistory` and `getRiskManagementGroups` carry only what the CMS
+  actually authors: an empty, blank or malformed value is an absent key (or
+  `null` for a whole section), never a `0`, a dash or a sentence of the
+  SDK's own. A start date is `YYYY-MM-DD` and must be a real date from 2000
+  up to today. The originator's money figures are editorial USD on every
+  deployment — never FX-convert them. A risk item's `description` is present
+  exactly when its `clauses` are non-empty.
+- **A failed CMS read rejects; it is not "no data".** `getOriginatorHistory`
+  and `getRiskManagementGroups` reject on a CMS outage (or no
+  `directusUrl`). For what to SHOW, treat a rejected `getRiskManagementGroups`
+  like `null`: fall back to `Strategy.securityStructure`. The pool getters
+  share their CMS reads per instance for 30 seconds (`getRiskPerformance` with
+  `getRiskManagementGroups`, `getOriginator` with `getOriginatorHistory`), so
+  a Details screen reads each collection once; a failed read is never reused.
+- **`strategyTotalsUsd(legs, expectedDeployments)` states its coverage.** It
+  sums a strategy's Total Active Lending and Lender Interest Earned in USD
+  over the legs the caller loaded, each at its own rate. It is `null`
+  (withheld) when there are no legs or any loaded leg lacks a usable rate;
+  otherwise `isPartial` / `missingDeployments` name every expected deployment
+  the sum does not cover. Only `isPartial: false` is the whole strategy. A
+  duplicated or unexpected leg throws `StrategyTotalsInputError`.
 - **The tranche rename is display-only.** `getTrancheDisplayName` maps the
   `Senior` tranche to "Upper Mezzanine" on Apxium strategies, because the true
   senior position is held by an institutional lender. Call it at the view
@@ -623,8 +686,8 @@ tag workflow only verifies that a pushed `vX.Y.Z` tag matches `package.json`.
 ## Support
 
 - Issues: <https://github.com/Kasu-Finance/kasu-sdk/issues>
-- Developer documentation: <https://devdocs.kasu.finance>
-- Product documentation: <https://docs.kasu.finance>
+- Developer documentation: <https://kasu.finance/docs/developers>
+- Product documentation: <https://kasu.finance/docs/user>
 
 ## License