docs: docs mismatch review draft-v31 (#4847)

Author: jcsec-security

docs/src/guides/advanced/11_compression.md

@@ -72,7 +72,7 @@ validation, and compressing it.
 
 For bytecode to be considered valid it must satisfy the following:
 
-1. Bytecode length must be less than 2097120 ((2^16 - 1) \* 32) bytes.
+1. Bytecode length must be at most 2097120 ((2^16 - 1) \* 32) bytes
 2. Bytecode length must be a multiple of 32.
 3. Number of words cannot be even.
 

docs/src/specs/contracts/chain_management/admin_role.md

@@ -20,7 +20,7 @@ Generally all the functionality of chain admin should be treated with maximal se
 
 ### Setting validators for a chain
 
-The admin of a chain can call `ValidatorTimelock` on the settlement layer to add or remove validators, i.e. addresses that have the right to `commit`/`verify`/`execute` batches etc.
+The admin of a chain can call `ValidatorTimelock` on the settlement layer to add or remove validators via  `addValidator`/`removeValidator` (which grant/revoke all six per-chain roles at once), or assign individual roles granularly via `addValidatorRoles`/`removeValidatorRoles` i.e. for an addresses to have the right to commit/verify/execute batches.
 
 The system is protected against malicious validators, they can never steal funds from users. However, this role is still relatively powerful: If the DA layer is not reliable, and a batch does get executed, the funds may be frozen. This is why the chains should be [cautious about DA layers that they use](#setting-da-layer). Note, that on L1 the `ValidatorTimelock` has 3h delay, while on Gateway this timelock will not be present.
 

docs/src/specs/contracts/chain_management/bridgehub.md

@@ -15,7 +15,7 @@ Note sure what CTM is? Check our the [overview](./chain_type_manager.md).
 
 > This document will not cover how ZK Gateway works, you can check it out in [a separate doc](../gateway/overview.md). 
 
-The Bridgehub is the contract where new chains can [register](./chain_genesis.md). The Bridgehub also serves as an AssetHandler for chains when migrating chains between settlement layers, read more about it [here](../gateway/chain_migration.md).
+The Bridgehub is the contract where new chains can [register](./chain_genesis.md). Chain migration between settlement layers is handled by dedicated `ChainAssetHandler` contracts (`L1ChainAssetHandler` on L1, `L2ChainAssetHandler` as an L2 predeploy at `0x1000a`), not by the Bridgehub directly. The Bridgehub retains only helper hooks gated `onlyChainAssetHandler` (`forwardedBridgeBurnSetSettlementLayer`, `forwardedBridgeMint`, `forwardedBridgeConfirmTransferResult`, and `registerNewZKChain`). Read more about chain migration [here](../gateway/chain_migration.md).
 
 Overall, it is the main registry for all the contracts. Note, that a clone of Bridgehub is also deployed on each L2 chain, it is used to start interop txs by checking that the chain is active. It is also used on settlement layers such as Gateway. All the in all, the architecture of the entire ecosystem can be seen below:
 

docs/src/specs/contracts/chain_management/chain_type_manager.md

@@ -62,7 +62,7 @@ In the current release, each chain will be an instance of ZKsync Era and so the
 
 In case of an emergency, the [security council](https://blog.zknation.io/introducing-zk-nation/) has the ability to freeze the ecosystem and conduct an emergency upgrade.
 
-In case we are aware that some of the committed batches on a chain are dangerous to be executed, the CTM can call `revertBatches` on that chain. For faster reaction, the admin of the ChainTypeManager has the ability to do so without waiting for govenrnace approval that may take a lot of time. This action does not lead to funds being lost, so it is considered suitable for the partially trusted role of the admin of the ChainTypeManager.
+In case we are aware that some of the committed batches on a chain are dangerous to be executed, the CTM can call `revertBatches` on that chain. This is performed by the CTM owner — the governance-controlled Protocol Upgrade Handler — typically as part of a freeze and emergency upgrade. This action does not lead to funds being lost. Note that reverting batches is not exclusive to the CTM: the underlying `revertBatchesSharedBridge` function on the chain is callable by both the CTM and the chain's validators (via the `REVERTER_ROLE` on the ValidatorTimelock), so a chain's operator can also revert its own not-yet-executed batches.
 
 ### Issues & caveats
 

docs/src/specs/contracts/chain_management/overview.md

@@ -77,8 +77,7 @@ be able to leverage them when available).
   - `ChainTypeRegistry` The chain type is shared for multiple chains, so initialization and upgrades have to be the same for all
     chains. Registration is not permissionless but happens based on the registrations in the bridgehub’s `Registry`. At
     registration a `DiamondProxy` is deployed and initialized with the appropriate `Facets` for each ZK Chain.
-  - `Facets` and `Verifier` are shared across chains that relies on the same chain type: `Base`, `Executor` , `Getters`, `Admin`
-    , `Mailbox.`The `Verifier` is the contract that actually verifies the proof, and is called by the `Executor`.
+  - `Facets` and `Verifier` are shared across chains that use the same chain type. The chain diamond is initialized with `Admin`, `Getters`, `Mailbox`, `Committer`, `Executor`, and `Migrator` facets. `ZKChainBase` is an inherited base contract, not a diamond facet. The `Committer` handles batch precommit/commit logic, including L2 log processing and batch commitment creation. The `Executor` handles proving, executing, and reverting batches, and calls the `Verifier` during proof validation. The `Migrator` handles settlement-layer migration logic
   - Upgrade Mechanism The system requires all chains to be up-to-date with the latest implementation, so whenever an
     update is needed, we have to “force” each chain to update, but due to decentralization, we have to give each chain a
     time frame. This is done in the update mechanism contract, this is where the bootloader and system contracts are

docs/src/specs/contracts/gateway/chain_migration.md

@@ -2,15 +2,15 @@
 
 ## Ecosystem Setup
 
-Chain migration reuses lots of logic from standard custom asset bridging which is enabled by the AssetRouter. The easiest way to imagine is that ZKChains are NFTs that are being migrated from one chain to another. Just like in case of the NFT contract, an CTM is assumed to have an `assetId := keccak256(abi.encode(L1_CHAIN_ID, address(ctmDeployer), bytes32(uint256(uint160(_ctmAddress)))))`. I.e. these are all assets with ADT = ctmDeployer contract on L1.
+Chain migration reuses lots of logic from standard custom asset bridging which is enabled by the AssetRouter. The easiest way to imagine is that ZKChains are NFTs that are being migrated from one chain to another. Just like in case of the NFT contract, an CTM is assumed to have an `assetId := keccak256(abi.encode(block.chainid, address(ctmDeploymentTracker), bytes32(uint256(uint160(_ctmAddress)))))`. I.e. these are all assets with ADT = ctmDeploymentTracker contract on L1.
 
-CTMDeployer is a very lightweight contract used to facilitate chain migration. Its main purpose is to serve as formal asset deployment tracker for CTMs. It serves two purposes:
+CTMDeploymentTracker is a very lightweight contract used to facilitate chain migration. Its main purpose is to serve as formal asset deployment tracker for CTMs. It serves two purposes:
 
-- Assign bridgehub as the asset handler for the “asset” of the CTM on the supported settlement layer.
+- Register the `ChainAssetHandler` (via `registerCTMAssetOnL1`) as the asset handler for the 'asset' of the CTM on the supported settlement layer.
 
-Currently, it can only be done by the owner of the CTMDeployer, but in the future, this method can become either permissionless or callable by the CTM owner.
+Currently, it can only be done by the owner of the CTMDeploymentTracker, but in the future, this method can become either permissionless or callable by the CTM owner.
 
-- Tell bridgehub which address on the L2 should serve as the L2 representation of the CTM on L1. Currently, it can only be done by the owner of the CTMDeployer, but in the future, this method can become callable by the CTM owner.
+- Tell bridgehub which address on the L2 should serve as the L2 representation of the CTM on L1. Currently, it can only be done by the owner of the CTMDeploymentTracker, but in the future, this method can become callable by the CTM owner.
 
 ![image.png](./img/ctm_gw_registration.png)
 

docs/src/specs/contracts/gateway/l2_gw_l1_messaging.md

@@ -30,11 +30,11 @@ The structure has the following recursive format:
 - `settledMessageRoot = keccak256(LocalRoot, AggregatedRoot)`
 - `LocalRoot` — the root of the binary merkle tree over `UserLog[]`. (the same as the one we have now). It only contains messages from the current batch.
 - `AggregatedRoot` — the root of the binary merkle tree over `ChainIdLeaf[]`.
-- `ChainIdLeaf = keccak256(CHAIN_ID_LEAF_PADDING, chain_id, ChainIdRoot`)
+- `ChainIdLeaf = keccak256(CHAIN_ID_LEAF_PADDING, ChainIdRoot, chain_id)`
 - `CHAIN_ID_LEAF_PADDING` — it is a constant padding, needed to ensure that the preimage of the ChainIdLeaf is larger than 64 bytes and so it can not be an internal node.
 - `chain_id` — the chain id of the chain the batches of which are aggregated.
 - `ChainIdRoot` = the root of the binary merkle tree `BatchRootLeaf[]`.
-- `BatchRootLeaf = keccak256(BATCH_LEAF_HASH_PADDING, batch_number, SettledRootOfBatch).`
+- `BatchRootLeaf = keccak256(BATCH_LEAF_PADDING, SettledRootOfBatch, batch_number).`
 
 In other words, we get the recursive structure, where for leaves of it, i.e. chains that do not aggregate any other chains, have empty `AggregatedRoot`.
 
@@ -97,9 +97,13 @@ This function will be internally used by the existing `_proveL2LogInclusion` fun
 
 We want to avoid breaking changes to SDKs, so we will modify the `zks_getL2ToL1LogProof` to return the data in the following format (the results of it are directly passed into the `proveL2LeafInclusion` method, so returned value must be supported by the contract):
 
-First `bytes32` corresponds to the metadata of the proof. The zero-th byte should tell the version of the metadata and must be equal to the `SUPPORTED_PROOF_METADATA_VERSION` (a constant of `0x01`).
+The first `bytes32` element of the proof encodes the proof metadata, laid out byte by byte (byte 0 being the most significant):
 
-Then, it should contain the number of 32-byte words that are needed to restore the current `BatchRootLeaf` , i.e. `logLeafProofLen` (it is called this way as it proves that a leaf belongs to the `SettledRootOfBatch`). The second byte contains the `batchLeafProofLen` . It is the length of the merkle path to prove that the `BatchRootLeaf` belonged to the `ChainIdRoot` .
+- byte 0 — metadata version; must equal `SUPPORTED_PROOF_METADATA_VERSION` (a constant of `0x01`).
+- byte 1 — `logLeafProofLen`: the number of 32-byte words needed to restore the current `BatchRootLeaf` (named this way because it proves a leaf belongs to the `SettledRootOfBatch`).
+- byte 2 — `batchLeafProofLen`: the length of the Merkle path proving that the `BatchRootLeaf` belongs to the `ChainIdRoot`.
+- byte 3 — `finalProofNode`: whether this proof is the last link in the chain of recursive settlement-layer proofs.
+- bytes 4–31 — zero.
 
 Then, the following happens:
 
@@ -109,10 +113,10 @@ If the settlement layer of the chain is the chain itself, we can just end here b
 
 If the chain is not a settlement layer of itself, we then need to calculate:
 
-- `BatchRootLeaf = keccak256(BATCH_LEAF_HASH_PADDING, SettledRootOfBatch, batch_number).`
+- `BatchRootLeaf = keccak256(BATCH_LEAF_PADDING, SettledRootOfBatch, batch_number).`
 - Consume one element from the `_proofs` array to get the mask for the merkle path of the batch leaf in the chain id tree.
 - Consume `batchLeafProofLen` elements to construct the `ChainIdRoot`
-- After that, we calculate the `chainIdLeaf = keccak256(CHAIN_ID_LEAF_PADDING, chainIdRoot, chainId`
+- After that, we calculate the `chainIdLeaf = keccak256(CHAIN_ID_LEAF_PADDING, chainIdRoot, chainId`)
 
 Now, we have the _supposed_ `chainIdRoot` for the chain inside its settlement layer. The only thing left to prove is that this root belonged to some batch of the settlement layer.
 
