@mento-protocol/mento-sdk 3.2.7 → 3.2.8

package/dist/esm/services/borrow/borrowMath.js

@@ -0,0 +1,127 @@
+import { MAX_LTV_ALLOWED_RATIO, LTV_RISK_MEDIUM, LTV_RISK_HIGH, REDEMPTION_RISK_MEDIUM, REDEMPTION_RISK_LOW, } from '../../core/constants';
+const DECIMAL_PRECISION = 10n ** 18n;
+const THOUSAND = 1000n;
+const NORMALIZED_MAX_LTV = DECIMAL_PRECISION;
+const DEBT_SUGGESTION_RATIOS = [300n, 600n, 800n];
+export function getLtv(collateral, debt, collPrice) {
+    const collateralUsd = (collateral * collPrice) / DECIMAL_PRECISION;
+    if (collateralUsd === 0n)
+        return null;
+    return (debt * DECIMAL_PRECISION) / collateralUsd;
+}
+export function getLiquidationPrice(collateral, debt, mcr) {
+    if (collateral <= 0n || debt <= 0n)
+        return null;
+    if (mcr <= DECIMAL_PRECISION)
+        return null;
+    // liquidationPrice = (debt * mcr) / collateral
+    return (debt * mcr) / collateral;
+}
+export function getLiquidationRisk(ltv, maxLtv) {
+    if (maxLtv <= 0n)
+        return 'low';
+    // Compare using cross-multiplication to avoid floor-division drift.
+    if (ltv * THOUSAND > maxLtv * LTV_RISK_HIGH)
+        return 'high';
+    if (ltv * THOUSAND > maxLtv * LTV_RISK_MEDIUM)
+        return 'medium';
+    return 'low';
+}
+export function getRedemptionRisk(debtInFront, totalDebt) {
+    if (totalDebt === 0n)
+        return null;
+    // Compare using cross-multiplication to avoid floor-division drift.
+    if (debtInFront * THOUSAND > totalDebt * REDEMPTION_RISK_LOW)
+        return 'low';
+    if (debtInFront * THOUSAND > totalDebt * REDEMPTION_RISK_MEDIUM)
+        return 'medium';
+    return 'high';
+}
+export function calculateMaxDebt(collateralUsd, maxLtv) {
+    return (collateralUsd * maxLtv) / DECIMAL_PRECISION;
+}
+export function calculateDebtSuggestions(maxDebt, minDebt) {
+    if (maxDebt <= 0n)
+        return [];
+    const suggestions = [];
+    for (let i = 0; i < DEBT_SUGGESTION_RATIOS.length; i++) {
+        let amount = (maxDebt * DEBT_SUGGESTION_RATIOS[i]) / THOUSAND;
+        // Mirror frontend behavior:
+        // - First suggestion is clamped up to minDebt.
+        // - Later suggestions below minDebt are omitted.
+        if (amount < minDebt) {
+            if (i === 0) {
+                amount = minDebt;
+            }
+            else {
+                continue;
+            }
+        }
+        // ltv relative to maxLtv (normalized to 1e18 where 1e18 === maxLtv)
+        const ltv = (amount * DECIMAL_PRECISION) / maxDebt;
+        // Hide suggestions that exceed maxLtv.
+        if (ltv > NORMALIZED_MAX_LTV) {
+            continue;
+        }
+        suggestions.push({
+            amount,
+            ltv,
+            risk: getLiquidationRisk(ltv, NORMALIZED_MAX_LTV),
+        });
+    }
+    return suggestions;
+}
+/**
+ * Computes collateralization metrics from the supplied collateral, debt, price, and MCR.
+ *
+ * This helper is lifecycle-agnostic: it does not inspect trove status. For example, a zombie
+ * trove with `debt === 0` may still hold collateral on-chain, but this function only reports
+ * the math implied by the inputs. Combine its output with `BorrowPosition.status` when building
+ * UI for open, zombie, closed, or liquidated troves.
+ */
+export function getLoanDetails(collateral, debt, interestRate, collPrice, mcr) {
+    // maxLtv = 1 / MCR (MCR is e.g. 1.1e18 meaning 110%)
+    const maxLtv = (DECIMAL_PRECISION * DECIMAL_PRECISION) / mcr;
+    // maxLtvAllowed = maxLtv * MAX_LTV_ALLOWED_RATIO / 1000
+    const maxLtvAllowed = (maxLtv * MAX_LTV_ALLOWED_RATIO) / THOUSAND;
+    const collateralUsd = collateral !== null && collPrice !== null
+        ? (collateral * collPrice) / DECIMAL_PRECISION
+        : null;
+    const ltv = debt !== null && collateralUsd !== null && collateralUsd > 0n
+        ? (debt * DECIMAL_PRECISION) / collateralUsd
+        : collateral !== null && collateral < 0n
+            ? DECIMAL_PRECISION
+            : null;
+    const status = ltv === null
+        ? null
+        : collateral !== null && (collateral < 0n || ltv > DECIMAL_PRECISION)
+            ? 'underwater'
+            : ltv > maxLtv
+                ? 'liquidatable'
+                : ltv > maxLtvAllowed
+                    ? 'at-risk'
+                    : 'healthy';
+    const maxDebt = collateralUsd !== null ? calculateMaxDebt(collateralUsd, maxLtv) : null;
+    const maxDebtAllowed = collateralUsd !== null && collateralUsd > 0n
+        ? (collateralUsd * maxLtvAllowed) / DECIMAL_PRECISION
+        : null;
+    const liquidationRisk = ltv !== null ? getLiquidationRisk(ltv, maxLtv) : null;
+    const liquidationPrice = collateral !== null && debt !== null && collateral > 0n
+        ? getLiquidationPrice(collateral, debt, mcr)
+        : null;
+    return {
+        collateral,
+        collateralUsd,
+        collPrice,
+        debt,
+        interestRate,
+        ltv,
+        maxLtv,
+        maxLtvAllowed,
+        liquidationPrice,
+        liquidationRisk,
+        maxDebt,
+        maxDebtAllowed,
+        status,
+    };
+}

