FM_BC_Bancor_Redeeming_VirtualSupply_v1.sol

Git Source

Inherits: IFM_BC_Bancor_Redeeming_VirtualSupply_v1, IFundingManager_v1, VirtualIssuanceSupplyBase_v1, VirtualCollateralSupplyBase_v1, RedeemingBondingCurveBase_v1

Author: Inverter Network

This contract enables the issuance and redeeming of tokens on a bonding curve, using a virtual supply for both the issuance and the collateral as input. It integrates Aragon's {BancorFormula} to manage the calculations for token issuance and redemption rates based on specified reserve ratios.

Inherits {BondingCurveBase_v1}, {RedeemingBondingCurveBase_v1}, {VirtualIssuanceSupplyBase_v1}, and {VirtualCollateralSupplyBase_v1}. Implements formulaWrapper functions for bonding curve calculations using the {BancorFormula}. {Orchestrator_v1} Admin manages configuration such as virtual supplies and reserve ratios. Ensure interaction adheres to defined transactional limits and decimal precision requirements to prevent computational overflows or underflows.

State Variables

formula

The interface of the Bancor Formula used to calculate the issuance and redeeming amount.

IBancorFormula public formula;

eighteenDecimals

Value is used to convert deposit amount to 18 decimals, which is required by the {BancorFormula}. which is required by the Bancor formula.

uint8 private constant eighteenDecimals = 18;

PPM

Parts per million used for calculation the reserve ratio for the Bancor formula.

uint32 internal constant PPM = 1_000_000;

reserveRatioForBuying

The reserve ratio for buying determines the rate of price growth. It is a measure of the fraction of the Token's value that is held in reserve. The value is a number between 0 and 100%, expressed in PPM. A higher reserve ratio means slower price growth. See Bancor Formula contract for reference.

uint32 internal reserveRatioForBuying;

reserveRatioForSelling

The reserve ratio for selling determines the rate of price growth. It is a measure of the fraction of the Token's value that is held in reserve. The value is a number between 0 and 100%, expressed in PPM. A higher reserve ratio means slower price growth. See Bancor Formula contract for reference.

uint32 internal reserveRatioForSelling;

_token

Token that is accepted by this funding manager for deposits.

IERC20 private _token;

collateralTokenDecimals

Token decimals of the Orchestrator token, which is used as collateral and stores within implementation for gas saving.

uint8 internal collateralTokenDecimals;

issuanceTokenDecimals

Token decimals of the issuance token, which is stored within the implementation for gas saving.

uint8 internal issuanceTokenDecimals;

__gap

Storage gap for future upgrades.

uint[50] private __gap;

Functions

supportsInterface

See {IERC165-supportsInterface}.

function supportsInterface(bytes4 interfaceId)
    public
    view
    virtual
    override(
        VirtualIssuanceSupplyBase_v1,
        VirtualCollateralSupplyBase_v1,
        RedeemingBondingCurveBase_v1
    )
    returns (bool);

onlyWhenCurveInteractionsAreClosed

Modifier to guarantee the buying and selling functionalities are closed.

modifier onlyWhenCurveInteractionsAreClosed();

init

function init(
    IOrchestrator_v1 orchestrator_,
    Metadata memory metadata,
    bytes memory configData
) external override(Module_v1) initializer;

buyFor

Buy tokens on behalf of a specified receiver address. This function is subject to a transactional limit, determined by the deposit token's decimal precision and the underlying bonding curve algorithm.

Redirects to the internal function _buyOrder by passing the receiver address and deposit amount. Important: The {BancorFormula} has an upper computational limit of (10^38). For tokens with 18 decimal places, this effectively leaves a maximum allowable deposit amount of (10^20). While this is substantially large, it is crucial to be aware of this constraint. Transactions exceeding this limit will be reverted.

function buyFor(address _receiver, uint _depositAmount, uint _minAmountOut)
    public
    virtual
    override(BondingCurveBase_v1)
    validReceiver(_receiver)
    buyingIsEnabled;