@@ -178,7 +182,7 @@ In order to ease the server migration, we support legacy format of L2→L1 logs
 
 To differentiate between legacy format and the one, the following approach is used;
 
-- Except for the first 3 bytes the first word in the new format contains 0s, which is unlikely in the old format, where leaves are hashed.
-- I.e. if the last 29 bytes are zeroes, then it is assumed to be the new format and vice versa.
+- Except for the first 4 bytes the first word in the new format contains 0s, which is unlikely in the old format, where leaves are hashed.
+- I.e. if the last 28 bytes are zeroes, then it is assumed to be the new format and vice versa.
 
 In the next release the old format will be removed.

docs/src/specs/contracts/settlement_contracts/data_availability/custom_da.md

@@ -65,4 +65,4 @@ This allows for a general-purpose solution that ensures DA consistency and verif
    - `L2_DA_VALIDATOR_OUTPUT_HASH_KEY` (the commitment) 
 
 4. L1 verification  
-	On L1 the Executor facet will call L1 DA validator, providing it with chain ID and batch number of the chain for which the DA must be verified, along with `l2DAValidatorOutputHash`, `operatorDAInput` and `_maxBlobsSupported` value. It's then L1 DA Validator job to verify the correctness of the DA on L1.
+	On L1 the Committer facet calls the L1 DA validator during batch commitment, providing it with chain ID and batch number of the chain for which the DA must be verified, along with `l2DAValidatorOutputHash`, `operatorDAInput` and `_maxBlobsSupported` value. It's then L1 DA Validator job to verify the correctness of the DA on L1.

