🏗︎ Scaffold Balancer v3

A starter kit for building on top of Balancer v3. Accelerate the process of creating custom pools and hooks contracts. Concentrate on mastering the core concepts within a swift and responsive environment augmented by a local fork and a frontend pool operations playground.

🔁 Development Life Cycle

1. Learn the core concepts for building on top of Balancer v3
2. Configure and deploy factories, pools, and hooks contracts to a local anvil fork of Sepolia
3. Interact with pools via a frontend that runs at localhost:3000

🪧 Table Of Contents

• 🧑‍💻 Environment Setup
• 👩‍🏫 Learn Core Concepts
• 🕵️ Explore the Examples
• 🌊 Create a Custom Pool
• 🏭 Create a Pool Factory
• 🪝 Create a Pool Hook
• 🚢 Deploy the Contracts
• 🧪 Test the Contracts

🧑‍💻 Environment Setup

1. Requirements 📜

• Node (>= v18.17)
• Yarn (v1 or v2+)
• Git
• Foundry (>= v0.2.0)

2. Quickstart 🏃

1. Ensure you have the latest version of foundry installed

   foundryup

2. Clone this repo & install dependencies

git clone https://github.com/balancer/scaffold-balancer-v3.git
cd scaffold-balancer-v3
yarn install

3. Set the necessary environment variables in a packages/foundry/.env file [^1] [^1]: The DEPLOYER_PRIVATE_KEY must start with 0x and must possess enough Sepolia ETH to deploy the contracts. The SEPOLIA_RPC_URL facilitates running a local fork and sending transactions to sepolia testnet

DEPLOYER_PRIVATE_KEY=0x...
SEPOLIA_RPC_URL=...

4. Start a local anvil fork of the Sepolia testnet

yarn fork

5. Deploy the mock tokens, pool factories, pool hooks, and custom pools contracts [^2] [^2]: The DEPLOYER_PRIVATE_KEY wallet receives the mock tokens and resulting BPT from pool initialization

yarn deploy

6. Start the nextjs frontend

yarn start

7. Explore the frontend

• Navigate to http://localhost:3000 to see the home page
• Visit the Pools Page to search by address or select using the pool buttons
• Vist the Debug Page to see the mock tokens, factory, and hooks contracts

8. Run the Foundry tests

yarn test

3. Scaffold ETH 2 Tips 🏗️

SE-2 offers a variety of configuration options for connecting an account, choosing networks, and deploying contracts

👩‍🏫 Learn Core Concepts

• Contract Architecture
• Balancer Pool Tokens
• Balancer Pool Types
• Building Custom AMMs
• Exploring Hooks and Custom Routers
• Hook Development Tips

🕵️ Explore the Examples

Each of the following examples have turn key deploy scripts that can be found in the foundry/script/ directory

1. Constant Sum Pool with Dynamic Swap Fee Hook

The swap fee percentage is altered by the hook contract before the pool calculates the amount for the swap

2. Constant Product Pool with Lottery Hook

An after swap hook makes a request to an oracle contract for a random number

3. Weighted Pool with Exit Fee Hook

An after remove liquidity hook adjusts the amounts before the vault transfers tokens to the user

🌊 Create a Custom Pool

1. Review the Docs 📖

• Create a custom AMM with a novel invariant

2. Recall the Key Requirements 🔑

• Must inherit from IBasePool and BalancerPoolToken
• Must implement onSwap, computeInvariant, and computeBalance
• Must implement getMaximumSwapFeePercentage and getMinimumSwapFeePercentage

3. Write a Custom Pool Contract 📝

• To get started, edit theConstantSumPool.sol contract directly or make a copy

🏭 Create a Pool Factory

After designing a pool contract, the next step is to prepare a factory contract because Balancer's off-chain infrastructure uses the factory address as a means to identify the type of pool, which is important for integration into the UI, SDK, and external aggregators

1. Review the Docs 📖

• Deploy a Custom AMM Using a Factory

2. Recall the Key Requirements 🔑

• A pool factory contract must inherit from BasePoolFactory
• Use the internal _create function to deploy a new pool
• Use the internal _registerPoolWithVault fuction to register a pool immediately after creation

3. Write a Factory Contract 📝

• To get started, edit theConstantSumFactory.sol contract directly or make a copy

🪝 Create a Pool Hook

1. Review the Docs 📖

• Extend an Existing Pool Type Using Hooks

2. Recall the Key Requirements 🔑

• A hooks contract must inherit from BasePoolHooks.sol
• A hooks contract should also inherit from VaultGuard.sol
• Must implement onRegister to determine if a pool is allowed to use the hook contract
• Must implement getHookFlags to define which hooks are supported
• The onlyVault modifier should be applied to all hooks functions (i.e. onRegister, onBeforeSwap, onAfterSwap ect.)

3. Write a Hook Contract 📝

• To get started, edit the VeBALFeeDiscountHook.sol contract directly or make a copy

🚢 Deploy the Contracts

The deploy scripts are located in the foundry/script/ directory. To better understand the lifecycle of deploying a pool that uses a hooks contract, see the diagram below

1. Modifying the Deploy Scripts 🛠️

For all the scaffold integrations to work properly, each deploy script must be imported into Deploy.s.sol and inherited by the DeployScript contract in Deploy.s.sol

2. Broadcast the Transactions 📡

To run all the deploy scripts

yarn deploy

🛈 To deploy to the live sepolia testnet, add the --network sepolia flag

🧪 Test the Contracts

The balancer-v3-monorepo provides testing utility contracts like BasePoolTest and BaseVaultTest. Therefore, the best way to begin writing tests for custom factories, pools, and hooks contracts is to leverage the examples established by the source code.

1. Testing Factories 👨‍🔬

The ConstantSumFactoryTest roughly mirrors the WeightedPool8020FactoryTest

yarn test --match-contract ConstantSumFactoryTest

2. Testing Pools 🏊

The ConstantSumPoolTest roughly mirrors the WeightedPoolTest

yarn test --match-contract ConstantSumPoolTest

3. Testing Hooks 🎣

The VeBALFeeDiscountHookExampleTest mirrors the VeBALFeeDiscountHookExampleTest

yarn test --match-contract VeBALFeeDiscountHookExampleTest