Detailed Sequence Diagrams

Below are the sequence diagrams illustrating each mutating function in the Gateway. These diagrams give a step-by-step overview of inputs, internal checks, and final state changes.

1. submitBatch(BatchHeader)

Context: This function is the most common entry point when L2 blocks are appended to L1. It requires the caller to have the APPENDER_ROLE. The diagram below explains how a new commit is validated, stored, and linked to the previous commit.

Key Points:

• If the system is uninitialized, the contract expects the first commit to have a zero prevBatchHash (the genesis batch).

• If already initialized, the prevBatchHash must match _lastCommitHash, ensuring proper ordering.

• A DuplicateCommit error is thrown if the same commit hash is reused.

Impact:

• Extends the main chain tip.

• Ensures L2 block ordering is strictly sequential.

• Genesis creation if the contract wasn’t initialized.

Developer Tips:

• The aggregator should always read _lastCommitHash (via gateway.lastCommitHash()) to build the correct prevBatchHash for the new batch.

• If you get InvalidPreviousCommit, it likely means you used the wrong parent hash.

2. forkChain(BatchHeader, targetForkId)

Context: Forking allows the system to create a new chain from an older commit instead of building on the current tip. This function is restricted to addresses with the FORKER_ROLE.

Key Points:

• The new fork is assigned a forkId = currentForkId + 1.

• Any fork IDs higher than targetForkId become abandoned.

• Previously abandoned forks can be restored if the chosen commit is in one of those forks.

Impact:

• Potentially redefines the canonical chain if new fork commits surpass the old chain.

• Each fork has its own chain tip, stored separately in _commits[forkId].

Developer Tips:

• Only fork if you’re sure the new chain is correct (e.g., after an L2 reorg).

• Watch for the ForkAbandoned and ForkRestored events to know which forks remain valid.

3. pause()

Context: This is how an admin stops further mutations during emergencies (e.g., suspicious activity, discovered vulnerability). Only addresses with the PAUSER_ROLE can call it.

Key Points:

• Once paused, submitBatch and forkChain revert if called.

• The system remains read-only until unpaused.

Impact:

• Freezes all batch submission and forking operations.

• No effect on read-only calls like locateBatch or isCanonicalBatch.

Developer Tips:

• Must coordinate with the UNPAUSER_ROLE to bring the system back once resolved.

4. unpause()

Context: Lifts the pause so normal operations can resume. Only addresses with the UNPAUSER_ROLE can call it.

Impact:

• Restores full contract functionality.

• Typically used after verifying that no malicious activity continues.

Developer Tips:

• Ensure you have the correct unpauser addresses configured.

• If the system was paused due to a bug, confirm it’s fixed before unpausing.

5. Role Functions (setRoleAdmin(), grantRole(), revokeRole(), renounceRole())

Context: The Gateway uses OpenZeppelin AccessControl, which stores roles and their admins. These sequence diagrams outline how each role-management method works.

Below is a representative diagram for setRoleAdmin; similar logic applies to grantRole, revokeRole, or renounceRole.

Developer Tips:

• Assign roles carefully (e.g., a Gnosis Safe) to prevent a single compromised EOA from controlling the contract.

• renounceRole is typically used by an address to relinquish a role it no longer needs.

6. Canonical Chain Determination

Context: A helpful read-only function, isCanonicalBatch(batchHash) checks whether a given batch is part of the chain tip’s ancestry. This is especially relevant in a multi-fork scenario.

Key Points:

• If the batch belongs to the currentForkId, it’s automatically canonical.

• Otherwise, we ensure no non-abandoned fork branches below that batch’s height, and we can trace from the tip’s fork back to the batch’s fork.

Developer Tips:

• Use isCanonicalBatch to confirm if a commit is on the recognized “main” chain.

• If a fork outpaces the old chain, its commits can become canonical, relegating the old chain’s commits to a non-canonical status.