> For the complete documentation index, see [llms.txt](https://docs.eclipse.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.eclipse.xyz/architecture/eclipse-architecture/eclipse-l1-gateway/detailed-sequence-diagrams.md). # 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)` {% @mermaid/diagram content="sequenceDiagram actor Caller participant Gateway participant State participant Commits participant LastCommit participant Registry ``` Caller->>Gateway: submitBatch(header) Note over Gateway: Requires APPENDER_ROLE Gateway->>Gateway: requireNotPaused() Gateway->>Gateway: calculateCommitHash() Gateway->>Registry: Check commit uniqueness alt Commit exists Registry-->>Gateway: true Gateway->>Caller: revert DuplicateCommit else Commit is new Registry-->>Gateway: false Gateway->>State: Check initialization & currentForkId alt Not Initialized Gateway->>Gateway: Verify prevBatchHash is zero Note over Gateway: Must be genesis batch Gateway->>State: Set height = 1 else Initialized Gateway->>LastCommit: Get lastCommitHash Note over Gateway: Must build on chain tip Gateway->>Gateway: Verify header.prevBatchHash == lastCommitHash alt Parent Hash Mismatch Gateway-->>Caller: Revert InvalidPreviousCommit end Gateway->>Commits: Get parent commit height Note over Gateway: Ensure sequential height Gateway->>Gateway: Calculate new height = parent + 1 end Gateway->>Gateway: Store new commit Note right of Gateway: Store height and parentHash alt Not Initialized Gateway->>State: Set initialized = true Gateway->>State: Set currentForkId = 1 end Gateway->>LastCommit: Update lastCommitHash Gateway->>Registry: Record commit hash Gateway-->>Caller: Return commitHash Note over Gateway: Emit BatchSubmitted event with (currentForkId, commitHash, height, header) end" %} ``` **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)` {% @mermaid/diagram content="sequenceDiagram actor Caller participant Gateway participant State participant Commits participant Forks participant LastCommit participant Registry ``` Caller->>Gateway: forkChain(header, targetForkId) Note over Gateway: Requires FORKER_ROLE Gateway->>Gateway: requireNotPaused() Gateway->>Gateway: calculateCommitHash() Gateway->>Registry: Check commit uniqueness alt Commit exists Registry-->>Gateway: true Gateway->>Caller: revert DuplicateCommit else Commit is new Registry-->>Gateway: false Gateway->>Gateway: Verify parent exists loop For forks 1 to targetForkId Gateway->>Forks: Check if abandoned alt Fork abandoned && forkHeight < parentHeight Gateway->>Forks: Restore fork (abandoned = false) Note over Gateway: Emit ForkRestored event end end Gateway->>State: Get currentForkId loop For forks targetForkId+1 to currentForkId Gateway->>Forks: Mark as abandoned Note over Gateway: Emit ForkAbandoned event end Gateway->>State: Increment currentForkId Gateway->>Forks: Create new fork entry Note right of Gateway: Set forkHeight, forkParent, abandoned=false Gateway->>Commits: Store first commit of new fork Gateway->>LastCommit: Update lastCommitHash Gateway->>Registry: Record commit hash Gateway-->>Caller: Return commitHash Note over Gateway: Emit ForkForced event end" %} ``` **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()` {% @mermaid/diagram content="sequenceDiagram actor Admin participant Gateway participant Pausable participant State ``` Admin->>Gateway: pause() Note over Gateway: Requires PAUSER_ROLE Gateway->>Pausable: Check if already paused alt Not Already Paused Gateway->>Pausable: Set paused = true Note over Gateway: Emit Paused(account) else Already Paused Gateway->>Gateway: Revert with "Pausable: paused" end" %} ``` **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()` {% @mermaid/diagram content="sequenceDiagram actor Admin participant Gateway participant Pausable participant State ``` Admin->>Gateway: unpause() Note over Gateway: Requires UNPAUSER_ROLE Gateway->>Pausable: Check if already unpaused alt Is Paused Gateway->>Pausable: Set paused = false Note over Gateway: Emit Unpaused(account) else Not Paused Gateway->>Gateway: Revert with "Pausable: not paused" end" %} ``` **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`. {% @mermaid/diagram content="sequenceDiagram actor Admin participant Gateway participant AccessControl ``` Admin->>Gateway: setRoleAdmin(role, adminRole) Note over Gateway: Requires DEFAULT_ADMIN_ROLE Gateway->>AccessControl: _setRoleAdmin(role, adminRole) Note over Gateway: Emit RoleAdminChanged event" %} ``` **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 {% @mermaid/diagram content="sequenceDiagram actor Caller participant Gateway participant Commits participant Forks ``` Caller->>Gateway: isCanonicalBatch(batchHash) Gateway->>Gateway: locateBatch(batchHash) alt Batch Not Found Gateway-->>Caller: return false else Batch Found Gateway->>Gateway: Get batch fork and height alt In Current Fork Gateway-->>Caller: return true else Previous Fork loop Forward Fork Check Gateway->>Forks: Check each newer fork alt Non-abandoned fork branches below batch Gateway-->>Caller: return false end end loop Backward Ancestry Check Gateway->>Forks: Walk back through fork parents alt Found batch fork Gateway-->>Caller: return true else Hit genesis without finding fork Gateway-->>Caller: return false else Invalid state Gateway-->>Caller: return false end end end end" %} ``` **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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.eclipse.xyz/architecture/eclipse-architecture/eclipse-l1-gateway/detailed-sequence-diagrams.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.