diff --git a/README.md b/README.md
index 0c366e3b..e9a62d5e 100644
--- a/README.md
+++ b/README.md
@@ -4,21 +4,27 @@
๐ ๏ธ This repo is a series of guides and internal prototyping tools for creating custom pools that integrate with Balancer v3. It is based off of commit hash 4bc7978d8b8c4ac8e42c5a4adf233663b8390678 from the BalancerV3 monorepo. This repo is to be updated once the monorepo is fully public.
-> ๐๐ PRE-REQs: It is highly recommended to read through the (BalancerV3 docs](https://docs-v3.balancer.fi/) before using this repo. Custom pools are built upon the architecture outlined within these docs. If you cannot find what you are looking for in the docs, and it is not in this README, please refer to the (BalancerV3 monorepo](https://github.com/balancer/balancer-v3-monorepo/tree/main) and/or reachout on the (Balancer Discord](TODO GET LINK).
+> ๐๐ PRE-REQs: It is highly recommended to read through the (BalancerV3 docs](https://docs-v3.balancer.fi/) before using this repo. Custom pools are built upon the architecture outlined within these docs. If you cannot find what you are looking for in the docs, and it is not in this README, please refer to the (BalancerV3 monorepo](https://github.com/balancer/balancer-v3-monorepo/tree/main) and/or reachout on the (Balancer Discord](https://discord.balancer.fi/).
๐งโ๐ซ This guide walks through example contracts for a custom pool, custom pool factory, test files, and deployment scripts. These files are used to deploy an example BalancerV3 custom pool that can be interacted with using a test, local front-end, on a test network (by default it is a foundry fork of Sepolia). The repo also provides a starting point for developers to create their own custom pools and factories.
-> When users clone this repo "off-the-shelf" they simply have to follow the environment setup instructions, run a few commands, and then they will have an example custom pool factory, and custom pools that they can interact with in a local front end.
+> When users clone this repo "off-the-shelf" they simply have to follow the environment setup instructions, run a few commands, and then they will have an example custom pool factory, and custom pools that they can interact with in a local front end.
Let's outline what this repo provides in more detail:
-1. A README to walk a dev through using the different functionalities of the repo.
+1. A README to walk a dev through using the different functionalities of the repo.
2. A front-end prototyping tool, example smart contracts and scripts, to help showcase simple integrations with Balancer's core architecture.
3. Use of the same front-end framework with your own custom pools, and walking you through how to do so using the example smart contracts and scripts to start.
## ๐ฅ Demo
-[๐ Watch this video](https://www.loom.com/share/31cabf0568a845abadcbdbb0df416b20?sid=9b1176c7-5ee4-4feb-8b6e-c971721440a0) to get a sense of the full stack dev environment where foundry is used to deploy a custom pool contract to a local fork and the nextjs frontend offers the opportunity to visualize the effects of swaps, joins, and exits with the pool.
+๐ Watch this video to quickly get started with the full stack development environment ๐
+
+[](https://www.loom.com/share/31cabf0568a845abadcbdbb0df416b20?sid=9b1176c7-5ee4-4feb-8b6e-c971721440a0)
+
+๐ Watch this video to get better acquainted with the smart contracts ๐
+
+[](https://drive.google.com/file/d/1x5IgDzKE2fQnpZdsfuLvb10c1OUAOH_z/view?usp=drive_link)
## ๐จ๐ปโ๐ซ Table of Contents
@@ -34,11 +40,13 @@ Let's outline what this repo provides in more detail:
In general, all smart contracts sections of this repo will already have `Example` smart contracts. These smart contract examples will be explained within this README.
---
+
## ๐จ๐จ Checkpoint 0: ๐ฆ Environment ๐
This section walks you through the set up of the repo environment so that you have a local front end with a foundry test fork off of Sepolia. The test fork will have deployed contracts to showcase how you can interact with custom pools in a test environment using the local pool explorer tab.
---
+
### ๐ง 0.1 Requirements
Before you begin, you need to install the following tools:
@@ -49,6 +57,7 @@ Before you begin, you need to install the following tools:
- [Foundry](https://book.getfoundry.sh/getting-started/installation)
---
+
### ๐๐ปโโ๏ธ 0.2 Quickstart
Next, we will run the following bash commands in your terminal to clone the repo and set up the repo accordingly.
@@ -100,11 +109,12 @@ yarn start
You now should have a local, testnet fork with newly deployed smart contracts and a local front end communicating with said smart contracts. You can start interacting with the newly deployed pools and other smart contracts, but first let's talk about wallets and this tool.
---
-### ๐ฆ 0.3 Wallet Connection Options, and Key Gotchas with Scaffold ETH 2
+
+### ๐๏ธ 0.3 Scaffold ETH 2 Configuration Guide
SE-2 offers a variety of full stack configuration options for connecting an account, choosing a network, and deploying contracts.
-##### 0.3.1 Burner Wallet
+0.3.1 Burner Wallet
If you do not have a wallet already connected to your web browser and thus your local host, then you will automatically use a burner wallet. First, what is a burner wallet?
@@ -116,21 +126,19 @@ To force the use of burner wallet, disable your browsers wallet extensions and r
-##### 0.3.2 Browser Extension Wallet
+0.3.2 Browser Extension Wallet
To use your preferred browser extension wallet, ensure that the account you are using matches the PK you previously provided in the `foundry/.env` file. As a convenience, the foundry deploy scripts max approve the vault contract to spend tokens.
โ ๏ธ You may need to add a local development network with rpc url `http://127.0.0.1:8545/` and chain id `31337`. Also, you may need to reset the nonce data for your wallet exension if it gets out of sync.
-
-
-With the wallet configurations understood and setup, we will touch on some SE-2 details before fully exploring the newly deployed local-test pool smart contracts.
-
-#### 0.3.2 Deployment
+0.3.3 Deployment Details
-This command runs `DeployFactoryAndPool.s.sol` which deploys a pool factory, deploys mock tokens, deploys a pool, and initializes the pool. The factory contract and mock tokens will show on the "Debug" page. The pool contract address will print in the terminal, but can also be selected from the dropdown on the "Pools" page. All deployment configuration options are specified in `HelperConfig.s.sol`
+This command runs `DeployFactoryAndPool.s.sol` which deploys a pool factory, deploys mock tokens, deploys a pool, and initializes the pool. The factory contract and mock tokens will show on the "Debug" page. The pool contract address will print in the terminal, but can also be selected from the dropdown on the "Pools" page. All deployment configuration options are specified in `HelperConfig.s.sol`. You may need to refresh your front end in your local host after running the below command.
```bash
yarn deploy:all
@@ -142,7 +150,11 @@ This command runs `DeployPool.s.sol` using the last pool factory you deployed. Y
yarn deploy:pool
```
-#### 0.3.3 Changing The Frontend Network Connection
+> ๐ Under the hood of SE-2: SE-2 is setup to hot reload the frontend with contracts that are directly deployed via the `DeployFactoryAndPool.s.sol` script. This means our frontend captures the pool factory and mock token contracts, but not the pool contract because it is deployed by calling a method on the factory.
+
+0.3.4 Changing The Frontend Network Connection
The network the frontend points at is set via `targetNetworks` in the `scaffold.config.ts` file using `chains` from viem. By default, the frontend runs on a local node at `http://127.0.0.1:8545`
@@ -151,7 +163,9 @@ const scaffoldConfig = {
targetNetworks: [chains.foundry],
```
-#### 0.3.4 Changing The Forked Network
+0.3.5 Changing The Forked Network
You can modify the `"fork"` alias in the `packages/foundry/package.json` file, but do not change the chain id. By default, the `yarn fork` command uses sepolia, but any of the network aliases from the `[rpc_endpoints]` of `foundry.toml` can be used
@@ -159,69 +173,93 @@ You can modify the `"fork"` alias in the `packages/foundry/package.json` file, b
"fork": "anvil --fork-url ${0:-sepolia} --chain-id 31337 --config-out localhost.json",
```
-> ** ๐ฎโ๐จPHEW, with the quick start deployments done, we can get into the fun stuff and show what can be done with this tool!**
+๐ See Pool Selection GIF
+
https://github.com/Dev-Rel-as-a-Service/scaffold-balancer-v3/assets/73561520/cc358227-3bf6-4b02-8dc5-36577c0cbdcd
+๐ Swap Preview
+
+๐ Join Preview
+
+๐ Exit Preview
+
+๐ Debug Preview
-At this point, you have now seen the capabilities of this repo and how it helps a developer (or team) onboard in building custom pools in BalancerV3.
+
+
+At this point, you have now seen the capabilities of this repo and how it helps a developer (or team) onboard in building custom pools in BalancerV3.
๐ Let's look under the hood, where we will start with understanding the example custom pool used within this repo., the `ConstantPricePool`.
---
+
## ๐จ๐จ Checkpoint 2: ๐ Create A Custom Pool
Ultimately, this repo can be used to create custom pool factories, custom pools from said factory, and register and initialize them so the pools can be interacted with using this repo's front end, all in a local environment. Before jumping into all of that, it is key that developers understand the general make-up of a custom pool.
-Therefore, this checkpoint focuses on writing the smart contract for a custom pool (without a factory). We will walk through the `ConstantPricePoolExample.sol` found within `packages/foundry/contracts/ConstantPricePoolExample.sol`.
+Therefore, this checkpoint focuses on writing the smart contract for a custom pool (without a factory). We will walk through the `ConstantPricePool.sol` found within `packages/foundry/contracts/ConstantPricePool.sol`.
---
+
### ๐ 2.1 Write a Custom Pool Contract
As a refresher, make sure to check out the [docs on creating custom pools as well](https://docs-v3.balancer.fi/concepts/guides/create-custom-amm-with-novel-invariant.html#build-your-custom-amm).
All custom pool contracts must inherit from `IBasePool` and `BalancerPoolToken` and implement the three required functions: `onSwap`, `computeInvariant`, and `computeBalance`.
-Let's walk through each function in `ConstantPricePoolExample.sol`
+Let's walk through each function in `ConstantPricePool.sol`
---
-#### 2.1.1 `onSwap()` Implementation
-
-Looking at monorepo, one sees that `onSwap()` is ultimately called within a `swap()` call in the [`Vault.sol`](https://github.com/balancer/balancer-v3-monorepo/blob/9bc5618d7717dfbafd3cfbf025e7d3317ad7cacb/pkg/vault/contracts/Vault.sol#L327).
-Essentially, the `onSwap()` call carries the custom pool logic that the vault queries to understand how much of the requested token the swap should return.
+#### 2.1.1 `onSwap()` Implementation
-This step can vary between custom pool variations. To paint a contrast, a simple implementation can be seen within this `ConstantPricePool` example, where the amount swapped in is simply the amount swapped out (see toggle below).
+Listed here for easy reference, the function discussed can also be found [here](https://github.com/Dev-Rel-as-a-Service/scaffold-balancer-v3/blob/1bb9e662e1f94bba7f30b7ad2a50bcee17ad9232/packages/foundry/contracts/ConstantPricePool.sol#L25C1-L26C1).
๐ฉ๐ฝโ๐ซ Code for `onSwap` functions
-Inside `ConstantPricePoolExample.sol`
+Inside `ConstantPricePool.sol`
```
/**
@@ -239,11 +277,16 @@ Inside `ConstantPricePoolExample.sol`
๐ฉ๐ฝโ๐ซ Code for `computeInvariant()` function
-Inside `ConstantPricePoolExample.sol`
+Inside `ConstantPricePool.sol`
```
/**
@@ -280,27 +317,26 @@ Inside `ConstantPricePoolExample.sol`
๐ฉ๐ฝโ๐ซ Code for `computeBalance()` function
-Inside `ConstantPricePoolExample.sol`
+Inside `ConstantPricePool.sol`
```
/**
@@ -329,6 +365,15 @@ Inside `ConstantPricePoolExample.sol`
๐ฉ๐ฝโ๐ซ Code for `constructor()`
+Inside `CustomPoolFactoryExample.sol`
```
constructor(
@@ -371,16 +415,30 @@ constructor(
}
```
+๐ฉ๐ฝโ๐ซ Code for `create()` function
+Inside `CustomPoolFactoryExample.sol`
```
/**
@@ -424,7 +482,12 @@ Below is the `create()` function used within our example:
}
```
-Here is the `_create()` internal function for reference:
+๐ฉ๐ฝโ๐ซ Code for `_create()` function
+Inside `CustomPoolFactoryExample.sol`
```
function _create(bytes memory constructorArgs, bytes32 salt) internal returns (address) {
@@ -432,45 +495,51 @@ function _create(bytes memory constructorArgs, bytes32 salt) internal returns (a
}
```
+