package/dist/esm/services/borrow/index.js

@@ -0,0 +1,3 @@
+export * from './BorrowService';
+export * from './borrowHelpers';
+export * from './borrowMath';

package/dist/esm/services/borrow/internal/borrowApprovalService.js

@@ -0,0 +1,48 @@
+import { encodeFunctionData } from 'viem';
+import { ERC20_ABI } from '../../../core/abis';
+import { buildErc20ApprovalParams, readErc20Allowance } from './borrowErc20';
+import { requireAddress, requireNonNegativeBigInt } from './borrowValidation';
+const ZERO_VALUE = '0';
+export class BorrowApprovalService {
+    constructor(publicClient) {
+        this.publicClient = publicClient;
+    }
+    buildCollateralApprovalParams(ctx, amount) {
+        const approvalAmount = requireNonNegativeBigInt(amount, 'amount');
+        return buildErc20ApprovalParams(ctx.addresses.collToken, ctx.addresses.borrowerOperations, approvalAmount);
+    }
+    buildDebtApprovalParams(ctx, spender, amount) {
+        const spenderAddress = requireAddress(spender, 'spender');
+        const approvalAmount = requireNonNegativeBigInt(amount, 'amount');
+        const data = encodeFunctionData({
+            abi: ERC20_ABI,
+            functionName: 'approve',
+            args: [spenderAddress, approvalAmount],
+        });
+        return { to: ctx.addresses.debtToken, data, value: ZERO_VALUE };
+    }
+    buildGasCompensationApprovalParams(ctx, amount) {
+        const approvalAmount = amount === undefined
+            ? ctx.systemParams.ethGasCompensation
+            : requireNonNegativeBigInt(amount, 'amount');
+        return buildErc20ApprovalParams(ctx.addresses.gasToken, ctx.addresses.borrowerOperations, approvalAmount);
+    }
+    async getCollateralAllowance(ctx, owner) {
+        const ownerAddress = requireAddress(owner, 'owner');
+        return readErc20Allowance(this.publicClient, ctx.addresses.collToken, ownerAddress, ctx.addresses.borrowerOperations);
+    }
+    async getDebtAllowance(ctx, owner, spender) {
+        const ownerAddress = requireAddress(owner, 'owner');
+        const spenderAddress = requireAddress(spender, 'spender');
+        return (await this.publicClient.readContract({
+            address: ctx.addresses.debtToken,
+            abi: ERC20_ABI,
+            functionName: 'allowance',
+            args: [ownerAddress, spenderAddress],
+        }));
+    }
+    async getGasTokenAllowance(ctx, owner) {
+        const ownerAddress = requireAddress(owner, 'owner');
+        return readErc20Allowance(this.publicClient, ctx.addresses.gasToken, ownerAddress, ctx.addresses.borrowerOperations);
+    }
+}

