chore: sync draft-v31-with-zksync-os with draft-v31

.github/workflows/l1-contracts-ci.yaml

@@ -38,17 +38,8 @@ jobs:
       - name: Build l1 contracts
         working-directory: l1-contracts
         run: |
-          rm -rf zkstack-out
           yarn build:foundry
 
-          # Fail if regenerated zkstack-out differs from what was committed
-          if [ -n "$(git status --porcelain -- zkstack-out)" ]; then
-            echo "::error::l1-contracts/zkstack-out is out of date. Run 'cd l1-contracts && yarn build:foundry' and commit the changes."
-            git --no-pager status --porcelain -- zkstack-out
-            git --no-pager diff -- zkstack-out || true
-            exit 1
-          fi
-
       - name: Build l2 contracts
         working-directory: l2-contracts
         run: |
@@ -110,6 +101,41 @@ jobs:
       - name: Lint errors
         run: yarn l1 errors-lint --check
 
+  check-zkstack-out:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install foundry-zksync
+        uses: ./.github/actions/install-zksync-foundry
+
+      - name: Use Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18.20.8
+          cache: yarn
+
+      - name: Install dependencies
+        run: yarn
+
+      - name: Build and check zkstack-out
+        working-directory: l1-contracts
+        run: |
+          rm -rf zkstack-out
+          yarn build:foundry
+
+          # Fail if regenerated zkstack-out differs from what was committed
+          if [ -n "$(git status --porcelain -- zkstack-out)" ]; then
+            echo "::error::l1-contracts/zkstack-out is out of date. Run 'cd l1-contracts && yarn build:foundry' and commit the changes."
+            git --no-pager status --porcelain -- zkstack-out
+            git --no-pager diff -- zkstack-out || true
+            exit 1
+          fi
+
   check-hashes:
     needs: [build]
     runs-on: ubuntu-latest
@@ -235,48 +261,48 @@ jobs:
       #   run: forge test --match-test MeasureGas --gas-snapshot-check=true
 
   # FIXME: uncomment once fixed.
-  # test-foundry-zksync:
-  #   needs: [build, lint]
-  #   runs-on: ubuntu-latest
+  test-foundry-zksync:
+    needs: [build, lint]
+    runs-on: ubuntu-latest
 
-  #   steps:
-  #     - name: Checkout the repository
-  #       uses: actions/checkout@v4
-  #       with:
-  #         submodules: recursive
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
 
-  #     - name: Use Node.js
-  #       uses: actions/setup-node@v3
-  #       with:
-  #         node-version: 18.20.8
-  #         cache: yarn
+      - name: Use Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18.20.8
+          cache: yarn
 
-  #     - name: Install foundry-zksync
-  #       uses: ./.github/actions/install-zksync-foundry
+      - name: Install foundry-zksync
+        uses: ./.github/actions/install-zksync-foundry
 
-  #     - name: Install dependencies
-  #       run: yarn
+      - name: Install dependencies
+        run: yarn
 
-  #     - name: Build system contract artifacts
-  #       run: yarn sc build:foundry
+      - name: Build system contract artifacts
+        run: yarn sc build:foundry
 
-  #     - name: Restore artifacts cache
-  #       uses: actions/cache/restore@v3
-  #       with:
-  #         fail-on-cache-miss: true
-  #         key: artifacts-l1-${{ github.sha }}
-  #         path: |
-  #           da-contracts/out
-  #           l1-contracts/cache-forge
-  #           l1-contracts/out
-  #           # TODO: cached `zkout` and the one for tests produce different hashes and so it causes the tests to fail
-  #           l2-contracts/cache-forge
-  #           l2-contracts/zkout
-  #           system-contracts/zkout
+      - name: Restore artifacts cache
+        uses: actions/cache/restore@v3
+        with:
+          fail-on-cache-miss: true
+          key: artifacts-l1-${{ github.sha }}
+          path: |
+            da-contracts/out
+            l1-contracts/cache-forge
+            l1-contracts/out
+            # TODO: cached `zkout` and the one for tests produce different hashes and so it causes the tests to fail
+            l2-contracts/cache-forge
+            l2-contracts/zkout
+            system-contracts/zkout
 
