Debt Issuance

Note: Debt Issuance is not available for Optimism.

What is the DebtIssuanceModule:

The DebtIssuanceModule is a module that enables users to issue and redeem SetTokens that contain default and all external positions, including debt positions. This can be thought of as a superset of Basic Issuance. The manager can define arbitrary issuance logic in the manager hook (e.g. allowlisting, issuance windows, supply caps), as well as specify issue and redeem fees.

Initializing the DebtIssuanceModule:

All modules need to be added to the SetToken as the first step. Learn how to add a module to your SetToken by referring to the Adding a Module guide.

Once you have added the DebtIssuanceModule to the SetToken, you must initialize the SetToken on the DebtIssuanceModule:

/**
 * MANAGER ONLY: Initializes this module to the SetToken with issuance-related hooks and fee information. Only callable
 * by the SetToken's manager. Hook addresses are optional. Address(0) means that no hook will be called
 *
 * @param _setToken                     Instance of the SetToken to issue
 * @param _maxManagerFee                Maximum fee that can be charged on issue and redeem
 * @param _managerIssueFee              Fee to charge on issuance
 * @param _managerRedeemFee             Fee to charge on redemption
 * @param _feeRecipient                 Address to send fees to
 * @param _managerIssuanceHook          Instance of the Manager Contract with the Pre-Issuance Hook function
 */
function initialize(ISetToken _setToken, uint256 _maxManagerFee, uint256 _managerIssueFee, uint256 _managerRedeemFee, address _feeRecipient, IManagerIssuanceHook _managerIssuanceHook)

The managerIssueFee and managerRedeemFee are fees that are charged when an user enters or exits your SetToken.

The pre issue hook is an optional parameter for a contract that can contain any custom logic you write prior to issuance. For example, the manager issuance contract can include whitelisting functionality, issuance limits and any other custom logic for operating your Set.

If you do not wish to provide a pre issuance hook, you can input the zero address (0x0000000000000000000000000000000000000000).

Issuing Sets:

In order to issue Sets you must call issue on the DebtIssuanceModule, the interface for issue is as follows:

function issue(ISetToken _setToken, uint256 _quantity, address _to) external

Input the address of the Set you wish to issue and the amount of SetTokens you wish to issue. In order for issuance to work ALL of the components must be owned by the calling address in the correct proportions (whether it's a wallet or smart contract address).

All equity components must be approved to the DebtIssuanceModule contract with appropriate allowance for transfer. Debt components are returned to you on issuance. This is to ensure an 100% mirroring of SetToken positions and ensure 0 slippage mint / redeems.

In order to figure out the correct token amounts needed for issuance you can call the following function which returns a list of equity units and debt units:

/**
 * Calculates the amount of each component needed to collateralize passed issue quantity plus fees of Sets as well as amount of debt
 * that will be returned to caller. Values DO NOT take into account any updates from pre action manager or module hooks.
 *
 * @param _setToken         Instance of the SetToken to issue
 * @param _quantity         Amount of Sets to be issued
 *
 * @return address[]        Array of component addresses making up the Set
 * @return uint256[]        Array of equity notional amounts of each component, respectively, represented as uint256
 * @return uint256[]        Array of debt notional amounts of each component, respectively, represented as uint256
 */
function getRequiredComponentIssuanceUnits(ISetToken _setToken, uint256 _quantity) public view returns (address[] memory, uint256[] memory)

Each component unit is denominated the component base units. For example, 1 USDC is 10 ** 6 and 1 WBTC is 10 ** 8.

Once you confirm you have all the required components to collateralize each position of the Set you will be able to issue which transfers those components to the SetToken and mint's the passed _quantity to the calling address.

Redeeming Sets:

Conversely, redeeming is the process of burning your SetToken balance and receiving the underlying collateral. You must approve ALL debt units to the DebtIssuanceModule.

The interface for redeem is as follows:

function redeem(ISetToken _setToken, uint256 _quantity, address _to) external

Specify the amount of Sets to redeem and then those Sets are burned and the components are transferred to the calling address. The following function will return the required amount of debt components to send and equity components to receive back:

/**
 * Calculates the amount of each component will be returned on redemption net of fees as well as how much debt needs to be paid down to.
 * redeem. Values DO NOT take into account any updates from pre action manager or module hooks.
 *
 * @param _setToken         Instance of the SetToken to issue
 * @param _quantity         Amount of Sets to be redeemed
 *
 * @return address[]        Array of component addresses making up the Set
 * @return uint256[]        Array of equity notional amounts of each component, respectively, represented as uint256
 * @return uint256[]        Array of debt notional amounts of each component, respectively, represented as uint256
 */
 function getRequiredComponentRedemptionUnits(ISetToken _setToken, uint256 _quantity)