@kasufinance/kasu-sdk 2.14.0 → 2.16.0

package/src/services/Portfolio/queries.ts

@@ -61,20 +61,47 @@ export const lastEpochQuery = gql`
     }
 `;
 
+/**
+ * The portfolio read. Its last-epoch figures pair each tranche's newest
+ * interest (epoch E) with the shares in force when clearing E applied it —
+ * the selection `getYieldHistory` makes (`positionEpochYield`). For that it
+ * reads, per lender and tranche, the newest share snapshot tagged before
+ * `$recentEpoch` and EVERY snapshot tagged from it on (with their times), and,
+ * for the listed pools (`$poolIds`) and tranches (`$trancheIds`), the
+ * clearings and share exits of those recent epochs. `$recentEpoch` is six
+ * epochs back (`RECENT_PAIRING_EPOCHS`); a newest interest older than that (a
+ * pool that clears rarely) is priced from a history read of its own. Lock
+ * snapshots are read the same way from one epoch further back
+ * (`$lockRecentEpoch`), since a top-up compares E with E − 1. Every list read
+ * with `$first` must come back SHORT of it — a full one is refused, never
+ * used truncated. `_meta` is the block the answer describes: the chain is
+ * read at that same block.
+ */
 export const lendingPortfolioQuery = gql`
     query LastEpochQuery(
         $userAddress: ID!
         $epochId: BigInt!
         $lastEpochId: BigInt!
+        $recentEpoch: BigInt!
+        $lockRecentEpoch: BigInt!
         $unusedPools: [String!]!
+        $poolIds: [String!]!
+        $trancheIds: [String!]!
         $first: Int!
     ) {
+        _meta {
+            block {
+                number
+            }
+        }
         user(id: $userAddress) {
             lendingPoolUserDetails(
                 first: $first
                 where: { lendingPool_not_in: $unusedPools }
             ) {
                 id
+                totalAcceptedDeposits
+                totalAcceptedWithdrawnAmount
                 lendingPool {
                     id
                     name
@@ -84,16 +111,34 @@ export const lendingPortfolioQuery = gql`
                     }
                 }
                 lendingPoolTrancheUserDetails(first: $first) {
+                    id
                     shares
+                    totalAcceptedDeposits
+                    totalAcceptedWithdrawnAmount
                     lendingPoolTrancheUserEpochSharesUpdates(
                         orderDirection: desc
                         orderBy: shareUpdatesIndex
-                        where: { epochId_lt: $epochId }
+                        where: { epochId_lt: $recentEpoch }
                         first: 1
                     ) {
+                        epochId
+                        shareUpdatesIndex
                         shares
+                        timestamp
+                    }
+                    recentUserShareUpdates: lendingPoolTrancheUserEpochSharesUpdates(
+                        orderDirection: desc
+                        orderBy: shareUpdatesIndex
+                        where: { epochId_gte: $recentEpoch }
+                        first: $first
+                    ) {
+                        epochId
+                        shareUpdatesIndex
+                        shares
+                        timestamp
                     }
                     userLendingPoolTrancheFixedTermDepositLocks(first: $first) {
+                        id
                         isLocked
                         unlockAmount
                         initialAmount
@@ -125,6 +170,26 @@ export const lendingPortfolioQuery = gql`
                         ) {
                             shares
                         }
+                        lockSharesBase: userLendingPoolTrancheFixedTermDepositLockShareUpdate(
+                            orderBy: shareUpdatesIndex
+                            orderDirection: desc
+                            first: 1
+                            where: { epochId_lt: $lockRecentEpoch }
+                        ) {
+                            epochId
+                            shareUpdatesIndex
+                            shares
+                        }
+                        lockSharesRecent: userLendingPoolTrancheFixedTermDepositLockShareUpdate(
+                            orderBy: shareUpdatesIndex
+                            orderDirection: desc
+                            first: $first
+                            where: { epochId_gte: $lockRecentEpoch }
+                        ) {
+                            epochId
+                            shareUpdatesIndex
+                            shares
+                        }
                     }
                     tranche {
                         id
@@ -134,9 +199,23 @@ export const lendingPortfolioQuery = gql`
                             first: 1
                             orderBy: shareUpdatesIndex
                             orderDirection: desc
-                            where: { epochId_lt: $epochId }
+                            where: { epochId_lt: $recentEpoch }
                         ) {
+                            epochId
+                            shareUpdatesIndex
                             shares
+                            timestamp
+                        }
+                        recentTrancheShareUpdates: lendingPoolTrancheShareUpdates(
+                            first: $first
+                            orderBy: shareUpdatesIndex
+                            orderDirection: desc
+                            where: { epochId_gte: $recentEpoch }
+                        ) {
+                            epochId
+                            shareUpdatesIndex
+                            shares
+                            timestamp
                         }
                         lendingPoolTrancheEpochInterest(
                             first: 1
@@ -144,12 +223,50 @@ export const lendingPortfolioQuery = gql`
                             orderDirection: desc
                             where: { epochId_lt: $epochId }
                         ) {
+                            epochId
                             epochInterestAmount
                         }
                     }
                 }
             }
         }
+        lendingPoolClearings(
+            first: $first
+            orderBy: id
+            orderDirection: asc
+            where: {
+                lendingPool_in: $poolIds
+                epochId_gte: $recentEpoch
+                epochId_lt: $epochId
+            }
+        ) {
+            id
+            epochId
+            startTimestamp
+            lendingPool {
+                id
+            }
+        }
+        recentWithdrawalsAccepted: userRequestEvents(
+            first: $first
+            orderBy: id
+            orderDirection: asc
+            where: {
+                type_in: [WithdrawalAccepted, ImmediateWithdrawalExecuted]
+                tranche_in: $trancheIds
+                epochId_gte: $recentEpoch
+                epochId_lt: $epochId
+            }
+        ) {
+            id
+            type
+            epochId
+            createdOn
+            sharesAmount
+            tranche {
+                id
+            }
+        }
         userRequests(
             first: $first
             where: {

package/src/services/Portfolio/types.ts

@@ -53,6 +53,12 @@ export interface PortfolioTrancheDepositDetails {
 }
 export interface PortfolioTranche extends TrancheData {
     investedAmount: string;
+    /**
+     * Set when `investedAmount` was raised to 0: the locked amount exceeded
+     * the tranche balance, which only a position the subgraph ledger cannot
+     * describe produces (see `PortfolioLendingPool.ledgerMismatch`).
+     */
+    investedAmountFloored?: true;
     yieldEarnings: {
         lastEpoch: string;
         lifetime: string;
@@ -77,8 +83,36 @@ export interface PortfolioTranche extends TrancheData {
         depositDetails: PortfolioTrancheDepositDetails[];
     }[];
 }
+/**
+ * The subgraph ledger and the chain disagreed about the lender's balance in
+ * a pool AT THE SAME BLOCK — shares moved to or from the wallet outside a
+ * deposit or withdrawal, or a lock whose recorded shares were lost. Balances
+ * then come from the chain; display units of the stable token.
+ */
+export interface LedgerMismatch {
+    /**
+     * `ledger-exceeds-chain`: the ledger credits shares the wallet does not
+     * hold — the pool's last-cycle figures are withheld (0), and
+     * `getYieldHistory` leaves the pool out. `chain-exceeds-ledger`: the
+     * wallet holds shares the ledger never credited — its figures cover only
+     * the ledger's shares.
+     */
+    kind: 'ledger-exceeds-chain' | 'chain-exceeds-ledger';
+    ledgerBalance: string;
+    chainBalance: string;
+}
+
 export interface PortfolioLendingPool extends Omit<PoolOverview, 'tranches'> {
     totalInvestedAmount: string;
+    /** Present only when ledger and chain disagree (see `LedgerMismatch`). */
+    ledgerMismatch?: LedgerMismatch;
+    /**
+     * `false` only when the chain could not be read at the subgraph's block
+     * (the node had pruned it, or not reached it) and `latest` was read
+     * instead: the balances are the chain's now, and ledger and chain were
+     * NOT compared, so no `ledgerMismatch` can be reported. Absent otherwise.
+     */
+    chainPinned?: false;
     totalYieldEarningsLastEpoch: string;
     totalYieldEarningsLifetime: string;
     isActive: boolean;
@@ -89,7 +123,16 @@ export interface LendingPortfolioData {
     lendingPools: PortfolioLendingPool[];
 }
 
+/** A lock share snapshot as the portfolio query reads it. */
+export interface LockShareSnapshot {
+    epochId: string;
+    shareUpdatesIndex: number;
+    shares: string;
+}
+
 export interface UserLendingPoolTrancheFixedTermDepositLock {
+    /** `{lendingPool}-{lockId}`; read by `lendingPortfolioQuery`. */
+    id?: string;
     isLocked: boolean;
     lockId: string;
     createdOn: string;
@@ -120,6 +163,13 @@ export interface UserLendingPoolTrancheFixedTermDepositLock {
               shares: string;
           }[]
         | undefined;
+    /**
+     * The newest lock snapshot tagged before `$lockRecentEpoch`, and every one
+     * tagged from it on: the candidates `getPortfolioLendingData` pairs a
+     * recent interest's epoch with. `lendingPortfolioQuery` responses only.
+     */
+    lockSharesBase?: LockShareSnapshot[] | undefined;
+    lockSharesRecent?: LockShareSnapshot[] | undefined;
 }
 
 export interface LastEpochQueryResult {
@@ -169,10 +219,23 @@ export interface LastEpochQueryResult {
     } | null;
 }
 
+/** A tranche or lender share snapshot as the portfolio query reads it. */
+export interface PortfolioShareSnapshot {
+    epochId: string;
+    shareUpdatesIndex: number;
+    shares: string;
+    /** Unix seconds. */
+    timestamp: string;
+}
+
 export interface LendingPortfolioQueryResult {
+    /** The block the subgraph answered at. */
+    _meta?: { block: { number: number } };
     user: {
         lendingPoolUserDetails: {
             id: string;
+            totalAcceptedDeposits: string;
+            totalAcceptedWithdrawnAmount: string;
             lendingPool: {
                 id: string;
                 name: string;
@@ -188,26 +251,32 @@ export interface LendingPortfolioQueryResult {
                 }[];
             };
             lendingPoolTrancheUserDetails: {
+                id: string;
                 shares: string;
                 userLendingPoolTrancheFixedTermDepositLocks: UserLendingPoolTrancheFixedTermDepositLock[];
+                /** The newest snapshot tagged before `$recentEpoch`. */
                 lendingPoolTrancheUserEpochSharesUpdates:
-                    | {
-                          shares: string;
-                      }[]
+                    | PortfolioShareSnapshot[]
                     | undefined;
+                /** Every snapshot tagged `$recentEpoch` or later. */
+                recentUserShareUpdates: PortfolioShareSnapshot[] | undefined;
                 totalAcceptedDeposits: string;
                 totalAcceptedWithdrawnAmount: string;
                 tranche: {
                     id: string;
                     shares: string;
                     balance: string;
+                    /** The newest snapshot tagged before `$recentEpoch`. */
                     lendingPoolTrancheShareUpdates:
-                        | {
-                              shares: string;
-                          }[]
+                        | PortfolioShareSnapshot[]
+                        | undefined;
+                    /** Every snapshot tagged `$recentEpoch` or later. */
+                    recentTrancheShareUpdates:
+                        | PortfolioShareSnapshot[]
                         | undefined;
                     lendingPoolTrancheEpochInterest:
                         | {
+                              epochId: string;
                               epochInterestAmount: string;
                           }[]
                         | undefined;
@@ -215,6 +284,22 @@ export interface LendingPortfolioQueryResult {
             }[];
         }[];
     } | null;
+    /** The clearings of `$recentEpoch` up to the last settled epoch. */
+    lendingPoolClearings: {
+        id: string;
+        epochId: string;
+        startTimestamp: string;
+        lendingPool: { id: string };
+    }[];
+    /** Every share exit (any lender) in the listed tranches, those epochs. */
+    recentWithdrawalsAccepted: {
+        id: string;
+        type: 'WithdrawalAccepted' | 'ImmediateWithdrawalExecuted';
+        epochId: string;
+        createdOn: string;
+        sharesAmount: string | null;
+        tranche: { id: string };
+    }[];
     userRequests: {
         createdOn: string;
         amountAccepted: string;