-  #     - name: Run tests
-  #       working-directory: ./l1-contracts
-  #       run: yarn test:zkfoundry
+      - name: Run tests
+        working-directory: ./l1-contracts
+        run: yarn test:zkfoundry
 
   check-verifier-generator-l1:
     runs-on: ubuntu-latest
@@ -368,15 +394,14 @@ jobs:
           ref: v1.16
 
       # To ignore coverage for certain directories modify the paths in this step as needed. The
-      # below default ignores coverage results for the test and script directories. It also ignores
-      # the ChainRegistrar contract since it is unused. Alternatively, to include coverage in all
-      # directories, comment out this step. Note that because this filtering applies to the lcov
-      # file, the summary table generated in the previous step will still include all files and
-      # directories. The `--rc branch_coverage=1` part keeps branch info in the filtered report,
-      # since lcov defaults to removing branch info.
+      # below default ignores coverage results for the test and script directories. Alternatively,
+      # to include coverage in all directories, comment out this step. Note that because this
+      # filtering applies to the lcov file, the summary table generated in the previous step will
+      # still include all files and directories. The `--rc branch_coverage=1` part keeps branch info
+      # in the filtered report, since lcov defaults to removing branch info.
       - name: Filter directories
         run: |
-          lcov --ignore-errors unused --remove lcov.info 'test/*' 'contracts/dev-contracts/*' 'lib/*' '../lib/*' 'lib/' 'deploy-scripts/*' 'contracts/chain-registrar/ChainRegistrar.sol' --output-file lcov.info --rc branch_coverage=1
+          lcov --ignore-errors unused --remove lcov.info 'test/*' 'contracts/dev-contracts/*' 'lib/*' '../lib/*' 'lib/' 'deploy-scripts/*' --output-file lcov.info --rc branch_coverage=1
 
       # This step posts a detailed coverage report as a comment and deletes previous comments on
       # each push. The below step is used to fail coverage if the specified coverage threshold is

.github/workflows/system-contracts-ci.yaml

@@ -106,53 +106,52 @@ jobs:
           cd system-contracts/bootloader/test_infra
           cargo run
 
-  # FIXME: uncomment once fixed.
-  # test-contracts:
-  #   needs: [build, lint]
-  #   runs-on: ubuntu-latest
-
-  #   steps:
-  #     - name: Checkout the repository
-  #       uses: actions/checkout@v4
-
-  #     - name: Use Node.js
-  #       uses: actions/setup-node@v3
-  #       with:
-  #         node-version: 18.20.8
-  #         cache: yarn
-
-  #     - name: Run anvil-zksync
-  #       uses: dutterbutter/anvil-zksync-action@v1.3.0
-  #       with:
-  #         mode: run
-  #         protocolVersion: 29
-  #         evmInterpreter: true
-  #         logFilePath: "anvil_zksync.log"
-  #         offline: true
-
-  #     - name: Install dependencies
-  #       run: yarn
-
-  #     - name: Restore artifacts cache
-  #       uses: actions/cache/restore@v3
-  #       with:
-  #         fail-on-cache-miss: true
-  #         key: artifacts-system-${{ github.sha }}
-  #         path: |
-  #           system-contracts/zkout
-  #           system-contracts/cache-forge
-  #           system-contracts/bootloader/build
-  #           system-contracts/artifacts-zk
-  #           system-contracts/cache-zk
-  #           system-contracts/typechain
-  #           system-contracts/contracts-preprocessed
-
-  #     - name: Run tests
-  #       run: yarn sc test
-
-  #     - name: Print output logs of anvil-zksync
-  #       if: always()
-  #       run: cat anvil_zksync.log
+  test-contracts:
+    needs: [build, lint]
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@v4
+
+      - name: Use Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18.20.8
+          cache: yarn
+
+      - name: Run anvil-zksync
+        uses: dutterbutter/anvil-zksync-action@v1.3.0
+        with:
+          mode: run
+          protocolVersion: 29
+          evmInterpreter: true
+          logFilePath: "anvil_zksync.log"
+          offline: true
+
+      - name: Install dependencies
+        run: yarn
+
+      - name: Restore artifacts cache
+        uses: actions/cache/restore@v3
+        with:
+          fail-on-cache-miss: true
+          key: artifacts-system-${{ github.sha }}
+          path: |
+            system-contracts/zkout
+            system-contracts/cache-forge
+            system-contracts/bootloader/build
+            system-contracts/artifacts-zk
+            system-contracts/cache-zk
+            system-contracts/typechain
+            system-contracts/contracts-preprocessed
+
+      - name: Run tests
+        run: yarn sc test
+
+      - name: Print output logs of anvil-zksync
+        if: always()
+        run: cat anvil_zksync.log
 
   test-contracts-foundry:
     needs: [lint]

