DepositRedemptionVault

Inherits: Policy, IDepositRedemptionVault, PolicyEnabler, ReentrancyGuard

Title: DepositRedemptionVault

A contract that manages the redemption of receipt tokens with facility coordination and borrowing

Constants

ONE_HUNDRED_PERCENT

The number representing 100%

uint16 public constant ONE_HUNDRED_PERCENT = 100e2;

_MONTHS_IN_YEAR

The number of months in a year

uint8 internal constant _MONTHS_IN_YEAR = 12;

_ONE_MONTH

Constant for one month

uint48 internal constant _ONE_MONTH = 30 days;

_NO_POSITION

Used to denote no position ID

uint256 internal constant _NO_POSITION = type(uint256).max;

DEPOSIT_MANAGER

The address of the token manager

IDepositManager public immutable DEPOSIT_MANAGER;

State Variables

_assetFacilityMaxBorrowPercentages

Per-asset-facility max borrow percentage (in 100e2, e.g. 8500 = 85%)

mapping(bytes32 => uint16) internal _assetFacilityMaxBorrowPercentages;

_assetFacilityAnnualInterestRates

Per-asset-facility interest rate (annual, in 100e2, e.g. 500 = 5%)

mapping(bytes32 => uint16) internal _assetFacilityAnnualInterestRates;

_claimDefaultRewardPercentage

Keeper reward percentage (in 100e2, e.g. 500 = 5%)

uint16 internal _claimDefaultRewardPercentage;

TRSRY

The TRSRY module.

TRSRYv1 public TRSRY;

DEPOS

The DEPOS module.

DEPOSv1 public DEPOS;

_userRedemptionCount

The number of redemptions per user

mapping(address => uint16) internal _userRedemptionCount;

_userRedemptions

The redemption for each user and redemption ID

Use _getUserRedemptionKey() to calculate the key for the mapping. A complex key is used to save gas compared to a nested mapping.

mapping(bytes32 => UserRedemption) internal _userRedemptions;

_authorizedFacilities

Registered facilities

EnumerableSet.AddressSet internal _authorizedFacilities;

_redemptionLoan

Loan for each redemption

Use _getUserRedemptionKey() to calculate the key for the mapping. A complex key is used to save gas compared to a nested mapping.

mapping(bytes32 => Loan) internal _redemptionLoan;

Functions

constructor

constructor(address kernel_, address depositManager_) Policy(Kernel(kernel_));

Parameters

Name	Type	Description
kernel_	`address`
depositManager_	`address`

configureDependencies

Define module dependencies for this policy.

function configureDependencies() external override returns (Keycode[] memory dependencies);

Returns

Name	Type	Description
dependencies	`Keycode[]`	- Keycode array of module dependencies.

requestPermissions

Function called by kernel to set module function permissions.

function requestPermissions()
        external
        pure
        override
        returns (Permissions[] memory permissions);

Returns

Name	Type	Description
permissions	`Permissions[]`	- Array of keycodes and function selectors for requested permissions.

authorizeFacility

Authorize a facility

function authorizeFacility(address facility_) external onlyAdminRole;

Parameters

Name	Type	Description
facility_	`address`	The address of the facility to authorize

deauthorizeFacility

Deauthorize a facility

function deauthorizeFacility(address facility_) external onlyEmergencyOrAdminRole;

Parameters

Name	Type	Description
facility_	`address`	The address of the facility to deauthorize

isAuthorizedFacility

Check if a facility is authorized

function isAuthorizedFacility(address facility_) external view returns (bool);

Parameters

Name	Type	Description
facility_	`address`	The address of the facility to check

Returns

Name	Type	Description
<none>	`bool`	True if the facility is authorized

getAuthorizedFacilities

Get all authorized facilities

function getAuthorizedFacilities() external view returns (address[] memory);

Returns

Name	Type	Description
<none>	`address[]`	Array of authorized facility addresses

_pullReceiptToken

Pull the receipt tokens from the caller

function _pullReceiptToken(
        IERC20 depositToken_,
        uint8 depositPeriod_,
        address facility_,
        uint256 amount_
    ) internal;

Parameters

Name	Type	Description
depositToken_	`IERC20`
depositPeriod_	`uint8`
facility_	`address`
amount_	`uint256`

