Core Architectural Elements

If the system is uninitialized and you submit a batch with a non-zero parent, it reverts. If it’s already initialized, you can’t reference bytes32(0) for the parent (genesis must be unique).

2. Fork Management

What It Is: The ability to create a new fork from an existing commit, potentially overriding the “canonical” chain. Rationale: If L2 reorgs or an undiscovered bug appears, the system can switch to an alternate history at an earlier commit without losing older state data.

We see this in GatewayForkTest.t.sol where we create a fork at height 5:

function testSimpleFork() public {
    // Extend main chain to 10 blocks
    extendChain(1, 10);
    // Create a fork from block 5
    uint16 fork2 = createFork(1, 5, 5);
    // ...
    validateChainState();
}

When you fork, the Gateway:

• Restores previously abandoned forks if necessary.

• Abandons any forks higher than the target.

• Increments currentForkId.

• Creates a new commit referencing the chosen parent.

3. Access Control

What It Is: Uses OpenZeppelin’s AccessControlEnumerable to define roles like APPENDER_ROLE for normal batch submissions, FORKER_ROLE for chain forks, and PAUSER_ROLE/UNPAUSER_ROLE for pausing/unpausing the contract. Rationale: This ensures only authorized parties can alter the contract’s state in sensitive ways.

GatewaySecurityTest.t.sol verifies unauthorized calls revert:

function testUnauthorizedBatchSubmission() public {
    vm.startPrank(unauthorized);
    Gateway.BatchHeader memory header = createBatchHeader(bytes32(0), 0, 100);
    // Expects revert: no APPENDER_ROLE
    vm.expectRevert(
        abi.encodeWithSelector(
            IAccessControl.AccessControlUnauthorizedAccount.selector, 
            unauthorized, 
            gateway.APPENDER_ROLE()
        )
    );
    gateway.submitBatch(header);
    vm.stopPrank();
}

4. Pausable Safety

What It Is: A mechanism to pause the Gateway (blocking submitBatch, forkChain, etc.) in emergencies, then unpause once resolved. Rationale: Allows contract administrators to quickly halt malicious or erroneous actions on the chain.

In GatewaySecurityTest.t.sol, we see:

function testPauseAndUnpause() public {
    // Pause with authorized pauser
    vm.startPrank(pauser);
    gateway.pause();
    assertTrue(gateway.paused());
    vm.stopPrank();

    // While paused, submissions revert
    vm.startPrank(appender);
    Gateway.BatchHeader memory header = createBatchHeader(bytes32(0), 0, 100);
    vm.expectRevert(Pausable.EnforcedPause.selector);
    gateway.submitBatch(header);
    vm.stopPrank();

    // Unpause with authorized unpauser
    vm.startPrank(unpauser);
    gateway.unpause();
    assertFalse(gateway.paused());
    vm.stopPrank();
}

If paused, no new commits or forks can be created until an authorized unpauser reactivates the system.