@kasufinance/kasu-sdk 2.15.0 → 2.16.0

package/dist/domain/yield-history.d.ts

@@ -15,6 +15,24 @@
  * on Base and XDC USDC, AUDD on XDC AUDD) — never converted to USD here;
  * shares are display units of tranche shares, as the subgraph's BigDecimals.
  */
+/**
+ * The largest change of a lock's shares, as a fraction of its shares before
+ * the epoch, that one clearing's fixed-term top-up can make. The top-up is
+ * the fixed rate's difference from the variable one on one week's balance
+ * (`LendingPool._applyFixedRateInterests`) — a fraction of a percent at any
+ * real rate — so 5 % is far above every genuine top-up and far below any
+ * accounting fault. A lock-share change outside it is NOT interest: it is
+ * left out of the yield (a share movement is never booked as yield). The one
+ * seen on chain is a lock whose recorded shares were set to zero at a
+ * clearing while its shares stayed in the fixed-term contract.
+ */
+export declare const MAX_TOP_UP_SHARE_FRACTION = 0.05;
+/**
+ * True when `sharesBefore → sharesAt` is a change one clearing's fixed-term
+ * top-up can make (`MAX_TOP_UP_SHARE_FRACTION`). A lock with no shares
+ * before has no top-up at all.
+ */
+export declare function isPlausibleTopUp(sharesBefore: number, sharesAt: number): boolean;
 /** One fixed-term lock inside a tranche position, at one epoch. */
 export interface EpochLockShares {
     /**
@@ -68,7 +86,13 @@ export interface EpochTrancheYield {
  * ```
  *
  * A zero denominator contributes 0 (a tranche or a lender with no shares
- * earned nothing at that close), never `NaN`.
+ * earned nothing at that close), never `NaN`. So does a NEGATIVE share count:
+ * the subgraph's per-lender shares are a ledger of accepted deposits and
+ * withdrawals, and a wallet whose shares arrived some other way (moved to it
+ * from another wallet) withdraws more than the ledger ever credited it. That
+ * position is not one the ledger can describe, and its negative count is not
+ * a negative yield. A lock-share change no top-up can make
+ * (`isPlausibleTopUp`) contributes no top-up.
  */
 export declare function epochTrancheYield(input: EpochTrancheYieldInput): EpochTrancheYield;
 /** One lender's settled yield in one tranche at one epoch. */

package/dist/domain/yield-history.js

@@ -15,6 +15,29 @@
  * on Base and XDC USDC, AUDD on XDC AUDD) — never converted to USD here;
  * shares are display units of tranche shares, as the subgraph's BigDecimals.
  */