_getUserRedemptionKey

function _getUserRedemptionKey(
        address user_,
        uint16 redemptionId_
    ) internal pure returns (bytes32);

Parameters

Name	Type	Description
user_	`address`
redemptionId_	`uint16`

Returns

Name	Type	Description
<none>	`bytes32`

_getAssetFacilityKey

Generate a key for the asset-facility parameter mappings

function _getAssetFacilityKey(
        address asset_,
        address facility_
    ) internal pure returns (bytes32);

Parameters

Name	Type	Description
asset_	`address`	The asset address
facility_	`address`	The facility address

Returns

Name	Type	Description
<none>	`bytes32`	The key for the mapping

getUserRedemptionCount

Gets the number of redemptions a user has started

function getUserRedemptionCount(address user_) external view returns (uint16 count);

Parameters

Name	Type	Description
user_	`address`	The address of the user

Returns

Name	Type	Description
count	`uint16`	The number of redemptions

getUserRedemption

Gets the details of a user's redemption

function getUserRedemption(
        address user_,
        uint16 redemptionId_
    ) external view returns (UserRedemption memory redemption);

Parameters

Name	Type	Description
user_	`address`	The address of the user
redemptionId_	`uint16`	The ID of the redemption

Returns

Name	Type	Description
redemption	`UserRedemption`	The details of the redemption

getUserRedemptions

Gets all redemptions for a user

Notes:
This function is gas-intensive for users with many redemptions.
The index of an element in the returned array is the redemption ID.
Redemptions with an amount of 0 (fully redeemed) are included in the array.

function getUserRedemptions(address user_) external view returns (UserRedemption[] memory);

Parameters

Name	Type	Description
user_	`address`	The address of the user

Returns

Name	Type	Description
<none>	`UserRedemption[]`	redemptions The array of redemptions

_onlyValidRedemptionId

function _onlyValidRedemptionId(address user_, uint16 redemptionId_) internal view;

Parameters

Name	Type	Description
user_	`address`
redemptionId_	`uint16`

onlyValidRedemptionId

modifier onlyValidRedemptionId(address user_, uint16 redemptionId_);

Parameters

Name	Type	Description
user_	`address`
redemptionId_	`uint16`

_validateFacility

function _validateFacility(address facility_) internal view;

Parameters

Name	Type	Description
facility_	`address`

onlyValidFacility

modifier onlyValidFacility(address facility_);

Parameters

Name	Type	Description
facility_	`address`

startRedemption

This function expects receipt tokens to be unwrapped (i.e. native ERC6909 tokens)

This function reverts if:

The contract is disabled
The amount is 0
The provided facility is not authorized

function startRedemption(
        IERC20 depositToken_,
        uint8 depositPeriod_,
        uint256 amount_,
        address facility_
    ) external nonReentrant onlyEnabled onlyValidFacility(facility_) returns (uint16 redemptionId);

Parameters

Name	Type	Description
depositToken_	`IERC20`	The address of the deposit token
depositPeriod_	`uint8`	The period of the deposit in months
amount_	`uint256`	The amount of deposit tokens to redeem
facility_	`address`	The facility to handle this redemption

Returns

Name	Type	Description
redemptionId	`uint16`	The ID of the user redemption

startRedemption

This function expects receipt tokens to be unwrapped (i.e. native ERC6909 tokens)

This function reverts if:

The contract is disabled
The amount is 0
The caller is not the owner of the position
The amount is greater than the remainingDeposit of the position
The facility that created the position is not authorized

function startRedemption(
        uint256 positionId_,
        uint256 amount_
    ) external nonReentrant onlyEnabled returns (uint16 redemptionId);

Parameters

Name	Type	Description
positionId_	`uint256`	The ID of the position to redeem from
amount_	`uint256`	The amount of deposit tokens to redeem

Returns

Name	Type	Description
redemptionId	`uint16`	The ID of the user redemption

cancelRedemption

Cancels a redemption of a quantity of deposit tokens

This function reverts if:
The contract is disabled
The caller is not the owner of the redemption ID
The facility in the redemption record is not authorized
The amount is 0
The amount is greater than the redemption amount
There is an unpaid loan