Parameters

Name	Type	Description
_receiver	address	The address that will receive the bought tokens.
_depositAmount	uint256	The amount of collateral token depoisited.
_minAmountOut	uint256	The minimum acceptable amount the user expects to receive from the transaction.

buy

Buy tokens for the sender's address. This function is subject to a transactional limit, determined by the deposit token's decimal precision and the underlying bonding curve algorithm.

Redirects to the internal function _buyOrder by passing the sender's address and deposit amount. Important: The {BancorFormula} has an upper computational limit of (10^38). While this is substantially large, it is crucial to be aware of this constraint. Transactions exceeding this limit will be reverted.

function buy(uint _depositAmount, uint _minAmountOut)
    public
    virtual
    override(BondingCurveBase_v1)
    buyingIsEnabled;

Parameters

Name	Type	Description
_depositAmount	uint256	The amount of collateral token depoisited.
_minAmountOut	uint256	The minimum acceptable amount the user expects to receive from the transaction.

sellTo

Redeem tokens and direct the proceeds to a specified receiver address. This function is subject to a transactional limit, determined by the issuing token's decimal precision and the underlying bonding curve algorithm.

Redirects to the internal function _sellOrder by passing the receiver address and deposit amount. Important: The {BancorFormula} has an upper computational limit of (10^26). For tokens with 18 decimal places, this effectively leaves a maximum allowable deposit amount of (10^8), or 100,000,000. Transactions exceeding this limit will be reverted.

function sellTo(address _receiver, uint _depositAmount, uint _minAmountOut)
    public
    virtual
    override(RedeemingBondingCurveBase_v1)
    validReceiver(_receiver)
    sellingIsEnabled;

Parameters

Name	Type	Description
_receiver	address	The address that will receive the redeemed tokens.
_depositAmount	uint256	The amount of issued token to deposited.
_minAmountOut	uint256	The minimum acceptable amount the user expects to receive from the transaction.

sell

Redeem collateral for the sender's address. This function is subject to a transactional limit, determined by the issuing token's decimal precision and the underlying bonding curve algorithm.

Redirects to the internal function _sellOrder by passing the sender's address and deposit amount. Important: The {BancorFormula} has an upper computational limit of (10^26). For tokens with 18 decimal places, this effectively leaves a maximum allowable deposit amount of (10^8), or 100,000,000. Transactions exceeding this limit will be reverted.

function sell(uint _depositAmount, uint _minAmountOut)
    public
    virtual
    override(RedeemingBondingCurveBase_v1)
    sellingIsEnabled;

Parameters

Name	Type	Description
_depositAmount	uint256	The amount of issued token depoisited.
_minAmountOut	uint256	The minimum acceptable amount the user expects to receive from the transaction.

getReserveRatioForBuying

Returns reserve ratio set for buying, used in the {BancorFormula} contract.

function getReserveRatioForBuying() external view returns (uint32);

Returns

Name	Type	Description
<none>	uint32	Reserve Ratio for buying.

getReserveRatioForSelling

Returns reserve ratio set for selling, used in the {BancorFormula} contract.

function getReserveRatioForSelling() external view returns (uint32);

Returns

Name	Type	Description
<none>	uint32	Reserve Ratio for selling.

getStaticPriceForBuying

Calculates and returns the static price for buying the issuance token. The return value is formatted in PPM.

Calculates the static price for either selling or buying the issuance token, based on the provided issuance token supply, collateral supply, and buy or sell reserve ratio. Note: The reserve ratio specifies whether the sell or buy price is returned. The formula used is: PPM * PPM * collateralSupply / (issuanceTokenSupply * reserveRatio). The formula is based on Aragon's BatchedBancorMarketMaker, which can be found here: https://github.com/AragonBlack/fundraising/blob/5ad1332955bab9d36cfad345ae92b7ad7dc0bdbe/apps/batched-bancor-market-maker/contracts/BatchedBancorMarketMaker.sol#L415