.gitignore

@@ -10,6 +10,7 @@ cache-zk/
 cache/
 contracts-preprocessed/
 era_test_node.log*
+foundry.lock
 node_modules/
 out/
 target/

.markdownlintignore

@@ -1,10 +1,10 @@
 # root
 node_modules
+CLAUDE.md
+AGENTS.md
 
 # l1-contracts
 l1-contracts/node_modules
-l1-contracts/CLAUDE.md
-l1-contracts/AGENTS.md
 
 # l1-contracts-foundry
 l1-contracts-foundry/lib

l1-contracts/AGENTS.md → AGENTS.md

@@ -40,6 +40,62 @@ address result = _tryAddress(target, "someFunction()");
 - They mask initialization issues and timing problems
 - The codebase should fail fast and clearly, not silently return defaults
 
+### Constructors and Immutables
+
+- ONLY contracts deployed on L1 should have immutables. Contracts on L2 are deployed within zksync os environment and so and so DO NOT SUPPORT CONSTRUCTORS ALL (and so no immutable can be set). It is important that the `*Base` contracts that the L2 contracts inherit from dont have immutables or constructors too.
+- If you want to add an immutable for L1, always double check whether it is possible to deterministically obtain from other contracts.
+- If there is variable that can be an immutable on L1, but we need a similar field on L2, a common pattern is to create a method in the base contract that can be inherited by both. On L2 it can be either a constant (esp if it is an L2 built-in contract address) or a storage variable that must be initialized within during the genesis. For example, look how `initL2` functions are used.
+
+## Updating test_infra Git Dependencies (Bootloader Tests)
+
+### Problem
+
+The bootloader test infrastructure at `system-contracts/bootloader/test_infra/` uses `nightly-2025-05-23` and has git
+dependencies on `zksync-era`. When the git rev in `Cargo.toml` is updated, **do NOT run `cargo update` or regenerate
+the entire `Cargo.lock`**. A full re-resolve will pull in latest crates.io versions of transitive dependencies (e.g.,
+`crc-fast`, `zerocopy`) that use `stdarch_x86_avx512` intrinsics, which are not stabilized on this nightly toolchain.
+This causes CI build failures on x86_64 runners.
+
+### Correct Approach: Selective Lockfile Update
+
+When updating the zksync-era git rev in `Cargo.toml`, update the lockfile by targeting only the git dependencies:
+
+```bash
+cd system-contracts/bootloader/test_infra
+
+# Update only the git dependencies, keeping all crates.io deps pinned
+cargo update -p zksync_multivm -p zksync_types -p zksync_contracts \
+  -p zksync_utils -p zksync_state -p zksync_vlog
+```
+
+This swaps the git rev for the zksync-era crates while preserving all other dependency versions at their current
+(known-working) state.
+
+### If the Lockfile Is Already Broken
+
+If a full `cargo update` was already run and the lockfile has incompatible versions, restore from the last known-good
+commit and selectively update:
+
+```bash
+cd system-contracts/bootloader/test_infra
+
+# Restore the old working lockfile (find the last commit before the breakage)
+git show <last-good-commit>:system-contracts/bootloader/test_infra/Cargo.lock > Cargo.lock
+
+# Then selectively update only git deps
+cargo update -p zksync_multivm -p zksync_types -p zksync_contracts \
+  -p zksync_utils -p zksync_state -p zksync_vlog
+```
+
+### Known Incompatible Crate Versions (on nightly-2025-05-23)
+
+These versions require `stdarch_x86_avx512` (stabilized in Rust 1.89) and fail on `nightly-2025-05-23`:
+
+- `crc-fast >= 1.4` (all versions use AVX-512 intrinsics on x86_64)
+- `zerocopy >= 0.8.39`
+
+Known-good versions: `crc-fast 1.3.0`, `zerocopy 0.8.27`
+
 ## Debugging Strategies
 
 When debugging Solidity compilation or script failures: