CronV1Pool
Uses Balancer math library for overflow/underflow checks on standard U256 containers. However, as many custom representations are used (i.e. non native word lengths) there are a number of explicit checks against the maximum of other word lengths. Furthermore there are unchecked operations (this code targets Solidity 0.7.x which didn't yet feature implicit arithmetic checks or have the 'unchecked' block feature) herein for reasons of efficiency or desired overflow. Wherever they appear they will be documented and accompanied with one of the following tags: - #unchecked - #overUnderFlowIntended Identified risks will be accompanied and described with the following tag: - #RISK
Conventions in the methods, variables and constants are as follows:
Fee Points (FP) is a system used herein to calculate applicable fees. THESE ABSOLUTELY SHOULD NOT BE CONFUSED WITH BASIS POINTS--THEY ARE NOT BASIS POINTS! It consists of fees, such as a swap fee, expressed in FP. The swap fee is multiplied by the amount of token being swapped and divided by the total fee points (TOTAL_FP), which is 100,000, to obtain the fee. For instance, a swap fee of 0.050% can be realized as follows:
POOL_ID
POOL_TYPE
slot1
slot2
slot3
slot4
priceOracle
adminAddrMap
partnerContractAddrMap
feeAddr
senderIsFactoryOwner
Ensure that the modified function is called by an address that is the factory owner.
Cannot be used on Balancer Vault callbacks (onJoin, onExit, onSwap) because msg.sender is the Vault address.
senderIsAdmin
Ensures that the modified function is called by an address with administrator privileges.
Cannot be used on Balancer Vault callbacks (onJoin, onExit, onSwap) because msg.sender is the Vault address.
senderIsArbitragePartner
Ensures the modified function is called by an address with arbitrage partner privileges.
Cannot be used on Balancer Vault callbacks (onJoin, onExit, onSwap) because msg.sender is the Vault address.
poolNotPaused
Ensures that the modified function is not executed if the pool is currently paused.
constructor
Creates an instance of the Cron-Fi TWAMM pool. A Cron-Fi TWAMM pool features virtual order management and virtualized reserves. Liquidity is managed through an instance of BalancerPoolToken. The fees associated with the pool are configurable at run-time.
Parameters
onSwap
Called by the vault when a user calls IVault.swap. Can be used to perform a Short-Term (ST) swap, Long-Term (LT) swap, or Partner swap ST swaps and Partner swaps behave like traditional Automated Market Maker atomic swaps (think Uniswap V2 swaps). LT swaps are virtual orders and behave differently, executing over successive blocks until their expiry. Each LT swap is assigned an order id that is logged in a LongTermSwap event and can also be fetched using getOrderIds for a given address. LT swaps can be withdrawn or cancelled through the IVault.exit function (see onExitPool documentation).
Parameters
Return Values
onJoinPool
Called by the Vault when a user calls IVault.joinPool. Can be use to add liquidity to the pool in exchange for Liquidity Provider (LP) pool tokens or to reward the pool with liquidity (MEV rewards from arbitrageurs). WARNING: The initial liquidity provider, in a call to join the pool with joinTypeU=0 (JoinType.Join), will sacrifice MINIMUM_LIQUIDITY, 1000, Liquidity Provider (LP) tokens. This may be an insignificant sacrifice for tokens with fewer decimal places and high worth (i.e. WBTC). Importantly, the reward capability remains when the pool is paused to mitigate any possible issue with underflowed pool reserves computed by differencing the pool accounting from the pool token balances.
Parameters
Return Values
onExitPool
Called by the Vault when a user calls IVault.exitPool. Can be used to remove liquidity from the pool in exchange for Liquidity Provider (LP) pool tokens, to withdraw proceeds of a Long-Term (LT) order, to cancel an LT order, or by the factory owner to withdraw protocol fees if they are being collected.
Parameters
Return Values
setAdminStatus
Set the administrator status of the provided address, _admin. Status "true" gives administrative privileges, "false" removes privileges.
CAREFUL! You can remove all administrative privileges, rendering the contract unmanageable. NOTE: Must be called by the factory owner.
Parameters
setFeeAddress
Enables Cron-Fi fee collection for Long-Term swaps when the provided address, _feeDestination is not the null address.
_CAREFUL! Only the feeDestination address can collect Cron-Fi fees from the pool. NOTE: Must be called by the factory owner.
Parameters
setPause
Sets whether the pool is paused or not. When the pool is paused: * New swaps of any kind cannot be issued. * Liquidity cannot be provided. * Virtual orders are not executed for the remainder of allowable operations, which include: removing liquidity, cancelling or withdrawing a Long-Term swap order, This is a safety measure that is not a part of expected pool operations.
NOTE: Must be called by an administrator.
Parameters
setParameter
Set fee parameters.
NOTE: Total FP = 100,000. Thus a fee portion is the number of FP out of 100,000. NOTE: Must be called by an administrator.
Parameters
setCollectBalancerFees
Enable or disable the collection of Balancer Fees. When enabled Balancer takes a a portion of every fee collected in the pool. The pool remits fees to Balancer automatically when onJoinPool and onExitPool are called. Disabling balancer fees through this function supersedes any setting of balancer fee values in onJoinPool and onExitPool.
NOTE: Must be called by the factory owner.
Parameters
setFeeShift
Sets the fee shift that splits Long-Term (LT) swap fees remaining after Balancer's cut between the Liquidity Providers (LP) and Cron-Fi, if Cron-Fi fee collection is enabled.
NOTE: Must be called by the factory owner.
Parameters
setArbitragePartner
Sets the arbitrageur list contract address, _arbitrageList, for an arbitrage partner, _arbPartner. To clear an arbitrage partner, set _arbitrageList to the null address.
NOTE: Must be called by an administrator.
Parameters
updateArbitrageList
Advances the specified arbitrage partner (msg.sender) arbitrageur list contract to the newest contract, if available. See IArbitrageurList for details on the calls made by this contract to that interface's nextList function.
NOTE: Must be called by an arbitrage partner.
Return Values
executeVirtualOrdersToBlock
Executes active virtual orders, Long-Term swaps, since the last virtual order block executed, updating reserve and other state variables to the current block.
Parameters
getVirtualPriceOracle
Get the virtual price oracle data for the pool at the specified block, _maxBlock.
_Check that blockNumber matches _maxBlock to ensure that maxBlock was correctly specified.
Parameters
Return Values
getVirtualReserves
Returns the TWAMM pool's reserves after the non-stateful execution of all virtual orders up to the specified maximum block (unless an invalid block is specified, which results in execution to the current block).
Parameters
Return Values
getPriceOracle
Get the price oracle data for the pool as of the last virtual order block.
Return Values
getOrderIds
Return an array of the order IDs for the specified user _owner. Allows all orders to be fetched at once or pagination through the _offset and _maxResults parameters. For instance to get the first 100 orderIds of a user, specify _offset=0 and _maxResults=100. To get the second 100 orderIds for the same user, specify _offset=100 and _maxResults=100. To get all results at once, either specify all known results or 0 for _maxResults.
Parameters
Return Values
getOrder
Return the order information of a given order id.
Parameters
Return Values
getOrderIdCount
Returns the number of virtual orders, Long-Term (LT) swaps, that have been transacted in this pool.
Return Values
getSalesRates
Returns the sales rate of each of the two order pools at the last virtual order block. This is the value persisted to state.
Return Values
getLastVirtualOrderBlock
Get the Last Virtual Order Block (LVOB) for the pool. This is the block number indicating the last block where virtual orders have been executed by the pool. If the LVOB is significantly less than the current block number, it indicates that the pool has been inactive and that a call to any function that requires the execution of virtual orders may incur siginificant gas use.
Return Values
getSalesRatesEndingPerBlock
Get the sales rate ending (per block) at the specified block number.
NOTE: these values are inserted into state at block numbers divisible by the Order Block Interval (OBI)--specifiying block numbers other than those evenly divisible by the OBI will result in the returned values being zero.
Parameters
getShortTermFeePoints
Gets the current Short-Term (ST) swap fee for the pool in Fee Points.
NOTE: Total FP = 100,000. Thus a fee portion is the number of FP out of 100,000.
Return Values
getPartnerFeePoints
Gets the current Partner swap fee for the pool in Fee Points.
NOTE: Total FP = 100,000. Thus a fee portion is the number of FP out of 100,000.
Return Values
getLongTermFeePoints
Gets the current Long-Term (LT) swap fee for the pool in Fee Points.
NOTE: Total FP = 100,000. Thus a fee portion is the number of FP out of 100,000.
Return Values
getOrderAmounts
Gets the amounts of Token0 and Token1 in active virtual orders waiting to be sold to the pool as of the last virtual order block.
Return Values
getProceedAmounts
Get the proceeds of Token0 and Token1 resulting from virtual orders, Long-Term swaps, up to the last virtual order block.
Return Values
getFeeShift
Gets the current value of the fee shift, which indicates how Long-Term (LT) swap fees are split between Cron-Fi and Liquidity Providers (LPs) when Cron-Fi fee collection is enabled.
Return Values
getCronFeeAmounts
Gets the amounts of Token0 and Token1 collected as Cron-Fi fees on Long-Term (LT) swaps as of the last virtual order block.
Return Values
isCollectingCronFees
Use to determine if the pool is collecting Cron-Fi fees currently (Cron-Fi fees are only collected on Long-Term swaps if enabled).
Return Values
isCollectingBalancerFees
Use to determine if the pool is collecting Balancer fees currently (Balancer fees apply to any fee collected by the pool--Short and Long Term swaps).
Return Values
getBalancerFee
Get the Balancer Fee charged by the pool.
Return Values
getBalancerFeeAmounts
Gets the amounts of Token0 and Token1 collected as Balancer fees on all swaps as of the last virtual order block.
Return Values
isPaused
Use to determine if the pool's virtual orders are currently paused. If virtual orders are paused, the pool will allow Long-Term (LT) swaps to be cancelled and withdrawn from as well as liquidity positions to be withdrawn.
Return Values
_senderIsFactoryOwner
Reverts with error if msg.sender is not the factory owner.
This internal function is a modifier contract size optimization.
_senderIsAdmin
Reverts with error if msg.sender is not a pool administrator.
This internal function is a modifier contract size optimization.
_senderIsArbitragePartner
Reverts with error if msg.sender is not an arbitrage partner.
This internal function is a modifier contract size optimization.
_poolNotPaused
Reverts with error if the pool is paused.
This internal function is a modifier contract size optimization.
_calculateProceeds
Computes the proceeds of a virtual order, Long-Term (LT) swap, for withdrawl or cancellation purposes. Proceeds are determined using the staking algorithm, where the user's order sales rate, _stakedAmountU128, represents their stake and the difference between the normalized proceeds at this juncture or their order end and order start are used to calculate their share. The normalized proceeds are stored in 128-bits with 64 fractional-bits, hence the scaling down by 64-bits below.
Note explanations for required underflow in this calculation below.
Parameters
Last updated