Trader Joe v2 contest details

• $95,000 USDC main award pot
• $5,000 USDC gas optimization award pot
• Join C4 Discord to register
• Submit findings using the C4 form
• Read our guidelines for more details
• Starts October 14, 2022 20:00 UTC
• Ends October 23, 2022 20:00 UTC

Description

This repository contains the Liquidity Book contracts, as well as tests and deploy scripts.

• The LBPair is the contract that contains all the logic of the actual pair for swaps, adds, removals of liquidity and fee claiming. This contract should never be deployed directly, and the factory should always be used for that matter.

• The LBToken is the contract that is used to calculate the shares of a user. The LBToken is a new token standard that is similar to ERC-1155, but without any callbacks (for safety reasons) and any functions or variables relating to ERC-721. To make liquidity management easier, helper functions were added to return user's positions.

• The LBFactory is the contract used to deploy the different pairs and acts as a registry for all the pairs already created. There are also privileged functions such as setting the parameters of the fees, the flashloan fee, setting the pair implementation, set if a pair should be ignored by the quoter and add new presets. Unless the creationUnlocked is true, only the owner of the factory can create pairs.

• The LBRouter is the main contract that user will interact with as it adds security checks. Most users shouldn't interact directly with the pair.

• The LBQuoter is a contract that is used to return the best route of all those given. This should be used before a swap to get the best return on a swap.

For more information, go to the documentation and the whitepaper.

Describe any novel or unique curve logic or mathematical models implemented in the contracts:

• Price curve is discretized into constant sum bins
• We use 128x128 fixed-point binary numbers to cover the entire price range
• The max number of bins is 2**24
• Each pair has a three-level trie that tracks the presence of liquidity in each bin

Does the token conform to the ERC-20 standard? In what specific ways does it differ?

• The token doesn't conform to the ERC-20 standard, but it's closer to the ERC-1155 standard.
• The token can only be used for sets of ERC-20, and thus, can't create any ERC721. It also removes the callbacks for safety reasons.

Identify any areas of specific concern in reviewing the code:

• The volatility accumulator formula has changed since the whitepaper was published, reviewers should refer to the docs for the most up to date version.
• One area of concern is whether users can "steal" tokens, i.e. they get more than expected. For example:
  • Receiving more tokens than expected during a swap
  • Performing a successful flash loan without repaying back the loaned tokens or the fee
  • Receiving more liquidity tokens than expected when adding liquidity
  • Receiving more tokens than expected when liquidity is removed
  • Receiving more fees than expected when fees are claimed
• Math rounding should never favour the user. For example, when liquidity is removed, token amounts should be rounded down to ensure they don't get more than expected and when an user swaps, it should round up the amountIn, while rounding down the amountOut to make sure they don't get more than expected.
• Ensuring invariants hold. For example:
  • When adding liquidity, reserves should only increase
  • When doing a flashLoan, fees should only increase
  • When removing liquidity, reserves should only decrease
  • When swapping tokens, L should remain constant, while x and y should follow L = p * x + y and fees should only increase
  • When adding liquidity to the active bin, if the tokens are not added with the same ratio as the reserve of the active bin, the fees should only increase
  • When claiming fees, the fees should only decrease and the reserves should stay constant

Contracts

All contracts under src are in Scope for this contest, including src/libraries and src/interfaces. Contracts under lib are not in Scope.

Core

LBToken

• 227 sloc
• External contracts called: None
• Libraries used: LBErrors, EnumerableSet

LBPair

• 837 sloc
• External contracts called: ERC20, LBFactory, ILBFlashLoanCallback
• Libraries used: LBToken, BinHelper, Math512Bits, SafeCast, SafeMath, TreeMath, Constants, ReentrancyGuardUpgradeable, Oracle, Decoder, SwapHelper, FeeDistributionHelper, TokenHelper

LBFactory

• 507 sloc
• External contracts called: LBPair
• Libraries used: EnumerableSet, Clones, LBErrors, PendingOwnable, Constants, Decoder, SafeCast

LBRouter

• 837 sloc
• External contracts called: LBPair, JoePair
• Libraries used: LBErrors, BinHelper, FeeHelper, TokenHelper, Math512Bits, SwapHelper, Constants

LBQuoter

• 214 sloc
• External contracts called: LBPair, JoeFactory, LBFactory, LBRouter
• Libraries used: JoeLibrary, BinHelper, Math512Bits

LBErrors

• 148 sloc
• External contracts called: None
• Libraries used: None

Libraries

BinHelper

• 48 sloc
• External contracts called: None
• Libraries used: Math128x128, LBErrors

BitMath

• 133 sloc
• External contracts called: None
• Libraries used: None

Buffer

• 24 sloc
• External contracts called: None
• Libraries used: None

Constants

• 11 sloc
• External contracts called: None
• Libraries used: None

Decoder

• 22 sloc
• External contracts called: None
• Libraries used: None

Encoder

• 22 sloc
• External contracts called: None
• Libraries used: None

FeeDistributionHelper

• 52 sloc
• External contracts called: ERC20
• Libraries used: LBErrors, FeeHelper, Constants, TokenHelper, SafeCast

FeeHelper

• 145 sloc
• External contracts called: None
• Libraries used: SafeCast, SafeMath, Constants

JoeLibrary

• 50 sloc
• External contracts called: None
• Libraries used: LBErrors

Math128x128

• 183 sloc
• External contracts called: None
• Libraries used: LBErrors, Math512Bits, BitMath, Constants

Math512Bits

• 229 sloc
• External contracts called: None
• Libraries used: LBErrors, BitMath

Oracle

• 166 sloc
• External contracts called: None
• Libraries used: LBErrors, Samples, Buffer

PendingOwnable

• 91 sloc
• External contracts called: None
• Libraries used: LBErrors

ReentrancyGuardUpgradeable

• 43 sloc
• External contracts called: None
• Libraries used: LBErrors

SafeCast

• 194 sloc
• External contracts called: None
• Libraries used: LBErrors

SafeMath

• 16 sloc
• External contracts called: None
• Libraries used: None

Samples

• 103 sloc
• External contracts called: None
• Libraries used: Encoder, Decoder

SwapHelper

• 120 sloc
• External contracts called: None
• Libraries used: FeeHelper, Constants, BinHelper, SafeMath, FeeDistributionHelper, Math512Bits

TokenHelper

• 75 sloc
• External contracts called: None
• Libraries used: LBErrors, Samples, Buffer

TreeMath

• 101 sloc
• External contracts called: None
• Libraries used: LBErrors, BitMath

Install foundry

Foundry documentation can be found here.

On Linux and macOS

Open your terminal and type in the following command:

curl -L https://foundry.paradigm.xyz | bash

This will download foundryup. Then install Foundry by running:

foundryup

To update foundry after installation, simply run foundryup again, and it will update to the latest Foundry release. You can also revert to a specific version of Foundry with foundryup -v $VERSION.

On Windows

If you use Windows, you need to build from source to get Foundry.

Download and run rustup-init from rustup.rs. It will start the installation in a console.

After this, run the following to build Foundry from source:

cargo install --git https://github.com/foundry-rs/foundry foundry-cli anvil --bins --locked

To update from source, run the same command again.

Install dependencies

To install dependencies, run the following to install dependencies:

forge install

---

Tests

To run tests, run the following command:

forge test

To run slither, run the following command:

slither --solc-remaps "ds-test/=lib/forge-std/lib/ds-test/src/ forge-std/=lib/forge-std/src/ openzeppelin/=lib/openzeppelin-contracts/contracts/" src/