function cancelRedemption(
        uint16 redemptionId_,
        uint256 amount_
    ) external nonReentrant onlyEnabled onlyValidRedemptionId(msg.sender, redemptionId_);

Parameters

Name	Type	Description
redemptionId_	`uint16`	The ID of the user redemption
amount_	`uint256`	The amount of deposit tokens to cancel

finishRedemption

Finishes a redemption of a quantity of deposit tokens

This function reverts if:
The contract is disabled
The caller is not the owner of the redemption ID
The facility in the redemption record is not authorized
The redemption amount is 0
It is too early for redemption
There is an unpaid loan

function finishRedemption(
        uint16 redemptionId_
    )
        external
        nonReentrant
        onlyEnabled
        onlyValidRedemptionId(msg.sender, redemptionId_)
        returns (uint256 actualAmount);

Parameters

Name	Type	Description
redemptionId_	`uint16`	The ID of the user redemption

Returns

Name	Type	Description
actualAmount	`uint256`	The quantity of deposit tokens transferred to the caller

_calculateInterest

function _calculateInterest(
        uint256 principal_,
        uint256 interestRate_,
        uint256 depositPeriod_
    ) internal pure returns (uint256);

Parameters

Name	Type	Description
principal_	`uint256`
interestRate_	`uint256`
depositPeriod_	`uint256`

Returns

Name	Type	Description
<none>	`uint256`

_previewBorrowAgainstRedemption

function _previewBorrowAgainstRedemption(
        address user_,
        uint16 redemptionId_
    ) internal view returns (uint256, uint256, uint48);

Parameters

Name	Type	Description
user_	`address`
redemptionId_	`uint16`

Returns

Name	Type	Description
<none>	`uint256`
<none>	`uint256`
<none>	`uint48`

previewBorrowAgainstRedemption

Preview the maximum amount that can be borrowed against an active redemption

Notes:
The calculated amount may differ from the actual amount borrowed (using borrowAgainstRedemption()) by a few wei, due to rounding behaviour in ERC4626 vaults.

function previewBorrowAgainstRedemption(
        address user_,
        uint16 redemptionId_
    ) external view returns (uint256, uint256, uint48);

Parameters

Name	Type	Description
user_	`address`	The address of the user
redemptionId_	`uint16`	The ID of the redemption to borrow against

Returns

Name	Type	Description
<none>	`uint256`	The principal amount that can be borrowed
<none>	`uint256`	The interest amount that will be charged
<none>	`uint48`	The due date of the loan

borrowAgainstRedemption

Borrows the maximum possible amount against an existing redemption. The loan will be for a fixed-term. The interest is calculated on the basis of that term, and the full amount will be payable in order to close the loan.

This function will revert if:

The contract is not enabled
The redemption ID is invalid
The facility is not authorized
The amount is 0
The interest rate is not set

function borrowAgainstRedemption(
        uint16 redemptionId_
    )
        external
        nonReentrant
        onlyEnabled
        onlyValidRedemptionId(msg.sender, redemptionId_)
        returns (uint256);

Parameters

Name	Type	Description
redemptionId_	`uint16`	The ID of the redemption to borrow against

Returns

Name	Type	Description
<none>	`uint256`	The quantity of underlying assets transferred to the recipient

repayLoan

This function will repay the outstanding loan amount. Interest is paid back first, followed by principal. To prevent irrecoverable overpayments, the maximum slippage is used to validate that a repayment is within bounds of the remaining loan principal.

This function will revert if:

The contract is not enabled
The redemption ID is invalid
The redemption has no loan
The amount is 0
The loan is expired, defaulted or fully repaid

function repayLoan(
        uint16 redemptionId_,
        uint256 amount_,
        uint256 maxSlippage_
    ) external nonReentrant onlyEnabled onlyValidRedemptionId(msg.sender, redemptionId_);

Parameters

Name	Type	Description
redemptionId_	`uint16`	The ID of the redemption
amount_	`uint256`	The amount to repay
maxSlippage_	`uint256`	The maximum slippage allowed for the repayment

_previewExtendLoan

function _previewExtendLoan(
        address asset_,
        address facility_,
        uint256 principal_,
        uint48 dueDate_,
        uint8 extensionMonths_
    ) internal view returns (uint48, uint256);

Parameters

