@mento-protocol/mento-sdk 3.2.0 → 3.2.2-beta0

package/dist/services/borrow/BorrowService.d.ts

@@ -6,16 +6,18 @@ import { AdjustTroveParams, BorrowPosition, CallParams, InterestRateBracket, Ope
  * handle interest rates and batch managers, and query position data.
  *
  * All `build*` methods return `CallParams` ({ to, data, value }) that can be
- * executed with any wallet client. The `debtTokenSymbol` parameter (e.g., 'USDm')
+ * executed with any wallet client. The `debtTokenSymbol` parameter (e.g., 'GBPm')
  * identifies which borrowing deployment to interact with.
  *
  * @example
  * ```typescript
  * const mento = await Mento.create(ChainId.CELO)
  *
+ * const ownerIndex = await mento.borrow.findNextAvailableOwnerIndex('GBPm', '0x...', '0x...')
+ *
  * // Open a trove
- * const tx = await mento.borrow.buildOpenTroveTransaction('USDm', {
- *   owner: '0x...', ownerIndex: 0,
+ * const tx = await mento.borrow.buildOpenTroveTransaction('GBPm', {
+ *   owner: '0x...', ownerIndex,
  *   collAmount: parseUnits('10', 18),
  *   boldAmount: parseUnits('1000', 18),
  *   annualInterestRate: parseUnits('0.05', 18),
@@ -34,7 +36,7 @@ export declare class BorrowService {
      * Builds a transaction to open a new trove (borrowing position).
      * Requires prior collateral approval via `buildCollateralApprovalParams`.
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @param params - Trove opening parameters including collateral, debt amount, and interest rate
      * @returns Transaction parameters ready to send
      */
@@ -42,16 +44,19 @@ export declare class BorrowService {
     /**
      * Builds a transaction to adjust an existing trove's collateral and/or debt.
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @param params - Adjustment parameters specifying collateral/debt changes
      * @returns Transaction parameters ready to send
      */
     buildAdjustTroveTransaction(debtTokenSymbol: string, params: AdjustTroveParams): Promise<CallParams>;
     /**
-     * Builds a transaction to adjust a zombie trove (a trove that fell below minimum debt
-     * after a liquidation). Same parameters as `buildAdjustTroveTransaction`.
+     * Builds a transaction to adjust a zombie trove. Zombie troves are still-open troves whose
+     * debt fell below the branch minimum debt, typically after a redemption.
+     *
+     * Use this when `getTroveData()` or `getUserTroves()` returns `status === 'zombie'`.
+     * Same parameters as `buildAdjustTroveTransaction`.
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @param params - Adjustment parameters specifying collateral/debt changes
      * @returns Transaction parameters ready to send
      */
@@ -59,7 +64,7 @@ export declare class BorrowService {
     /**
      * Builds a transaction to close a trove, repaying all debt and reclaiming collateral.
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @param troveId - The NFT token ID identifying the trove
      * @returns Transaction parameters ready to send
      */
@@ -68,7 +73,7 @@ export declare class BorrowService {
      * Builds a transaction to add collateral to an existing trove.
      * Requires prior collateral approval via `buildCollateralApprovalParams`.
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @param troveId - The NFT token ID identifying the trove
      * @param amount - Amount of collateral to add (in wei)
      * @returns Transaction parameters ready to send
@@ -77,7 +82,7 @@ export declare class BorrowService {
     /**
      * Builds a transaction to withdraw collateral from an existing trove.
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @param troveId - The NFT token ID identifying the trove
      * @param amount - Amount of collateral to withdraw (in wei)
      * @returns Transaction parameters ready to send
@@ -86,7 +91,7 @@ export declare class BorrowService {
     /**
      * Builds a transaction to borrow additional debt against an existing trove.
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @param troveId - The NFT token ID identifying the trove
      * @param amount - Additional debt amount to borrow (in wei)
      * @param maxFee - Maximum upfront fee the borrower is willing to pay (in wei)
@@ -96,7 +101,7 @@ export declare class BorrowService {
     /**
      * Builds a transaction to repay debt on an existing trove.
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @param troveId - The NFT token ID identifying the trove
      * @param amount - Amount of debt to repay (in wei)
      * @returns Transaction parameters ready to send
@@ -105,7 +110,7 @@ export declare class BorrowService {
     /**
      * Builds a transaction to change the annual interest rate on a trove.
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @param troveId - The NFT token ID identifying the trove
      * @param newRate - New annual interest rate (18-decimal fixed-point, e.g., parseUnits('0.05', 18) for 5%)
      * @param maxFee - Maximum upfront fee the borrower is willing to pay (in wei)
@@ -114,15 +119,17 @@ export declare class BorrowService {
     buildAdjustInterestRateTransaction(debtTokenSymbol: string, troveId: string, newRate: bigint, maxFee: bigint): Promise<CallParams>;
     /**
      * Builds a transaction to claim collateral surplus after a liquidation.
+     * This is for collateral held in the surplus pool after `closedByLiquidation`.
+     * Zombie troves with remaining collateral should usually be closed or adjusted instead.
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @returns Transaction parameters ready to send
      */
     buildClaimCollateralTransaction(debtTokenSymbol: string): Promise<CallParams>;
     /**
      * Builds a transaction to delegate interest rate management to a batch manager.
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @param troveId - The NFT token ID identifying the trove
      * @param manager - Address of the batch manager contract
      * @param maxFee - Maximum upfront fee the borrower is willing to pay (in wei)
@@ -132,7 +139,7 @@ export declare class BorrowService {
     /**
      * Builds a transaction to remove a trove from a batch manager, setting a new individual rate.
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @param troveId - The NFT token ID identifying the trove
      * @param newRate - New individual annual interest rate (18-decimal fixed-point)
      * @param maxFee - Maximum upfront fee the borrower is willing to pay (in wei)
@@ -142,7 +149,7 @@ export declare class BorrowService {
     /**
      * Builds a transaction to switch a trove to a different batch manager.
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @param troveId - The NFT token ID identifying the trove
      * @param newManager - Address of the new batch manager contract
      * @param maxFee - Maximum upfront fee the borrower is willing to pay (in wei)
@@ -153,7 +160,7 @@ export declare class BorrowService {
      * Builds a transaction to delegate interest rate management to another address
      * with bounded rate constraints.
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @param troveId - The NFT token ID identifying the trove
      * @param delegate - Address to delegate interest rate management to
      * @param minRate - Minimum allowed annual interest rate (18-decimal fixed-point)
@@ -167,7 +174,7 @@ export declare class BorrowService {
     /**
      * Builds a transaction to remove the interest rate delegate from a trove.
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @param troveId - The NFT token ID identifying the trove
      * @returns Transaction parameters ready to send
      */
@@ -176,7 +183,7 @@ export declare class BorrowService {
      * Builds approval params to allow BorrowerOperations to spend collateral tokens.
      * Must be executed before `buildOpenTroveTransaction` or `buildAddCollTransaction`.
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @param amount - Amount of collateral to approve (in wei)
      * @returns Transaction parameters for the ERC-20 approve call
      */
@@ -184,7 +191,7 @@ export declare class BorrowService {
     /**
      * Builds approval params for the debt token (e.g., for repayment or closing).
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @param spender - Address to approve as spender
      * @param amount - Amount of debt tokens to approve (in wei)
      * @returns Transaction parameters for the ERC-20 approve call
@@ -193,7 +200,7 @@ export declare class BorrowService {
     /**
      * Builds approval params for the gas compensation token (required when opening a trove).
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @param amount - Amount to approve (in wei). If omitted, approves the gas compensation amount.
      * @returns Transaction parameters for the ERC-20 approve call
      */
@@ -201,7 +208,7 @@ export declare class BorrowService {
     /**
      * Gets the current collateral token allowance for BorrowerOperations.
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @param owner - Address to check allowance for
      * @returns Current allowance in wei
      */
@@ -209,7 +216,7 @@ export declare class BorrowService {
     /**
      * Gets the current debt token allowance for a specific spender.
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @param owner - Address to check allowance for
      * @param spender - Address of the approved spender
      * @returns Current allowance in wei
@@ -218,31 +225,36 @@ export declare class BorrowService {
     /**
      * Gets the current gas compensation token allowance.
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @param owner - Address to check allowance for
      * @returns Current allowance in wei
      */
     getGasTokenAllowance(debtTokenSymbol: string, owner: string): Promise<bigint>;
     /**
      * Fetches on-chain data for a specific trove.
+     * The returned position reflects the trove's current lifecycle status, including
+     * zombie troves that may still hold collateral even when their debt is zero.
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @param troveId - The NFT token ID identifying the trove
      * @returns Trove position data including collateral, debt, interest rate, and status
      */
     getTroveData(debtTokenSymbol: string, troveId: string): Promise<BorrowPosition>;
     /**
-     * Fetches all troves owned by an address.
+     * Fetches troves currently owned by an address via the Trove NFT.
+     * This includes zombie troves that have been removed from `SortedTroves` but are still owned
+     * by the address. Closed or liquidated troves are not returned once their Trove NFT is burned
+     * or transferred away.
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @param owner - Address to query troves for
-     * @returns Array of trove positions owned by the address
+     * @returns Array of trove positions currently owned by the address
      */
     getUserTroves(debtTokenSymbol: string, owner: string): Promise<BorrowPosition[]>;
     /**
      * Gets the current collateral token price from the price feed.
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @returns Collateral price in 18-decimal fixed-point format
      */
     getCollateralPrice(debtTokenSymbol: string): Promise<bigint>;
@@ -250,21 +262,21 @@ export declare class BorrowService {
      * Gets the system parameters for a borrowing deployment.
      * Returns MCR, CCR, SCR, BCR, minimum debt, gas compensation, and minimum interest rate.
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @returns System parameters (all values in 18-decimal fixed-point)
      */
     getSystemParams(debtTokenSymbol: string): Promise<SystemParams>;
     /**
      * Checks whether the borrowing system has been shut down (e.g., during a crisis).
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @returns true if the system is shut down, false otherwise
      */
     isSystemShutDown(debtTokenSymbol: string): Promise<boolean>;
     /**
      * Gets aggregate collateral and debt statistics for the borrowing branch.
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @returns Total collateral and total debt across all troves (in wei)
      */
     getBranchStats(debtTokenSymbol: string): Promise<{
@@ -274,21 +286,21 @@ export declare class BorrowService {
     /**
      * Gets the distribution of debt across interest rate brackets.
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @returns Array of brackets, each with a rate and total debt at that rate
      */
     getInterestRateBrackets(debtTokenSymbol: string): Promise<InterestRateBracket[]>;
     /**
      * Gets the weighted average interest rate across all active troves.
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @returns Average annual interest rate in 18-decimal fixed-point
      */
     getAverageInterestRate(debtTokenSymbol: string): Promise<bigint>;
     /**
      * Gets information about a batch manager's configuration.
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @param address - Address of the batch manager
      * @returns Batch manager config (min/max rate, min change period), or null if not a valid manager
      */
@@ -300,7 +312,7 @@ export declare class BorrowService {
     /**
      * Estimates the upfront fee for opening a new trove.
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @param amount - Debt amount to borrow (in wei)
      * @param rate - Annual interest rate (18-decimal fixed-point)
      * @returns Estimated upfront fee in wei
@@ -309,7 +321,7 @@ export declare class BorrowService {
     /**
      * Estimates the upfront fee for increasing debt on an existing trove.
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @param troveId - The NFT token ID identifying the trove
      * @param debtIncrease - Amount of additional debt (in wei)
      * @returns Estimated upfront fee in wei
@@ -318,7 +330,7 @@ export declare class BorrowService {
     /**
      * Estimates the upfront fee for changing a trove's interest rate.
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @param troveId - The NFT token ID identifying the trove
      * @param newRate - New annual interest rate (18-decimal fixed-point)
      * @returns Estimated upfront fee in wei
@@ -327,19 +339,40 @@ export declare class BorrowService {
     /**
      * Estimates the upfront fee for joining a batch manager.
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @param troveId - The NFT token ID identifying the trove
      * @param batchAddress - Address of the batch manager to join
      * @returns Estimated upfront fee in wei
      */
     predictJoinBatchUpfrontFee(debtTokenSymbol: string, troveId: string, batchAddress: string): Promise<bigint>;
     /**
-     * Gets the next available owner index for opening a new trove.
-     * Each owner can have multiple troves, indexed starting from 0.
+     * Gets the current number of troves owned by an address via the Trove NFT.
+     *
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
+     * @param owner - Address of the trove owner
+     * @returns The number of troves currently owned by the address
+     */
+    getOwnedTroveCount(debtTokenSymbol: string, owner: string): Promise<number>;
+    /**
+     * Finds the first safe owner index for opening a trove with the given transaction sender.
+     *
+     * The `opener` must be the address that will call BorrowerOperations on-chain.
+     * For smart accounts, pass the smart account address rather than the controlling EOA.
+     *
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
+     * @param owner - Address that will own the trove NFT
+     * @param opener - Address that will submit the open-trove transaction on-chain
+     * @returns The first owner index that does not already map to an existing trove
+     */
+    findNextAvailableOwnerIndex(debtTokenSymbol: string, owner: string, opener: string): Promise<number>;
+    /**
+     * Gets the current number of troves owned by an address via the Trove NFT.
+     *
+     * @deprecated Use `findNextAvailableOwnerIndex` when preparing an open-trove transaction.
      *
-     * @param debtTokenSymbol - The debt token symbol (e.g., 'USDm')
+     * @param debtTokenSymbol - The debt token symbol (e.g., 'GBPm')
      * @param owner - Address of the trove owner
-     * @returns The next available index (pass to OpenTroveParams.ownerIndex)
+     * @returns The number of troves currently owned by the address
      */
     getNextOwnerIndex(debtTokenSymbol: string, owner: string): Promise<number>;
     private withContext;