This repository contains the Balancer Protocol V3 core smart contracts, including the Vault and standard Pools, along with their tests.
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.
v3-interfaces: Solidity interfaces for all contracts.v3-solidity-utils: miscellaneous Solidity helpers and utilities used in many different contracts.v3-pool-hooks: hook examples to illustrate potential capabilities and how to build one.v3-pool-utils: Solidity utilities used to develop Pool contracts.v3-pool-stable: containsStablePool, along with its associated factory.v3-pool-weighted: containsWeightedPool, along with its associated factory.v3-vault: contains the mainVaultcontract, which is the cornerstone of Balancer V3, and its extensions. Also includes the standardRouterandBatchRouter, which supports end-user interactions with the Vault.
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 useSolidity 0.8.24 or higher is required to support the upcoming Cancun hardfork with transient storage. We strongly recommend using the latest released version of the Solidity compiler (at least 0.8.24), to incorporate all the latest bug fixes.
Before any tests can be run, the repository needs to be prepared:
$ yarn # install all dependenciesYou will also need to configure your environment variables to point to RPC endpoints in order to run fork tests.
Write your preferred RPC URL to .env, and source it. For example:
$ sed 's,YOUR_MAINNET_RPC_URL,<YOUR_RPC_URL>,g' .env.example > .env
$ source .env$ yarn build # compile all contractsMost tests are standalone and simply require installation of dependencies and compilation.
In order to run all tests (including those with extra dependencies), configure your RPC endpoints by sourcing your .env file and run:
$ yarn test # run all testsTo instead run a single package's tests, run:
$ cd pkg/<package> # e.g. cd pkg/vault
$ yarn testYou can see a sample report of a test run here.
To instead run a single package's forge tests, run:
$ cd pkg/<package> # e.g. cd pkg/vault
$ yarn test:forgeTo instead run a single package's hardhat tests, run:
$ cd pkg/<package> # e.g. cd pkg/vault
$ yarn test:hardhatHardhat tests will also update snapshots for bytecode size and gas usage if applicable for a given package.
To run Slither static analyzer, Python 3.8+ is a requirement.
This step will create a Python virtual environment with Slither installed. It only needs to be executed once:
$ yarn slither-install$ yarn slitherThe analyzer's global settings can be found in .slither.config.json.
Some of the analyzer's known findings are already filtered out using --triage-mode option; the results of the triage can be found in slither.db.json files inside each individual workspace.
To run Slither in triage mode:
$ yarn slither:triage$ yarn coverageThe coverage command generates a coverage report for each package found in the ./package/coverage/index.html directory. The coverage.sh script can generate Forge and Hardhat reports and/or merge them. The Yarn command uses Forge by default as most of the tests are written with it, and it's the most reliable option.
Note: We suggest adopting lcov 1.16 since forge coverage --report lcov command works better in this version.
Upgradeability | Not Applicable. The system cannot be upgraded.
Most of the Solidity source code is licensed under the GNU General Public License Version 3 (GPL v3): see LICENSE.
- All other files, including tests and the
pvtdirectory are unlicensed.
