|
| 1 | +# AVM development guide |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +The Aztec Virtual Machine (AVM) is the subsystem that executes public transactions and proves that execution was correct. |
| 6 | + |
| 7 | +The current directory holds the C++ simulator, and the code to generate a ZK proof of execution. It is divided in 3 main parts |
| 8 | +- **Simulation**: takes an input transaction and executes the code. Simulation can be done in either |
| 9 | + - **Fast mode**: tries to execute as fast as possible and generates minimal outputs. This flow is used by block building. |
| 10 | + - **For witness generation**: this mode generates execution events, that will later be used to build a trace and prove execution. |
| 11 | +- **Trace generation** (tracegen): takes a series of execution events and creates a trace (a matrix of rows and columns) that encodes the execution of the program, memory evolution, etc. |
| 12 | +- **Constraining**: uses the Barretenberg proving system to generate a ZK proof stating that the trace satisfies the AVM relations. Also known as proving. |
| 13 | + |
| 14 | +## Directory Structure |
| 15 | + |
| 16 | +``` |
| 17 | +barretenberg/cpp/vm2 |
| 18 | +├── simulation/ |
| 19 | + ├── lib/ # Supporting simulation code that does not generate events. |
| 20 | + ├── standalone/ # Simulation code exclusive to fast mode. Does not generate events. |
| 21 | + └── gadgets/ # Simulation code used for witness generation. Generates events. Some of it might be reused in fast mode. |
| 22 | +├── tracegen/ # Code for trace generation. |
| 23 | +├── constraining/ # Prover and verifier code. |
| 24 | +├── common/ # Utilities and configurations shared by all submodules. |
| 25 | +├── dsl/ # Noir AVM recursive verifier code. |
| 26 | +├── generated/ # Files generated from the PIL relation files in barretenberg/cpp/pil/vm2. See @barretenberg/cpp/pil/vm2/CLAUDE.md. |
| 27 | +├── integration_tests/ # Tests that exercise simulation, tracegen and proving. |
| 28 | +├── optimized/ # Hand-crafted versions of some of the relations. |
| 29 | +├── testing/ # Testing fixtures and utilities shared by all submodules. |
| 30 | +├── tooling/ # AVM cli debugger and stat collection. |
| 31 | +├── simulation_helper.*pp # Externally facing simulation API. |
| 32 | +├── tracegen_helper.*pp # Externally facing tracegen API. |
| 33 | +└── proving_helper.*pp # Externally facing proving API. |
| 34 | +``` |
| 35 | + |
| 36 | +## Git workflow for the AVM |
| 37 | + |
| 38 | +**IMPORTANT**: When comparing branches or looking at diffs for AVM work, use `merge-train/avm` as the base branch, NOT `master`. The master branch is often outdated for AVM development. |
| 39 | + |
| 40 | +Examples: |
| 41 | +- `git diff merge-train/avm...HEAD` (not `git diff master...HEAD`) |
| 42 | +- `git log merge-train/avm..HEAD` (not `git log master..HEAD`) |
| 43 | + |
| 44 | +## Main targets, executables and tests |
| 45 | + |
| 46 | +We use cmake to build. These commands should be executed in the `barretenberg/cpp/` directory. |
| 47 | +Configure cmake with `cmake --preset clang20-assert`. This is only needed once. |
| 48 | + |
| 49 | +1. **The `bb-avm` binary**: this binary can be used as a standalone CLI to simulate and prove. |
| 50 | + It can be built with `cmake --build --preset clang20-assert --target bb-avm`. |
| 51 | + Note that this will take long to build, approximately 4 minutes, so it's not good for fast iteration. |
| 52 | + You may want to rely on the linter for fast iteration. |
| 53 | + The built binary will be located in `barretenberg/cpp/build/bin/bb-avm`. |
| 54 | +2. **The `vm2_tests` binary**: all AVM unit tests are compiler into this binary. |
| 55 | + It can be built with `cmake --build --preset clang20-assert --target vm2_tests`. |
| 56 | + Note that this will take even longer than 4 minutes to build. |
| 57 | + Tests should be run in the `barretenberg/cpp/build` directory due to data dependencies. |
| 58 | + You can then run a specific test using `./bin/vm2_tests --gtest_filter="*test_name*"`. |
| 59 | +3. **The `nodejs_module`**: fast simulation (without proving) is compiled and exported as a node module. |
| 60 | + It can be built with `cmake --build --preset clang20-assert --target nodejs_module`. |
| 61 | + This builds quickly. If working only on fast simulation, this is a good way to see if the code |
| 62 | + compiles. If you ever need to run fast simulation from Typescript then: |
| 63 | + - the nodejs module needs to be copied to the right location, by executing |
| 64 | + `(cd ../../barretenberg/ts/; ./scripts/copy_native.sh)` (still at `barretenberg/cpp/`). |
| 65 | + - the `yarn-project` needs to be bootstrapped. |
| 66 | + |
| 67 | +## Interactions of the AVM with TypeScript code. |
| 68 | + |
| 69 | +While `vm2_tests` provide good unit test coverage, most end to end AVM code is exercised and tested via TypeScript. |
| 70 | + |
| 71 | +To run TS tests, the `yarn-project` (usually in `~/aztec-packages/yarn-project`) project has to be up to date. |
| 72 | +You can find instructions in @`yarn-project/CLAUDE.md`. In short, run `bootstrap.sh` in that folder to build it. |
| 73 | + |
| 74 | +NOTE: Building `yarn-project` is only necessary if |
| 75 | +- It has never been done before |
| 76 | +- You changed some typescript file |
| 77 | + |
| 78 | +1. **The `bb-avm` binary**: a good test for this binary is what we call the "bulk test". |
| 79 | + Run `LOG_LEVEL=verbose yarn test src/avm_proving_tests/avm_bulk.test.ts` in the |
| 80 | + `yarn-project/bb-prover` directory. This test will simulate (for witgen), tracegen, and prove. |
| 81 | + It takes a while (around 30 seconds) but it's not too long. |
| 82 | + |
| 83 | + NOTE: This test generates "avm inputs" and calls the `bb-avm` binary. The output of that test should have a line that looks something like |
| 84 | + `/mnt/user-data/<user_name>/aztec-packages/barretenberg/cpp/build/bin/bb-avm avm_prove --avm-inputs /tmp/<dir>/avm_inputs.bin -o /tmp/bb-<something> -v`. |
| 85 | + After running the test for the first time, the AVM inputs will have been generated. |
| 86 | + If you need to iterate on C++-only changes, you can directly execute call `bb-avm` via that command. |
| 87 | +2. **Fast simulation**: to test fast simulation you can run `yarn test src/public` in the |
| 88 | + `yarn-project/simulator/` directory. |
0 commit comments