+/**
+ * The largest change of a lock's shares, as a fraction of its shares before
+ * the epoch, that one clearing's fixed-term top-up can make. The top-up is
+ * the fixed rate's difference from the variable one on one week's balance
+ * (`LendingPool._applyFixedRateInterests`) — a fraction of a percent at any
+ * real rate — so 5 % is far above every genuine top-up and far below any
+ * accounting fault. A lock-share change outside it is NOT interest: it is
+ * left out of the yield (a share movement is never booked as yield). The one
+ * seen on chain is a lock whose recorded shares were set to zero at a
+ * clearing while its shares stayed in the fixed-term contract.
+ */
+export const MAX_TOP_UP_SHARE_FRACTION = 0.05;
+/**
+ * True when `sharesBefore → sharesAt` is a change one clearing's fixed-term
+ * top-up can make (`MAX_TOP_UP_SHARE_FRACTION`). A lock with no shares
+ * before has no top-up at all.
+ */
+export function isPlausibleTopUp(sharesBefore, sharesAt) {
+    if (!(sharesBefore > 0))
+        return sharesAt === sharesBefore;
+    return (Math.abs(sharesAt - sharesBefore) <=
+        sharesBefore * MAX_TOP_UP_SHARE_FRACTION);
+}
 /**
  * The ONE per-epoch formula. `Portfolio.getPortfolioLendingData` runs it for
  * the last settled epoch and `getYieldHistory` for every epoch of a window, so
@@ -29,24 +52,31 @@
  * ```
  *
  * A zero denominator contributes 0 (a tranche or a lender with no shares
- * earned nothing at that close), never `NaN`.
+ * earned nothing at that close), never `NaN`. So does a NEGATIVE share count:
+ * the subgraph's per-lender shares are a ledger of accepted deposits and
+ * withdrawals, and a wallet whose shares arrived some other way (moved to it
+ * from another wallet) withdraws more than the ledger ever credited it. That
+ * position is not one the ledger can describe, and its negative count is not
+ * a negative yield. A lock-share change no top-up can make
+ * (`isPlausibleTopUp`) contributes no top-up.
  */
 export function epochTrancheYield(input) {
-    const base = input.trancheShares === 0
-        ? 0
-        : (input.epochInterest * input.userShares) / input.trancheShares;
+    const base = input.trancheShares > 0 && input.userShares > 0
+        ? (input.epochInterest * input.userShares) / input.trancheShares
+        : 0;
     let variable = base;
     const locks = input.locks.map((lock) => {
         if (!lock.active)
             return 0;
-        const topUp = input.trancheSharesNow === 0
-            ? 0
-            : ((lock.sharesAtEpoch - lock.sharesBeforeEpoch) *
+        const topUp = input.trancheSharesNow > 0 &&
+            isPlausibleTopUp(lock.sharesBeforeEpoch, lock.sharesAtEpoch)
+            ? ((lock.sharesAtEpoch - lock.sharesBeforeEpoch) *
                 input.trancheBalanceNow) /
-                input.trancheSharesNow;
-        const lockBase = input.userShares === 0
-            ? 0
-            : (base * lock.sharesBeforeEpoch) / input.userShares;
+                input.trancheSharesNow
+            : 0;
+        const lockBase = input.userShares > 0
+            ? (base * lock.sharesBeforeEpoch) / input.userShares
+            : 0;
         variable -= lockBase;
         return lockBase + topUp;
     });

package/dist/domain/yield-history.js.map

@@ -1 +1 @@
-{"version":3,"file":"yield-history.js","sourceRoot":"","sources":["../../src/domain/yield-history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AA4CH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,iBAAiB,CAC7B,KAA6B;IAE7B,MAAM,IAAI,GACN,KAAK,CAAC,aAAa,KAAK,CAAC;QACrB,CAAC,CAAC,CAAC;QACH,CAAC,CAAC,CAAC,KAAK,CAAC,aAAa,GAAG,KAAK,CAAC,UAAU,CAAC,GAAG,KAAK,CAAC,aAAa,CAAC;IAEzE,IAAI,QAAQ,GAAG,IAAI,CAAC;IACpB,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACnC,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,OAAO,CAAC,CAAC;QAE3B,MAAM,KAAK,GACP,KAAK,CAAC,gBAAgB,KAAK,CAAC;YACxB,CAAC,CAAC,CAAC;YACH,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,iBAAiB,CAAC;gBAC1C,KAAK,CAAC,iBAAiB,CAAC;gBAC5B,KAAK,CAAC,gBAAgB,CAAC;QAEjC,MAAM,QAAQ,GACV,KAAK,CAAC,UAAU,KAAK,CAAC;YAClB,CAAC,CAAC,CAAC;YACH,CAAC,CAAC,CAAC,IAAI,GAAG,IAAI,CAAC,iBAAiB,CAAC,GAAG,KAAK,CAAC,UAAU,CAAC;QAE7D,QAAQ,IAAI,QAAQ,CAAC;QAErB,OAAO,QAAQ,GAAG,KAAK,CAAC;IAC5B,CAAC,CAAC,CAAC;IAEH,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,SAAS,EAAE,EAAE,CAAC,GAAG,GAAG,SAAS,EAAE,QAAQ,CAAC,CAAC;IAE1E,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AACtC,CAAC;AAwCD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,qBAAqB,CACjC,OAAqC,EACrC,SAA6B,EAAE;;IAE/B,MAAM,MAAM,GAAG,MAAA,MAAM,CAAC,MAAM,0CAAE,WAAW,EAAE,CAAC;IAC5C,MAAM,SAAS,GAAG,MAAA,MAAM,CAAC,SAAS,0CAAE,WAAW,EAAE,CAAC;IAClD,MAAM,OAAO,GAAG,IAAI,GAAG,EAA6B,CAAC;IAErD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC1B,IAAI,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,MAAM,EAAE,CAAC;YAChE,SAAS;QACb,CAAC;QACD,IACI,SAAS,KAAK,SAAS;YACvB,KAAK,CAAC,SAAS,CAAC,WAAW,EAAE,KAAK,SAAS,EAC7C,CAAC;YACC,SAAS;QACb,CAAC;QAED,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACzC,IAAI,KAAK,EAAE,CAAC;YACR,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,QAAQ,CAAC;YACjC,SAAS;QACb,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE;YACvB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ;SAC3B,CAAC,CAAC;IACP,CAAC;IAED,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC;AACvE,CAAC"}
+{"version":3,"file":"yield-history.js","sourceRoot":"","sources":["../../src/domain/yield-history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,IAAI,CAAC;AAE9C;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAC5B,YAAoB,EACpB,QAAgB;IAEhB,IAAI,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC;QAAE,OAAO,QAAQ,KAAK,YAAY,CAAC;IAC1D,OAAO,CACH,IAAI,CAAC,GAAG,CAAC,QAAQ,GAAG,YAAY,CAAC;QACjC,YAAY,GAAG,yBAAyB,CAC3C,CAAC;AACN,CAAC;AA4CD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,iBAAiB,CAC7B,KAA6B;IAE7B,MAAM,IAAI,GACN,KAAK,CAAC,aAAa,GAAG,CAAC,IAAI,KAAK,CAAC,UAAU,GAAG,CAAC;QAC3C,CAAC,CAAC,CAAC,KAAK,CAAC,aAAa,GAAG,KAAK,CAAC,UAAU,CAAC,GAAG,KAAK,CAAC,aAAa;QAChE,CAAC,CAAC,CAAC,CAAC;IAEZ,IAAI,QAAQ,GAAG,IAAI,CAAC;IACpB,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACnC,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,OAAO,CAAC,CAAC;QAE3B,MAAM,KAAK,GACP,KAAK,CAAC,gBAAgB,GAAG,CAAC;YAC1B,gBAAgB,CAAC,IAAI,CAAC,iBAAiB,EAAE,IAAI,CAAC,aAAa,CAAC;YACxD,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,iBAAiB,CAAC;gBAC1C,KAAK,CAAC,iBAAiB,CAAC;gBAC5B,KAAK,CAAC,gBAAgB;YACxB,CAAC,CAAC,CAAC,CAAC;QAEZ,MAAM,QAAQ,GACV,KAAK,CAAC,UAAU,GAAG,CAAC;YAChB,CAAC,CAAC,CAAC,IAAI,GAAG,IAAI,CAAC,iBAAiB,CAAC,GAAG,KAAK,CAAC,UAAU;YACpD,CAAC,CAAC,CAAC,CAAC;QAEZ,QAAQ,IAAI,QAAQ,CAAC;QAErB,OAAO,QAAQ,GAAG,KAAK,CAAC;IAC5B,CAAC,CAAC,CAAC;IAEH,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,SAAS,EAAE,EAAE,CAAC,GAAG,GAAG,SAAS,EAAE,QAAQ,CAAC,CAAC;IAE1E,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AACtC,CAAC;AAwCD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,qBAAqB,CACjC,OAAqC,EACrC,SAA6B,EAAE;;IAE/B,MAAM,MAAM,GAAG,MAAA,MAAM,CAAC,MAAM,0CAAE,WAAW,EAAE,CAAC;IAC5C,MAAM,SAAS,GAAG,MAAA,MAAM,CAAC,SAAS,0CAAE,WAAW,EAAE,CAAC;IAClD,MAAM,OAAO,GAAG,IAAI,GAAG,EAA6B,CAAC;IAErD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC1B,IAAI,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,MAAM,EAAE,CAAC;YAChE,SAAS;QACb,CAAC;QACD,IACI,SAAS,KAAK,SAAS;YACvB,KAAK,CAAC,SAAS,CAAC,WAAW,EAAE,KAAK,SAAS,EAC7C,CAAC;YACC,SAAS;QACb,CAAC;QAED,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACzC,IAAI,KAAK,EAAE,CAAC;YACR,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,QAAQ,CAAC;YACjC,SAAS;QACb,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE;YACvB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ;SAC3B,CAAC,CAAC;IACP,CAAC;IAED,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC;AACvE,CAAC"}

package/dist/services/Portfolio/portfolio.d.ts

@@ -77,7 +77,12 @@ export declare class Portfolio {
      * Cost: three parallel `SystemVariables` reads and the positions query in
      * one round, then one subgraph request per page of the longest series
      * (1000 rows a page) — normally two subgraph round trips in all, never one
-     * per epoch.
+     * per epoch — alongside one `LendingPool.userBalance` call per pool at
+     * the subgraph's block. A pool whose ledger credits more than the wallet
+     * holds at that block (shares moved away outside a withdrawal) is left
+     * out; if the node says it cannot serve that block, `latest` is read
+     * and nothing is. Any other failure of those reads (a rate limit, a
+     * network error) THROWS: the history needs a working RPC.
      *
      * On a LITE deployment, a subgraph that lacks the entities (a validation
      * error naming them) yields `[]`; on a full deployment that error throws,
@@ -87,6 +92,54 @@ export declare class Portfolio {
      * network read.
      */
     getYieldHistory(userAddress: string, options?: YieldHistoryOptions): Promise<YieldHistoryEntry[]>;
+    /**
+     * Read the chain at the subgraph's block, so the chain and the ledger
+     * describe the same state: after every clearing the subgraph runs a few
+     * blocks behind, and a `latest` read would then disagree with an
+     * honest ledger (interest moved every balance, deposits were accepted)
+     * and book that difference as a ledger fault.
+     *
+     * Only when the node says it cannot serve that block (pruned, or behind
+     * the subgraph: `isBlockUnavailableError`) does it fall back to `latest`,
+     * and it says so (`blockTag: undefined`): unpinned figures are never
+     * compared with the ledger, and `getPortfolioLendingData` marks the pools
+     * `chainPinned: false`. Any other failure — a rate limit, a timeout, a
+     * network error — is thrown, never turned into an unpinned read.
+     */
+    private readChainAt;
+    /**
+     * One pool's balances: the ledger's (the subgraph counts a lender's
+     * shares as accepted deposits − accepted withdrawals ± top-ups) checked
+     * against the chain's `LendingPool.userBalance` at the SAME block.
+     *
+     * The ledger does not follow shares that move between wallets any other
+     * way (an administrative move of a position is the case seen on chain):
+     * the receiving wallet goes negative as it withdraws, the sending one
+     * keeps shares it no longer holds. Where the two disagree at that block —
+     * or any ledger balance is negative — the tranche balances are read from
+     * the chain at that block (`userActiveAssets`, one call per tranche), the
+     * tranche's ledger `yieldEarned` moves by the same difference, and the
+     * pool carries `ledgerMismatch`. Unpinned (the node could not serve the
+     * block), only a negative ledger balance is corrected. A pool that agrees
+     * — every ordinary lender — costs nothing extra.
+     *
+     * Lifetime figures stay ledger figures: they cannot tell moved principal
+     * from interest.
+     */
+    private reconcilePool;
+    /**
+     * The last-epoch figures of positions whose newest interest is OLDER than
+     * the recent window. Pools clear independently, and some clear only when
+     * the originator repays, so a pool's last cycle can be weeks back: it is
+     * priced at THAT epoch, from a history read of just those positions over
+     * just those epochs, through the same `positionEpochYield` — so it equals
+     * the history's newest bar.
+     *
+     * A lender who has since left the tranche (no ledger shares now) gets no
+     * figure: an old pool's last cycle is not theirs to show. Costs nothing
+     * when no position qualifies.
+     */
+    private staleLastEpochYields;
     /**
      * A money figure as a plain decimal string. Below a millionth of a token
      * (the stable asset's own precision) is float noise, never money, so it