DebtManagementLib

Git Source

Title: DebtManagementLib

Author: yearn.finance; extracted as library by Golem Foundation

Library for managing debt allocation and rebalancing between a multistrategy vault and its strategies

This library handles the complex logic of moving assets between the vault's idle reserves and individual strategies to maintain target debt levels. It ensures proper accounting, respects minimum idle requirements, and handles loss scenarios during withdrawals. Key Features:

• Debt rebalancing: Moves assets to/from strategies to match target debt allocations
• Loss protection: Enforces maximum acceptable loss thresholds during withdrawals
• Idle management: Maintains minimum idle reserves in the vault for liquidity
• Strategy constraints: Respects individual strategy deposit/withdrawal limits
• Shutdown handling: Ensures controlled wind-down when vault is in shutdown mode The library follows the ERC4626 standard for strategy interactions and implements robust error handling for edge cases like insufficient liquidity or unrealized losses. Originally part of Yearn V3 Multistrategy Vault (Vyper), extracted to separate library due to Solidity contract size limitations. https://github.com/yearn/yearn-vaults-v3

Notes:

• security-contact: [email protected]

• ported-from: https://github.com/yearn/yearn-vaults-v3/blob/master/contracts/VaultV3.vy

Related pages

• DeFi Concepts Primer
• Core Concepts

State Variables

MAX_BPS

Maximum basis points (100%)

Used for loss tolerance calculations

uint256 public constant MAX_BPS = 10_000

Functions

updateDebt

Rebalances strategy debt allocation by depositing or withdrawing assets

Core debt management function handling bidirectional asset movement

OPERATION MODES:

1. REDUCE DEBT (targetDebt < currentDebt):

• Withdraws assets from strategy back to vault
• Increases totalIdle, decreases totalDebt
• Respects strategy's maxRedeem limit
• Validates loss within maxLoss tolerance
• Ensures minimumTotalIdle is maintained

2. INCREASE DEBT (targetDebt > currentDebt):

• Deposits idle assets from vault to strategy
• Decreases totalIdle, increases totalDebt
• Respects strategy's maxDeposit limit
• Respects strategy's maxDebt cap
• Ensures minimumTotalIdle is preserved

SPECIAL VALUES:

• targetDebt = type(uint256).max: Deposit all available idle (up to maxDebt)
• targetDebt = 0: Withdraw all assets from strategy

SAFETY CHECKS:

• Prevents withdrawals if unrealized losses exist
• Uses actual balance diff for precise accounting
• Validates losses within maxLoss tolerance
• Maintains minimumTotalIdle buffer
• Auto-shutdown: Forces targetDebt = 0 if vault shutdown

LOSS HANDLING:

• maxLoss in basis points (0-10000)
• Loss = (assetsToWithdraw - actuallyWithdrawn)
• Reverts if loss exceeds tolerance
• Common values: 0 (no loss), 100 (1%), 10000 (100%)

function updateDebt(
    mapping(address => IMultistrategyVault.StrategyParams) storage strategies,
    uint256 totalIdle,
    uint256 totalDebt,
    address strategy,
    uint256 targetDebt,
    uint256 maxLoss,
    uint256 minimumTotalIdle,
    address asset,
    bool isShutdown
) external returns (UpdateDebtResult memory result);

Parameters

Name	Type	Description
strategies	mapping(address => IMultistrategyVault.StrategyParams)	Storage mapping of strategy parameters
totalIdle	uint256	Current vault idle assets
totalDebt	uint256	Current total debt across all strategies
strategy	address	Strategy address to rebalance
targetDebt	uint256	Target debt for strategy, or type(uint256).max for max)
maxLoss	uint256	Maximum acceptable loss in basis points (0-10000)
minimumTotalIdle	uint256	Minimum idle to maintain in vault
asset	address	Vault's asset token address
isShutdown	bool	Whether vault is shutdown (forces withdrawals)

Returns

Name	Type	Description
result	UpdateDebtResult	Updated debt, totalIdle, and totalDebt values

_withdrawFromStrategy

Internal function to withdraw from strategy

function _withdrawFromStrategy(address strategy, uint256 assetsToWithdraw) internal;

Parameters

Name	Type	Description
strategy	address	Strategy to withdraw from
assetsToWithdraw	uint256	Amount to withdraw

Structs

UpdateDebtResult

Return values from updateDebt operation

Returned to vault to update storage after debt operation

struct UpdateDebtResult {
    /// @notice New debt amount for the strategy
    uint256 newDebt;
    /// @notice New total idle amount for the vault
    uint256 newTotalIdle;
    /// @notice New total debt across all strategies
    uint256 newTotalDebt;
}

UpdateDebtVars

Working variables for updateDebt calculation

Follows Vyper implementation structure to avoid stack-too-deep errors

struct UpdateDebtVars {
    /// @notice Target debt we want strategy to have
    uint256 newDebt;
    /// @notice Current debt strategy has
    uint256 currentDebt;
    /// @notice Amount to withdraw if reducing debt
    uint256 assetsToWithdraw;
    /// @notice Amount to deposit if increasing debt
    uint256 assetsToDeposit;
    /// @notice Minimum amount vault must keep idle
    uint256 minimumTotalIdle;
    /// @notice Current idle in vault
    uint256 totalIdle;
    /// @notice Available idle after reserving minimum
    uint256 availableIdle;
    /// @notice Max withdrawable from strategy per maxRedeem
    uint256 withdrawable;
    /// @notice Max deposit to strategy per maxDeposit
    uint256 maxDeposit;
    /// @notice Strategy's maximum debt limit
    uint256 maxDebt;
    /// @notice Vault's asset token address
    address asset;
    /// @notice Asset balance before operation (for diff accounting)
    uint256 preBalance;
    /// @notice Asset balance after operation (for diff accounting)
    uint256 postBalance;
    /// @notice Actual amount withdrawn (may differ from requested)
    uint256 withdrawn;
    /// @notice Actual amount deposited (may differ from requested)
    uint256 actualDeposit;
}