Skip to content

Commit

Permalink
feat: adding natspec (#64)
Browse files Browse the repository at this point in the history 
* feat: add interfaces for bPool

* feat: add interfaces for bFactory

* fix: parameter names in events from IBPool.sol

* feat: add natspec for IBFactory

* feat: add natspec for IBPool.sol

* fix: revert unnecessary change

* feat: add inheritdoc tag

* feat: add natspec for BMath.sol

* feat: inheritdoc in one line

* feat: improve bMath natspec

* feat: improve bPool natspec

* feat: improve IBFactory natspec

* feat: improve IBPool natspec

* feat: improve natspec

* fix: notice line in BMath

* feat: clarify price denomination in calcSpotPrice

* fix: wrong path in natspec smells config

* fix: missing natspec
  • Loading branch information
@0xAustrian
0xAustrian authored Jun 7, 2024
1 parent cb23dbf commit 45d29b1
Show file tree
Hide file tree
Showing 7 changed files with 422 additions and 91 deletions.
2 changes: 1 addition & 1 deletion natspec-smells.config.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,5 +4,5 @@

/** @type {import('@defi-wonderland/natspec-smells').Config} */
module.exports = {
include: 'src'
include: 'src/**/*.sol'
};
12 changes: 11 additions & 1 deletion src/contracts/BFactory.sol
View file
Original file line number Diff line number Diff line change
@@ -1,19 +1,25 @@
// SPDX-License-Identifier: GPL-3.0-or-later
pragma solidity 0.8.25;

// Builds new BPools, logging their addresses and providing `isBPool(address) -> (bool)`
import {BPool} from './BPool.sol';
import {IBFactory} from 'interfaces/IBFactory.sol';
import {IBPool} from 'interfaces/IBPool.sol';

/**
* @title BFactory
* @notice Creates new BPools, logging their addresses and acting as a registry of pools.
*/
contract BFactory is IBFactory {
/// @dev Mapping indicating whether the address is a BPool.
mapping(address => bool) internal _isBPool;
/// @dev bLabs address.
address internal _blabs;

constructor() {
_blabs = msg.sender;
}

/// @inheritdoc IBFactory
function newBPool() external returns (IBPool _pool) {
IBPool bpool = new BPool();
_isBPool[address(bpool)] = true;
Expand All @@ -22,23 +28,27 @@ contract BFactory is IBFactory {
return bpool;
}

/// @inheritdoc IBFactory
function setBLabs(address b) external {
require(msg.sender == _blabs, 'ERR_NOT_BLABS');
emit LOG_BLABS(msg.sender, b);
_blabs = b;
}

/// @inheritdoc IBFactory
function collect(IBPool pool) external {
require(msg.sender == _blabs, 'ERR_NOT_BLABS');
uint256 collected = pool.balanceOf(address(this));
bool xfer = pool.transfer(_blabs, collected);
require(xfer, 'ERR_ERC20_FAILED');
}

/// @inheritdoc IBFactory
function isBPool(address b) external view returns (bool) {
return _isBPool[b];
}

/// @inheritdoc IBFactory
function getBLabs() external view returns (address) {
return _blabs;
}
Expand Down
180 changes: 109 additions & 71 deletions src/contracts/BMath.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,22 @@ import {BNum} from './BNum.sol';

contract BMath is BConst, BNum {
/**
*
* calcSpotPrice
* sP = spotPrice
* bI = tokenBalanceIn ( bI / wI ) 1
* bO = tokenBalanceOut sP = ----------- * ----------
* wI = tokenWeightIn ( bO / wO ) ( 1 - sF )
* wO = tokenWeightOut
* sF = swapFee
*
* @notice Calculate the spot price of a token in terms of another one
* @dev The price denomination depends on the decimals of the tokens.
* @dev To obtain the price with 18 decimals the next formula should be applied to the result
* @dev spotPrice = spotPrice ÷ (10^tokenInDecimals) × (10^tokenOutDecimals)
* @param tokenBalanceIn The balance of the input token in the pool
* @param tokenWeightIn The weight of the input token in the pool
* @param tokenBalanceOut The balance of the output token in the pool
* @param tokenWeightOut The weight of the output token in the pool
* @param swapFee The swap fee of the pool
* @dev Formula:
* sP = spotPrice
* bI = tokenBalanceIn ( bI / wI ) 1
* bO = tokenBalanceOut sP = ----------- * ----------
* wI = tokenWeightIn ( bO / wO ) ( 1 - sF )
* wO = tokenWeightOut
* sF = swapFee
*/
function calcSpotPrice(
uint256 tokenBalanceIn,
Expand All @@ -31,16 +38,21 @@ contract BMath is BConst, BNum {
}

/**
*
* calcOutGivenIn
* aO = tokenAmountOut
* bO = tokenBalanceOut
* bI = tokenBalanceIn / / bI \ (wI / wO) \
* aI = tokenAmountIn aO = bO * | 1 - | -------------------------- | ^ |
* wI = tokenWeightIn \ \ ( bI + ( aI * ( 1 - sF )) / /
* wO = tokenWeightOut
* sF = swapFee
*
* @notice Calculate the amount of token out given the amount of token in for a swap
* @param tokenBalanceIn The balance of the input token in the pool
* @param tokenWeightIn The weight of the input token in the pool
* @param tokenBalanceOut The balance of the output token in the pool
* @param tokenWeightOut The weight of the output token in the pool
* @param tokenAmountIn The amount of the input token
* @param swapFee The swap fee of the pool
* @dev Formula:
* aO = tokenAmountOut
* bO = tokenBalanceOut
* bI = tokenBalanceIn / / bI \ (wI / wO) \
* aI = tokenAmountIn aO = bO * | 1 - | -------------------------- | ^ |
* wI = tokenWeightIn \ \ ( bI + ( aI * ( 1 - sF )) / /
* wO = tokenWeightOut
* sF = swapFee
*/
function calcOutGivenIn(
uint256 tokenBalanceIn,
Expand All @@ -61,16 +73,21 @@ contract BMath is BConst, BNum {
}

/**
*
* calcInGivenOut
* aI = tokenAmountIn
* bO = tokenBalanceOut / / bO \ (wO / wI) \
* bI = tokenBalanceIn bI * | | ------------ | ^ - 1 |
* aO = tokenAmountOut aI = \ \ ( bO - aO ) / /
* wI = tokenWeightIn --------------------------------------------
* wO = tokenWeightOut ( 1 - sF )
* sF = swapFee
*
* @notice Calculate the amount of token in given the amount of token out for a swap
* @param tokenBalanceIn The balance of the input token in the pool
* @param tokenWeightIn The weight of the input token in the pool
* @param tokenBalanceOut The balance of the output token in the pool
* @param tokenWeightOut The weight of the output token in the pool
* @param tokenAmountOut The amount of the output token
* @param swapFee The swap fee of the pool
* @dev Formula:
* aI = tokenAmountIn
* bO = tokenBalanceOut / / bO \ (wO / wI) \
* bI = tokenBalanceIn bI * | | ------------ | ^ - 1 |
* aO = tokenAmountOut aI = \ \ ( bO - aO ) / /
* wI = tokenWeightIn --------------------------------------------
* wO = tokenWeightOut ( 1 - sF )
* sF = swapFee
*/
function calcInGivenOut(
uint256 tokenBalanceIn,
Expand All @@ -91,16 +108,22 @@ contract BMath is BConst, BNum {
}

/**
*
* calcPoolOutGivenSingleIn
* pAo = poolAmountOut / \
* tAi = tokenAmountIn /// / // wI \ \\ \ wI \
* wI = tokenWeightIn //| tAi *| 1 - || 1 - -- | * sF || + tBi \ -- \
* tW = totalWeight pAo=|| \ \ \\ tW / // | ^ tW | * pS - pS
* tBi = tokenBalanceIn \\ ------------------------------------- / /
* pS = poolSupply \\ tBi / /
* sF = swapFee \ /
*
* @notice Calculate the amount of pool tokens that should be minted,
* given a single token in when joining a pool
* @param tokenBalanceIn The balance of the input token in the pool
* @param tokenWeightIn The weight of the input token in the pool
* @param poolSupply The total supply of the pool tokens
* @param totalWeight The total weight of the pool
* @param tokenAmountIn The amount of the input token
* @param swapFee The swap fee of the pool
* @dev Formula:
* pAo = poolAmountOut / \
* tAi = tokenAmountIn /// / // wI \ \\ \ wI \
* wI = tokenWeightIn //| tAi *| 1 - || 1 - -- | * sF || + tBi \ -- \
* tW = totalWeight pAo=|| \ \ \\ tW / // | ^ tW | * pS - pS
* tBi = tokenBalanceIn \\ ------------------------------------- / /
* pS = poolSupply \\ tBi / /
* sF = swapFee \ /
*/
function calcPoolOutGivenSingleIn(
uint256 tokenBalanceIn,
Expand Down Expand Up @@ -129,16 +152,21 @@ contract BMath is BConst, BNum {
}

/**
*
* calcSingleInGivenPoolOut
* tAi = tokenAmountIn //(pS + pAo)\ / 1 \\
* pS = poolSupply || --------- | ^ | --------- || * bI - bI
* pAo = poolAmountOut \\ pS / \(wI / tW)//
* bI = balanceIn tAi = --------------------------------------------
* wI = weightIn / wI \
* tW = totalWeight | 1 - ---- | * sF
* sF = swapFee \ tW /
*
* @notice Given amount of pool tokens out, calculate the amount of tokens in that should be sent
* @param tokenBalanceIn The balance of the input token in the pool
* @param tokenWeightIn The weight of the input token in the pool
* @param poolSupply The current total supply
* @param totalWeight The sum of the weight of all tokens in the pool
* @param poolAmountOut The expected amount of pool tokens
* @param swapFee The swap fee of the pool
* @dev Formula:
* tAi = tokenAmountIn //(pS + pAo)\ / 1 \\
* pS = poolSupply || --------- | ^ | --------- || * bI - bI
* pAo = poolAmountOut \\ pS / \(wI / tW)//
* bI = balanceIn tAi = --------------------------------------------
* wI = weightIn / wI \
* tW = totalWeight | 1 - ---- | * sF
* sF = swapFee \ tW /
*/
function calcSingleInGivenPoolOut(
uint256 tokenBalanceIn,
Expand Down Expand Up @@ -166,17 +194,22 @@ contract BMath is BConst, BNum {
}

/**
*
* calcSingleOutGivenPoolIn
* tAo = tokenAmountOut / / \\
* bO = tokenBalanceOut / // pS - (pAi * (1 - eF)) \ / 1 \ \\
* pAi = poolAmountIn | bO - || ----------------------- | ^ | --------- | * b0 ||
* ps = poolSupply \ \\ pS / \(wO / tW)/ //
* wI = tokenWeightIn tAo = \ \ //
* tW = totalWeight / / wO \ \
* sF = swapFee * | 1 - | 1 - ---- | * sF |
* eF = exitFee \ \ tW / /
*
* @notice Calculate the amount of token out given the amount of pool tokens in
* @param tokenBalanceOut The balance of the output token in the pool
* @param tokenWeightOut The weight of the output token in the pool
* @param poolSupply The total supply of the pool tokens
* @param totalWeight The total weight of the pool
* @param poolAmountIn The amount of pool tokens
* @param swapFee The swap fee of the pool
* @dev Formula:
* tAo = tokenAmountOut / / \\
* bO = tokenBalanceOut / // pS - (pAi * (1 - eF)) \ / 1 \ \\
* pAi = poolAmountIn | bO - || ----------------------- | ^ | --------- | * b0 ||
* ps = poolSupply \ \\ pS / \(wO / tW)/ //
* wI = tokenWeightIn tAo = \ \ //
* tW = totalWeight / / wO \ \
* sF = swapFee * | 1 - | 1 - ---- | * sF |
* eF = exitFee \ \ tW / /
*/
function calcSingleOutGivenPoolIn(
uint256 tokenBalanceOut,
Expand Down Expand Up @@ -207,17 +240,22 @@ contract BMath is BConst, BNum {
}

/**
*
* calcPoolInGivenSingleOut
* pAi = poolAmountIn // / tAo \\ / wO \ \
* bO = tokenBalanceOut // | bO - -------------------------- |\ | ---- | \
* tAo = tokenAmountOut pS - || \ 1 - ((1 - (tO / tW)) * sF)/ | ^ \ tW / * pS |
* ps = poolSupply \\ -----------------------------------/ /
* wO = tokenWeightOut pAi = \\ bO / /
* tW = totalWeight -------------------------------------------------------------
* sF = swapFee ( 1 - eF )
* eF = exitFee
*
* @notice Calculate the amount of pool tokens in given an amount of single token out
* @param tokenBalanceOut The balance of the output token in the pool
* @param tokenWeightOut The weight of the output token in the pool
* @param poolSupply The total supply of the pool tokens
* @param totalWeight The total weight of the pool
* @param tokenAmountOut The amount of the output token
* @param swapFee The swap fee of the pool
* @dev Formula:
* pAi = poolAmountIn // / tAo \\ / wO \ \
* bO = tokenBalanceOut // | bO - -------------------------- |\ | ---- | \
* tAo = tokenAmountOut pS - || \ 1 - ((1 - (tO / tW)) * sF)/ | ^ \ tW / * pS |
* ps = poolSupply \\ -----------------------------------/ /
* wO = tokenWeightOut pAi = \\ bO / /
* tW = totalWeight -------------------------------------------------------------
* sF = swapFee ( 1 - eF )
* eF = exitFee
*/
function calcPoolInGivenSingleOut(
uint256 tokenBalanceOut,
Expand Down
Loading

0 comments on commit 45d29b1

Please sign in to comment.