Doc improvements from @benesjan

Author: just-mitch

cspell.json

@@ -28,9 +28,14 @@
     "bbfree",
     "bbmalloc",
     "benesjan",
+    "bignum",
     "Bincode",
     "bincoded",
     "bleurgh",
+    "blobbasefee",
+    "blobhash",
+    "Blobhashes",
+    "blobshash",
     "bodyparser",
     "bootnode",
     "bootnodes",
@@ -49,6 +54,7 @@
     "cbind",
     "cbinds",
     "Celestia",
+    "chainid",
     "chainsafe",
     "cheatcode",
     "cheatcodes",
@@ -112,6 +118,7 @@
     "enrs",
     "entrypoints",
     "erc",
+    "exitable",
     "falsey",
     "fargate",
     "Fernet",
@@ -143,6 +150,7 @@
     "hasher",
     "headstart",
     "herskind",
+    "hevm",
     "homomorphic",
     "ierc",
     "IGSE",
@@ -247,6 +255,7 @@
     "preimage",
     "preimages",
     "prestat",
+    "prevrandao",
     "println",
     "productionify",
     "protobuf",
@@ -269,6 +278,7 @@
     "reentrancy",
     "reexecute",
     "reexecution",
+    "reinitialise",
     "repr",
     "Reserialize",
     "retag",
@@ -289,6 +299,7 @@
     "sigchld",
     "Signerless",
     "siloes",
+    "slashable",
     "sload",
     "snakecase",
     "socat",
@@ -314,6 +325,7 @@
     "sysbox",
     "templating",
     "tldr",
+    "tload",
     "tmpfs",
     "toplevel",
     "tparam",
@@ -322,6 +334,7 @@
     "trivago",
     "tsbuildinfo",
     "tsdoc",
+    "tstore",
     "txes",
     "typechain",
     "typecheck",
@@ -389,5 +402,9 @@
     "lib",
     "*.cmake"
   ],
-  "flagWords": ["anonymous", "offence", "offences"]
+  "flagWords": [
+    "anonymous",
+    "offence",
+    "offences"
+  ]
 }

l1-contracts/src/core/RollupCore.sol

@@ -52,7 +52,7 @@ import {G1Point, G2Point} from "@aztec/shared/libraries/BN254Lib.sol";
  *      - Slots are grouped into epochs (configurable size, e.g., 32 slots)
  *      - Each slot has one designated proposer from the validator set
  *      - Each block is expected to include attestations from committee members
- *      - Committees remain stable throughout an epoch
+ *      - There is one committee per epoch
  *
  *      Key invariants:
  *      - The L2 chain is linear (no forks) but can be rolled back
@@ -73,8 +73,8 @@ import {G1Point, G2Point} from "@aztec/shared/libraries/BN254Lib.sol";
  *         purposes:
  *         - Attest to data availability for transaction data not posted on L1, which is required by provers to generate
  *           epoch proofs
- *         - Re-execute everything and attest to the resulting state root, acting as training wheels for the proving
- *           system
+ *         - Re-execute everything and attest to the resulting state root, acting as training wheels for the public
+ *           part of the system (proving systems used in public and AVM)
  *
  *      3) Proposers: Drafted from the validator set (currently proposers are part of the committee for the epoch,
  *         though this may change). They have exclusive rights to propose a block at a given slot, ensuring orderly
@@ -135,7 +135,7 @@ import {G1Point, G2Point} from "@aztec/shared/libraries/BN254Lib.sol";
  *        `prune()` manually, or automatically on the next proposal.
  *      - The committee for the epoch is expected to disseminate transaction data to allow proving, so a prune is
  *        considered a slashable offense, that causes validators to vote for slashing the committee of the unproven
- * epoch.
+ *        epoch.
  *      - When the pending chain is pruned, all unproven blocks are removed from the pending chain, and the chain
  *        resumes from the last proven block.
  *