docs/src/specs/contracts/settlement_contracts/data_availability/pubdata.md

@@ -13,8 +13,8 @@ pre-Boojum system these are represented as separate fields while for boojum they
 array. Once 4844 gets integrated this bytes array will move from being part of the calldata to blob data.
 
 While the structure of the pubdata changes, the way in which one can go about pulling the information will remain the
-same. Basically, we just need to filter all of the transactions to the L1 ZKsync contract for only the `commitBatches`
-transactions where the proposed block has been referenced by a corresponding `executeBatches` call (the reason for this
+same. Basically, we just need to filter all of the transactions to the L1 ZKsync contract for only the `commitBatchesSharedBridge`
+transactions where the proposed block has been referenced by a corresponding `executeBatchesSharedBridge` call (the reason for this
 is that a committed or even proven block can be reverted but an executed one cannot). Once we have all the committed
 batches that have been executed, we then will pull the transaction input and the relevant fields, applying them in order
 to reconstruct the current state of L2.
@@ -65,7 +65,7 @@ natively by VM _system_ logs. Here is a short comparison table for better unders
 | Emitted by VM via an opcode.                                                                                    | VM knows nothing about them.                                                                                                                                                                                                        |
 | Consistency and correctness is enforced by the verifier on L1 (i.e. their hash is part of the block commitment. | Consistency and correctness is enforced by the L1Messenger system contract. The correctness of the behavior of the L1Messenger is enforced implicitly by prover in a sense that it proves the correctness of the execution overall. |
 | We don’t calculate their Merkle root.                                                                           | We calculate their Merkle root on the L1Messenger system contract.                                                                                                                                                                  |
-| We have constant small number of those.                                                                         | We can have as much as possible as long as the commitBatches function on L1 remains executable (it is the job of the operator to ensure that only such transactions are selected)                                                   |
+| We have constant small number of those.                                                                         | We can have as much as possible as long as the commitBatchesSharedBridge function on L1 remains executable (it is the job of the operator to ensure that only such transactions are selected)                                                   |
 | In EIP4844 they will remain part of the calldata.                                                               | In EIP4844 they will become part of the blobs.                                                                                                                                                                                      |
 
 #### Backwards-compatibility
@@ -194,7 +194,7 @@ all concatenated together to yield the final compressed version.
 
 For bytecode to be considered valid it must satisfy the following:
 
-1. Bytecode length must be less than 2097120 ((2^16 - 1) \* 32) bytes.
+1. Bytecode length must be at most 2097120 ((2^16 - 1) \* 32) bytes
 2. Bytecode length must be a multiple of 32.
 3. Number of 32-byte words cannot be even.
 
@@ -429,7 +429,7 @@ With Boojum, the interface for committing batches is the following one:
 /// @param bootloaderHeapInitialContentsHash Hash of the initial contents of the bootloader heap. In practice it serves as the commitment to the transactions in the batch.
 /// @param eventsQueueStateHash Hash of the events queue state. In practice it serves as the commitment to the events in the batch.
 /// @param systemLogs concatenation of all L2 -> L1 system logs in the batch
-/// @param totalL2ToL1Pubdata Total pubdata committed to as part of bootloader run. Contents are: l2Tol1Logs <> l2Tol1Messages <> publishedBytecodes <> stateDiffs
+/// @param operatorDAInput The data-availability input provided by the operator, processed by the L1DAValidator. Its contents depend on the DA mode (for rollups: the state-diff hash, the pubdata, and blob commitment data).
 struct CommitBatchInfo {
   uint64 batchNumber;
   uint64 timestamp;
@@ -440,7 +440,7 @@ struct CommitBatchInfo {
   bytes32 bootloaderHeapInitialContentsHash;
   bytes32 eventsQueueStateHash;
   bytes systemLogs;
-  bytes totalL2ToL1Pubdata;
+  bytes operatorDAInput;
 }
 
 ```