README.md

Balancer V2 Monorepo

This repository contains the Balancer Protocol V2 core smart contracts, including the Vault and standard Pools, along with their tests. Deployment configuration and information can be found at the balancer-deployments repository.

For a high-level introduction to Balancer V2, see Introducing Balancer V2: Generalized AMMs.

Structure

This is a Yarn monorepo, with the packages meant to be published in the pkg directory. Newly developed packages may not be published yet.

Active development occurs in this repository, which means some contracts in it might not be production-ready. Proceed with caution.

Packages

• v2-interfaces: Solidity interfaces for all contracts.
• v2-vault: the Vault contract and all core interfaces, including IVault and the Pool interfaces: IBasePool, IGeneralPool and IMinimalSwapInfoPool.
• v2-pool-weighted: the WeightedPool, and LiquidityBootstrappingPool contracts, along with their associated factories.
• v2-pool-linear: the LinearPool contracts, along with its associated factory. Derived Linear Pools can be found in the Orb Collective repo.
• v2-pool-utils: Solidity utilities used to develop Pool contracts.
• v2-solidity-utils: miscellaneous Solidity helpers and utilities used in many different contracts.
• v2-standalone-utils: miscellaneous standalone utility contracts.
• v2-liquidity-mining: contracts that compose the liquidity mining (veBAL) system.
• v2-governance-scripts: contracts that execute complex governance actions.

Pre-requisites

The build & test instructions below should work out of the box with Node 18. More specifically, it is recommended to use the LTS version 18.15.0; Node 19 and higher are not supported. Node 18.16.0 has a known issue that makes the build flaky.

Multiple Node versions can be installed in the same system, either manually or with a version manager. One option to quickly select the suggested Node version is using nvm, and running:

$ nvm use

Clone

This repository uses git submodules; use --recurse-submodules option when cloning. For example, using https:

$ git clone --recurse-submodules https://github.com/balancer-labs/balancer-v2-monorepo.git

Build and Test

Before any tests can be run, the repository needs to be prepared:

First time build

$ yarn # install all dependencies
$ yarn workspace @balancer-labs/balancer-js build # build balancer-js first

Regular build

$ yarn build # compile all contracts

Most tests are standalone and simply require installation of dependencies and compilation.

In order to run all tests (including those with extra dependencies), run:

$ yarn test # run all tests

To instead run a single package's tests, run:

$ cd pkg/<package> # e.g. cd pkg/v2-vault
$ yarn test

You can see a sample report of a test run here.

Foundry (Forge) tests

To run Forge tests, first install Foundry. The installation steps below apply to Linux or MacOS. Follow the link for additional options.

$ curl -L https://foundry.paradigm.xyz | bash
$ source ~/.bashrc # or open a new terminal
$ foundryup

Then, to run tests in a single package, run:

$ cd pkg/<package> # e.g. cd pkg/v2-vault
$ yarn test-fuzz

Security

Multiple independent reviews and audits were performed by Certora, OpenZeppelin and Trail of Bits. The latest reports from these engagements are located in the audits directory.

Bug bounties apply to most of the smart contracts hosted in this repository: head to Balancer V2 Bug Bounties to learn more.

All core smart contracts are immutable, and cannot be upgraded. See page 6 of the Trail of Bits audit:

Upgradeability | Not Applicable. The system cannot be upgraded.

Licensing

Most of the Solidity source code is licensed under the GNU General Public License Version 3 (GPL v3): see LICENSE.

Exceptions

• All files in the openzeppelin directory of the v2-solidity-utils package are based on the OpenZeppelin Contracts library, and as such are licensed under the MIT License: see LICENSE.
• The LogExpMath contract from the v2-solidity-utils package is licensed under the MIT License.
• All other files, including tests and the pvt directory are unlicensed.