Contract Source Code:
// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24 <0.9.0;
/**
* @title Context
* @dev Provides information about the current execution context, including the
* sender of the transaction and its data. While these are generally available
* via msg.sender and msg.data, they should not be accessed in such a direct
* manner, as when dealing with meta-transactions the account sending and
* paying for execution may not be the actual sender (as far as an application
* is concerned).
* @notice This contract is used through inheritance. It will make available the
* modifier `_msgSender()`, which can be used to reference the account that
* called a function within an implementing contract.
*/
abstract contract Context {
/*//////////////////////////////////////////////////////////////
INTERNAL FUNCTIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Gets the sender of the current call
* @dev Provides a way to retrieve the message sender that supports meta-transactions
* @return Sender address (msg.sender in the base implementation)
*/
function _msgSender() internal view virtual returns (address) {
return msg.sender;
}
/**
* @notice Gets the complete calldata of the current call
* @dev Provides a way to retrieve the message data that supports meta-transactions
* @return Complete calldata bytes
*/
function _msgData() internal view virtual returns (bytes calldata) {
return msg.data;
}
/**
* @notice Gets the length of any context-specific suffix in the message data
* @dev Used in meta-transaction implementations to account for additional data
* @return Length of the context suffix (0 in the base implementation)
*/
function _contextSuffixLength() internal view virtual returns (uint256) {
return 0;
}
}
// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24 <0.9.0;
import {Context} from "./Context.sol";
/**
* @title Ownable
* @dev Contract module which provides a basic access control mechanism, where
* there is an account (an owner) that can be granted exclusive access to
* specific functions.
* @notice By default, the owner account will be the one that deploys the contract.
* This can later be changed with {transferOwnership} and {renounceOwnership}.
*/
abstract contract Ownable is Context {
/*//////////////////////////////////////////////////////////////
STATE VARIABLES
//////////////////////////////////////////////////////////////*/
/// @notice Address of the current owner
address private _owner;
/*//////////////////////////////////////////////////////////////
EVENTS
//////////////////////////////////////////////////////////////*/
/// @notice Emitted when ownership is transferred
event OwnershipTransferred(
address indexed previousOwner,
address indexed newOwner
);
/*//////////////////////////////////////////////////////////////
CUSTOM ERRORS
//////////////////////////////////////////////////////////////*/
/// @notice Thrown when non-owner tries to call owner-only function
error UnauthorizedAccount(address account);
/// @notice Thrown when trying to transfer ownership to invalid address
error InvalidOwner(address owner);
/*//////////////////////////////////////////////////////////////
MODIFIERS
//////////////////////////////////////////////////////////////*/
/**
* @dev Throws if called by any account other than the owner
*/
modifier onlyOwner() {
_checkOwner();
_;
}
/*//////////////////////////////////////////////////////////////
CONSTRUCTOR
//////////////////////////////////////////////////////////////*/
/**
* @dev Initializes the contract setting the deployer as the initial owner
*/
constructor() {
_transferOwnership(_msgSender());
}
/*//////////////////////////////////////////////////////////////
PUBLIC FUNCTIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Leaves the contract without owner
* @dev Renouncing ownership will leave the contract without an owner,
* thereby removing any functionality that is only available to the owner
*/
function renounceOwnership() public virtual onlyOwner {
_transferOwnership(address(0));
}
/**
* @notice Transfers ownership of the contract to a new account
* @dev The new owner cannot be the zero address
* @param newOwner The address that will become the new owner
*/
function transferOwnership(address newOwner) public virtual onlyOwner {
if (newOwner == address(0)) {
revert InvalidOwner(address(0));
}
_transferOwnership(newOwner);
}
/*//////////////////////////////////////////////////////////////
VIEW FUNCTIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Returns the address of the current owner
* @return Current owner address
*/
function owner() public view virtual returns (address) {
return _owner;
}
/*//////////////////////////////////////////////////////////////
INTERNAL FUNCTIONS
//////////////////////////////////////////////////////////////*/
/**
* @dev Transfers ownership of the contract to a new account (`newOwner`)
* Internal function without access restriction
*/
function _transferOwnership(address newOwner) internal virtual {
address oldOwner = _owner;
_owner = newOwner;
emit OwnershipTransferred(oldOwner, newOwner);
}
/**
* @dev Throws if the sender is not the owner
*/
function _checkOwner() internal view virtual {
if (owner() != _msgSender()) {
revert UnauthorizedAccount(_msgSender());
}
}
}
// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24 <0.9.0;
/**
* @title ReentrancyGuard
* @dev Contract module that helps prevent reentrant calls to a function
* @notice This module is used through inheritance. It will make available the modifier
* `nonReentrant`, which can be applied to functions to make sure there are no nested
* (reentrant) calls to them.
*/
abstract contract ReentrancyGuard {
/*//////////////////////////////////////////////////////////////
STATE VARIABLES
//////////////////////////////////////////////////////////////*/
/// @notice Guard state constants
uint256 private constant NOT_ENTERED = 1;
uint256 private constant ENTERED = 2;
/// @notice Current state of the guard
uint256 private _status;
/*//////////////////////////////////////////////////////////////
CUSTOM ERRORS
//////////////////////////////////////////////////////////////*/
error ReentrantCall();
/*//////////////////////////////////////////////////////////////
MODIFIERS
//////////////////////////////////////////////////////////////*/
/**
* @dev Prevents a contract from calling itself, directly or indirectly.
* Calling a `nonReentrant` function from another `nonReentrant`
* function is not supported. It is possible to prevent this from happening
* by making the `nonReentrant` function external, and making it call a
* `private` function that does the actual work.
*/
modifier nonReentrant() {
_nonReentrantBefore();
_;
_nonReentrantAfter();
}
/*//////////////////////////////////////////////////////////////
CONSTRUCTOR
//////////////////////////////////////////////////////////////*/
/**
* @notice Initializes the contract by setting the initial reentrancy guard state
*/
constructor() {
_status = NOT_ENTERED;
}
/*//////////////////////////////////////////////////////////////
VIEW FUNCTIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Checks if a protected function is currently executing
* @return True if the contract is in the entered state
*/
function _reentrancyGuardEntered() internal view returns (bool) {
return _status == ENTERED;
}
/*//////////////////////////////////////////////////////////////
PRIVATE FUNCTIONS
//////////////////////////////////////////////////////////////*/
/**
* @dev Sets guard state before protected function execution
* @notice Reverts if a reentrant call is detected
*/
function _nonReentrantBefore() private {
if (_status == ENTERED) {
revert ReentrantCall();
}
_status = ENTERED;
}
/**
* @dev Resets guard state after protected function execution
*/
function _nonReentrantAfter() private {
_status = NOT_ENTERED;
}
}
// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24 <0.9.0;
import {IDUSXProvider} from "./IDUSXProvider.sol";
import {IERC20Token} from "./IERC20Token.sol";
import {IERC20TokenRebase} from "./IERC20TokenRebase.sol";
import {IFeesDistributor} from "./IFees.sol";
import {IFeesWithdrawer} from "./IFees.sol";
import {IFloor} from "./IFloor.sol";
import {ILenderOwner} from "./ILenderOwner.sol";
import {ILiquidationHelper} from "./ILiquidationHelper.sol";
import {IMarketLens} from "./IMarketLens.sol";
import {IMiscHelper} from "./IMiscHelper.sol";
import {IOracle} from "./IOracle.sol";
import {IPSM} from "./IPSM.sol";
import {IRepayHelper} from "./IRepayHelper.sol";
import {IStableOwner} from "./IStableOwner.sol";
import {IStakedDUSX} from "./IStakedDUSX.sol";
import {ISupplyHangingCalculator} from "./ISupplyHangingCalculator.sol";
import {IVault} from "./IVault.sol";
import {IVoteEscrowedSTTX} from "./IVoteEscrowedSTTX.sol";
import {IDynamicInterestRate} from "./IDynamicInterestRate.sol";
import {IMinter} from "./IMinter.sol";
interface IBaseContracts {
struct CoreTokens {
IERC20Token dusx;
IERC20TokenRebase sttx;
IStakedDUSX stDUSX;
IVoteEscrowedSTTX veSTTX;
}
struct PSMContracts {
IPSM psmCircle;
IPSM psmTether;
IStableOwner stableOwner;
}
struct OracleContracts {
IOracle oracleChainlink;
IOracle oracleFloorPrice;
}
struct HelperContracts {
IMiscHelper helper;
ILiquidationHelper liquidationHelper;
IRepayHelper repayHelper;
IMarketLens marketLens;
}
error ZeroAddress();
error ContractAlreadySet();
// Struct getters
function coreTokens() external view returns (CoreTokens memory);
function psmContracts() external view returns (PSMContracts memory);
function oracleContracts() external view returns (OracleContracts memory);
function helperContracts() external view returns (HelperContracts memory);
// Individual contract getters
function dusxProvider() external view returns (IDUSXProvider);
function feesDistributor() external view returns (IFeesDistributor);
function feesWithdrawer() external view returns (IFeesWithdrawer);
function floor() external view returns (IFloor);
function lenderOwner() external view returns (ILenderOwner);
function minter() external view returns (IMinter);
function supplyCalculator()
external
view
returns (ISupplyHangingCalculator);
function vault() external view returns (IVault);
function dynamicInterestRate() external view returns (IDynamicInterestRate);
// Convenience getters for struct members
function dusx() external view returns (IERC20Token);
function sttx() external view returns (IERC20TokenRebase);
function stDUSX() external view returns (IStakedDUSX);
function veSTTX() external view returns (IVoteEscrowedSTTX);
function psmCircle() external view returns (IPSM);
function psmTether() external view returns (IPSM);
function stableOwner() external view returns (IStableOwner);
function oracleChainlink() external view returns (IOracle);
function oracleFloorPrice() external view returns (IOracle);
function helper() external view returns (IMiscHelper);
function liquidationHelper() external view returns (ILiquidationHelper);
function repayHelper() external view returns (IRepayHelper);
function marketLens() external view returns (IMarketLens);
}
// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24 <0.9.0;
/**
* @title IDUSXProvider
* @dev Interface for DUSX token provision and distribution operations
* @notice Defines functionality for:
* 1. Token provision management
* 2. Supply control
* 3. Distribution tracking
*/
interface IDUSXProvider {
/*//////////////////////////////////////////////////////////////
PROVISION OPERATIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Provides DUSX tokens to the requesting address
* @param amount The quantity of DUSX tokens to provide in base units
* @dev Handles:
* · Token minting/transfer
* · Supply tracking
* · State updates
*
* Requirements:
* · Caller is authorized
* · Amount > 0
* · Within supply limits
*
* Effects:
* · Increases recipient balance
* · Updates total supply
* · Emits provision event
*/
function provide(uint256 amount) external;
}
// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24 <0.9.0;
/**
* @title IDynamicInterestRate
* @dev Interface for dynamic interest rate calculations in the lending protocol
* @notice Defines methods for retrieving time-based interest rates that:
* 1. Adjust based on market conditions
* 2. Support per-second and base rate calculations
* 3. Maintain precision through proper scaling
*
* This interface is crucial for:
* · Accurate interest accrual
* · Dynamic market response
* · Protocol yield calculations
*/
interface IDynamicInterestRate {
/*//////////////////////////////////////////////////////////////
INTEREST RATE QUERIES
//////////////////////////////////////////////////////////////*/
/**
* @notice Retrieves the current interest rate per second
* @return uint256 Interest rate per second, scaled by 1e18
* @dev Used for precise interest calculations over time periods
*/
function getInterestPerSecond() external view returns (uint256);
/**
* @notice Retrieves the current base interest rate
* @return uint256 Base interest rate, scaled by 1e18
* @dev Represents the foundational rate before adjustments
*/
function getInterestRate() external view returns (uint256);
}
// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24 <0.9.0;
/**
* @title IERC20Custom
* @dev Interface for the ERC20 fungible token standard (EIP-20)
* @notice Defines functionality for:
* 1. Token transfers
* 2. Allowance management
* 3. Balance tracking
* 4. Token metadata
*/
interface IERC20Custom {
/*//////////////////////////////////////////////////////////////
EVENTS
//////////////////////////////////////////////////////////////*/
/**
* @dev Emitted on token transfer between addresses
* @param from Source address (0x0 for mints)
* @param to Destination address (0x0 for burns)
* @param value Amount of tokens transferred
* @notice Tracks:
* · Regular transfers
* · Minting operations
* · Burning operations
*/
event Transfer(address indexed from, address indexed to, uint256 value);
/**
* @dev Emitted when spending allowance is granted
* @param owner Address granting permission
* @param spender Address receiving permission
* @param value Amount of tokens approved
* @notice Records:
* · New approvals
* · Updated allowances
* · Revoked permissions
*/
event Approval(
address indexed owner,
address indexed spender,
uint256 value
);
/*//////////////////////////////////////////////////////////////
TRANSFER OPERATIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Transfers tokens to specified recipient
* @param to Recipient address
* @param value Amount to transfer in base units
* @return bool True if transfer succeeds
* @dev Requirements:
* · Caller has sufficient balance
* · Recipient is valid
* · Amount > 0
*
* Effects:
* · Decreases caller balance
* · Increases recipient balance
* · Emits Transfer event
*/
function transfer(address to, uint256 value) external returns (bool);
/**
* @notice Executes transfer on behalf of token owner
* @param from Source address
* @param to Destination address
* @param value Amount to transfer in base units
* @return bool True if transfer succeeds
* @dev Requirements:
* · Caller has sufficient allowance
* · Source has sufficient balance
* · Valid addresses
*
* Effects:
* · Decreases allowance
* · Updates balances
* · Emits Transfer event
*/
function transferFrom(
address from,
address to,
uint256 value
) external returns (bool);
/*//////////////////////////////////////////////////////////////
APPROVAL OPERATIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Authorizes address to spend tokens
* @param spender Address to authorize
* @param value Amount to authorize in base units
* @return bool True if approval succeeds
* @dev Controls:
* · Spending permissions
* · Delegation limits
* · Authorization levels
*
* Security:
* · Overwrites previous allowance
* · Requires explicit value
* · Emits Approval event
*/
function approve(address spender, uint256 value) external returns (bool);
/*//////////////////////////////////////////////////////////////
TOKEN METADATA
//////////////////////////////////////////////////////////////*/
/**
* @notice Retrieves human-readable token name
* @return string Full token name
*/
function name() external view returns (string memory);
/**
* @notice Retrieves token trading symbol
* @return string Short token identifier
*/
function symbol() external view returns (string memory);
/**
* @notice Retrieves token decimal precision
* @return uint8 Number of decimal places
* @dev Standard:
* · 18 for most tokens
* · Used for display formatting
*/
function decimals() external view returns (uint8);
/*//////////////////////////////////////////////////////////////
BALANCE QUERIES
//////////////////////////////////////////////////////////////*/
/**
* @notice Retrieves total token supply
* @return uint256 Current total supply
* @dev Reflects:
* · All minted tokens
* · Minus burned tokens
* · In base units
*/
function totalSupply() external view returns (uint256);
/**
* @notice Retrieves account token balance
* @param account Address to query
* @return uint256 Current balance in base units
* @dev Returns:
* · Available balance
* · Includes pending rewards
* · Excludes locked tokens
*/
function balanceOf(address account) external view returns (uint256);
/**
* @notice Retrieves remaining spending allowance
* @param owner Token owner address
* @param spender Authorized spender address
* @return uint256 Current allowance in base units
* @dev Shows:
* · Approved amount
* · Remaining limit
* · Delegation status
*/
function allowance(
address owner,
address spender
) external view returns (uint256);
}
// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24 <0.9.0;
import {IERC20Custom} from "./IERC20Custom.sol";
/**
* @title IERC20Token
* @dev Extended interface for ERC20 tokens with supply control capabilities
* @notice Defines functionality for:
* 1. Token minting
* 2. Token burning
* 3. Supply management
*/
interface IERC20Token is IERC20Custom {
/*//////////////////////////////////////////////////////////////
SUPPLY MANAGEMENT
//////////////////////////////////////////////////////////////*/
/**
* @notice Mints new tokens to specified account
* @param account Address to receive minted tokens
* @param amount Quantity of tokens to mint in base units
* @dev Controls:
* · Supply expansion
* · Balance updates
* · Event emission
*
* Requirements:
* · Caller is authorized
* · Within maxSupply
* · Valid recipient
*/
function mint(address account, uint256 amount) external;
/**
* @notice Burns tokens from specified account
* @param account Address to burn tokens from
* @param amount Quantity of tokens to burn in base units
* @dev Manages:
* · Supply reduction
* · Balance updates
* · Event emission
*
* Requirements:
* · Caller is authorized
* · Sufficient balance
* · Amount > 0
*/
function burn(address account, uint256 amount) external;
/*//////////////////////////////////////////////////////////////
VIEW FUNCTIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Retrieves maximum token supply limit
* @return uint256 Maximum supply cap in base units
* @dev Enforces:
* · Supply ceiling
* · Mint restrictions
* · Protocol limits
*
* Note: This is an immutable value that
* cannot be exceeded by minting operations
*/
function maxSupply() external view returns (uint256);
}
// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24 <0.9.0;
import {IERC20Custom} from "./IERC20Custom.sol";
/**
* @title IERC20TokenRebase
* @dev Extended interface for ERC20 tokens with elastic supply and safe management
* @notice Defines functionality for:
* 1. Supply elasticity (rebasing)
* 2. Safe-based token management
* 3. Supply control mechanisms
* 4. Configuration management
*/
interface IERC20TokenRebase is IERC20Custom {
/*//////////////////////////////////////////////////////////////
SUPPLY MANAGEMENT
//////////////////////////////////////////////////////////////*/
/**
* @notice Mints new tokens to specified account
* @param account Address to receive minted tokens
* @param amount Quantity of tokens to mint in base units
* @dev Requires:
* · Caller is authorized minter
* · Within maxSupply limits
* · Valid recipient
*/
function mint(address account, uint256 amount) external;
/**
* @notice Burns tokens from specified account
* @param account Address to burn tokens from
* @param amount Quantity of tokens to burn in base units
* @dev Requires:
* · Caller is authorized
* · Account has sufficient balance
* · Amount > 0
*/
function burn(address account, uint256 amount) external;
/*//////////////////////////////////////////////////////////////
REBASE OPERATIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Executes supply rebase based on current parameters
* @dev Triggers:
* · Supply adjustment
* · Balance recalculation
* · Event emission
*
* Considers:
* · Rebase interval
* · Basis points
* · Supply limits
*/
function rebase() external;
/**
* @notice Configures rebase parameters
* @param rebaseInterval Time period between rebases (in seconds)
* @param rebaseBasisPoints Scale factor for rebase (in basis points)
* @dev Controls:
* · Rebase frequency
* · Rebase magnitude
* · Supply elasticity
*/
function setRebaseConfig(
uint256 rebaseInterval,
uint256 rebaseBasisPoints
) external;
/*//////////////////////////////////////////////////////////////
SAFE MANAGEMENT
//////////////////////////////////////////////////////////////*/
/**
* @notice Initializes new token management safe
* @param safe Address of safe to create
* @dev Establishes:
* · Safe permissions
* · Access controls
* · Management capabilities
*/
function createSafe(address safe) external;
/**
* @notice Removes existing token management safe
* @param safe Address of safe to remove
* @dev Handles:
* · Permission revocation
* · State cleanup
* · Access termination
*/
function destroySafe(address safe) external;
/*//////////////////////////////////////////////////////////////
VIEW FUNCTIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Retrieves floor contract address
* @return address Active floor contract
* @dev Used for:
* · Price stability
* · Supply control
*/
function floor() external view returns (address);
/**
* @notice Retrieves authorized minter address
* @return address Active minter contract
* @dev Controls:
* · Mint permissions
* · Supply expansion
*/
function minter() external view returns (address);
/**
* @notice Returns absolute maximum token supply
* @return uint256 Maximum supply cap in base units
* @dev Enforces:
* · Hard supply limit
* · Mint restrictions
*/
function maxSupply() external view returns (uint256);
/**
* @notice Calculates maximum supply after rebase
* @return uint256 Post-rebase maximum supply in base units
* @dev Considers:
* · Current max supply
* · Rebase parameters
* · Supply caps
*/
function maxSupplyRebased() external view returns (uint256);
/**
* @notice Calculates total supply after rebase
* @return uint256 Post-rebase total supply in base units
* @dev Reflects:
* · Current supply
* · Rebase effects
* · Supply limits
*/
function totalSupplyRebased() external view returns (uint256);
}
// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24 <0.9.0;
/**
* @title IFeesWithdrawer
* @dev Interface for protocol fee withdrawal operations
* @notice Defines functionality for:
* 1. Secure fee withdrawal
* 2. Access control for withdrawals
* 3. Protocol revenue management
*
* This interface ensures:
* · Controlled access to protocol fees
* · Safe transfer of accumulated revenue
* · Proper accounting of withdrawn amounts
*/
interface IFeesWithdrawer {
/*//////////////////////////////////////////////////////////////
WITHDRAWAL OPERATIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Withdraws accumulated protocol fees to designated recipients
* @dev Only callable by authorized withdrawers
* Handles:
* · Fee accounting updates
* · Transfer of tokens
* · Event emission for tracking
*/
function withdraw() external;
}
/**
* @title IFeesDistributor
* @dev Interface for protocol fee distribution and allocation
* @notice Defines functionality for:
* 1. Fee distribution across protocol components
* 2. Dynamic allocation management
* 3. Floor token revenue sharing
*
* This interface manages:
* · Revenue distribution logic
* · Allocation percentages
* · Protocol incentive mechanisms
*/
interface IFeesDistributor {
/*//////////////////////////////////////////////////////////////
DISTRIBUTION OPERATIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Distributes accumulated protocol fees according to set allocations
* @dev Handles the distribution of fees to:
* · Floor token stakers
* · Protocol treasury
* · Other designated recipients
*/
function distribute() external;
/*//////////////////////////////////////////////////////////////
VIEW FUNCTIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Returns current percentage allocated to Floor token stakers
* @return uint256 Floor allocation percentage, scaled by 1e18
*/
function floorAllocation() external view returns (uint256);
}
// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24 <0.9.0;
/**
* @title IFloor
* @dev Interface for protocol floor price management and capital operations
* @notice Defines functionality for:
* 1. Token deposit management
* 2. Refund processing
* 3. Capital tracking
*/
interface IFloor {
/*//////////////////////////////////////////////////////////////
DEPOSIT OPERATIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Processes token deposits into the floor contract
* @param msgSender Address initiating the deposit
* @param amount Quantity of tokens to deposit
* @dev Handles:
* · Token transfer validation
* · Capital tracking updates
* · Event emission
*/
function deposit(address msgSender, uint256 amount) external;
/*//////////////////////////////////////////////////////////////
REFUND OPERATIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Processes token refunds from the floor contract
* @param msgSender Address receiving the refund
* @param amount Quantity of tokens to refund
* @dev Ensures:
* · Sufficient contract balance
* · Authorized withdrawal
* · Capital accounting
*/
function refund(address msgSender, uint256 amount) external;
/*//////////////////////////////////////////////////////////////
VIEW FUNCTIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Returns current total capital held in the floor contract
* @return uint256 Current capital amount in base units
* @dev Used for:
* · Floor price calculations
* · Protocol health metrics
* · Capital adequacy checks
*/
function capital() external view returns (uint256);
}
// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24 <0.9.0;
import {Rebase} from "../library/AuxRebase.sol";
import {IERC20Custom} from "./IERC20Custom.sol";
import {IOracle} from "./IOracle.sol";
import {IVault} from "./IVault.sol";
/**
* @title ILender
* @dev Interface for lending operations and management
* @notice Defines the core lending protocol functionality including:
* 1. Collateral management and borrowing operations
* 2. Interest rate and fee management
* 3. Liquidation handling
* 4. Vault integration
*
* The interface is designed to support:
* · Over-collateralized lending
* · Dynamic interest rates
* · Liquidation mechanisms
* · Fee collection and distribution
*/
interface ILender {
/*//////////////////////////////////////////////////////////////
ADMIN CONFIGURATION
//////////////////////////////////////////////////////////////*/
/**
* @notice Updates the interest rate for borrowing
* @param newInterestRate New interest rate (scaled by 1e18)
*/
function changeInterestRate(uint256 newInterestRate) external;
/**
* @notice Sets global and per-address borrowing limits
* @param newBorrowLimit Total borrowing limit for the protocol
* @param perAddressPart Maximum borrow amount per address
*/
function changeBorrowLimit(
uint256 newBorrowLimit,
uint256 perAddressPart
) external;
/*//////////////////////////////////////////////////////////////
CORE LENDING OPERATIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Updates protocol state with accrued interest
*/
function accrue() external;
/**
* @notice Updates the exchange rate from the oracle
*/
function updateExchangeRate() external;
/**
* @notice Withdraws accumulated protocol fees
* @param amountToProvide Amount of fees to withdraw
*/
function withdrawFees(uint256 amountToProvide) external;
/*//////////////////////////////////////////////////////////////
LIQUIDATION HANDLING
//////////////////////////////////////////////////////////////*/
/**
* @notice Liquidates undercollateralized positions
* @param liquidator Address performing the liquidation
* @param users Array of user addresses to liquidate
* @param maxBorrowParts Maximum borrow parts to liquidate per user
* @param to Address to receive liquidated collateral
*/
function liquidate(
address liquidator,
address[] memory users,
uint256[] memory maxBorrowParts,
address to
) external;
/*//////////////////////////////////////////////////////////////
VAULT OPERATIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Deposits collateral into the vault
* @param amount Amount of collateral to deposit
*/
function vaultDepositAddCollateral(uint256 amount) external;
/**
* @notice Withdraws borrowed assets from the vault
* @param msgSender Address initiating the withdrawal
* @param amount Amount to withdraw
* @return part Borrow part assigned
* @return share Share of the vault
*/
function borrowVaultWithdraw(
address msgSender,
uint256 amount
) external returns (uint256 part, uint256 share);
/*//////////////////////////////////////////////////////////////
COLLATERAL MANAGEMENT
//////////////////////////////////////////////////////////////*/
/**
* @notice Adds collateral to a lending position
* @param to Address to credit the collateral
* @param skim True to skim tokens from the contract
* @param share Amount of shares to add as collateral
*/
function addCollateral(address to, bool skim, uint256 share) external;
/**
* @notice Removes collateral from a lending position
* @param to Address to receive the removed collateral
* @param share Amount of shares to remove
*/
function removeCollateral(address to, uint256 share) external;
/*//////////////////////////////////////////////////////////////
BORROWING OPERATIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Borrows assets against deposited collateral
* @param msgSender Address initiating the borrow
* @param amount Amount to borrow
* @return part Borrow part assigned
* @return share Share of the borrowed amount
*/
function borrow(
address msgSender,
uint256 amount
) external returns (uint256 part, uint256 share);
/**
* @notice Repays borrowed assets
* @param payer Address paying the debt
* @param to Address whose debt to repay
* @param skim True to skim tokens from the contract
* @param part Amount of borrow part to repay
* @return amount Actual amount repaid
*/
function repay(
address payer,
address to,
bool skim,
uint256 part
) external returns (uint256 amount);
/*//////////////////////////////////////////////////////////////
VIEW FUNCTIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Gets the oracle contract address
* @return IOracle Oracle interface
*/
function oracle() external view returns (IOracle);
/**
* @notice Gets interest accrual information
* @return Last accrual timestamp, accumulated interest, interest per second
*/
function accrueInfo() external view returns (uint256, uint256, uint256);
/**
* @notice Gets the required collateral ratio
* @return uint256 Collateral ratio (scaled by 1e5)
*/
function collateralRatio() external view returns (uint256);
/**
* @notice Gets the liquidation bonus multiplier
* @return uint256 Liquidation multiplier (scaled by 1e5)
*/
function liquidationMultiplier() external view returns (uint256);
/**
* @notice Gets total collateral shares in the protocol
* @return uint256 Total collateral share amount
*/
function totalCollateralShare() external view returns (uint256);
/**
* @notice Gets the vault contract address
* @return IVault Vault interface
*/
function vault() external view returns (IVault);
/**
* @notice Gets the fee recipient address
* @return address Fee recipient
*/
function feeTo() external view returns (address);
/**
* @notice Gets the collateral token address
* @return IERC20Custom Collateral token interface
*/
function collateral() external view returns (IERC20Custom);
/**
* @notice Gets total borrow state
* @return Rebase Total borrow information
*/
function totalBorrow() external view returns (Rebase memory);
/**
* @notice Gets user's borrow part
* @param account User address
* @return uint256 User's borrow part
*/
function userBorrowPart(address account) external view returns (uint256);
/**
* @notice Gets user's collateral share
* @param account User address
* @return uint256 User's collateral share
*/
function userCollateralShare(
address account
) external view returns (uint256);
/**
* @notice Gets protocol borrowing limits
* @return total Total protocol borrow limit
* @return borrowPartPerAddress Per-address borrow limit
*/
function borrowLimit()
external
view
returns (uint256 total, uint256 borrowPartPerAddress);
/**
* @notice Gets the DUSX token address
* @return IERC20Custom DUSX token interface
*/
function dusx() external view returns (IERC20Custom);
/**
* @notice Gets all accounts with active positions
* @return address[] Array of account addresses
*/
function accounts() external view returns (address[] memory);
/**
* @notice Gets the collateral precision factor
* @return uint256 Collateral precision
*/
function collateralPrecision() external view returns (uint256);
}
// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24 <0.9.0;
import {ILender} from "./ILender.sol";
/**
* @title ILenderOwner
* @dev Interface for protocol-level lender management and configuration
* @notice Defines functionality for:
* 1. Interest rate management
* 2. Borrow limit control
* 3. Risk parameter adjustment
*/
interface ILenderOwner {
/*//////////////////////////////////////////////////////////////
INTEREST MANAGEMENT
//////////////////////////////////////////////////////////////*/
/**
* @notice Updates lender's interest rate configuration
* @param lender The lender contract to modify
* @param newInterestRate New interest rate value in basis points
* @dev Controls:
* · Interest accrual
* · Yield generation
* · Protocol revenue
*
* Requirements:
* · Caller is authorized
* · Rate within bounds
* · Valid lender contract
*/
function changeInterestRate(
ILender lender,
uint256 newInterestRate
) external;
/*//////////////////////////////////////////////////////////////
LIMIT MANAGEMENT
//////////////////////////////////////////////////////////////*/
/**
* @notice Updates lender's borrowing constraints
* @param lender The lender contract to modify
* @param newBorrowLimit New total protocol borrow limit
* @param perAddressPart Maximum borrow limit per address
* @dev Manages:
* · Protocol exposure
* · Individual limits
* · Risk thresholds
*
* Requirements:
* · Caller is authorized
* · Valid limits
* · perAddressPart <= newBorrowLimit
*
* Security:
* · Prevents overleveraging
* · Controls risk exposure
* · Ensures protocol stability
*/
function changeBorrowLimit(
ILender lender,
uint256 newBorrowLimit,
uint256 perAddressPart
) external;
/*//////////////////////////////////////////////////////////////
DEPRECATION MANAGEMENT
//////////////////////////////////////////////////////////////*/
/**
* @notice Checks if a lender contract is deprecated
* @param lender The lender address to check
* @return bool True if the lender is deprecated, false otherwise
* @dev Used to:
* · Prevent operations on deprecated markets
* · Control market lifecycle
* · Manage protocol upgrades
*
* Security:
* · Read-only function
* · No state modifications
* · Access control not required
*/
function deprecated(address lender) external view returns (bool);
/**
* @notice Checks if a lender contract is in manual mode
* @param lender The lender address to check
* @return bool True if the lender is in manual mode, false otherwise
* @dev Used to:
* · Determine if borrow limits are managed manually
* · Control automatic interest rate adjustments
*
* Security:
* · Read-only function
* · No state modifications
* · Access control not required
*/
function manual(address lender) external view returns (bool);
}
// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24 <0.9.0;
import {IERC20Custom} from "./IERC20Custom.sol";
import {ILender} from "../interface/ILender.sol";
import {IMiscHelper} from "../interface/IMiscHelper.sol";
/**
* @title ILiquidationHelper
* @dev Interface for liquidation assistance operations
* @notice Defines comprehensive liquidation functionality including:
* 1. Direct liquidation execution
* 2. Liquidation amount calculations
* 3. Position health checks
* 4. Preview and simulation functions
*
* The helper provides:
* · Maximum and partial liquidation support
* · Customizable recipient addresses
* · Pre-execution liquidation simulations
* · Automated DUSX amount calculations
*/
interface ILiquidationHelper {
/*//////////////////////////////////////////////////////////////
CONFIGURATION
//////////////////////////////////////////////////////////////*/
/*//////////////////////////////////////////////////////////////
LIQUIDATION EXECUTION
//////////////////////////////////////////////////////////////*/
/**
* @notice Liquidates maximum possible amount for an account
* @param lender Address of the lending contract
* @param account Address to be liquidated
* @return collateralAmount Amount of collateral received
* @return adjustedBorrowPart Adjusted borrow amount after liquidation
* @return requiredDUSXAmount DUSX tokens needed to execute liquidation
* @dev Automatically calculates maximum liquidatable amount
*/
function liquidateMax(
ILender lender,
address account
)
external
returns (
uint256 collateralAmount,
uint256 adjustedBorrowPart,
uint256 requiredDUSXAmount
);
/**
* @notice Liquidates specific amount for an account
* @param lender Address of the lending contract
* @param account Address to be liquidated
* @param borrowPart Amount of borrow position to liquidate
* @return collateralAmount Amount of collateral received
* @return adjustedBorrowPart Adjusted borrow amount after liquidation
* @return requiredDUSXAmount DUSX tokens needed to execute liquidation
* @dev Validates borrowPart against maximum liquidatable amount
*/
function liquidate(
ILender lender,
address account,
uint256 borrowPart
)
external
returns (
uint256 collateralAmount,
uint256 adjustedBorrowPart,
uint256 requiredDUSXAmount
);
/*//////////////////////////////////////////////////////////////
LIQUIDATION WITH CUSTOM RECIPIENT
//////////////////////////////////////////////////////////////*/
/**
* @notice Liquidates maximum amount and sends to specified recipient
* @param lender Address of the lending contract
* @param account Address to be liquidated
* @param recipient Address to receive liquidated assets
* @dev Combines max liquidation with custom recipient
*/
function liquidateMaxTo(
ILender lender,
address account,
address recipient
) external;
/**
* @notice Liquidates specific amount and sends to specified recipient
* @param lender Address of the lending contract
* @param account Address to be liquidated
* @param recipient Address to receive liquidated assets
* @param borrowPart Amount of borrow position to liquidate
* @dev Combines partial liquidation with custom recipient
*/
function liquidateTo(
ILender lender,
address account,
address recipient,
uint256 borrowPart
) external;
/*//////////////////////////////////////////////////////////////
LIQUIDATION PREVIEWS
//////////////////////////////////////////////////////////////*/
/**
* @notice Previews maximum possible liquidation amounts
* @param lender Address of the lending contract
* @param account Address to check
* @return liquidatable Whether the account can be liquidated
* @return requiredDUSXAmount DUSX tokens needed for liquidation
* @return adjustedBorrowPart Final borrow amount after liquidation
* @return returnedCollateralAmount Collateral amount to be received
* @dev Simulates liquidation without executing
*/
function previewMaxLiquidation(
ILender lender,
address account
)
external
view
returns (
bool liquidatable,
uint256 requiredDUSXAmount,
uint256 adjustedBorrowPart,
uint256 returnedCollateralAmount
);
/**
* @notice Previews specific liquidation amounts
* @param lender Address of the lending contract
* @param account Address to check
* @param borrowPart Amount of borrow position to liquidate
* @return liquidatable Whether the account can be liquidated
* @return requiredDUSXAmount DUSX tokens needed for liquidation
* @return adjustedBorrowPart Final borrow amount after liquidation
* @return returnedCollateralAmount Collateral amount to be received
* @dev Simulates partial liquidation without executing
*/
function previewLiquidation(
ILender lender,
address account,
uint256 borrowPart
)
external
view
returns (
bool liquidatable,
uint256 requiredDUSXAmount,
uint256 adjustedBorrowPart,
uint256 returnedCollateralAmount
);
/*//////////////////////////////////////////////////////////////
VIEW FUNCTIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Checks if an account is eligible for liquidation
* @param lender Address of the lending contract
* @param account Address to check
* @return bool True if account can be liquidated
* @dev Considers collateral ratio and position health
*/
function isLiquidatable(
ILender lender,
address account
) external view returns (bool);
/**
* @notice Returns the DUSX token contract used for liquidations
* @return IERC20Custom DUSX token interface
* @dev DUSX is required to execute liquidations
*/
function dusx() external view returns (IERC20Custom);
/**
* @notice Returns the helper utility contract
* @return IMiscHelper Helper interface for additional functions
* @dev Helper provides supporting calculations and checks
*/
function helper() external view returns (IMiscHelper);
}
// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24 <0.9.0;
import {ILender} from "./ILender.sol";
/**
* @title IMarketLens
* @dev Interface for viewing and analyzing lending market data
* @notice Provides functionality for:
* 1. Market size analysis
* 2. Borrowing metrics
* 3. Risk assessment data
*/
interface IMarketLens {
/*//////////////////////////////////////////////////////////////
MARKET METRICS
//////////////////////////////////////////////////////////////*/
/**
* @notice Calculates total borrowed amount from a specific lending market
* @param lender Address of the lending market to analyze
* @return uint256 Total borrowed amount in base units
* @dev Aggregates:
* · Active loan positions
* · Accrued interest
* · Pending liquidations
*
* Used for:
* · Market size analysis
* · Risk assessment
* · Protocol health monitoring
*/
function getTotalBorrowed(ILender lender) external view returns (uint256);
}
// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24 <0.9.0;
import {IERC20Custom} from "./IERC20Custom.sol";
/**
* @title IMinter
* @dev Interface for the Minter contract
*/
interface IMinter {
/**
* @notice Enables whitelist minting phase
*/
function enableWhitelistMint() external;
/**
* @notice Enables public minting phase
*/
function enablePublicMint() external;
/**
* @notice Adds a wallet to the whitelist
* @param wallet Wallet address to whitelist
*/
function addToWhitelist(address wallet) external;
/**
* @notice Mints tokens during whitelist phase
* @param stablecoin Stablecoin used for minting
* @param stableAmount Amount of stablecoin to mint against
*/
function whitelistMint(
IERC20Custom stablecoin,
uint256 stableAmount
) external;
/**
* @notice Mints tokens during public phase
* @param stablecoin Stablecoin used for minting
* @param stableAmount Amount of stablecoin to mint against
*/
function publicMint(IERC20Custom stablecoin, uint256 stableAmount) external;
/**
* @notice Mints remaining token supply
* @param stablecoin Stablecoin used for minting
*/
function mintRemainingSupply(IERC20Custom stablecoin) external;
/**
* @notice Sends accumulated DUSX to floor contract
*/
function sendToFloorDUSX() external;
/**
* @notice Verifies if a wallet is whitelisted
* @param wallet Address to verify
* @return bool Whitelist status
*/
function verifyWallet(address wallet) external view returns (bool);
/**
* @notice Calculates mint amount for given stablecoin input
* @param stablecoin Stablecoin used for calculation
* @param stableAmount Amount of stablecoin
* @return uint256 Calculated mint amount
*/
function calcMintAmount(
IERC20Custom stablecoin,
uint256 stableAmount
) external view returns (uint256);
/**
* @notice Gets the current token reserve
* @return uint256 Current token reserve
*/
function tokenReserve() external view returns (uint256);
/**
* @notice Gets the current mint ratio
* @return uint256 Current mint ratio
*/
function getCurrentRatio() external view returns (uint256);
/**
* @notice Gets the current mint rate
* @return uint256 Current mint rate
*/
function getCurrentRate() external view returns (uint256);
}
// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24 <0.9.0;
import {IDynamicInterestRate} from "./IDynamicInterestRate.sol";
import {IFeesDistributor} from "./IFees.sol";
import {IFeesWithdrawer} from "./IFees.sol";
import {IFloor} from "./IFloor.sol";
import {ILender} from "./ILender.sol";
import {ILenderOwner} from "./ILenderOwner.sol";
import {ILiquidationHelper} from "./ILiquidationHelper.sol";
import {IMarketLens} from "./IMarketLens.sol";
import {IPSM} from "./IPSM.sol";
import {IRepayHelper} from "./IRepayHelper.sol";
import {IStakedDUSX} from "./IStakedDUSX.sol";
import {ISupplyHangingCalculator} from "./ISupplyHangingCalculator.sol";
/**
* @title IMiscHelper
* @dev Interface for miscellaneous helper functions across the protocol
* @notice Provides comprehensive helper methods for:
* 1. Protocol configuration and parameter management
* 2. Floor token operations
* 3. Staked DUSX token management
* 4. PSM (Peg Stability Module) operations
* 5. Lending operations including borrowing and repayment
* 6. System-wide view functions
*
* This interface acts as a central utility hub for coordinating
* various protocol components and simplifying complex operations
*/
interface IMiscHelper {
/*//////////////////////////////////////////////////////////////
CONFIGURATION FUNCTIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Sets the supply hanging calculator contract
* @param supplyHangingCalculator_ New calculator contract address
* @dev Used for calculating supply adjustments
*/
function setSupplyHangingCalculator(
ISupplyHangingCalculator supplyHangingCalculator_
) external;
/**
* @notice Sets core protocol parameters and contract addresses
* @param repayHelper_ Repayment helper contract
* @param liquidationHelper_ Liquidation helper contract
* @param dynamicInterestRate_ Interest rate calculator
* @param feesDistributor_ Fee distribution contract
* @param feesWithdrawer_ Fee withdrawal contract
* @param lenderOwner_ Lender owner contract
* @param marketLens_ Market data viewer contract
* @dev Updates all main protocol component addresses
*/
function setParameters(
IRepayHelper repayHelper_,
ILiquidationHelper liquidationHelper_,
IDynamicInterestRate dynamicInterestRate_,
IFeesDistributor feesDistributor_,
IFeesWithdrawer feesWithdrawer_,
ILenderOwner lenderOwner_,
IMarketLens marketLens_
) external;
/**
* @notice Sets the list of active lender contracts
* @param lenders_ Array of lender addresses
* @dev Updates the protocol's lending markets
*/
function setLenders(ILender[] memory lenders_) external;
/**
* @notice Sets the list of PSM contracts
* @param pegStabilityModules_ Array of PSM addresses
* @dev Updates available stablecoin PSM modules
*/
function setPegStabilityModules(
IPSM[] memory pegStabilityModules_
) external;
/*//////////////////////////////////////////////////////////////
FLOOR TOKEN OPERATIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Deposits Floor tokens into the protocol
* @param amount Amount of Floor tokens to deposit
*/
function depositFloor(uint256 amount) external;
/**
* @notice Refunds Floor tokens from the protocol
* @param amount Amount of Floor tokens to refund
*/
function refundFloor(uint256 amount) external;
/*//////////////////////////////////////////////////////////////
STAKED DUSX OPERATIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Deposits DUSX tokens for staking
* @param amount Amount of DUSX to stake
*/
function depositStakedDUSX(uint256 amount) external;
/**
* @notice Withdraws staked DUSX tokens
* @param amount Amount of staked DUSX to withdraw
*/
function withdrawStakedDUSX(uint256 amount) external;
/*//////////////////////////////////////////////////////////////
PSM OPERATIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Swaps DUSX for stablecoin through PSM
* @param psm PSM contract to use for swap
* @param receiver Address to receive stablecoins
* @param amountDUSX Amount of DUSX to swap
*/
function psmSwapDUSXForStable(
IPSM psm,
address receiver,
uint256 amountDUSX
) external;
/**
* @notice Swaps stablecoin for DUSX through PSM
* @param psm PSM contract to use for swap
* @param receiver Address to receive DUSX
* @param amountStable Amount of stablecoin to swap
*/
function psmSwapStableForDUSX(
IPSM psm,
address receiver,
uint256 amountStable
) external;
/*//////////////////////////////////////////////////////////////
LENDING OPERATIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Withdraws borrowed tokens from vault
* @param lender Lender contract to withdraw from
* @param amount Amount to withdraw
*/
function lenderBorrowVaultWithdraw(ILender lender, uint256 amount) external;
/**
* @notice Executes a borrow operation
* @param lender Lender contract to borrow from
* @param amount Amount to borrow
*/
function lenderBorrow(ILender lender, uint256 amount) external;
/**
* @notice Repays borrowed tokens
* @param lender Lender contract to repay to
* @param payer Address paying the debt
* @param to Address receiving any excess
* @param skim Whether to skim tokens from contract
* @param part Amount of borrow part to repay
*/
function lenderRepay(
ILender lender,
address payer,
address to,
bool skim,
uint256 part
) external;
/**
* @notice Executes liquidation for multiple users
* @param lender Lender contract to liquidate from
* @param liquidator Address performing liquidation
* @param users Array of addresses to liquidate
* @param maxBorrowParts Maximum borrow parts to liquidate per user
* @param to Address to receive liquidated assets
*/
function lenderLiquidate(
ILender lender,
address liquidator,
address[] memory users,
uint256[] memory maxBorrowParts,
address to
) external;
/*//////////////////////////////////////////////////////////////
VIEW FUNCTIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Returns current APR for staked DUSX
* @return uint256 Annual percentage rate
*/
function aprStakedDUSX() external view returns (uint256);
/**
* @notice Returns repayment helper contract
*/
function repayHelper() external view returns (IRepayHelper);
/**
* @notice Returns liquidation helper contract
*/
function liquidationHelper() external view returns (ILiquidationHelper);
/**
* @notice Returns dynamic interest rate calculator
*/
function dynamicInterestRate() external view returns (IDynamicInterestRate);
/**
* @notice Returns floor token contract
*/
function floor() external view returns (IFloor);
/**
* @notice Returns fees distributor contract
*/
function feesDistributor() external view returns (IFeesDistributor);
/**
* @notice Returns fees withdrawer contract
*/
function feesWithdrawer() external view returns (IFeesWithdrawer);
/**
* @notice Returns lender contract at specified index
* @param index Position in lenders array
*/
function lenders(uint256 index) external view returns (ILender);
/**
* @notice Returns total number of lender contracts
*/
function lendersLength() external view returns (uint256);
/**
* @notice Returns lender owner contract
*/
function lenderOwner() external view returns (ILenderOwner);
/**
* @notice Returns market lens contract
*/
function marketLens() external view returns (IMarketLens);
/**
* @notice Returns PSM contract at specified index
* @param index Position in PSM array
*/
function pegStabilityModules(uint256 index) external view returns (IPSM);
/**
* @notice Returns total number of PSM contracts
*/
function pegStabilityModulesLength() external view returns (uint256);
/**
* @notice Returns staked DUSX token contract
*/
function stDUSX() external view returns (IStakedDUSX);
/**
* @notice Returns supply hanging calculator contract
*/
function supplyHangingCalculator()
external
view
returns (ISupplyHangingCalculator);
}
// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24 <0.9.0;
/**
* @title IOracle
* @dev Interface for basic price feed operations
* @notice Defines functionality for:
* 1. Asset price retrieval
* 2. Price precision handling
*/
interface IOracle {
/*//////////////////////////////////////////////////////////////
PRICE QUERIES
//////////////////////////////////////////////////////////////*/
/**
* @notice Retrieves current asset price
* @param asset Address of the asset to price
* @return uint256 Current price in base units with precision
* @dev Provides:
* · Latest price data
* · Standardized precision
* · Asset valuation
*
* Note: Check implementation for specific precision details
*/
function getPrice(address asset) external view returns (uint256);
}
/**
* @title ITwapOracle
* @dev Interface for time-weighted average price calculations
* @notice Defines functionality for:
* 1. TWAP updates
* 2. Time-weighted calculations
* 3. Price smoothing
*/
interface ITwapOracle {
/*//////////////////////////////////////////////////////////////
TWAP OPERATIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Updates time-weighted average price
* @param asset Address of the asset to update
* @return uint256 New TWAP value in base units
* @dev Calculates:
* · Time-weighted price
* · Cumulative values
* · Price averages
*
* Features:
* · Manipulation resistance
* · Smoothing effect
* · Historical tracking
*/
function updateTwap(address asset) external returns (uint256);
}
// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24 <0.9.0;
import {IERC20Custom} from "./IERC20Custom.sol";
/**
* @title IPSM
* @dev Interface for Peg Stability Module (PSM) operations
* @notice Defines functionality for:
* 1. Stablecoin/DUSX swaps
* 2. Peg maintenance
* 3. Supply tracking
*/
interface IPSM {
/*//////////////////////////////////////////////////////////////
SWAP OPERATIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Executes stablecoin to DUSX swap
* @param msgSender Address initiating the swap
* @param receiver Address receiving the DUSX
* @param stableTokenAmount Amount of stablecoins to swap
* @dev Handles:
* · Stablecoin deposit
* · DUSX minting
* · Supply tracking
*/
function swapStableForDUSX(
address msgSender,
address receiver,
uint256 stableTokenAmount
) external;
/**
* @notice Executes DUSX to stablecoin swap
* @param msgSender Address initiating the swap
* @param receiver Address receiving the stablecoins
* @param stableTokenAmount Amount of stablecoins to receive
* @dev Handles:
* · DUSX burning
* · Stablecoin release
* · Supply adjustment
*/
function swapDUSXForStable(
address msgSender,
address receiver,
uint256 stableTokenAmount
) external;
/*//////////////////////////////////////////////////////////////
VIEW FUNCTIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Retrieves the stablecoin token contract
* @return IERC20Custom Stablecoin token interface
* @dev Used for:
* · Token transfers
* · Balance checks
* · Allowance verification
*/
function stableToken() external view returns (IERC20Custom);
/**
* @notice Returns total DUSX tokens minted through PSM
* @return uint256 Total minted amount in base units
* @dev Tracks:
* · Total supply impact
* · PSM utilization
* · Protocol growth metrics
*/
function dusxMinted() external view returns (uint256);
/**
* @notice Returns the maximum amount of DUSX that can be minted through PSM
* @return uint256 Maximum mintable amount in base units
* @dev Used for:
* · Supply control
* · Risk management
* · Protocol safety
*/
function dusxMintCap() external view returns (uint256);
}
// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24 <0.9.0;
import {IERC20Custom} from "./IERC20Custom.sol";
import {ILender} from "./ILender.sol";
import {IMiscHelper} from "./IMiscHelper.sol";
/**
* @title IRepayHelper
* @dev Interface for streamlined loan repayment operations and management
* @notice Defines functionality for:
* 1. Loan repayment processing
* 2. Multi-loan management
* 3. Helper contract integration
* 4. Token interactions
*/
interface IRepayHelper {
/*//////////////////////////////////////////////////////////////
CONFIGURATION
//////////////////////////////////////////////////////////////*/
/*//////////////////////////////////////////////////////////////
REPAYMENT OPERATIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Processes partial loan repayment
* @param lender Address of the lending contract
* @param to Address whose loan is being repaid
* @param amount Amount to repay in base units
* @return part Share of the loan repaid
* @dev Handles:
* · Token transfers
* · Loan accounting
* · Share calculations
*
* Requirements:
* · Amount > 0
* · Sufficient balance
* · Valid addresses
*/
function repayAmount(
ILender lender,
address to,
uint256 amount
) external returns (uint256 part);
/**
* @notice Processes complete loan repayment
* @param lender Address of the lending contract
* @param to Address whose loan is being repaid
* @return amount Total amount repaid in base units
* @dev Manages:
* · Full debt calculation
* · Complete repayment
* · Account settlement
*
* Effects:
* · Clears entire debt
* · Updates balances
* · Emits events
*/
function repayTotal(
ILender lender,
address to
) external returns (uint256 amount);
/**
* @notice Processes multiple complete loan repayments
* @param lender Address of the lending contract
* @param tos Array of addresses whose loans are being repaid
* @return amount Total amount repaid across all loans
* @dev Executes:
* · Batch processing
* · Multiple settlements
* · Aggregate accounting
*
* Optimizations:
* · Gas efficient
* · Bulk processing
* · Single transaction
*/
function repayTotalMultiple(
ILender lender,
address[] calldata tos
) external returns (uint256 amount);
/*//////////////////////////////////////////////////////////////
VIEW FUNCTIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Retrieves DUSX token contract
* @return IERC20Custom Interface of the DUSX token
* @dev Used for:
* · Token operations
* · Balance checks
* · Allowance verification
*/
function dusx() external view returns (IERC20Custom);
/**
* @notice Retrieves helper contract
* @return IMiscHelper Interface of the helper contract
* @dev Provides:
* · Helper functionality
* · Integration access
* · Utility methods
*/
function helper() external view returns (IMiscHelper);
}
// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24 <0.9.0;
import {IERC20Token} from "./IERC20Token.sol";
/**
* @title IStableOwner Interface
* @dev Interface for StableOwner contract that manages stable token supply
* @notice Defines the external interface for stable token supply management
*/
interface IStableOwner {
/*//////////////////////////////////////////////////////////////
EVENTS
//////////////////////////////////////////////////////////////*/
/// @notice Emitted when stable token contract is updated
/// @param stable New stable token contract address
event StableSet(IERC20Token indexed stable);
/// @notice Emitted when new tokens are minted
/// @param account Recipient of minted tokens
/// @param amount Amount of tokens minted
event TokensMinted(address indexed account, uint256 amount);
/// @notice Emitted when tokens are burned
/// @param account Account tokens were burned from
/// @param amount Amount of tokens burned
event TokensBurned(address indexed account, uint256 amount);
/*//////////////////////////////////////////////////////////////
FUNCTIONS
//////////////////////////////////////////////////////////////*/
/// @notice Updates the stable token contract address
/// @param stable_ New stable token contract address
function setStable(IERC20Token stable_) external;
/// @notice Creates new stable tokens
/// @param account Address to receive minted tokens
/// @param amount Number of tokens to mint
function mint(address account, uint256 amount) external;
/// @notice Destroys existing stable tokens
/// @param account Address to burn tokens from
/// @param amount Number of tokens to burn
function burn(address account, uint256 amount) external;
/// @notice The managed stable token contract
/// @return The IERC20Token interface of the stable token
function stable() external view returns (IERC20Token);
}
// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24 <0.9.0;
/**
* @title IStakedDUSX
* @dev Interface for staked DUSX token operations and reward distribution
* @notice Defines functionality for:
* 1. DUSX token staking
* 2. Reward distribution
* 3. Position management
*/
interface IStakedDUSX {
/*//////////////////////////////////////////////////////////////
REWARD DISTRIBUTION
//////////////////////////////////////////////////////////////*/
/**
* @notice Distributes protocol fees as staking rewards
* @param amount Amount of fees to distribute in base units
* @dev Handles:
* · Pro-rata distribution
* · Reward accounting
* · Distribution events
*
* Rewards are:
* · Automatically calculated
* · Immediately available
* · Proportional to stake
*/
function distributeFees(uint256 amount) external;
/**
* @notice Claims pending fee rewards for the caller
* @return claimedAmount Amount of fees claimed
* @dev Allows users to manually claim their accumulated fees
*/
function claimFees() external returns (uint256 claimedAmount);
/*//////////////////////////////////////////////////////////////
STAKING OPERATIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Processes DUSX token deposits for staking
* @param from Address providing the tokens
* @param to Address receiving the staked position
* @param amount Quantity of tokens to stake in base units
* @dev Manages:
* · Token transfers
* · Position creation
* · Reward calculations
*
* Supports:
* · Direct deposits
* · Delegated deposits
* · Position tracking
*/
function deposit(address from, address to, uint256 amount) external;
/**
* @notice Initiates a withdrawal from staked DUSX
* @param amount Amount of tokens to withdraw
*/
function beginWithdrawal(uint256 amount) external;
/**
* @notice Processes withdrawal of staked DUSX tokens
* @param account Address withdrawing tokens
* @dev Handles:
* · Position updates
* · Reward claims
* · Token transfers
*
* Ensures:
* · Sufficient balance
* · Reward distribution
* · Clean exit
*/
function withdraw(address account) external;
/**
* @notice Views pending unclaimed fees for an account
* @param account Address to check for pending fees
* @return pendingAmount Amount of pending fees available to claim
* @dev Calculates based on the fee accumulator and account's last claimed value
*/
function pendingFees(
address account
) external view returns (uint256 pendingAmount);
}
// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24 <0.9.0;
/**
* @title ISupplyHangingCalculator
* @dev Interface for calculating and managing token supply adjustments
* @notice Defines functionality for:
* 1. Supply hanging calculations
* 2. Safety margin management
* 3. Risk-adjusted metrics
*/
interface ISupplyHangingCalculator {
/*//////////////////////////////////////////////////////////////
SAFETY PARAMETERS
//////////////////////////////////////////////////////////////*/
/**
* @notice Retrieves current safety margin for supply calculations
* @return uint256 Safety margin percentage scaled by 1e18
* @dev Used for:
* · Risk adjustment
* · Supply buffer
* · Protocol protection
*/
function safetyMargin() external view returns (uint256);
/*//////////////////////////////////////////////////////////////
SUPPLY HANGING CALCULATIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Calculates current supply hanging with safety margins
* @return uint256 Risk-adjusted supply hanging in base units
* @dev Includes:
* · Safety margin application
* · Risk adjustments
* · Protocol constraints
*
* Used for:
* · Safe supply management
* · Conservative adjustments
* · Risk-aware operations
*/
function getSupplyHanging() external view returns (uint256);
/**
* @notice Calculates raw supply hanging without safety margins
* @return uint256 Unadjusted supply hanging in base units
* @dev Provides:
* · Raw calculations
* · No safety buffers
* · Maximum theoretical values
*
* Used for:
* · Analysis purposes
* · Maximum bounds
* · Stress testing
*/
function getSupplyHangingUnsafe() external view returns (uint256);
}
// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24 <0.9.0;
import {Rebase} from "../library/AuxRebase.sol";
import {IERC20Custom} from "./IERC20Custom.sol";
/**
* @title IVault
* @dev Interface for advanced vault operations with elastic share system
* @notice Defines functionality for:
* 1. Token custody and management
* 2. Share-based accounting
* 3. Elastic supply mechanics
* 4. Amount/share conversions
*/
interface IVault {
/*//////////////////////////////////////////////////////////////
DEPOSIT OPERATIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Processes token deposits into vault
* @param token Token contract to deposit
* @param from Source of tokens
* @param to Recipient of shares
* @param amount Token amount (in base units, 0 for share-based)
* @param share Share amount (0 for amount-based)
* @return amountIn Actual tokens deposited
* @return shareIn Actual shares minted
* @dev Handles:
* · Token transfers
* · Share minting
* · Balance updates
*
* Requirements:
* · Valid token contract
* · Authorized caller
* · Sufficient balance
* · Either amount or share > 0
*
* Note: Only one of amount/share should be non-zero
*/
function deposit(
IERC20Custom token,
address from,
address to,
uint256 amount,
uint256 share
) external returns (uint256 amountIn, uint256 shareIn);
/*//////////////////////////////////////////////////////////////
WITHDRAWAL OPERATIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Processes token withdrawals from vault
* @param token Token contract to withdraw
* @param from Source of shares
* @param to Recipient of tokens
* @param amount Token amount (in base units, 0 for share-based)
* @param share Share amount (0 for amount-based)
* @return amountOut Actual tokens withdrawn
* @return shareOut Actual shares burned
* @dev Manages:
* · Share burning
* · Token transfers
* · Balance updates
*
* Requirements:
* · Valid token contract
* · Sufficient shares
* · Either amount or share > 0
* · Authorized withdrawal
*
* Security:
* · Validates balances
* · Checks permissions
* · Updates state atomically
*/
function withdraw(
IERC20Custom token,
address from,
address to,
uint256 amount,
uint256 share
) external returns (uint256 amountOut, uint256 shareOut);
/*//////////////////////////////////////////////////////////////
SHARE TRANSFERS
//////////////////////////////////////////////////////////////*/
/**
* @notice Transfers vault shares between accounts
* @param token Associated token contract
* @param from Source of shares
* @param to Recipient of shares
* @param share Amount of shares to transfer
* @dev Executes:
* · Direct share movement
* · Balance updates
* · Event emission
*
* Requirements:
* · Sufficient share balance
* · Valid addresses
* · Share amount > 0
*
* Note: Bypasses amount calculations for efficiency
*/
function transfer(
IERC20Custom token,
address from,
address to,
uint256 share
) external;
/*//////////////////////////////////////////////////////////////
BALANCE QUERIES
//////////////////////////////////////////////////////////////*/
/**
* @notice Retrieves account's vault share balance
* @param token Token contract to query
* @param account Address to check
* @return uint256 Share balance
* @dev Provides:
* · Raw share balance
* · Without conversion
* · Current state
*
* Use toAmount() to convert to token amount
*/
function balanceOf(
IERC20Custom token,
address account
) external view returns (uint256);
/*//////////////////////////////////////////////////////////////
CONVERSION OPERATIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Converts token amount to vault shares
* @param token Token contract for conversion
* @param amount Amount of tokens to convert
* @param roundUp Whether to round up result
* @return share Equivalent share amount
* @dev Calculates:
* · Share equivalent
* · Based on totals
* · Handles precision
*
* Rounding:
* true = ceiling (≥)
* false = floor (≤)
*/
function toShare(
IERC20Custom token,
uint256 amount,
bool roundUp
) external view returns (uint256 share);
/**
* @notice Converts vault shares to token amount
* @param token Token contract for conversion
* @param share Amount of shares to convert
* @param roundUp Whether to round up result
* @return amount Equivalent token amount
* @dev Calculates:
* · Token equivalent
* · Based on totals
* · Handles precision
*
* Rounding:
* true = ceiling (≥)
* false = floor (≤)
*/
function toAmount(
IERC20Custom token,
uint256 share,
bool roundUp
) external view returns (uint256 amount);
/**
* @notice Gets the list of active controllers
* @return Array of controller addresses
*/
function getControllers() external view returns (address[] memory);
/*//////////////////////////////////////////////////////////////
VAULT TOTALS
//////////////////////////////////////////////////////////////*/
/**
* @notice Retrieves vault's total supply tracking
* @param token Token contract to query
* @return vaultTotals Rebase struct containing:
* · elastic: Total token amount
* · base: Total shares
* @dev Provides:
* · Current vault state
* · Supply tracking
* · Conversion basis
*
* Used for:
* · Share calculations
* · Amount conversions
* · State validation
*/
function totals(
IERC20Custom token
) external view returns (Rebase memory vaultTotals);
}
// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24 <0.9.0;
/**
* @title IVoteEscrowedSTTX
* @dev Interface for vote-escrowed STTX (veSTTX) token operations
* @notice Defines functionality for:
* 1. Token withdrawal management
* 2. Escrow position handling
* 3. Voting power release
*/
interface IVoteEscrowedSTTX {
/*//////////////////////////////////////////////////////////////
WITHDRAWAL OPERATIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Processes withdrawal of escrowed STTX tokens
* @dev Handles:
* · Lock period verification
* · Position liquidation
* · Token transfers
*
* Requirements:
* · Lock period expired
* · Active position exists
* · Caller is position owner
*
* Effects:
* · Releases locked tokens
* · Removes voting power
* · Clears escrow position
*/
function withdraw() external;
}
// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24 <0.9.0;
/**
* @title Rebase Library
* @dev Library for handling elastic supply token calculations and adjustments
* @notice This library provides mathematical operations for elastic/base token conversions
* and supply adjustments. It handles two key concepts:
*
* 1. Elastic Supply: The actual total supply that can expand or contract
* 2. Base Supply: The underlying base amount that remains constant
*/
/*//////////////////////////////////////////////////////////////
TYPES
//////////////////////////////////////////////////////////////*/
/**
* @dev Core data structure for elastic supply tracking
* @param elastic Current elastic (rebased) supply
* @param base Current base (non-rebased) supply
*/
struct Rebase {
uint256 elastic;
uint256 base;
}
/**
* @title AuxRebase
* @dev Auxiliary functions for elastic supply calculations
* @notice Provides safe mathematical operations for elastic/base conversions
* with optional rounding control
*/
library AuxRebase {
/*//////////////////////////////////////////////////////////////
ELASTIC SUPPLY OPERATIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Increases the elastic supply
* @param total Current total supply state
* @param elastic Amount to add to elastic supply
* @return newElastic Updated elastic supply after addition
*/
function addElastic(
Rebase storage total,
uint256 elastic
) internal returns (uint256 newElastic) {
newElastic = total.elastic += elastic;
}
/**
* @notice Decreases the elastic supply
* @param total Current total supply state
* @param elastic Amount to subtract from elastic supply
* @return newElastic Updated elastic supply after subtraction
*/
function subElastic(
Rebase storage total,
uint256 elastic
) internal returns (uint256 newElastic) {
newElastic = total.elastic -= elastic;
}
/*//////////////////////////////////////////////////////////////
CONVERSION OPERATIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Converts an elastic amount to its base amount
* @param total Current total supply state
* @param elastic Amount of elastic tokens to convert
* @param roundUp If true, rounds up the result
* @return base Equivalent amount in base units
* @dev
* · If elastic supply is 0, returns elastic amount as base
* · Handles potential precision loss during conversion
* · Rounding can cause slight variations in converted amounts
* · Recommended for scenarios requiring precise supply tracking
*
* Rounding Behavior:
* · roundUp = false: Always rounds down (truncates)
* · roundUp = true: Rounds up if there's a fractional remainder
*
* Edge Cases:
* · total.elastic == 0: Returns input elastic as base
* · Potential for minimal precision differences
*/
function toBase(
Rebase memory total,
uint256 elastic,
bool roundUp
) internal pure returns (uint256 base) {
if (total.elastic == 0) {
base = elastic;
} else {
base = (elastic * total.base) / total.elastic;
if (roundUp && (base * total.elastic) / total.base < elastic) {
base++;
}
}
}
/**
* @notice Converts a base amount to its elastic amount
* @param total Current total supply state
* @param base Amount of base tokens to convert
* @param roundUp If true, rounds up the result
* @return elastic Equivalent amount in elastic units
* @dev
* · If base supply is 0, returns base amount as elastic
* · Handles potential precision loss during conversion
* · Rounding can cause slight variations in converted amounts
* · Recommended for scenarios requiring precise supply tracking
*
* Rounding Behavior:
* · roundUp = false: Always rounds down (truncates)
* · roundUp = true: Rounds up if there's a fractional remainder
*
* Edge Cases:
* · total.base == 0: Returns input base as elastic
* · Potential for minimal precision differences
*/
function toElastic(
Rebase memory total,
uint256 base,
bool roundUp
) internal pure returns (uint256 elastic) {
if (total.base == 0) {
elastic = base;
} else {
elastic = (base * total.elastic) / total.base;
if (roundUp && (elastic * total.base) / total.elastic < base) {
elastic++;
}
}
}
/*//////////////////////////////////////////////////////////////
COMBINED OPERATIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Adds elastic tokens and calculates corresponding base amount
* @param total Current total supply state
* @param elastic Amount of elastic tokens to add
* @param roundUp If true, rounds up base conversion
* @return (Rebase, uint256) Updated total supply and calculated base amount
*/
function add(
Rebase memory total,
uint256 elastic,
bool roundUp
) internal pure returns (Rebase memory, uint256 base) {
base = toBase(total, elastic, roundUp);
total.elastic += elastic;
total.base += base;
return (total, base);
}
/**
* @notice Subtracts base tokens and calculates corresponding elastic amount
* @param total Current total supply state
* @param base Amount of base tokens to subtract
* @param roundUp If true, rounds up elastic conversion
* @return (Rebase, uint256) Updated total supply and calculated elastic amount
*/
function sub(
Rebase memory total,
uint256 base,
bool roundUp
) internal pure returns (Rebase memory, uint256 elastic) {
elastic = toElastic(total, base, roundUp);
total.elastic -= elastic;
total.base -= base;
return (total, elastic);
}
/**
* @notice Adds specific amounts to both elastic and base supplies
* @param total Current total supply state
* @param elastic Amount of elastic tokens to add
* @param base Amount of base tokens to add
* @return Rebase Updated total supply after addition
*/
function add(
Rebase memory total,
uint256 elastic,
uint256 base
) internal pure returns (Rebase memory) {
total.elastic += elastic;
total.base += base;
return total;
}
/**
* @notice Subtracts specific amounts from both elastic and base supplies
* @param total Current total supply state
* @param elastic Amount of elastic tokens to subtract
* @param base Amount of base tokens to subtract
* @return Rebase Updated total supply after subtraction
*/
function sub(
Rebase memory total,
uint256 elastic,
uint256 base
) internal pure returns (Rebase memory) {
total.elastic -= elastic;
total.base -= base;
return total;
}
}
// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24 <0.9.0;
import {Ownable} from "../abstract/Ownable.sol";
import {ReentrancyGuard} from "../abstract/ReentrancyGuard.sol";
import {Rebase, AuxRebase} from "../library/AuxRebase.sol";
import {IBaseContracts} from "../interface/IBaseContracts.sol";
import {IDynamicInterestRate} from "../interface/IDynamicInterestRate.sol";
import {IERC20Custom} from "../interface/IERC20Custom.sol";
import {IFloor} from "../interface/IFloor.sol";
import {IFeesDistributor} from "../interface/IFees.sol";
import {IFeesWithdrawer} from "../interface/IFees.sol";
import {ILender} from "../interface/ILender.sol";
import {ILenderOwner} from "../interface/ILenderOwner.sol";
import {ILiquidationHelper} from "../interface/ILiquidationHelper.sol";
import {IMarketLens} from "../interface/IMarketLens.sol";
import {IPSM} from "../interface/IPSM.sol";
import {IRepayHelper} from "../interface/IRepayHelper.sol";
import {IStakedDUSX} from "../interface/IStakedDUSX.sol";
import {ISupplyHangingCalculator} from "../interface/ISupplyHangingCalculator.sol";
import {IVault} from "../interface/IVault.sol";
/**
* @title MiscHelper
* @dev Central coordinator for protocol operations and interactions
* @notice Provides:
* · Core protocol operation coordination
* · Cross-contract interaction management
* · System-wide parameter updates
*/
contract MiscHelper is Ownable, ReentrancyGuard {
using AuxRebase for Rebase;
/*//////////////////////////////////////////////////////////////
STORAGE
//////////////////////////////////////////////////////////////*/
/// @notice Precision constants
uint256 public constant TENK_PRECISION = 10_000;
/// @notice Repayment helper contract
IRepayHelper public repayHelper;
/// @notice Liquidation helper contract
ILiquidationHelper public liquidationHelper;
/// @notice Dynamic interest rate model
IDynamicInterestRate public dynamicInterestRate;
/// @notice Floor price contract
IFloor public immutable floor;
/// @notice Fees distribution contract
IFeesDistributor public feesDistributor;
/// @notice Fees withdrawal contract
IFeesWithdrawer public feesWithdrawer;
/// @notice Lender ownership management contract
ILenderOwner public lenderOwner;
/// @notice Market analytics contract
IMarketLens public marketLens;
/// @notice Array of peg stability module contracts
IPSM[] public pegStabilityModules;
/// @notice Staked DUSX token contract
IStakedDUSX public immutable stDUSX;
/// @notice Supply hanging calculator contract
ISupplyHangingCalculator public supplyHangingCalculator;
/// @notice Base contracts registry
IBaseContracts public immutable baseContracts;
/// @notice Vault contract reference
IVault public immutable vault;
/// @notice Flag to track if parameters have been initialized
bool public parametersSet;
/*//////////////////////////////////////////////////////////////
CUSTOM ERRORS
//////////////////////////////////////////////////////////////*/
/// @notice Thrown when a zero address is provided
error ZeroAddress();
/// @notice Thrown when parameters are already set
error AlreadyInitialized();
/*//////////////////////////////////////////////////////////////
MODIFIERS
//////////////////////////////////////////////////////////////*/
/**
* @notice Restricts function access to repay helper
* @dev Reverts if caller is not the repay helper contract
*/
modifier onlyRepayHelper() {
if (address(repayHelper) != _msgSender()) {
revert UnauthorizedAccount(_msgSender());
}
_;
}
/**
* @notice Restricts function access to liquidation helper
* @dev Reverts if caller is not the liquidation helper contract
*/
modifier onlyLiquidationHelper() {
if (address(liquidationHelper) != _msgSender()) {
revert UnauthorizedAccount(_msgSender());
}
_;
}
/*//////////////////////////////////////////////////////////////
CONSTRUCTOR
//////////////////////////////////////////////////////////////*/
/**
* @notice Initializes the MiscHelper contract
* @param baseContracts_ Base contracts registry address
*/
constructor(IBaseContracts baseContracts_) {
_ensureNonzeroAddress(address(baseContracts_));
baseContracts = baseContracts_;
vault = baseContracts.vault();
floor = baseContracts.floor();
stDUSX = baseContracts.stDUSX();
supplyHangingCalculator = baseContracts.supplyCalculator();
_ensureNonzeroAddress(address(vault));
_ensureNonzeroAddress(address(floor));
_ensureNonzeroAddress(address(stDUSX));
_ensureNonzeroAddress(address(supplyHangingCalculator));
// Initialize PSMs
IPSM[] memory psms_ = new IPSM[](2);
psms_[0] = baseContracts.psmCircle();
psms_[1] = baseContracts.psmTether();
if (address(psms_[0]) == address(0) || address(psms_[1]) == address(0))
revert ZeroAddress();
pegStabilityModules = psms_;
}
/*//////////////////////////////////////////////////////////////
CONFIGURATION FUNCTIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Updates core protocol parameters by fetching from BaseContracts
*/
function setParameters() external onlyOwner {
if (parametersSet) {
revert AlreadyInitialized();
}
// Get helper contracts
repayHelper = baseContracts.repayHelper();
liquidationHelper = baseContracts.liquidationHelper();
marketLens = baseContracts.marketLens();
// Get other contracts
dynamicInterestRate = baseContracts.dynamicInterestRate();
feesDistributor = baseContracts.feesDistributor();
feesWithdrawer = baseContracts.feesWithdrawer();
lenderOwner = baseContracts.lenderOwner();
// Validate all addresses
_ensureNonzeroAddress(address(repayHelper));
_ensureNonzeroAddress(address(liquidationHelper));
_ensureNonzeroAddress(address(marketLens));
_ensureNonzeroAddress(address(dynamicInterestRate));
_ensureNonzeroAddress(address(feesDistributor));
_ensureNonzeroAddress(address(feesWithdrawer));
_ensureNonzeroAddress(address(lenderOwner));
parametersSet = true;
}
/*//////////////////////////////////////////////////////////////
FLOOR OPERATIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Deposits into the floor
* @param amount Deposit amount
* @dev Includes reentrancy protection
*
* Requirements:
* · Valid deposit amount
*
* Effects:
* · Deposits into floor
* · Updates interest rates
*/
function depositFloor(uint256 amount) external {
floor.deposit(_msgSender(), amount);
_updateInterestRateAndBorrowLimit();
}
/**
* @notice Refunds from the floor
* @param amount Refund amount
* @dev Includes reentrancy protection
*
* Requirements:
* · Valid refund amount
*
* Effects:
* · Refunds from floor
* · Updates interest rates
*/
function refundFloor(uint256 amount) external nonReentrant {
_distributeFees();
floor.refund(_msgSender(), amount);
_updateInterestRateAndBorrowLimit();
}
/*//////////////////////////////////////////////////////////////
STAKED DUSX OPERATIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Deposits into staked DUSX
* @param amount Deposit amount
* @dev Includes reentrancy protection
*
* Requirements:
* · Valid deposit amount
*
* Effects:
* · Deposits into staked DUSX
* · Updates interest rates
*/
function depositStakedDUSX(uint256 amount) external nonReentrant {
_distributeFees();
stDUSX.deposit(_msgSender(), _msgSender(), amount);
_updateInterestRateAndBorrowLimit();
}
/**
* @notice Withdraws from staked DUSX
* @dev Includes reentrancy protection
*
* Requirements:
* · Valid withdrawal amount
*
* Effects:
* · Withdraws from staked DUSX
* · Updates interest rates
*/
function withdrawStakedDUSX() external nonReentrant {
_distributeFees();
stDUSX.withdraw(_msgSender());
_updateInterestRateAndBorrowLimit();
}
/*//////////////////////////////////////////////////////////////
PSM OPERATIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Swaps DUSX for stable using PSM
* @param psm PSM contract
* @param receiver Receiver address
* @param amountDUSX DUSX amount
* @dev Includes reentrancy protection
*
* Requirements:
* · Valid PSM contract
* · Valid receiver address
* · Valid DUSX amount
*
* Effects:
* · Swaps DUSX for stable
* · Updates interest rates
*/
function psmSwapDUSXForStable(
IPSM psm,
address receiver,
uint256 amountDUSX
) external nonReentrant {
psm.swapDUSXForStable(_msgSender(), receiver, amountDUSX);
_updateInterestRateAndBorrowLimit();
}
/**
* @notice Swaps stable for DUSX using PSM
* @param psm PSM contract
* @param receiver Receiver address
* @param amountStable Stable amount
* @dev Includes reentrancy protection
*
* Requirements:
* · Valid PSM contract
* · Valid receiver address
* · Valid stable amount
*
* Effects:
* · Swaps stable for DUSX
* · Updates interest rates
*/
function psmSwapStableForDUSX(
IPSM psm,
address receiver,
uint256 amountStable
) external nonReentrant {
psm.swapStableForDUSX(_msgSender(), receiver, amountStable);
_updateInterestRateAndBorrowLimit();
}
/*//////////////////////////////////////////////////////////////
LENDER OPERATIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Withdraws from lender vault
* @param lender Lender contract
* @param amount Withdrawal amount
* @dev Includes reentrancy protection
*
* Requirements:
* · Valid lender contract
* · Valid withdrawal amount
*
* Effects:
* · Withdraws from lender vault
* · Updates interest rates
*/
function lenderBorrowVaultWithdraw(
ILender lender,
uint256 amount
) external nonReentrant {
lender.borrowVaultWithdraw(_msgSender(), amount);
_updateInterestRateAndBorrowLimit();
}
/**
* @notice Borrows from lender
* @param lender Lender contract
* @param amount Borrow amount
* @dev Includes reentrancy protection
*
* Requirements:
* · Valid lender contract
* · Valid borrow amount
*
* Effects:
* · Borrows from lender
* · Updates interest rates
*/
function lenderBorrow(
ILender lender,
uint256 amount
) external nonReentrant {
lender.borrow(_msgSender(), amount);
_updateInterestRateAndBorrowLimit();
}
/**
* @notice Repays lender
* @param lender Lender contract
* @param payer Payer address
* @param to Repayment recipient address
* @param skim Skimming flag
* @param part Repayment part
* @dev Only callable by repay helper
*
* Requirements:
* · Valid lender contract
* · Valid payer address
* · Valid repayment recipient address
* · Valid repayment part
*
* Effects:
* · Repays lender
* · Updates interest rates
*/
function lenderRepay(
ILender lender,
address payer,
address to,
bool skim,
uint256 part
) external nonReentrant onlyRepayHelper {
lender.repay(payer, to, skim, part);
_updateInterestRateAndBorrowLimit();
}
/**
* @notice Liquidates lender
* @param lender Lender contract
* @param liquidator Liquidator address
* @param users User addresses
* @param maxBorrowParts Maximum borrow parts
* @param to Liquidation recipient address
* @dev Only callable by liquidation helper
*
* Requirements:
* · Valid lender contract
* · Valid liquidator address
* · Valid user addresses
* · Valid maximum borrow parts
* · Valid liquidation recipient address
*
* Effects:
* · Liquidates lender
* · Updates interest rates
*/
function lenderLiquidate(
ILender lender,
address liquidator,
address[] memory users,
uint256[] memory maxBorrowParts,
address to
) external nonReentrant onlyLiquidationHelper {
lender.liquidate(liquidator, users, maxBorrowParts, to);
_updateInterestRateAndBorrowLimit();
}
/*//////////////////////////////////////////////////////////////
VIEW FUNCTIONS
//////////////////////////////////////////////////////////////*/
/**
* @notice Calculates APR for staked DUSX
* @return APR value
* @dev Includes reentrancy protection
*
* Requirements:
* · Valid staked DUSX balance
*
* Effects:
* · Calculates APR
*/
function aprStakedDUSX() external view returns (uint256) {
uint256 totalBorrowed = 0;
address[] memory lenders = vault.getControllers();
uint256 length = lenders.length;
for (uint256 i; i < length; i++) {
totalBorrowed += marketLens.getTotalBorrowed(ILender(lenders[i]));
}
if (IERC20Custom(address(stDUSX)).totalSupply() == 0) {
return 0;
} else {
return
((totalBorrowed *
dynamicInterestRate.getInterestRate() *
(TENK_PRECISION - feesDistributor.floorAllocation())) /
TENK_PRECISION) /
IERC20Custom(address(stDUSX)).totalSupply();
}
}
/*//////////////////////////////////////////////////////////////
PRIVATE FUNCTIONS
//////////////////////////////////////////////////////////////*/
/**
* @dev Distributes fees
* @notice Called before lending operations
*
* Effects:
* · Distributes fees
* · Updates fee state
*/
function _distributeFees() private {
feesWithdrawer.withdraw();
feesDistributor.distribute();
}
/**
* @dev Updates interest rates and borrow limits
* @notice Called after lending operations
*
* Effects:
* · Updates dynamic interest rates
* · Adjusts borrow limits
* · Maintains system stability
*/
function _updateInterestRateAndBorrowLimit() private {
uint256 supplyHanging = supplyHangingCalculator.getSupplyHanging();
uint256 psmTotalCapital = 0;
uint256 pegStabilityModulesLength = pegStabilityModules.length;
for (uint256 i; i < pegStabilityModulesLength; i++) {
psmTotalCapital += pegStabilityModules[i].dusxMinted();
}
uint256 newBorrowLimit = 0;
if (supplyHanging < psmTotalCapital) {
newBorrowLimit = psmTotalCapital - supplyHanging;
}
address[] memory lenders = vault.getControllers();
uint256 lendersLength = lenders.length;
for (uint256 i; i < lendersLength; i++) {
uint256 totalBorrowed = marketLens.getTotalBorrowed(
ILender(lenders[i])
);
uint256 adjustedBorrowLimit = totalBorrowed + newBorrowLimit;
lenderOwner.changeInterestRate(
ILender(lenders[i]),
dynamicInterestRate.getInterestPerSecond()
);
if (
!lenderOwner.deprecated(address(lenders[i])) &&
!lenderOwner.manual(address(lenders[i]))
) {
lenderOwner.changeBorrowLimit(
ILender(lenders[i]),
adjustedBorrowLimit,
adjustedBorrowLimit
);
}
}
}
// Validates that an address is not zero
function _ensureNonzeroAddress(address addr) private pure {
if (addr == address(0)) {
revert ZeroAddress();
}
}
}