/aztec-packages

Primary LanguageC++Apache License 2.0Apache-2.0

Aztec Monorepo

All the packages that make up Aztec.

  • l1-contracts: Solidity code for the Ethereum contracts that process rollups
  • yarn-project: Typescript code for client and backend
  • docs: Documentation source for the docs site

Popular packages

  • Aztec.nr: A Noir framework for smart contracts on Aztec.
  • Aztec: A package for starting up local dev net modules, including a local 'sandbox' devnet, an Ethereum network, deployed rollup contracts and Aztec execution environment.
  • Aztec.js: A tool for interacting with the Aztec network. It communicates via the Private Execution Environment (PXE).
  • Example contracts: Example contracts for the Aztec network, written in Noir.
  • End to end tests: Integration tests written in Typescript--a good reference for how to use the packages for specific tasks.
  • Aztec Boxes: Example starter projects.

Issues Board

All issues being worked on are tracked on the Aztec Github Project. For a higher-level roadmap, check the milestones overview section of our docs.

Development Setup

Run bootstrap.sh full in the project root to set up your environment. This will update git submodules, download ignition transcripts, install Foundry, compile Solidity contracts, install the current node version via nvm, and build all typescript packages.

Alternatively, to just hack on Noir contracts and Typescript, run ./bootstrap.sh fast, which will download existing builds for barretenberg and nargo from the CI cache. Note that this requires AWS ECR credentials, and only works on Ubuntu.

To build Typescript code, make sure to have nvm (node version manager) installed.

To build noir code, make sure that you are using the version from yarn-project/noir-compiler/src/noir-version.json.

Install nargo by running

noirup -v TAG_FROM_THE_FILE

Continuous Integration

This repository uses CircleCI for continuous integration. Build steps are managed using build-system. Small packages are built and tested as part of a docker build operation, while larger ones and end-to-end tests spin up a large AWS spot instance. Each successful build step creates a new docker image that gets tagged with the package name and commit.

All packages need to be included in the build manifest, which declares what paths belong to each package, as well as dependencies between packages. When the CI runs, if none of the rebuild patterns or dependencies were changed, then the build step is skipped and the last successful image is re-tagged with the current commit. Read more on the build-system repository README.

It is faster to debug CI failures within a persistent ssh session compared to pushing and waiting. You can create a session with "Rerun step with SSH" on CircleCI which will generate an ssh command for debugging on a worker. Run that command locally and then do

cd project
./build-system/scripts/setup_env "$(git rev-parse HEAD)" "" https://github.com/AztecProtocol/aztec-packages
source /tmp/.bash_env*
set +euo
{start testing your CI commands here}

This provide an interactive environment for debugging the CI test.

Debugging

Logging goes through the DebugLogger module in Typescript. To see the log output, set a DEBUG environment variable to the name of the module you want to debug, to aztec:*, or to * to see all logs.

Releases

Releases are driven by release-please, which maintains a 'Release PR' containing an updated CHANGELOG.md since the last release. Triggering a new release is simply a case of merging this PR to master. A github workflow will create the tagged release triggering CircleCI to build and deploy the version at that tag.

Contribute

There are many ways you can participate and help build high quality software. Check out the contribution guide!

Syncing noir

We currently use git-subrepo to manage a mirror of noir. This tool was chosen because it makes code checkout and development as simple as possible (compared to submodules or subtrees), with the tradeoff of complexity around sync's.

There is an automatic mirror pushing noir to a PR on noir side. If the mirror is not working, generally we need to do a "git subrepo pull noir".

Recovering if the sync is not happening with basic pull commands:

  • manually editing the commit variable in noir/noir-repo/.gitrepo: this needs to exist in the branch we push to, and have the same content as our base. This is similar to submodules, except instead of pointing to the final state of the module, it points to the last commit we have sync'd from, for purposes of commit replay. This can be fixed to match the commit in master after merges.
  • manually editing the parent variable in noir/noir-repo/.gitrepo: this is the parent of the last sync commit on aztec side. If you get errors with a commit not being found in the upstream repo, and the commit mentioned is not the commit variable above, it might indicate this is somehow incorrect. This can happen when commit content is ported without its history, e.g. squashes
  • use pull --force ONLY where you would use git reset. That is, if you really want to match some upstream noir for a purpose its fine, but you'll lose local changes (if any)

Earthly

Earthly is a reproducible build tool that aims to combine the functionality of Docker, Makefiles and BASH. Non-build earthly targets should start with 'test', 'run', or 'bench' as a general rule (but not hard rule) while builds can be nouns or start with build-. If something is a bundle of targets for CI, we can do e.g. build-ci, test-ci etc. See barretenberg/cpp/Earthfile for an example of a fairly involved Earthfile that can be used for inspiration. Earthly docs https://docs.earthly.dev/ are extensive and show the various build patterns.

In a nutshell:

  • Docker-like syntax defines all builds. We lean on docker heavily for when to rebuild and cache, and how to run in a reproducible manner.
  • It supports modularization of the build manifest into multiple directories that can be imported. Simple functions and conditional logic can be used.
  • We provide two modes, one for CI by passing --ci and one for local with incremental builds.
  • We do NOT provide a native execution story for anything but Linux and WASM currently.