Installation and Tooling
This is designed to be tested and deployed with Foundry. All that should be required is to install Python 3.11, Homebrew, and then install foundry, pull the code, and then run in the root of the project’s directory:
foundryup --version $(awk '$1~/^[^#]/' foundry.lock)
Note: awk in the above command is used to ignore comments in foundry.lock
pip3 install -r requirements.txt
Now that you have the dependencies installed, you are ready to build the project. Do:
forge build in the project directory to install the submodules and create the artifacts.
And you are done!
Running the tests
A full test suite can be run with the following command:.env file. See Fork test.
Equation tests
The most critical aspect of this AMM is its math. Therefore, every math equation has been tested individually through fuzz testing. These tests aim to check the precision of the Solidity implementation of the equations for all possible ranges of values (see the bounds of the equations here). The equation results are compared against Python scripts that run the exact same equation but without the math restrictions of Solidity (no floating numbers). The Python math also relies on the Decimal library to make sure that the floating numbers have enough precision to be useful for these tests. The Python results are then used as the source of truth. See the equation tests.Pool and Factory tests
All the factory and pool functionality is tested thourgh unit and fuzz tests. These suites of tests also inclue the result of a series of swaps carried out in an implementation of the AMM developed independently in Python, where the state of the curve variables are compared against the Solidity implementation of the pool to make sure that the evolution of the state of the pool through each swap is consistent in both implementations. See the liquidity tests.Fork tests
The fork tests are important for testing the pool against the real assets that the AMM is offering support to. These fork tests run the exact same tests described in the section above, but with the real y tokens deployed in Ethereum and Polygon mainnet. Bare in mind that some configuration of environment variables is necessary to run the fork tests. Specifically, the rpc key urls for communicating with the blockchains. In the.env file, make sure to include the following variables:
Access control
The factory and pool contracts use minimal access control mechanisms to ensure simplicity. These mechanisms are tested here.Invariant tests
All of the invariants of the product are tested. The access control invariants are tested here, while the other invariants tests can be found here.Precision Logging Tests
The precision logging tests are used to test the precision of the Solidity implementation of the equations against the Python implementation of the same equations. The precision tests are located in the equations folder and are denoted by thePrecisionLogger suffix.
To run the precision tests, you can run the following command:
python3 script/python/plot_equation.py {YourEquationHere}
This will run the precision tests for the equation denoted by {YourEquationHere} and log them in a file named {YourEquationHere}Precision.csv followed by opening up a plot of the results over time. To add a new precision test for a new equation, add the equation to the python script plot_equation.py in the list at the top of the file. After adding that, add a solidity test file that adheres to the interface of the other precision test files that can be found in the other equation directories. In particular it should have 2 functions: testEquations_{YourEquationHere}PrecisionLogger() which will run the precision tests for the equation and log the results to a file, and testEquations_{YourEquationHere}PrecisionPlotter() which will read the results from the file and plot them.