function getStaticPriceForBuying()
    external
    view
    override(BondingCurveBase_v1)
    returns (uint);

Returns

Name	Type	Description
<none>	uint256	uint The static price for buying the issuance token.

getStaticPriceForSelling

Calculates and returns the static price for selling the issuance token. The return value is formatted in PPM.

function getStaticPriceForSelling()
    external
    view
    override(RedeemingBondingCurveBase_v1)
    returns (uint);

Returns

Name	Type	Description
<none>	uint256	uint The static price for selling the issuance token.

token

Returns the token.

function token() public view returns (IERC20);

Returns

Name	Type	Description
<none>	IERC20	The token.

transferOrchestratorToken

Transfer a specified amount of Tokens to a designated receiver address.

This function MUST be restricted to be called only by the {Orchestrator_v1}.

function transferOrchestratorToken(address to, uint amount)
    external
    virtual
    onlyPaymentClient;

Parameters

Name	Type	Description
to	address	The address that will receive the tokens.
amount	uint256	The amount of tokens to be transfered.

setVirtualIssuanceSupply

Sets the virtual issuance supply to a new value.

This function calls the internal function _setVirtualIssuanceSupply. The function must be implemented by the downstream contract. The downstream contract should manage access control for setting the supply.

function setVirtualIssuanceSupply(uint _virtualSupply)
    external
    virtual
    override(VirtualIssuanceSupplyBase_v1)
    onlyOrchestratorAdmin
    onlyWhenCurveInteractionsAreClosed;

Parameters

Name	Type	Description
_virtualSupply	uint256	The new value to set for the virtual issuance supply.

setVirtualCollateralSupply

Sets the virtual collateral supply to a new value.

This function should call the internal function _setVirtualCollateralSupply. The function must be implemented by the downstream contract. The downstream contract should manage access control for setting the supply.

function setVirtualCollateralSupply(uint _virtualSupply)
    external
    virtual
    override(VirtualCollateralSupplyBase_v1)
    onlyOrchestratorAdmin
    onlyWhenCurveInteractionsAreClosed;

Parameters

Name	Type	Description
_virtualSupply	uint256	The new value to set for the virtual collateral supply.

setReserveRatioForBuying

Set the reserve ratio used for issuing tokens on a bonding curve.

This function can only be called by the {Orchestrator_v1} admin.

function setReserveRatioForBuying(uint32 _reserveRatio)
    external
    virtual
    onlyOrchestratorAdmin
    onlyWhenCurveInteractionsAreClosed;

Parameters

Name	Type	Description
_reserveRatio	uint32	The new reserve ratio for buying, expressed in PPM.

setReserveRatioForSelling

Set the reserve ratio used for redeeming tokens on a bonding curve.

This function can only be called by the {Orchestrator_v1} admin.

function setReserveRatioForSelling(uint32 _reserveRatio)
    external
    virtual
    onlyOrchestratorAdmin
    onlyWhenCurveInteractionsAreClosed;

Parameters

Name	Type	Description
_reserveRatio	uint32	The new reserve ratio for selling, expressed in PPM.

_issueTokensFormulaWrapper

Calculates the amount of tokens to mint for a given deposit amount using the {BancorFormula}. This internal function is an override of {BondingCurveBase_v1}'s abstract function. It handles decimal conversions and calculations through the bonding curve.

function _issueTokensFormulaWrapper(uint _depositAmount)
    internal
    view
    override(BondingCurveBase_v1)
    returns (uint mintAmount);

Parameters

Name	Type	Description
_depositAmount	uint256	The amount of collateral deposited to purchase tokens.

Returns

Name	Type	Description
mintAmount	uint256	The amount of tokens that will be minted.

_redeemTokensFormulaWrapper

Calculates the amount of collateral to be received when redeeming a given amount of tokens. This internal function is an override of {RedeemingBondingCurveBase_v1}'s abstract function. It handles decimal conversions and calculations through the bonding curve. Note the {BancorFormula} assumes 18 decimals for all tokens.

