ExchangeIssuanceZeroEx

ExchangeIssuanceZeroEx can be used to issue and redeem any SetToken using native chain currency (ex: ETH, MATIC) or an ERC20 as the paying/receiving token.

• When issuing, the contract converts the input token into the components required to mint a SetToken.

• When redeeming, it converts redeemed components into the desired output token.

• All swaps are done using 0x Exchange.

Users of ExchangeIssuanceZeroEx must fetch quotes for the Set's underlying components from 0x via off-chain API calls and submit returned quote data with their issuance or redemption request. The API response also includes expected outcome quantities for the trade which can be used to estimate the cost of issuance.

Before issuing or redeeming for the first time, approveSetToken should be called to authorize ExchangeIssuanceZeroEx to trade the Set's components with 0x.

To obtain the inputs required execute an issuance call, you can follow the recipe in the code block below:

NOTES:

• set.js exposes a UtilsAPI class which is useful for batching quote requests, managing request cadences (0x's services are rate-limited) and handling the authentication required to use 0x's gated endpoints. (By default it uses their public endpoints).

• when issuing, it's sometimes necessary to add a small buffer to your "paying currency" amount in addition to the total suggested by 0x. This helps prevent reverts caused by tiny rounding errors. Any unused paying currency will be returned to you at the end of the transaction.

• IMPORTANT: You should sanity check the cumulative cost of the component quotes you receive and make sure it's within slippage tolerances that are acceptable to you. For example, when issuing, add up the quote sellAmount quantities and determine if the total is a fair price for the amount of SetToken you wish to buy.

// Note: `EIZEInstance` is an instance of the ExchangeIssuanceZeroEx contract
const [ issuanceModuleAddress ] = await setTokenInstance.getModules();

const (components, positions) = await EIZEInstance.getRequiredIssuanceComponents(
  issuanceModuleAddress,
  setTokenAddress,
  setTokenAmount
);

// => components
> [ 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 ]
// => positions
> [ 247590731 ]
  
// Example 0x API quote request 
const zeroExQuery = "https://api.0x.org/swap/v1/quote?" +
  "buyToken=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48&" +. // Underlying component to buy
  "sellToken=0x4Ddc2D193948926D02f9B1fE9e1daa0718270ED5&" + // Paying currency
  "buyAmount=247590731&" +
  "slippagePercentage=0.5";
  
const quote = await axios.get(zeroExQuery);

// quote =>
> { 
    data: 0xd9627aa40000....0000004ac4b595a7620548b9,
    sellAmount: 51189391275348190
    buyAmount: 247590731
  }

Select Methods

approveSetToken

Runs all the necessary approval functions for a SetToken's components that are required before issuing or redeeming a SetToken. This function only needs to be called once before the first time this smart contract is used on any particular SetToken.

function approveSetToken(ISetToken _setToken, address _issuanceModule)

Parameter Guide

Parameter Name	Type	Description
_setToken	ISetToken	Instance of the SetToken being initialized
_issuanceModule	address	Address of the issuance module which will be approved to spend component tokens

issueExactSetForToken()

Issues an exact amount of SetTokens for given amount of input ERC20 tokens. Any excess input tokens are returned to the user.

function issueExactSetFromToken(
    ISetToken _setToken,
    IERC20 _inputToken,
    uint256 _amountSetToken,
    uint256 _maxAmountInputToken,
    bytes[] memory _componentQuotes,
    address _issuanceModule
    bool _isDebtIssuance
) returns (uint256 excessInputToken)

Parameter Guide

Parameter Name	Type	Description
_setToken	ISetToken	Instance of the SetToken
_inputToken	address	Address of the input token
_amountSetToken	address	Amount of SetTokens to issue
_maxAmountInputToken	uint256	Maximum amount of input tokens to be used to issue SetTokens
_componentQuotes	bytes[]	The encoded 0x transactions to execute
_issuanceModule	address	Address of issuance module to call issue with
_isDebtIssuance	bool	true if _setToken uses DebtIssuanceModuleV2 to issue/redeem. false if it uses BasicIssuanceModule

issueExactSetForETH()

Issues an exact amount of SetTokens for given amount of native chain currency (e.g ETH, MATIC). Any excess native currency is returns to the user.

IMPORTANT: When fetching 0x quotes for this method, you must specify the WETH token address (or its equivalent for non-ETH chains) as the "paying currency" or sellToken. When executing the method, send ETH with it using the transaction's `value` attribute. ExchangeIssuanceZeroEx will wrap it into WETH and execute the 0x trades with it as an ERC20.

function issueExactSetFromETH(
    ISetToken _setToken,
    uint256 _amountSetToken,
    bytes[] memory _componentQuotes,
    address _issuanceModule
    bool _isDebtIssuance
) returns (uint256 excessETH)

Parameter Guide

Parameter Name	Type	Description
_setToken	ISetToken	Instance of the SetToken
_amountSetToken	address	Amount of SetTokens to issue
_componentQuotes	bytes[]	The encoded 0x transactions to execute
_issuanceModule	address	Address of issuance module to call issue with
_isDebtIssuance	bool	true if _setToken uses DebtIssuanceModuleV2 to issue/redeem. false if it uses BasicIssuanceModule

redeemExactSetForToken()

Redeems an exact amount of SetTokens for an ERC20 token. The SetToken must be approved by the sender to this contract.

function redeemExactSetForToken(
    ISetToken _setToken,
    IERC20 _receiveToken,
    uint256 _amountSetToken,
    uint256 _minAmountReceiveToken,
    bytes[] memory _componentQuotes,
    address _issuanceModule
    bool _isDebtIssuance
) returns (uint256 excessInputToken)

Parameter Guide

Parameter Name	Type	Description
_setToken	ISetToken	Instance of the SetToken
_receiveToken	address	Address of the receive token
_amountSetToken	address	Amount of SetTokens to redeem
_minAmountReceiveToken	uint256	Minumum amount of tokens to receive for redeeming SetTokens
_componentQuotes	bytes[]	The encoded 0x transactions to execute
_issuanceModule	address	Address of issuance module to call redeem with
_isDebtIssuance	bool	true if _setToken uses DebtIssuanceModuleV2 to issue/redeem. false if it uses BasicIssuanceModule

redeemExactSetForETH()

Redeems an exact amount of SetTokens for a native chain currency (e.g ETH, MATIC). The SetToken must be approved by the sender to this contract.

IMPORTANT: When fetching 0x quotes for this method, you must specify the WETH token address (or its equivalent for non-ETH chains) as the "receive currency" or buyToken. When executing the method, ExchangeIssuanceZeroEx will receive WETH from 0x, unwrap it and forward the native currency to you.

function redeemExactSetForToken(
    ISetToken _setToken,
    uint256 _amountSetToken,
    bytes[] memory _componentQuotes,
    address _issuanceModule
    bool _isDebtIssuance
) returns (uint256 excessInputToken)

Parameter Guide

Parameter Name	Type	Description
_setToken	ISetToken	Instance of the SetToken
_amountSetToken	address	Amount of SetTokens to redeem
_componentQuotes	bytes[]	The encoded 0x transactions to execute
_issuanceModule	address	Address of issuance module to call redeem with
_isDebtIssuance	bool	true if _setToken uses DebtIssuanceModuleV2 to issue/redeem. false if it uses BasicIssuanceModule

Select View Methods

getRequiredIssuanceComponents

Returns component positions required for issuance. This method can be called to fetch the necessary inputs to fetch 0x API issuance quotes.

function getRequiredRedemptionComponents(
  address _issuanceModule, 
  bool _isDebtIssuance,
  ISetToken _setToken, 
  uint256 _amountSetToken
) returns(address[] memory components, uint256[] memory positions)

Parameter Guide

Parameter Name	Type	Description
_issuanceModule	address	Address of issuance module to call redeem with
_isDebtIssuance	bool	true if _setToken uses DebtIssuanceModuleV2 to issue/redeem. false if it uses BasicIssuanceModule
_setToken	ISetToken	Instance of the SetToken
_amountSetToken	address	Amount of SetTokens to redeem

getRequiredRedemptionComponents

Returns component positions required for redemption. This method can be called to fetch the necessary inputs to fetch 0x API redemption quotes

function getRequiredRedemptionComponents(
  address _issuanceModule, 
  bool _isDebtIssuance,
  ISetToken _setToken, 
  uint256 _amountSetToken
) returns(address[] memory components, uint256[] memory positions)

Parameter Guide

Parameter Name	Type	Description
_issuanceModule	address	Address of issuance module to call redeem with
_isDebtIssuance	bool	true if _setToken uses DebtIssuanceModuleV2 to issue/redeem. false if is uses BasicIssuanceModule
_setToken	ISetToken	Instance of the SetToken
_amountSetToken	address	Amount of SetTokens to redeem