BancorFormula

Function `init()`

should be executed after construction (too large for the constructor)

Function `purchaseTargetAmount(uint256 _supply, uint256 _reserveBalance, uint32 _reserveWeight, uint256 _amount) → uint256`

given a token supply, reserve balance, weight and a deposit amount (in the reserve token),

calculates the target amount for a given conversion (in the main token)

Formula:

return = _supply * ((1 + _amount / _reserveBalance) ^ (_reserveWeight / 1000000) - 1)

Parameters:

_supply: liquid token supply
_reserveBalance: reserve balance
_reserveWeight: reserve weight, represented in ppm (1-1000000)
_amount: amount of reserve tokens to get the target amount for

Function `saleTargetAmount(uint256 _supply, uint256 _reserveBalance, uint32 _reserveWeight, uint256 _amount) → uint256`

given a token supply, reserve balance, weight and a sell amount (in the main token),

calculates the target amount for a given conversion (in the reserve token)

Formula:

return = _reserveBalance * (1 - (1 - _amount / _supply) ^ (1000000 / _reserveWeight))

Parameters:

_supply: liquid token supply
_reserveBalance: reserve balance
_reserveWeight: reserve weight, represented in ppm (1-1000000)
_amount: amount of liquid tokens to get the target amount for

Return Values:

reserve token amount

Function `crossReserveTargetAmount(uint256 _sourceReserveBalance, uint32 _sourceReserveWeight, uint256 _targetReserveBalance, uint32 _targetReserveWeight, uint256 _amount) → uint256`

given two reserve balances/weights and a sell amount (in the first reserve token),

calculates the target amount for a conversion from the source reserve token to the target reserve token

Formula:

return = _targetReserveBalance * (1 - (_sourceReserveBalance / (_sourceReserveBalance + _amount)) ^ (_sourceReserveWeight / _targetReserveWeight))

Parameters:

_sourceReserveBalance: source reserve balance
_sourceReserveWeight: source reserve weight, represented in ppm (1-1000000)
_targetReserveBalance: target reserve balance
_targetReserveWeight: target reserve weight, represented in ppm (1-1000000)
_amount: source reserve amount

Return Values:

target reserve amount

Function `fundCost(uint256 _supply, uint256 _reserveBalance, uint32 _reserveRatio, uint256 _amount) → uint256`

given a pool token supply, reserve balance, reserve ratio and an amount of requested pool tokens,

calculates the amount of reserve tokens required for purchasing the given amount of pool tokens

Formula:

return = _reserveBalance * (((_supply + _amount) / _supply) ^ (MAX_WEIGHT / _reserveRatio) - 1)

Parameters:

_supply: pool token supply
_reserveBalance: reserve balance
_reserveRatio: reserve ratio, represented in ppm (2-2000000)
_amount: requested amount of pool tokens

Return Values:

reserve token amount

Function `fundSupplyAmount(uint256 _supply, uint256 _reserveBalance, uint32 _reserveRatio, uint256 _amount) → uint256`

given a pool token supply, reserve balance, reserve ratio and an amount of reserve tokens to fund with,

calculates the amount of pool tokens received for purchasing with the given amount of reserve tokens

Formula:

return = _supply * ((_amount / _reserveBalance + 1) ^ (_reserveRatio / MAX_WEIGHT) - 1)

Parameters:

_supply: pool token supply
_reserveBalance: reserve balance
_reserveRatio: reserve ratio, represented in ppm (2-2000000)
_amount: amount of reserve tokens to fund with

Return Values:

pool token amount

Function `liquidateReserveAmount(uint256 _supply, uint256 _reserveBalance, uint32 _reserveRatio, uint256 _amount) → uint256`

given a pool token supply, reserve balance, reserve ratio and an amount of pool tokens to liquidate,

calculates the amount of reserve tokens received for selling the given amount of pool tokens

Formula:

return = _reserveBalance * (1 - ((_supply - _amount) / _supply) ^ (MAX_WEIGHT / _reserveRatio))

Parameters:

_supply: pool token supply
_reserveBalance: reserve balance
_reserveRatio: reserve ratio, represented in ppm (2-2000000)
_amount: amount of pool tokens to liquidate

Return Values:

reserve token amount

Function `balancedWeights(uint256 _primaryReserveStakedBalance, uint256 _primaryReserveBalance, uint256 _secondaryReserveBalance, uint256 _reserveRateNumerator, uint256 _reserveRateDenominator) → uint32, uint32`

The arbitrage incentive is to convert to the point where the on-chain price is equal to the off-chain price.

We want this operation to also impact the primary reserve balance becoming equal to the primary reserve staked balance.

In other words, we want the arbitrager to convert the difference between the reserve balance and the reserve staked balance.

Formula input:

let t denote the primary reserve token staked balance
let s denote the primary reserve token balance
let r denote the secondary reserve token balance
let q denote the numerator of the rate between the tokens
let p denote the denominator of the rate between the tokens

Where p primary tokens are equal to q secondary tokens

Formula output:

compute x = W(t / r q / p log(s / t)) / log(s / t)
return x / (1 + x) as the weight of the primary reserve token
return 1 / (1 + x) as the weight of the secondary reserve token

Where W is the Lambert W Function

If the rate-provider provides the rates for a common unit, for example:

P = 2 ==> 2 primary reserve tokens = 1 ether
Q = 3 ==> 3 secondary reserve tokens = 1 ether

Then you can simply use p = P and q = Q

If the rate-provider provides the rates for a single unit, for example:

P = 2 ==> 1 primary reserve token = 2 ethers
Q = 3 ==> 1 secondary reserve token = 3 ethers

Then you can simply use p = Q and q = P

Parameters:

_primaryReserveStakedBalance: the primary reserve token staked balance
_primaryReserveBalance: the primary reserve token balance
_secondaryReserveBalance: the secondary reserve token balance
_reserveRateNumerator: the numerator of the rate between the tokens
_reserveRateDenominator: the denominator of the rate between the tokens

Note that numerator / denominator should represent the amount of secondary tokens equal to one primary token