Name	Type	Description
asset_	`address`
facility_	`address`
principal_	`uint256`
dueDate_	`uint48`
extensionMonths_	`uint8`

Returns

Name	Type	Description
<none>	`uint48`
<none>	`uint256`

previewExtendLoan

Preview the interest payable for extending a loan

This function will revert if:
The redemption ID is invalid
The loan is invalid
The loan is expired, defaulted or fully repaid
The months is 0

function previewExtendLoan(
        address user_,
        uint16 redemptionId_,
        uint8 months_
    ) external view onlyValidRedemptionId(user_, redemptionId_) returns (uint48, uint256);

Parameters

Name	Type	Description
user_	`address`	The address of the user
redemptionId_	`uint16`	The ID of the redemption
months_	`uint8`	The number of months to extend the loan

Returns

Name	Type	Description
<none>	`uint48`	The new due date
<none>	`uint256`	The interest payable upon extension

extendLoan

Extend a loan's due date

This function will revert if:
The contract is not enabled
The redemption ID is invalid
The loan is invalid
The loan is expired, defaulted or fully repaid
The months is 0

function extendLoan(
        uint16 redemptionId_,
        uint8 months_
    ) external nonReentrant onlyEnabled onlyValidRedemptionId(msg.sender, redemptionId_);

Parameters

Name	Type	Description
redemptionId_	`uint16`	The ID of the redemption
months_	`uint8`	The number of months to extend the loan

claimDefaultedLoan

Claim a defaulted loan and collect the reward

This function will revert if:
The contract is not enabled
The redemption ID is invalid
The loan is invalid
The loan is not expired
The loan is already defaulted

function claimDefaultedLoan(
        address user_,
        uint16 redemptionId_
    ) external nonReentrant onlyEnabled onlyValidRedemptionId(user_, redemptionId_);

Parameters

Name	Type	Description
user_	`address`	The address of the user
redemptionId_	`uint16`	The ID of the redemption

getRedemptionLoan

Get all loans for a redemption

function getRedemptionLoan(
        address user_,
        uint16 redemptionId_
    ) external view returns (Loan memory);

Parameters

Name	Type	Description
user_	`address`	The address of the user
redemptionId_	`uint16`	The ID of the redemption

Returns

Name	Type	Description
<none>	`Loan`	The loan

setMaxBorrowPercentage

Notes:
When setting the max borrow percentage, keep in mind the annual interest rate and claim default reward percentage, as the three configuration values can create incentives for borrowers to not repay their loans (e.g. claim default on their own loan)
This function allows setting the value even if the asset or facility are not registered

This function reverts if:

The contract is not enabled
The caller does not have the admin or manager role
asset_ is the zero address
facility_ is the zero address
percent_ is out of range

function setMaxBorrowPercentage(
        IERC20 asset_,
        address facility_,
        uint16 percent_
    ) external onlyEnabled onlyManagerOrAdminRole;

Parameters

Name	Type	Description
asset_	`IERC20`	The address of the asset
facility_	`address`	The address of the facility
percent_	`uint16`	The maximum borrow percentage

getMaxBorrowPercentage

Get the maximum borrow percentage for an asset-facility combination

function getMaxBorrowPercentage(
        IERC20 asset_,
        address facility_
    ) external view returns (uint16);

Parameters

Name	Type	Description
asset_	`IERC20`	The address of the asset
facility_	`address`	The address of the facility

Returns

Name	Type	Description
<none>	`uint16`	The maximum borrow percentage (100e2 == 100%)

setAnnualInterestRate

Notes:
When setting the annual interest rate, keep in mind the max borrow percentage and claim default reward percentage, as the three configuration values can create incentives for borrowers to not repay their loans (e.g. claim default on their own loan)
This function allows setting the value even if the asset or facility are not registered

This function reverts if:

The contract is not enabled
The caller does not have the admin or manager role
asset_ is the zero address
facility_ is the zero address
percent_ is out of range

function setAnnualInterestRate(
        IERC20 asset_,
        address facility_,
        uint16 rate_
    ) external onlyEnabled onlyManagerOrAdminRole;

Parameters

Name	Type	Description
asset_	`IERC20`	The address of the asset
facility_	`address`	The address of the facility
rate_	`uint16`	The annual interest rate (100e2 == 100%)

getAnnualInterestRate