package/dist/esm/services/borrow/internal/borrowContextStore.js

@@ -0,0 +1,35 @@
+import { getBorrowRegistry } from '../../../core/constants';
+import { readSystemParams, resolveAddressesFromRegistry } from './borrowRegistryReader';
+import { requireDebtTokenSymbol } from './borrowValidation';
+export class BorrowContextStore {
+    constructor(publicClient, chainId) {
+        this.publicClient = publicClient;
+        this.chainId = chainId;
+        this.deployments = new Map();
+        this.initializing = new Map();
+    }
+    async ensureInitialized(debtTokenSymbol) {
+        const symbol = requireDebtTokenSymbol(debtTokenSymbol);
+        const cached = this.deployments.get(symbol);
+        if (cached)
+            return cached;
+        const inFlight = this.initializing.get(symbol);
+        if (inFlight)
+            return inFlight;
+        const initPromise = (async () => {
+            const registryAddress = getBorrowRegistry(this.chainId, symbol);
+            const addresses = await resolveAddressesFromRegistry(this.publicClient, registryAddress);
+            const systemParams = await readSystemParams(this.publicClient, addresses.borrowerOperations);
+            const ctx = { addresses, systemParams };
+            this.deployments.set(symbol, ctx);
+            return ctx;
+        })();
+        this.initializing.set(symbol, initPromise);
+        try {
+            return await initPromise;
+        }
+        finally {
+            this.initializing.delete(symbol);
+        }
+    }
+}

package/dist/esm/services/borrow/internal/borrowErc20.js

@@ -0,0 +1,38 @@
+import { encodeFunctionData } from 'viem';
+import { ERC20_ABI } from '../../../core/abis';
+import { validateAddress } from '../../../utils/validation';
+const ZERO_VALUE = '0';
+function requireBigInt(value, fieldName) {
+    if (typeof value !== 'bigint') {
+        throw new Error(`${fieldName} must be a bigint`);
+    }
+    if (value < 0n) {
+        throw new Error(`${fieldName} cannot be negative`);
+    }
+    return value;
+}
+export function buildErc20ApprovalParams(token, spender, amount) {
+    validateAddress(token, 'token');
+    validateAddress(spender, 'spender');
+    if (amount < 0n) {
+        throw new Error('Approval amount cannot be negative');
+    }
+    const data = encodeFunctionData({
+        abi: ERC20_ABI,
+        functionName: 'approve',
+        args: [spender, amount],
+    });
+    return { to: token, data, value: ZERO_VALUE };
+}
+export async function readErc20Allowance(publicClient, token, owner, spender) {
+    validateAddress(token, 'token');
+    validateAddress(owner, 'owner');
+    validateAddress(spender, 'spender');
+    const allowanceRaw = await publicClient.readContract({
+        address: token,
+        abi: ERC20_ABI,
+        functionName: 'allowance',
+        args: [owner, spender],
+    });
+    return requireBigInt(allowanceRaw, 'allowance');
+}

package/dist/esm/services/borrow/internal/borrowHints.js

@@ -0,0 +1,27 @@
+import { HINT_HELPERS_ABI, SORTED_TROVES_ABI } from '../../../core/abis';
+import { COLL_INDEX } from '../../../core/constants';
+import { ceilSqrt, requireNonNegativeBigInt } from './borrowValidation';
+export async function getTroveOperationHints(publicClient, ctx, interestRate) {
+    const annualInterestRate = requireNonNegativeBigInt(interestRate, 'interestRate');
+    const troveCount = (await publicClient.readContract({
+        address: ctx.addresses.sortedTroves,
+        abi: SORTED_TROVES_ABI,
+        functionName: 'getSize',
+        args: [],
+    }));
+    const sqrtCount = ceilSqrt(troveCount);
+    const numTrials = 10n * (sqrtCount > 0n ? sqrtCount : 1n);
+    const [approxHint] = (await publicClient.readContract({
+        address: ctx.addresses.hintHelpers,
+        abi: HINT_HELPERS_ABI,
+        functionName: 'getApproxHint',
+        args: [COLL_INDEX, annualInterestRate, numTrials, 42n],
+    }));
+    const [upperHint, lowerHint] = (await publicClient.readContract({
+        address: ctx.addresses.sortedTroves,
+        abi: SORTED_TROVES_ABI,
+        functionName: 'findInsertPosition',
+        args: [annualInterestRate, approxHint, approxHint],
+    }));
+    return { upper: upperHint, lower: lowerHint };
+}