@@ -199,7 +199,7 @@ contract RollupCore is EIP712("Aztec Rollup", "1"), Ownable, IStakingCore, IVali
   bool public isRewardsClaimable = false;
 
   /**
-   * @notice Initializes the Aztec rollup with all required configuration
+   * @notice Initializes the Aztec rollup with all required configurations
    * @dev Sets up time parameters, deploys auxiliary contracts (slasher, reward booster),
    *      initializes staking, validator selection, and creates inbox/outbox contracts
    * @param _feeAsset The ERC20 token used for transaction fees
@@ -236,7 +236,7 @@ contract RollupCore is EIP712("Aztec Rollup", "1"), Ownable, IStakingCore, IVali
     StakingLib.initialize(_stakingAsset, _gse, exitDelay, address(slasher), _config.stakingQueueConfig);
     ExtRollupLib2.initializeValidatorSelection(_config.targetCommitteeSize);
 
-    // If no booster specifically provided deploy one.
+    // If no booster is specifically provided, deploy one.
     if (address(_config.rewardConfig.booster) == address(0)) {
       _config.rewardConfig.booster = ExtRollupLib3.deployRewardBooster(_config.rewardBoostConfig);
     }
@@ -520,12 +520,22 @@ contract RollupCore is EIP712("Aztec Rollup", "1"), Ownable, IStakingCore, IVali
 
   /**
    * @notice Sets up validator selection for the current epoch
-   * @dev Can be called by anyone at the start of an epoch. Samples the committee
-   *      and determines proposers for all slots in the epoch. Also stores a seed
-   *      that is used for future sampling. Automatically called during `propose`.
-   *      External mainly for testing and to setup an epoch if there were no block proposals.
+   * @dev Can be called by anyone at the start of an epoch. Samples the committee and determines proposers for all
+   *      slots in the epoch. Also stores a seed that is used for future sampling. The corresponding library
+   *      functionality is automatically called when `RollupCore.propose(...)` is called (via the
+   *      `ExtRollupLib.propose(...)` -> `ProposeLib.propose(...)` -> `ValidatorSelectionLib.setupEpoch(...)`).
+   *
+   *      If there are missed proposals then setupEpoch does not get called automatically. Since the next committee
+   *      selection is computed based on the latest stored seed and the epoch number, we would only fail to get a
+   *      fresh seed if:
+   *      1. All the proposals in the epoch were missed
+   *      2. Nobody called setupEpoch on the Rollup contract
+   *
+   *      While an attacker might theoretically benefit from preventing a fresh seed (e.g. by DoSing all proposers),
+   *      preventing anyone from calling this function directly is not really feasible. This makes attacks on seed
+   *      generation impractical.
    */