Get the annual interest rate for an asset-facility combination

function getAnnualInterestRate(
        IERC20 asset_,
        address facility_
    ) external view returns (uint16);

Parameters

Name	Type	Description
asset_	`IERC20`	The address of the asset
facility_	`address`	The address of the facility

Returns

Name	Type	Description
<none>	`uint16`	The annual interest rate, in terms of 100e2

setClaimDefaultRewardPercentage

Set the reward percentage when a claiming a defaulted loan

Notes:
When setting the claim default reward percentage, keep in mind the annual interest rate and max borrow percentage, as the three configuration values can create incentives for borrowers to not repay their loans (e.g. claim default on their own loan)

function setClaimDefaultRewardPercentage(
        uint16 percent_
    ) external onlyEnabled onlyManagerOrAdminRole;

Parameters

Name	Type	Description
percent_	`uint16`	The claim default reward percentage

getClaimDefaultRewardPercentage

Get the claim default reward percentage

function getClaimDefaultRewardPercentage() external view returns (uint16);

Returns

Name	Type	Description
<none>	`uint16`	The claim default reward percentage, in terms of 100e2

supportsInterface

function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool);

Parameters

Name	Type	Description
interfaceId	`bytes4`

Returns

Name	Type	Description
<none>	`bool`

DepositRedemptionVault

Constants​

ONE_HUNDRED_PERCENT​

_MONTHS_IN_YEAR​

_ONE_MONTH​

_NO_POSITION​

DEPOSIT_MANAGER​

State Variables​

_assetFacilityMaxBorrowPercentages​

_assetFacilityAnnualInterestRates​

_claimDefaultRewardPercentage​

TRSRY​

DEPOS​

_userRedemptionCount​

_userRedemptions​

_authorizedFacilities​

_redemptionLoan​

Functions​

constructor​

configureDependencies​

requestPermissions​

authorizeFacility​

deauthorizeFacility​

isAuthorizedFacility​

getAuthorizedFacilities​

_pullReceiptToken​

_getUserRedemptionKey​

_getAssetFacilityKey​

getUserRedemptionCount​

getUserRedemption​

getUserRedemptions​

_onlyValidRedemptionId​

onlyValidRedemptionId​

_validateFacility​

onlyValidFacility​

startRedemption​

startRedemption​

cancelRedemption​

finishRedemption​

_calculateInterest​

_previewBorrowAgainstRedemption​

previewBorrowAgainstRedemption​

borrowAgainstRedemption​

repayLoan​

_previewExtendLoan​

previewExtendLoan​

extendLoan​

claimDefaultedLoan​

getRedemptionLoan​

setMaxBorrowPercentage​

getMaxBorrowPercentage​

setAnnualInterestRate​

getAnnualInterestRate​

setClaimDefaultRewardPercentage​

getClaimDefaultRewardPercentage​

supportsInterface​

Constants

ONE_HUNDRED_PERCENT

_MONTHS_IN_YEAR

_ONE_MONTH

_NO_POSITION

DEPOSIT_MANAGER

State Variables

_assetFacilityMaxBorrowPercentages

_assetFacilityAnnualInterestRates

_claimDefaultRewardPercentage

TRSRY

DEPOS

_userRedemptionCount

_userRedemptions

_authorizedFacilities

_redemptionLoan

Functions

constructor

configureDependencies

requestPermissions

authorizeFacility

deauthorizeFacility

isAuthorizedFacility

getAuthorizedFacilities

_pullReceiptToken

_getUserRedemptionKey

_getAssetFacilityKey

getUserRedemptionCount

getUserRedemption

getUserRedemptions

_onlyValidRedemptionId

onlyValidRedemptionId

_validateFacility

onlyValidFacility

startRedemption

startRedemption

cancelRedemption

finishRedemption

_calculateInterest

_previewBorrowAgainstRedemption

previewBorrowAgainstRedemption

borrowAgainstRedemption

repayLoan

_previewExtendLoan

previewExtendLoan

extendLoan

claimDefaultedLoan

getRedemptionLoan

setMaxBorrowPercentage

getMaxBorrowPercentage

setAnnualInterestRate

getAnnualInterestRate

setClaimDefaultRewardPercentage

getClaimDefaultRewardPercentage

supportsInterface