Overview

The RebalancingSetTokenIssuanceModule is a module (see Set Whitepaper Section 4.2: Modules) in Core that allows for the issuance and redemption of a rebalancing SetToken (Set Whitepaper Section 9) from its base SetToken components. Rebalancing SetToken issuance is the process of minting a rebalancing SetToken, which involves taking the underlying components to mint a base SetToken and then minting the rebalancing SetToken using the base SetToken. Rebalancing SetToken redemption is the process of redeeming a rebalancing SetToken into its base SetToken, and then redeeming the base SetToken into its components into a single transaction. Learn more about issuing, redeeming, depositing, and withdrawing in Section 6.3 - 6.5 of the Set whitepaper.

Collateralization

All SetTokens are fully collateralized by their components, the components being held in the Vault. Sets are backed by their components in a ratio that correlates with the component’s unit (parameter on each SetToken) and its natural unit.

A Set is collateralized by its underlying components, and a rebalancing SetToken is collateralized by a base SetToken. See Figure 1 for more details about collateralization.

Calculating Required Component Quantities

The formula for calculating the required components to mint a certain quantity of a Set is generally:

REQUIRED_COMPONENT_QUANTITY = SET_QUANTITY * COMPONENT_UNIT / NATURAL_UNIT

In the case of the rebalancing SetToken, the parameter “unitShares” represents the unit of the Collateral Set. Learn more about the natural unit in Section 5.3.1 in the Whitepaper.

Modules

The Rebalancing Set Issuance Module is a registered module in Core.sol, which means it has privileged functionality to deposit, withdraw, transfer, issue, and redeem Sets. Modules are meant to extend the functionality of Core without a complete redeployment or upgrade of Core. A multi-sig interaction is required to add and remove Modules. These privileged interactions are defined in CoreModuleInteraction.sol.

Rebalancing Set Issuance Module (“The Module”)

*** External Functions

• Constructor: This function sets the addresses of Core, Vault, WrappedEther and the TransferProxy. Fallback function: This contract can only receive ether from the WrappedEther instance. issueRebalancingSet(address _rebalancingSetAddress, uint256 _rebalancingSetQuantity, bool _keepChangeInVault): This function issues a rebalancing SetToken using the sender’s components. The sender must have the components approved to the TransferProxy. Any excess base SetToken is returned directly to the user or attributed to the user in the Vault depending on the passed in keepChangeInVault parameter.
• issueRebalancingSetWrappingEther(address _rebalancingSetAddress, uint256 _rebalancingSetQuantity, bool _keepChangeInVault): This payable function issues a RebalancingSetToken using the sender’s components and Ether. The function will wrap the required Ether into wrapped Ether for usage in the base SetToken issuance process. The sender must have the other components approved to the TransferProxy. Any excess base SetToken is returned directly to the user or attributed to the user in the Vault depending on the passed in keepChangeInVault parameter. Any excess ether is returned to the user.
• redeemRebalancingSet(address _rebalancingSetAddress, uint256 _rebalancingSetQuantity, bool _keepChangeInVault): This function redeems a user’s rebalancing SetToken into the base SetToken components. The base SetToken quantity redeemed may not be a multiple of the naturalUnit of the base SetToken. If it is not, the base SetToken redeem quantity is rounded down to the next naturalUnit. Any excess base SetToken generated from the rounding is returned directly to the user or attributed to the user in the Vault.
• redeemRebalancingSetUnwrappingEther(address _rebalancingSetAddress, uint256 _rebalancingSetQuantity, bool _keepChangeInVault): This function redeems a user’s rebalancing SetToken into the base SetToken components and unwraps any wrapped Ether into Ether before sending to the user. Excess base SetToken generated from base SetToken calculation is returned to the user.

issueRebalancingSet Specification

Ahead of issuance, the sender must have all her required base SetToken components approved to the TransferProxy. The sender then calls this function with the rebalancing SetToken address (_rebalancingSetAddress), rebalancing SetToken quantity (_rebalancingSetQuantity), and a boolean (_keepChangeInVault) whether to keep the base SetToken change in the Vault. The _rebalancingSetAddress must be a valid SetToken, and the _rebalancingSetQuantity must be a multiple of the RebalancingSet’s natural unit.

The implied BaseSet quantity is derived using the RebalancingSet required components formula. The requirement for a valid BaseSet quantity is that it is a multiple of the natural unit of the BaseSet. If it is not, the BaseSet quantity value is rounded up to the next BaseSet natural unit.

The BaseSet is issued using the sender’s components. The resulting BaseSet is attributed to the module. We then ensure that there is proper allowance from the Module to the TransferProxy.

The RebalancingSet is then issued using the Module’s BaseSet and attributed to the sender.

Any BaseSet (due to the potential rounding up in the calculation) is returned to the end user. The Vault and the RebalancingSetIssuanceModule contracts are checked for base Sets.

issueRebalancingSetWrappingEther Specification

IssueRebalancingSetWrappingEther is primarily similar to issueRebalancingSet. The primary difference between this function and the prior function is that this function handles the wrapping of Ether into wrappedEther for use in issuance of Sets that include Ether. We use different functions to be efficient with token transfers. At the end, any excess Ether is also returned to the user.

redeemRebalancingSet Specification

1. The rebalancing SetToken is redeemed into the Vault from the sender to the smart contract address.
2. The base SetToken Redeem quantity is calculated by calculating the implied base SetToken quantity from the rebalancing SetToken Required Components formula in Figure 1. The value is normalized to the base SetToken natural unit.
3. The Set is withdrawn from the Vault to RebalancingSetIssuanceModule, and the base SetToken is redeemed. The components are withdrawn to the sender.
4. Any BaseSet (due to the potential rounding down in the calculation) is returned to the end user.

redeemRebalancingSetUnwrappingEther Specification

This function is similar to redeemRebalancingSet. The only difference is that after the base SetToken is redeemed, wrapped Ether is unwrapped - and the ether is sent to the sender.