package/dist/esm/services/borrow/internal/borrowPositionParser.js

@@ -0,0 +1,82 @@
+import { zeroAddress } from 'viem';
+import { validateAddress } from '../../../utils/validation';
+const MAX_SAFE_INTEGER_BIGINT = BigInt(Number.MAX_SAFE_INTEGER);
+function requireAddress(value, fieldName) {
+    if (typeof value !== 'string') {
+        throw new Error(`${fieldName} must be a string address`);
+    }
+    validateAddress(value, fieldName);
+    return value;
+}
+function requireBigInt(value, fieldName) {
+    if (typeof value !== 'bigint') {
+        throw new Error(`${fieldName} must be a bigint`);
+    }
+    if (value < 0n) {
+        throw new Error(`${fieldName} cannot be negative`);
+    }
+    return value;
+}
+function requireNonNegativeInteger(value, fieldName) {
+    if (typeof value === 'bigint') {
+        if (value < 0n) {
+            throw new Error(`${fieldName} cannot be negative`);
+        }
+        if (value > MAX_SAFE_INTEGER_BIGINT) {
+            throw new Error(`${fieldName} exceeds Number.MAX_SAFE_INTEGER`);
+        }
+        return Number(value);
+    }
+    if (typeof value === 'number') {
+        if (!Number.isSafeInteger(value)) {
+            throw new Error(`${fieldName} must be a safe integer`);
+        }
+        if (value < 0) {
+            throw new Error(`${fieldName} cannot be negative`);
+        }
+        return value;
+    }
+    throw new Error(`${fieldName} must be a number or bigint`);
+}
+export function mapTroveStatus(statusNum) {
+    if (!Number.isSafeInteger(statusNum) || statusNum < 0) {
+        throw new Error(`Invalid trove status: ${statusNum}`);
+    }
+    switch (statusNum) {
+        case 0:
+            return 'nonExistent';
+        case 1:
+            return 'active';
+        case 2:
+            return 'closedByOwner';
+        case 3:
+            return 'closedByLiquidation';
+        case 4:
+            return 'zombie';
+        default:
+            throw new Error(`Unknown trove status: ${statusNum}`);
+    }
+}
+export function parseBorrowPosition(troveId, latestData, trovesData) {
+    if (typeof troveId !== 'string' || troveId.length === 0) {
+        throw new Error('troveId must be a non-empty string');
+    }
+    const latest = latestData;
+    const trove = trovesData;
+    const interestBatchManager = requireAddress(trove.interestBatchManager, 'trovesData.interestBatchManager');
+    return {
+        troveId,
+        collateral: requireBigInt(latest.entireColl, 'latestData.entireColl'),
+        debt: requireBigInt(latest.entireDebt, 'latestData.entireDebt'),
+        annualInterestRate: requireBigInt(latest.annualInterestRate, 'latestData.annualInterestRate'),
+        status: mapTroveStatus(requireNonNegativeInteger(trove.status, 'trovesData.status')),
+        interestBatchManager: interestBatchManager.toLowerCase() === zeroAddress ? null : interestBatchManager,
+        lastDebtUpdateTime: requireNonNegativeInteger(trove.lastDebtUpdateTime, 'trovesData.lastDebtUpdateTime'),
+        lastInterestRateAdjTime: requireNonNegativeInteger(latest.lastInterestRateAdjTime, 'latestData.lastInterestRateAdjTime'),
+        redistBoldDebtGain: requireBigInt(latest.redistBoldDebtGain, 'latestData.redistBoldDebtGain'),
+        redistCollGain: requireBigInt(latest.redistCollGain, 'latestData.redistCollGain'),
+        accruedInterest: requireBigInt(latest.accruedInterest, 'latestData.accruedInterest'),
+        recordedDebt: requireBigInt(latest.recordedDebt, 'latestData.recordedDebt'),
+        accruedBatchManagementFee: requireBigInt(latest.accruedBatchManagementFee, 'latestData.accruedBatchManagementFee'),
+    };
+}

