@kasufinance/kasu-sdk 2.15.0 → 2.17.0

package/dist/domain/index.d.ts

@@ -64,5 +64,5 @@ export { combineTvlHistories, poolTvl, TvlHistoryInputError } from './pool-tvl';
 export type { PoolTvlHistoryEntry, StrategyTvlHistoryEntry, TvlHistoryInputErrorCode, TvlHistoryLeg, } from './pool-tvl';
 export { aggregateYieldHistory, epochTrancheYield } from './yield-history';
 export type { EpochLockShares, EpochTrancheYield, EpochTrancheYieldInput, YieldHistoryEntry, YieldHistoryFilter, YieldHistoryPoint, } from './yield-history';
-export { accruedInterest, dailyInterest, projectedAnnualEarnings, SECONDS_PER_WEEK, weeklyInterest, weightedAverageApy, } from './yields';
-export type { InterestSlice, PoolAccrual } from './yields';
+export { accruedInterest, accruedInterestSince, dailyInterest, epochAccrual, epochEndTimestamp, MAX_ACCRUAL_EPOCHS, projectedAnnualEarnings, SECONDS_PER_WEEK, weeklyInterest, weightedAverageApy, } from './yields';
+export type { EpochAccrual, InterestSlice, PoolAccrual } from './yields';

package/dist/domain/index.js