function _redeemTokensFormulaWrapper(uint _depositAmount)
    internal
    view
    override(RedeemingBondingCurveBase_v1)
    returns (uint redeemAmount);

Parameters

Name	Type	Description
_depositAmount	uint256	The amount of tokens to be redeemed for collateral.

Returns

Name	Type	Description
redeemAmount	uint256	The amount of collateral that will be received.

_setIssuanceToken

Sets the issuance token for the Bonding Curve Funding Manager. This function overrides the internal function set in {BondingCurveBase_v1}, adding an input validation specific for the {BancorFormula} utilizing implementation, after which it updates the issuanceToken state variable and caches the decimals as issuanceTokenDecimals.

function _setIssuanceToken(address _issuanceToken)
    internal
    override(BondingCurveBase_v1);

Parameters

Name	Type	Description
_issuanceToken	address	The token which will be issued by the Bonding Curve.

_setVirtualCollateralSupply

Internal function to directly set the virtual collateral supply to a new value.

function _setVirtualCollateralSupply(uint _virtualSupply)
    internal
    override(VirtualCollateralSupplyBase_v1);

Parameters

Name	Type	Description
_virtualSupply	uint256	The new value to set for the virtual collateral supply.

_setVirtualIssuanceSupply

Internal function to directly set the virtual issuance supply to a new value. Virtual supply cannot be zero, or result in rounded down being zero when conversion is done for use in the Bancor Formulat.

function _setVirtualIssuanceSupply(uint _virtualSupply)
    internal
    override(VirtualIssuanceSupplyBase_v1);

Parameters

Name	Type	Description
_virtualSupply	uint256	The new value to set for the virtual issuance supply.

_setReserveRatioForBuying

Sets the reserve ratio for buying tokens. The function will revert if the ratio is greater than the constant PPM.

function _setReserveRatioForBuying(uint32 _reserveRatio) internal;

Parameters

Name	Type	Description
_reserveRatio	uint32	The reserve ratio to be set for buying tokens. Must be <= PPM.

_setReserveRatioForSelling

Sets the reserve ratio for selling tokens. Similar to its counterpart for buying, this function sets the reserve ratio for selling tokens. The function will revert if the ratio is greater than the constant PPM.

function _setReserveRatioForSelling(uint32 _reserveRatio) internal;

Parameters

Name	Type	Description
_reserveRatio	uint32	The reserve ratio to be set for selling tokens. Must be <= PPM.

_validateReserveRatio

Validates the reserve ratio for buying and selling. The function will revert if the ratio is greater than the constant PPM.

function _validateReserveRatio(uint32 _reserveRatio) internal pure;

Parameters

Name	Type	Description
_reserveRatio	uint32	The reserve ratio to be validated. Must be <= PPM.

_checkCurveInteractionClosedModifier

Checks if the buy and sell functionality is closed.

function _checkCurveInteractionClosedModifier() internal view;

_handleCollateralTokensBeforeBuy

Handles incoming collateral tokens by transferring them from the provider.

function _handleCollateralTokensBeforeBuy(address _provider, uint _amount)
    internal
    virtual
    override;

Parameters

Name	Type	Description
_provider	address	The address that provides the collateral tokens.
_amount	uint256	The amount of collateral tokens to handle.

_handleIssuanceTokensAfterBuy

Handles issuance tokens by minting them to the receiver.

function _handleIssuanceTokensAfterBuy(
    address _receiver,
    uint _issuanceTokenAmount
) internal virtual override;

Parameters

Name	Type	Description
_receiver	address	The address that will receive the bought tokens.
_issuanceTokenAmount	uint256	The amount of issuance tokens to handle.

_handleCollateralTokensAfterSell

Handles collateral tokens by transferring them to the receiver.

function _handleCollateralTokensAfterSell(
    address _receiver,
    uint _collateralTokenAmount
) internal virtual override;

Parameters

Name	Type	Description
_receiver	address	The address that will receive the collateral tokens.
_collateralTokenAmount	uint256	The amount of collateral tokens to handle.