Awesome

<img src="logo.svg" alt="Balancer" height="128px">

Balancer V3 Monorepo

This repository contains the Balancer Protocol V3 core smart contracts, including the Vault and standard Pools, along with their tests.

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

• 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: contains StablePool, along with its associated factory.
• v3-pool-weighted: contains WeightedPool, along with its associated factory.
• v3-vault: contains the main Vault contract, which is the cornerstone of Balancer V3, and its extensions. Also includes the standard Router and BatchRouter, which supports end-user interactions with the Vault.

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

Solidity 0.8.24 or higher is required to support the upcoming Cancun hard fork 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.

Build and Test

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

First time build

$ yarn # install all dependencies

You 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

Regular build & test

$ 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), configure your RPC endpoints by sourcing your .env file and run:

$ yarn test # run all tests

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

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

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

Foundry (Forge) tests

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

$ cd pkg/<package> # e.g. cd pkg/vault
$ yarn test:forge

Hardhat tests

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

$ cd pkg/<package> # e.g. cd pkg/vault
$ yarn test:hardhat

Hardhat tests will also update snapshots for bytecode size and gas usage if applicable for a given package.

Medusa tests

Medusa is a tool, developed by Trail of Bits, that allow us to execute stateful fuzz tests in contracts, in a way smarter than Forge. That's because Medusa has an optimizer to create a path of transactions which is not completely random.

To run Medusa tests, we first need to install Echidna. To do so, install echidna using the release page or brew install echidna in Mac. Notice that the Mac installation will also install Crytic-compiller, so this step can be skipped when installing Medusa.

Then, install Medusa using this installation guide (or just copy the adequate precompiled binary to a directory within your PATH).

Finally, run yarn test:medusa. This command is available inside the packages vault, pool-weighted and pool-stable.

Static analysis

To run Slither static analyzer, Python 3.8+ is a requirement.

Installation in virtual environment

This step will create a Python virtual environment with Slither installed. It only needs to be executed once:

$ yarn slither-install

Run analyzer

$ yarn slither

The 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

Coverage

$ yarn coverage

The 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.

Security

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 other files, including tests and the pvt directory are unlicensed.