@@ -46,5 +46,5 @@ export { compareTrancheSeniority, derivePoolStatus, MIN_TRANCHE_CAPACITY, netTra
 export { classifyWalletFailure, isUnpredictableGas, isUserRejected, } from './wallet-errors';
 export { combineTvlHistories, poolTvl, TvlHistoryInputError } from './pool-tvl';
 export { aggregateYieldHistory, epochTrancheYield } from './yield-history';
-export { accruedInterest, dailyInterest, projectedAnnualEarnings, SECONDS_PER_WEEK, weeklyInterest, weightedAverageApy, } from './yields';
+export { accruedInterest, accruedInterestSince, dailyInterest, epochAccrual, epochEndTimestamp, MAX_ACCRUAL_EPOCHS, projectedAnnualEarnings, SECONDS_PER_WEEK, weeklyInterest, weightedAverageApy, } from './yields';
 //# sourceMappingURL=index.js.map

package/dist/domain/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/domain/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/domain/index.ts"],"names":[],"mappings":"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"}

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":"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"}

package/dist/domain/yields.d.ts

@@ -18,6 +18,16 @@
  * window, and the accrual spreads an epoch's interest across it.
  */
 export declare const SECONDS_PER_WEEK = 604800;
+/**
+ * The most unpaid interest {@link accruedInterestSince} shows for one pool:
+ * this many epochs of its weekly figure (owner ruling 2026-11-07).
+ *
+ * A pool can stop being cleared without being flagged stopped. On Base, one
+ * pool is more than six epochs behind and another more than a hundred.
+ * Uncapped, the figure would show interest that may never be credited. Four
+ * epochs covers any ordinary late clearing.
+ */
+export declare const MAX_ACCRUAL_EPOCHS = 4;
 /** One slice of a position that earns at a single rate. */
 export interface InterestSlice {
     /** The lender's current balance in this slice, in stable display units. */
@@ -34,13 +44,41 @@ export interface InterestSlice {
      */
     epochRate: number;
 }
-/** One pool's contribution to the current cycle's accrual. */
+/**
+ * One pool's contribution to the current cycle's accrual, anchored on its
+ * last clearing TRANSACTION.
+ *
+ * @deprecated Use {@link EpochAccrual} with {@link accruedInterestSince}. A
+ * clearing transaction's timestamp is the wrong anchor: see `accruedInterest`.
+ */
 export interface PoolAccrual {
     /** That pool's projected net interest for one epoch (`weeklyInterest`). */
     weeklyInterest: number;
     /** Unix SECONDS at which THAT pool last cleared a cycle. */
     clearingTimestamp: number;
 }
+/**
+ * One pool's contribution to the unpaid interest — the input of
+ * {@link accruedInterestSince}. Build it with {@link epochAccrual}, which
+ * validates every field and derives the two timestamps; do not assemble one
+ * by hand.
+ */
+export interface EpochAccrual {
+    /** That pool's projected net interest for one epoch (`weeklyInterest`). */
+    weeklyInterest: number;
+    /**
+     * Unix SECONDS from which the pool's unpaid interest accrues: the earlier
+     * of the moment its last clearing STARTED and `epochEnd`. Never after
+     * `epochEnd`.
+     */
+    accruesFrom: number;
+    /**
+     * Unix SECONDS at which the pool's last cleared epoch ENDS
+     * (`epochEndTimestamp(initialEpochStart, lastClearedEpoch)`). The accrual
+     * holds from `accruesFrom + 604 800` until `epochEnd + 604 800`.
+     */
+    epochEnd: number;
+}
 /**
  * Interest the slices accrue over ONE epoch, net of the fee.
  *
@@ -72,30 +110,177 @@ export declare function weeklyInterest(slices: readonly InterestSlice[], feePerc
  */
 export declare function dailyInterest(weekly: number | null): number | null;
 /**
- * Interest accrued since each pool's OWN last cycle close — the moving part
- * of lifetime interest (lifetime = settled on chain + this).
+ * Interest accrued since each pool's OWN last clearing transaction, capped at
+ * one epoch per pool.
  *
  * ```
  * accrued = Σ_pool  weekly_pool × clamp(now − clearing_pool, 0, 604 800) / 604 800
  * ```
  *
- * **Per pool, because pools clear independently.** One shared anchor accrues
- * a stale pool's share from a close it never had, and when another pool
- * clears it drops the total by the stale pool's whole weekly share. Anchored
- * per pool, the total is monotonic across any single pool's clearing: that
- * pool swaps its accrued share for a capitalised one, and no other term moves.
+ * Per pool, because pools clear independently: one shared anchor accrues a
+ * stale pool's share from a close it never had, and when another pool clears
+ * it drops the total by the stale pool's whole weekly share.
  *
- * **The one-epoch cap is load-bearing.** Clearings are not exactly weekly,
- * and `weeklyInterest` is per EPOCH, so extrapolating past seven days would
- * promise interest the close will not credit; a late clearing under-reports
- * instead. The low clamp makes a close ahead of the local clock zero, never
- * negative.
+ * **The one-epoch cap rested on a wrong premise.** It assumed a late
+ * clearing credits only one epoch, so accruing past seven days would promise
+ * interest no close pays. The contracts say otherwise. `ClearingCoordinator`
+ * states that clearing "must be executed once per epoch for each lending
+ * pool" and that "clearing epochs must be executed in order"; `doClearing`
+ * reverts unless the target epoch is the pool's `nextLendingPoolClearingEpoch`,
+ * and it calls `LendingPool.applyInterests(targetEpoch)` on every clearing,
+ * late or not ("if clearing for the epoch is executed only after the clearing
+ * period, only yield will be applied"). Every missed epoch's interest is
+ * therefore credited when the clearings catch up — on Base, one pool cleared
+ * epochs 116 to 119 in the same block, four weeks credited at once.
+ * Capped, the figure freezes as soon as a clearing is a week late; anchored
+ * on the transaction, it also DIPS on a catch-up (elapsed resets to zero
+ * while only one week is credited per clearing).
  *
+ * The low clamp makes a close ahead of the local clock zero, never negative.
  * A non-finite term contributes nothing; a non-finite `nowSeconds` accrues
- * nothing. Callers fail closed upstream by not offering an accrual for a pool
- * whose weekly interest or anchor is unknown.
+ * nothing.
+ *
+ * @deprecated Use {@link accruedInterestSince} with {@link epochAccrual}:
+ * identical while clearings run on time, and it keeps accruing, up to four
+ * epochs, when they run late. Kept, behaviour-identical, for existing
+ * callers.
  */
 export declare function accruedInterest(accruals: readonly PoolAccrual[], nowSeconds: number): number;
+/**
+ * Unix SECONDS at which `epoch` ENDS — the start of the next one:
+ *
+ * ```
+ * epochEnd(e) = initialEpochStart + (e + 1) × 604 800
+ * ```
+ *
+ * `SystemVariables.epochStartTimestamp(e)` is `initial + e × EPOCH_DURATION`,
+ * and the initial start is written once, at initialisation, so the end of any
+ * epoch follows from `epochStartTimestamp(0)` with no further read.
+ *
+ * FAILS CLOSED with `NaN`: a non-integer, non-finite or negative epoch, an
+ * initial start that is not a positive integer, or a result past
+ * `Number.MAX_SAFE_INTEGER`.
+ *
+ * @param initialEpochStart unix seconds, `epochStartTimestamp(0)`.
+ * @param epoch the epoch number, 0-based.
+ */
+export declare function epochEndTimestamp(initialEpochStart: number, epoch: number): number;
+/**
+ * Builds one pool's {@link EpochAccrual} from what the chain and the subgraph
+ * say about its last clearing:
+ *
+ * ```
+ * epochEnd    = epochEndTimestamp(initialEpochStart, lastClearedEpoch)
+ * accruesFrom = min(clearingStartedAt, epochEnd)
+ * ```
+ *
+ * - **On time** (the clearing started inside its window, before its epoch
+ *   ended): `accruesFrom` is the clearing's start. Clearing applies the
+ *   epoch's interest first and only then accepts requests, so today's
+ *   balance — which includes a deposit that clearing accepted — is never
+ *   charged for time before it: a new lender starts at exactly 0.
+ * - **Late** (it started at or after its epoch end): `accruesFrom` is the
+ *   epoch end. A late clearing accepts no requests and credits exactly one
+ *   epoch, so the time it did not credit is kept.
+ *
+ * `lastClearedEpoch` is the newest epoch whose clearing has STARTED (the
+ * subgraph has a `LendingPoolClearing` for it), not the newest that has
+ * finished, and `clearingStartedAt` is that clearing's `startTimestamp`.
+ * `ClearingCoordinator.doClearing` mints the epoch's interest in its FIRST
+ * transaction (`applyInterests`), while `nextLendingPoolClearingEpoch` only
+ * advances when the clearing ENDS, so it is the wrong source.
+ *
+ * FAILS CLOSED with `null`: whatever {@link epochEndTimestamp} rejects, a
+ * `clearingStartedAt` that is not a finite positive number, or a
+ * `weeklyInterest` that is not finite or is negative. The caller then offers
+ * no term for that pool.
+ *
+ * @param input.weeklyInterest the pool's net interest for one epoch.
+ * @param input.initialEpochStart unix seconds, `epochStartTimestamp(0)`.
+ * @param input.lastClearedEpoch the newest epoch whose clearing has started.
+ * @param input.clearingStartedAt unix seconds, that clearing's start.
+ */
+export declare function epochAccrual(input: {
+    weeklyInterest: number;
+    initialEpochStart: number;
+    lastClearedEpoch: number;
+    clearingStartedAt: number;
+}): EpochAccrual | null;
+/**
+ * Interest accrued and not yet credited — the moving part of lifetime
+ * interest (lifetime = settled on chain + this). Per term, with
+ * `W` = 604 800 s:
+ *
+ * ```
+ * accrued = min( weekly × ( min(max(now − accruesFrom, 0), W)
+ *                         + max(now − (epochEnd + W), 0) ) / W,
+ *                MAX_ACCRUAL_EPOCHS × weekly )
+ * ```
+ *
+ * Read along the clock, for one pool:
+ * 1. from `accruesFrom`, one epoch of interest accrues linearly;
+ * 2. it then HOLDS from `accruesFrom + W` until `epochEnd + W`, the end of
+ *    the next epoch — at most 48 h after an on-time clearing (its clearing
+ *    window), no time at all after a late one (`accruesFrom == epochEnd`);
+ * 3. then it resumes, up to {@link MAX_ACCRUAL_EPOCHS} (4) epochs of
+ *    `weekly` in all, and stops there.
+ *
+ * **Why it keeps accruing past one epoch.** Clearing must run once per
+ * epoch for each pool, in order (`ClearingCoordinator.doClearing` reverts
+ * unless the target epoch is the pool's `nextLendingPoolClearingEpoch`), and
+ * every clearing, on time or late, starts with
+ * `LendingPool.applyInterests(targetEpoch)`. A missed epoch is therefore
+ * credited when the clearings catch up (on Base, one pool cleared epochs 116
+ * to 119 in the same block).
+ *
+ * **Why it stops at four epochs** (owner ruling 2026-11-07). A pool can stop
+ * being cleared without being flagged stopped. On Base today one pool is
+ * more than six epochs behind and another more than a hundred. Past four
+ * epochs the figure would show interest that may never be credited. Four
+ * covers any ordinary late clearing.
+ *
+ * **Why the hold.** Without it an on-time anchor accrues past one epoch
+ * while the next on-time clearing — which credits exactly one — is still to
+ * come, and the total steps DOWN when it lands. With it, at a constant
+ * balance, `settled + accrued` never steps down at a clearing (`t` = the
+ * NEW clearing's start, `E` = the end of the epoch it clears):
+ * - on time after on time: identical to the deprecated `accruedInterest`
+ *   at every instant. With `gap` = `t` − the previous clearing's start, it
+ *   steps UP by `weekly × (W − gap) / W` when `gap < W` (at most 2/7 of one
+ *   weekly, as before), and not at all when `gap ≥ W`;
+ * - late after on time, and late after late: exactly continuous;
+ * - on time after late: steps UP by `weekly × (E − t) / W`, at most 2/7 of
+ *   one weekly.
+ * A deposit or top-up accepted at an on-time clearing starts at 0, so it
+ * never dips the total either.
+ *
+ * **At the cap.** All of the above holds for a pool below the cap, where
+ * the cap changes nothing. A pool AT the cap shows `4 × weekly` before a
+ * catch-up clearing; after it, one more `weekly` is settled and the new term
+ * shows `min(elapsed′, 4 × weekly)`, so `after = min(elapsed′ + weekly,
+ * 5 × weekly) ≥ before`. Each clearing steps the total UP by at most one
+ * weekly until the pool is back under the cap. Never down, and never above
+ * settled plus `4 × weekly` per pool.
+ *
+ * **Never negative**, and non-decreasing in `now`. A term is skipped — it
+ * contributes nothing — when `weeklyInterest` is not finite or is negative,
+ * when `accruesFrom` or `epochEnd` is not finite, when `accruesFrom >
+ * epochEnd` (inconsistent: the anchor is never after the epoch end), or when
+ * an elapsed time overflows. A non-finite `nowSeconds` accrues nothing.
+ *
+ * **Per pool, because pools clear independently.** One shared anchor accrues
+ * a stale pool's share from a close it never had.
+ *
+ * **Accepted approximation.** `weekly` is today's balance at today's epoch
+ * rate. Over a multi-week gap the chain compounds weekly and may apply other
+ * epochs' rates, so a long accrual reads slightly LOW. It is a ticking
+ * estimate, not a ledger.
+ *
+ * Callers fail closed upstream: no term for a pool whose weekly interest or
+ * clearing is unknown (`epochAccrual` returns `null`), and none for a pool
+ * that has stopped — it will never clear again.
+ */
+export declare function accruedInterestSince(accruals: readonly EpochAccrual[], nowSeconds: number): number;
 /**
  * What `amount` earns in a year at a NET rate — the "≈ $Y a year" line.
  * Feed it `netEffectiveApy(...)`, never a gross APY: the result is a lender's