package/dist/esm/services/borrow/internal/borrowReadService.js

@@ -0,0 +1,271 @@
+import { BORROWER_OPERATIONS_ABI, HINT_HELPERS_ABI, MULTI_TROVE_GETTER_ABI, PRICE_FEED_ABI, TROVE_MANAGER_ABI, TROVE_NFT_ABI, } from '../../../core/abis';
+import { COLL_INDEX } from '../../../core/constants';
+import { multicall } from '../../../utils/multicall';
+import { parseBorrowPosition } from './borrowPositionParser';
+import { deriveTroveId, formatTroveId, MAX_SAFE_INTEGER_BIGINT, parseTroveId, requireAddress, requireNonNegativeBigInt, } from './borrowValidation';
+const TROVE_ID_BATCH_SIZE = 64;
+const TROVE_OWNER_BATCH_SIZE = 64;
+const TROVE_DETAIL_BATCH_SIZE = 64;
+const OWNER_INDEX_PROBE_BATCH_SIZE = 64;
+export class BorrowReadService {
+    constructor(publicClient) {
+        this.publicClient = publicClient;
+    }
+    async getTroveData(ctx, troveId) {
+        const parsedTroveId = parseTroveId(troveId);
+        const [latestData, trovesData] = await this.readContractsInChunks([
+            {
+                address: ctx.addresses.troveManager,
+                abi: TROVE_MANAGER_ABI,
+                functionName: 'getLatestTroveData',
+                args: [parsedTroveId],
+            },
+            {
+                address: ctx.addresses.troveManager,
+                abi: TROVE_MANAGER_ABI,
+                functionName: 'Troves',
+                args: [parsedTroveId],
+            },
+        ], 2);
+        return parseBorrowPosition(formatTroveId(parsedTroveId), latestData, trovesData);
+    }
+    async getUserTroves(ctx, owner) {
+        const ownerAddress = requireAddress(owner, 'owner');
+        const ownedTroveCount = await this.getOwnedTroveCount(ctx, ownerAddress);
+        if (ownedTroveCount === 0) {
+            return [];
+        }
+        const troveCount = (await this.publicClient.readContract({
+            address: ctx.addresses.troveManager,
+            abi: TROVE_MANAGER_ABI,
+            functionName: 'getTroveIdsCount',
+            args: [],
+        }));
+        if (troveCount === 0n) {
+            return [];
+        }
+        const troveIdContracts = [];
+        for (let i = 0n; i < troveCount; i++) {
+            troveIdContracts.push({
+                address: ctx.addresses.troveManager,
+                abi: TROVE_MANAGER_ABI,
+                functionName: 'getTroveFromTroveIdsArray',
+                args: [i],
+            });
+        }
+        const troveIds = (await this.readContractsInChunks(troveIdContracts, TROVE_ID_BATCH_SIZE)).map((troveId) => troveId);
+        const ownerContracts = troveIds.map((troveId) => ({
+            address: ctx.addresses.troveNFT,
+            abi: TROVE_NFT_ABI,
+            functionName: 'ownerOf',
+            args: [troveId],
+        }));
+        const troveOwners = await this.readContractsInChunks(ownerContracts, TROVE_OWNER_BATCH_SIZE);
+        const matchedTroveIds = troveIds.filter((troveId, index) => troveOwners[index].toLowerCase() === ownerAddress.toLowerCase());
+        if (matchedTroveIds.length === 0) {
+            return [];
+        }
+        const troveDetailContracts = matchedTroveIds.flatMap((troveId) => ([
+            {
+                address: ctx.addresses.troveManager,
+                abi: TROVE_MANAGER_ABI,
+                functionName: 'getLatestTroveData',
+                args: [troveId],
+            },
+            {
+                address: ctx.addresses.troveManager,
+                abi: TROVE_MANAGER_ABI,
+                functionName: 'Troves',
+                args: [troveId],
+            },
+        ]));
+        const detailResults = await this.readContractsInChunks(troveDetailContracts, TROVE_DETAIL_BATCH_SIZE * 2);
+        return matchedTroveIds.map((troveId, index) => {
+            const offset = index * 2;
+            return parseBorrowPosition(formatTroveId(troveId), detailResults[offset], detailResults[offset + 1]);
+        });
+    }
+    async getCollateralPrice(ctx) {
+        return (await this.publicClient.readContract({
+            address: ctx.addresses.priceFeed,
+            abi: PRICE_FEED_ABI,
+            functionName: 'fetchPrice',
+            args: [],
+        }));
+    }
+    async isSystemShutDown(ctx) {
+        return (await this.publicClient.readContract({
+            address: ctx.addresses.borrowerOperations,
+            abi: BORROWER_OPERATIONS_ABI,
+            functionName: 'hasBeenShutDown',
+            args: [],
+        }));
+    }
+    async getBranchStats(ctx) {
+        const [totalColl, totalDebt] = await Promise.all([
+            this.publicClient.readContract({
+                address: ctx.addresses.borrowerOperations,
+                abi: BORROWER_OPERATIONS_ABI,
+                functionName: 'getEntireBranchColl',
+                args: [],
+            }),
+            this.publicClient.readContract({
+                address: ctx.addresses.borrowerOperations,
+                abi: BORROWER_OPERATIONS_ABI,
+                functionName: 'getEntireBranchDebt',
+                args: [],
+            }),
+        ]);
+        return { totalColl: totalColl, totalDebt: totalDebt };
+    }
+    async getInterestRateBrackets(ctx) {
+        const result = (await this.publicClient.readContract({
+            address: ctx.addresses.multiTroveGetter,
+            abi: MULTI_TROVE_GETTER_ABI,
+            functionName: 'getDebtPerInterestRateAscending',
+            args: [COLL_INDEX, 0n, 500n],
+        }));
+        const entries = result[0] ?? [];
+        const grouped = new Map();
+        for (const item of entries) {
+            const rate = requireNonNegativeBigInt(item.interestRate, 'interestRate');
+            const debt = requireNonNegativeBigInt(item.debt, 'debt');
+            const key = rate.toString();
+            grouped.set(key, (grouped.get(key) ?? 0n) + debt);
+        }
+        return Array.from(grouped.entries())
+            .map(([rate, totalDebt]) => ({
+            rate: BigInt(rate),
+            totalDebt,
+        }))
+            .sort((a, b) => (a.rate < b.rate ? -1 : a.rate > b.rate ? 1 : 0));
+    }
+    async getAverageInterestRate(ctx) {
+        const brackets = await this.getInterestRateBrackets(ctx);
+        if (brackets.length === 0)
+            return 0n;
+        let weightedRateSum = 0n;
+        let totalDebt = 0n;
+        for (const bracket of brackets) {
+            weightedRateSum += bracket.rate * bracket.totalDebt;
+            totalDebt += bracket.totalDebt;
+        }
+        return totalDebt === 0n ? 0n : weightedRateSum / totalDebt;
+    }
+    async getBatchManagerInfo(ctx, address) {
+        const batchManagerAddress = requireAddress(address, 'address');
+        const exists = (await this.publicClient.readContract({
+            address: ctx.addresses.borrowerOperations,
+            abi: BORROWER_OPERATIONS_ABI,
+            functionName: 'checkBatchManagerExists',
+            args: [batchManagerAddress],
+        }));
+        if (!exists)
+            return null;
+        const manager = (await this.publicClient.readContract({
+            address: ctx.addresses.borrowerOperations,
+            abi: BORROWER_OPERATIONS_ABI,
+            functionName: 'getInterestBatchManager',
+            args: [batchManagerAddress],
+        }));
+        return {
+            minRate: requireNonNegativeBigInt(manager.minInterestRate, 'minInterestRate'),
+            maxRate: requireNonNegativeBigInt(manager.maxInterestRate, 'maxInterestRate'),
+            minChangePeriod: requireNonNegativeBigInt(manager.minInterestRateChangePeriod, 'minInterestRateChangePeriod'),
+        };
+    }
+    async predictOpenTroveUpfrontFee(ctx, amount, rate) {
+        const borrowedAmount = requireNonNegativeBigInt(amount, 'amount');
+        const annualInterestRate = requireNonNegativeBigInt(rate, 'rate');
+        return (await this.publicClient.readContract({
+            address: ctx.addresses.hintHelpers,
+            abi: HINT_HELPERS_ABI,
+            functionName: 'predictOpenTroveUpfrontFee',
+            args: [COLL_INDEX, borrowedAmount, annualInterestRate],
+        }));
+    }
+    async predictAdjustUpfrontFee(ctx, troveId, debtIncrease) {
+        const parsedTroveId = parseTroveId(troveId);
+        const debtIncreaseAmount = requireNonNegativeBigInt(debtIncrease, 'debtIncrease');
+        return (await this.publicClient.readContract({
+            address: ctx.addresses.hintHelpers,
+            abi: HINT_HELPERS_ABI,
+            functionName: 'predictAdjustTroveUpfrontFee',
+            args: [COLL_INDEX, parsedTroveId, debtIncreaseAmount],
+        }));
+    }
+    async predictAdjustInterestRateUpfrontFee(ctx, troveId, newRate) {
+        const parsedTroveId = parseTroveId(troveId);
+        const newAnnualInterestRate = requireNonNegativeBigInt(newRate, 'newRate');
+        return (await this.publicClient.readContract({
+            address: ctx.addresses.hintHelpers,
+            abi: HINT_HELPERS_ABI,
+            functionName: 'predictAdjustInterestRateUpfrontFee',
+            args: [COLL_INDEX, parsedTroveId, newAnnualInterestRate],
+        }));
+    }
+    async predictJoinBatchUpfrontFee(ctx, troveId, batchAddress) {
+        const parsedTroveId = parseTroveId(troveId);
+        const managerAddress = requireAddress(batchAddress, 'batchAddress');
+        return (await this.publicClient.readContract({
+            address: ctx.addresses.hintHelpers,
+            abi: HINT_HELPERS_ABI,
+            functionName: 'predictJoinBatchInterestRateUpfrontFee',
+            args: [COLL_INDEX, parsedTroveId, managerAddress],
+        }));
+    }
+    async getOwnedTroveCount(ctx, owner) {
+        const ownerAddress = requireAddress(owner, 'owner');
+        const ownerTroveCount = (await this.publicClient.readContract({
+            address: ctx.addresses.troveNFT,
+            abi: TROVE_NFT_ABI,
+            functionName: 'balanceOf',
+            args: [ownerAddress],
+        }));
+        if (ownerTroveCount > MAX_SAFE_INTEGER_BIGINT) {
+            throw new Error('Owner trove count exceeds Number.MAX_SAFE_INTEGER');
+        }
+        return Number(ownerTroveCount);
+    }
+    async findNextAvailableOwnerIndex(ctx, owner, opener) {
+        const ownerAddress = requireAddress(owner, 'owner');
+        const openerAddress = requireAddress(opener, 'opener');
+        let candidateIndex = await this.getOwnedTroveCount(ctx, ownerAddress);
+        while (candidateIndex <= Number.MAX_SAFE_INTEGER) {
+            const batchIndices = Array.from({ length: Math.min(OWNER_INDEX_PROBE_BATCH_SIZE, Number.MAX_SAFE_INTEGER - candidateIndex + 1) }, (_, offset) => candidateIndex + offset);
+            const statusContracts = batchIndices.map((ownerIndex) => ({
+                address: ctx.addresses.troveManager,
+                abi: TROVE_MANAGER_ABI,
+                functionName: 'getTroveStatus',
+                args: [deriveTroveId(openerAddress, ownerAddress, ownerIndex)],
+            }));
+            const statuses = await this.readContractsInChunks(statusContracts, OWNER_INDEX_PROBE_BATCH_SIZE);
+            const availableOffset = statuses.findIndex((status) => status === 0 || status === 0n);
+            if (availableOffset !== -1) {
+                return batchIndices[availableOffset];
+            }
+            candidateIndex += batchIndices.length;
+        }
+        throw new Error('Next available owner index exceeds Number.MAX_SAFE_INTEGER');
+    }
+    async getNextOwnerIndex(ctx, owner) {
+        return this.getOwnedTroveCount(ctx, owner);
+    }
+    async readContractsInChunks(contracts, chunkSize) {
+        if (contracts.length === 0) {
+            return [];
+        }
+        const results = [];
+        for (let index = 0; index < contracts.length; index += chunkSize) {
+            const chunk = contracts.slice(index, index + chunkSize);
+            const chunkResults = await multicall(this.publicClient, chunk, { allowFailure: false });
+            for (const result of chunkResults) {
+                if (result.status === 'failure') {
+                    throw result.error;
+                }
+                results.push(result.result);
+            }
+        }
+        return results;
+    }
+}