@kasufinance/kasu-sdk 2.14.0 → 2.16.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)`, `getPoolTvlHistoryWindow(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  |
@@ -142,6 +142,22 @@ slightly more than lifetime interest (up to about 0.2 %, top-ups are valued at
 today's share price), so show "earned to date" from the lifetime figure, not
 from the sum of the bars.
 
+Each cycle's interest is paired with the shares in force when that cycle's
+clearing applied it — before the clearing accepted any request — so a
+withdrawal the pool manager accepted between clearings is out of the next
+cycle's figures, and the newest bar equals `getPositions`' last-epoch figure.
+
+The subgraph counts a lender's shares as a ledger of accepted deposits and
+withdrawals. Shares moved to or from a wallet any other way are not on it.
+`getPositions` compares the ledger with the chain AT THE BLOCK THE SUBGRAPH
+ANSWERED AT (so indexing lag is never a fault). Where they disagree it reads
+the tranche balances from the chain, so a balance is never negative, and
+sets `ledgerMismatch` on the pool. `ledger-exceeds-chain` (the wallet sent
+shares away) withholds the pool's last-cycle figures and leaves the pool out
+of `getYieldHistory`. An `investedAmount` raised to 0 carries
+`investedAmountFloored`. Lifetime figures stay ledger figures, which include
+the moved principal.
+
 `kasu.strategies.getPoolTvlHistory(poolId, { fromEpoch?, count?, timeoutMs?,
 signal? })` returns the strategy's TVL (total lent by everyone) as
 `{ epochId, timestamp, tvl, kind }[]`, ascending in time: one
@@ -223,15 +239,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
@@ -252,6 +269,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
@@ -662,8 +702,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