-  function setupEpoch() public override(IValidatorSelectionCore) {
+  function setupEpoch() external override(IValidatorSelectionCore) {
     ExtRollupLib2.setupEpoch();
   }
 

l1-contracts/src/core/interfaces/IRollup.sol

@@ -84,7 +84,8 @@ struct RollupConfig {
 struct RollupStore {
   CompressedChainTips tips; // put first such that the struct slot structure is easy to follow for cheatcodes
   mapping(uint256 blockNumber => bytes32 archive) archives;
-  mapping(uint256 blockNumber => CompressedTempBlockLog temp) tempBlockLogs;
+  // The following represents a circular buffer. Key is `blockNumber % size`.
+  mapping(uint256 circularIndex => CompressedTempBlockLog temp) tempBlockLogs;
   RollupConfig config;
 }
 

l1-contracts/src/core/libraries/TimeLib.sol

@@ -73,6 +73,24 @@ library TimeLib {
     return _a + Epoch.wrap(store.proofSubmissionEpochs + 1);
   }
 
+  /**
+   * @notice Calculates the maximum number of blocks that can be pruned from the pending chain
+   * @dev The maximum prunable blocks is determined by:
+   *      - epochDuration: number of slots in an epoch
+   *      - proofSubmissionEpochs: number of epochs allowed for proof submission
+   *
+   *      The formula is: epochDuration * (proofSubmissionEpochs + 1)
+   *
+   *      The +1 accounts for blocks in the current epoch, ensuring they are included
+   *      in the prunable window along with blocks from previous epochs within the
+   *      proof submission window.
+   *
+   *      This value is used to:
+   *      1. Size the circular storage buffer (roundaboutSize = maxPrunableBlocks + 1)
+   *      2. Determine when blocks become stale and can be overwritten
+   *
+   * @return The maximum number of blocks that can be pruned.
+   */
   function maxPrunableBlocks() internal view returns (uint256) {
     TimeStorage storage store = getStorage();
     return uint256(store.epochDuration) * (uint256(store.proofSubmissionEpochs) + 1);

l1-contracts/src/core/libraries/crypto/SampleLib.sol

@@ -58,12 +58,12 @@ library SampleLib {
     }
 
     // Clear transient storage.
-    // Note that we are cleaing the `sampleIndicies` and do not keep track of a separate list of
-    // `sampleIndex` that was written to. The reasoning being that we are only overwriting for
-    // duplicate cases, so `sampleIndicies` isa superset of the `sampleIndex` that have been drawn
-    // (due to account for duplicates). Thereby clearing the `sampleIndicies` clears all.
-    // Due to the cost of `tstore` and `tload` it is cheaper just to overwrite it all, than checking
-    // if there is even anything to override.
+    // Note that we are clearing the `sampleIndices` and do not keep track of a separate list of
+    // `sampleIndex` values that were written to. The reasoning is that we only overwrite values for
+    // duplicate cases, so `sampleIndices` is a superset of the `sampleIndex` values that have been drawn
+    // (to account for duplicates). Therefore, clearing `sampleIndices` clears everything.
+    // Due to the cost of `tstore` and `tload` operations, it is cheaper to overwrite all values
+    // rather than checking if there is anything to override.
     for (uint256 i = 0; i < _committeeSize; i++) {
       setOverrideValue(sampledIndices[i], 0);
     }

l1-contracts/src/core/libraries/rollup/AttestationLib.sol

@@ -14,8 +14,7 @@ enum SignatureDomainSeparator {
 
 // A committee attestation can be made up of a signature and an address.
 // Committee members that have attested will produce a signature, and if they have not attested, the signature will be
-// empty and
-// an address provided.
+// empty and an address provided.
 struct CommitteeAttestation {
   address addr;
   Signature signature;
@@ -128,11 +127,14 @@ library AttestationLib {
   }
 
   /**
-   * Returns the addresses from the CommitteeAttestations, using the array of signers to populate where there are
-   * signatures.
-   * Indices with signatures will have a zero address.
+   * Recovers the committee from the addresses in the attestations and signers.
+   *
    * @param _attestations - The committee attestations
+   * @param _signers The addresses of the committee members that signed the attestations. Provided in order to not have
+   * to recover them from their attestations' signatures (and hence save gas). The addresses of the non-signing
+   * committee members are directly included in the attestations.
    * @param _length - The number of addresses to return, should match the number of committee members
+   * @return The addresses of the committee members.
    */
   function reconstructCommitteeFromSigners(
     CommitteeAttestations memory _attestations,

l1-contracts/src/core/libraries/rollup/BlobLib.sol

@@ -81,14 +81,15 @@ library BlobLib {
    * @notice  Validate an L2 block's blobs and return the blobHashes, the hashed blobHashes, and blob commitments.
    *
    *          We assume that the Aztec related blobs will be first in the propose transaction, additional blobs can be
-   * at the end.
+   *          at the end.
    *
    * Input bytes:
    * input[0] - num blobs in block
    * input[1:] - blob commitments (48 bytes * num blobs in block)
    * @param _blobsInput - The above bytes to verify our input blob commitments match real blobs
    * @param _checkBlob - Whether to skip blob related checks. Hardcoded to true (See RollupCore.sol -> checkBlob),
-   * exists only to be overriden in tests.
+   * exists only to be overridden in tests.
+   *
    * Returns for proposal:
    * @return blobHashes - All of the blob hashes included in this block, to be emitted in L2BlockProposed event.
    * @return blobsHashesCommitment - A hash of all blob hashes in this block, to be included in the block header. See
@@ -156,12 +157,10 @@ library BlobLib {
    * we know that the data in each blob of the epoch corresponds to the tx effects of all our proven txs in the epoch.
    *
    * The rollup circuits calculate each z_i and y_i as above, so if this function passes but they do not match the
-   * values from the
-   * circuit, then proof verification will fail.
+   * values from the circuit, then proof verification will fail.
    *
    * Each commitment C_i is injected into the circuits and their correctness is validated using the blobCommitmentsHash,
-   * as
-   * explained below in calculateBlobCommitmentsHash().
+   * as explained below in calculateBlobCommitmentsHash().
    *
    */
   function validateBatchedBlob(bytes calldata _blobInput) internal view returns (bool success) {
@@ -172,7 +171,7 @@ library BlobLib {
 
   /**
    * @notice  Calculate the current state of the blobCommitmentsHash. Called for each new proposed block.
-   * @param _previousblobCommitmentsHash - The previous block's blobCommitmentsHash.
+   * @param _previousBlobCommitmentsHash - The previous block's blobCommitmentsHash.
    * @param _blobCommitments - The commitments corresponding to this block's blobs.
    * @param _isFirstBlockOfEpoch - Whether this block is the first of an epoch (see below).
    *
@@ -195,20 +194,20 @@ library BlobLib {
    *
    */
   function calculateBlobCommitmentsHash(
-    bytes32 _previousblobCommitmentsHash,
+    bytes32 _previousBlobCommitmentsHash,
     bytes[] memory _blobCommitments,
     bool _isFirstBlockOfEpoch
-  ) internal pure returns (bytes32 currentblobCommitmentsHash) {
+  ) internal pure returns (bytes32 currentBlobCommitmentsHash) {
     uint256 i = 0;
-    currentblobCommitmentsHash = _previousblobCommitmentsHash;
+    currentBlobCommitmentsHash = _previousBlobCommitmentsHash;
     // If we are at the first block of an epoch, we reinitialise the blobCommitmentsHash.
     // Blob commitments are collected and proven per root rollup proof => per epoch.
     if (_isFirstBlockOfEpoch) {
       // Initialise the blobCommitmentsHash
-      currentblobCommitmentsHash = Hash.sha256ToField(abi.encodePacked(_blobCommitments[i++]));
+      currentBlobCommitmentsHash = Hash.sha256ToField(abi.encodePacked(_blobCommitments[i++]));
     }
     for (i; i < _blobCommitments.length; i++) {
-      currentblobCommitmentsHash = Hash.sha256ToField(abi.encodePacked(currentblobCommitmentsHash, _blobCommitments[i]));
+      currentBlobCommitmentsHash = Hash.sha256ToField(abi.encodePacked(currentBlobCommitmentsHash, _blobCommitments[i]));
     }
   }
 

l1-contracts/src/core/libraries/rollup/EpochProofLib.sol

@@ -35,7 +35,7 @@ import {SafeCast} from "@oz/utils/math/SafeCast.sol";
  *      The submitEpochRootProof() function is the main entry point called from RollupCore.submitEpochRootProof().
  *      It serves as the mechanism by which provers can finalize epochs, advancing the proven chain tip and
  *      triggering reward distribution. This is a critical operation that moves blocks from "pending" to "proven"
- * status.
+ *      status.
  *
  *      Attestation Verification:
  *      Before accepting an epoch proof, this library verifies the attestations for the last block in the epoch.
@@ -66,13 +66,6 @@ library EpochProofLib {
   using AttestationLib for CommitteeAttestations;
   using CompressedTimeMath for CompressedSlot;
 
-  // This is a temporary struct to avoid stack too deep errors
-  struct BlobVarsTemp {
-    uint256 blobOffset;
-    uint256 offset;
-    uint256 i;
-  }
-
   /**
    * @notice Submit a validity proof for an epoch's state transitions, advancing the proven chain tip
    *
@@ -116,6 +109,8 @@ library EpochProofLib {
     Epoch endEpoch = assertAcceptable(_args.start, _args.end);
 
     // Verify attestations for the last block in the epoch
+    // -> This serves as training wheels for the public part of the system (proving systems used in public and AVM)
+    // ensuring committee consensus on the epoch's validity alongside the cryptographic proof verification below.
     verifyLastBlockAttestations(_args.end, _args.attestations);
 
     require(verifyEpochRootProof(_args), Errors.Rollup__InvalidProof());
@@ -151,8 +146,6 @@ library EpochProofLib {
   ) internal view returns (bytes32[] memory) {
     RollupStore storage rollupStore = STFLib.getStorage();
 
-    // TODO(#7373): Public inputs are not fully verified
-
     {
       // We do it this way to provide better error messages than passing along the storage values
       {

l1-contracts/src/core/libraries/rollup/STFLib.sol

@@ -35,7 +35,7 @@ import {CompressedSlot, CompressedTimeMath} from "@aztec/shared/libraries/Compre
  *      - The temporary block logs use a circular storage pattern where blocks are stored at index (blockNumber %
  *        roundaboutSize).
  *        This reuses storage slots for old blocks that have been proven or pruned.
- *        The roundabout size is calculated as maxPrunableBlocks() + 1 to ensure at least the last provable block
+ *        The roundabout size is calculated as maxPrunableBlocks() + 1 to ensure at least the last proven block
  *        remains accessible even after pruning operations. This saves gas costs by minimizing storage writes to fresh
  *        slots.
  *
@@ -195,7 +195,7 @@ library STFLib {
     uint256 pending = tips.getPendingBlockNumber();
 
     // @note  We are not deleting the blocks, but we are "winding back" the pendingTip to the last block that was
-    // proven.
+    //        proven.
     //        We can do because any new block proposed will overwrite a previous block in the block log,
     //        so no values should "survive".
     //        People must therefore read the chain using the pendingTip as a boundary.
@@ -221,7 +221,7 @@ library STFLib {
    * @return The number of slots in the circular storage buffer
    */
   function roundaboutSize() internal view returns (uint256) {
-    // Must be ensured to contain at least the last provable even after a prune.
+    // Must be ensured to contain at least the last proven block even after a prune.
     return TimeLib.maxPrunableBlocks() + 1;
   }
 
@@ -392,8 +392,9 @@ library STFLib {
    *          The deadline is the point in time where it is no longer acceptable, (if you touch the line you die)
    *      - If epoch(_ts) >= epoch N + Proof submission window + 1, pruning is allowed
    *
-   *      This mechanism ensures rollup liveness by preventing indefinite stalling on unproven blocks
-   *      while providing sufficient time for proof generation and submission.
+   *      This mechanism ensures rollup liveness by preventing indefinite stalling on unprovable blocks (e.g due to
+   *      the committee failing to disseminate the data) while providing sufficient time for proof generation and
+   *      submission.
    *
    * @param _ts The current timestamp to check against
    * @return True if pruning is allowed at the given timestamp, false otherwise