{"id":28630887,"url":"https://github.com/aztecprotocol/l1-contracts","last_synced_at":"2025-08-30T07:04:47.733Z","repository":{"id":276150897,"uuid":"928327180","full_name":"AztecProtocol/l1-contracts","owner":"AztecProtocol","description":"Mirror of Aztec l1-contract artifacts.","archived":false,"fork":false,"pushed_at":"2025-08-30T02:51:49.000Z","size":4098,"stargazers_count":4,"open_issues_count":1,"forks_count":8,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-08-30T04:23:35.659Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Solidity","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AztecProtocol.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-02-06T13:03:45.000Z","updated_at":"2025-07-31T20:41:19.000Z","dependencies_parsed_at":"2025-02-06T15:42:50.140Z","dependency_job_id":"9bc22015-b6c4-4a41-a959-f7b100dec5b1","html_url":"https://github.com/AztecProtocol/l1-contracts","commit_stats":null,"previous_names":["aztecprotocol/l1-contracts"],"tags_count":219,"template":false,"template_full_name":null,"purl":"pkg:github/AztecProtocol/l1-contracts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AztecProtocol%2Fl1-contracts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AztecProtocol%2Fl1-contracts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AztecProtocol%2Fl1-contracts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AztecProtocol%2Fl1-contracts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AztecProtocol","download_url":"https://codeload.github.com/AztecProtocol/l1-contracts/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AztecProtocol%2Fl1-contracts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272815839,"owners_count":24997662,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-30T02:00:09.474Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-12T13:08:59.723Z","updated_at":"2025-08-30T07:04:47.712Z","avatar_url":"https://github.com/AztecProtocol.png","language":"Solidity","readme":"# L1 Contracts\n\nThis directory contains the Ethereum smart contracts for progressing the state of the Rollup.\n\n## Installation\n\nYou can install foundry as https://book.getfoundry.sh/ or by running the `./bootstrap.sh` script.\n\nAlternatively you can use docker instead, it will handle installations and run tests. Simply run `docker build .` from the `l1-contracts` folder.\n\n## Structure\n\nThe `src` folder contain contracts that is to be used by the local developer testnet. It is grouped into 3 categories:\n\n- `core` contains the required contracts, the bare minimum.\n- `governance` contains the contracts for the governance system.\n- `mock` contains stubs, for now an always true verifier.\n- `periphery` stuff that is nice to have, convenience contracts and functions belong in here.\n\n## Running tests\n\nThe tests are located in the `test` folder, and execute two consecutive L2Blocks. The blocks and the values they are checked against is generated using the block builder tests (there also is a typescript test in `l2-block-publisher.test.ts` that tests E2E). The tests are currently limited in functionality as it is mainly decoding happening, but will expand over time to include L1 \u003c-\u003e L2 communication and cross chain applications.\n\nAs mentioned earlier, you can also use docker. If you rerun `docker build .` after changing the contracts, it will use a cache for most values, and rerun your tests in a few seconds.\n\n## Formatting\n\nWe use `forge fmt` to format. But follow a few general guidelines beyond the standard:\n\n- use `_` prefix for function arguments, e.g.,\n  - Don't `function transfer(address to, uint256 amount);`\n  - Do `function transfer(address _to, uint256 _amount);`\n- use `_` prefix for `internal` and `private` functions.\n\n## Gas Reports\n\nYou can run `./bootstrap.sh gas_report` to generate a detailed gas report for the current state and update the gas_report.md file.\n\nIf you want something more manageble you should be using the `./boostrap.sh gas_benchmark` which will give you some \"happy path\" gas numbers for set with and without validators in a format that might be slightly simpler to figure out. The values outputted from this can also be seen over time at https://aztecprotocol.github.io/aztec-packages/dev/l1-gas-bench/.\n\nWhen running CI or tests with `./bootstrap.sh test`, the script will automatically check if gas usage has changed by running `./bootstrap.sh gas_report check`. If gas usage has changed, the test will fail and show a diff of the changes.\n\nIf the changes in gas usage are expected and desired:\n\n1. Review the diff shown in the output\n2. Run `./bootstrap.sh gas_report` to update the gas report file\n3. Commit the updated gas_report.md file\n\nNOTE: Our gas reporting excludes certain tests due to Forge limitations:\n\n- FeeRollupTest and MinimalFeeModelTest test suites are excluded\n- testInvalidBlobHash and testInvalidBlobProof test cases are excluded\n\nThis is related to [this Foundry issue](https://github.com/foundry-rs/foundry/issues/10074).\n\nThis means that we don't report gas for blob validation (currently 50k gas per blob, and we use 3 blobs per propose in production).\n\nIf you want to run gas reports directly with `forge`, you must use the environment variable `FORGE_GAS_REPORT=true` instead of the `--gas-report` flag. The `./bootstrap.sh gas_report` command does this for you automatically.\n\n## Contracts:\n\nThe contracts are in a very early stage, and don't worry about gas costs right now. Instead they prioritize development velocity.\n\n### Decoder\n\nJob: Extract values from `L2Block`\n\nThe decoder is a core rollup contract which takes the `L2Block` bytes and computes/extracts values required to:\n\n1. keep track of the state\n1. perform proof verification\n\nIf the structure of the `L2Block` changes, so should the decoder!\n\n### Rollup\n\nJob: Keep track of state and perform state transitions.\n\nIt is the job of the rollup contract to store the state of the rollup and progress it when receiving a new L2 block that is built on top of the current state.\n\nCurrently not running any proofs _nor_ access control so blocks can be submitted by anyone and can be complete garbage.\n\n---\n\n# Branching Tree Technique\n\nFor writing tests we will be using the [Branching Tree Technique](https://www.youtube.com/watch?v=0-EmbNVgFA4).\nThe approach is simple, for a function that is to be tested (all functions) you should write a `.tree` file first.\nThen the tree file can be used to generate a solidity tests file using [Bulloak](https://github.com/alexfertel/bulloak) by running the `scaffold` command.\n\n```bash\nbulloak scaffold -w **/*.tree\n```\n\nTo check that the tests are following the expected format, you can run the `check` command.\n\n```bash\nbulloak check **/*.tree\n```\n\nWe assume that you already have `bulloak` installed, if not you can install it as `cargo install bulloak`.\nAlso, we suggest using [Ascii Tree Generator](https://marketplace.visualstudio.com/items?itemName=aprilandjan.ascii-tree-generator), since the pipes can be a bit of a pain otherwise.\n\nFor examples, see the tests for the registry.\n\n---\n\n# Linter\n\nWe use an extended version of solhint (https://github.com/LHerskind/solhint) to include custom rules. These custom rules relate to how errors should be named, using custom errors instead of reverts etc, see `.solhint.json` for more specifics about the rules.\n\nThe linter is the only node module we need which is the reason behind not going full yarn-project on it.\n\nTo run the linter, simply run:\n\n```bash\nyarn lint\n```\n\nIf the output is something to the tune of:\n\n```bash\n$ solhint --config ./.solhint.json \"src/**/*.sol\"\n[solhint] Warning: Rule 'custom-errors' doesn't exist\n[solhint] Warning: Rule 'private-func-leading-underscore' doesn't exist\n[solhint] Warning: Rule 'private-vars-no-leading-underscore' doesn't exist\n[solhint] Warning: Rule 'func-param-name-leading-underscore' doesn't exist\n[solhint] Warning: Rule 'strict-override' doesn't exist\n```\n\nIt is likely that it is a old cached version of the linter that is being used, you can update it as:\n\n```bash\nyarn add https://github.com/LHerskind/solhint\\#master\n```\n\n---\n\n# Slither \u0026 Slitherin\n\nWe use slither as an automatic way to find blunders and common vulnerabilities in our contracts. It is not part of the docker image due to its slowness, but it can be run using the following command to generate a markdown file with the results:\n\n```bash\nyarn slither\n```\n\nWhen this command is run in CI, it will fail if the markdown file generated in docker don't match the one in the repository.\n\nWe assume that you already have slither installed. You can install it with `pip3 install slither-analyzer==0.10.0 slitherin==0.5.0`. It is kept out of the bootstrap script as it is not a requirement for people who just want to run tests or are uninterested in the contracts.\n\n\u003e We are not running the `naming-convention` detector because we have our own rules for naming which is enforced by the linter.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faztecprotocol%2Fl1-contracts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faztecprotocol%2Fl1-contracts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faztecprotocol%2Fl1-contracts/lists"}