# State Transition Diagrams

The following **state machine diagrams** show how the Gateway transitions at a higher level (beyond per-function details). These highlight the Gateway’s lifecycle from *Uninitialized* to *Initialized*, how fork creation interacts with normal operation, and how pausing works.

## 1. Initialization and Batch Submission

{% @mermaid/diagram content="stateDiagram-v2
\[\*] --> Uninitialized: Deploy

```
state Uninitialized {
    [*] --> WaitingForGenesis
}

state Initialized {
    [*] --> Active
    Active --> Paused: pause()
    Paused --> Active: unpause()
    
    state Active {
        [*] --> NormalOperation
        NormalOperation --> ForkCreation: forkChain()
        ForkCreation --> NormalOperation
    }
}

Uninitialized --> Initialized: submitBatch(genesis)

state NormalOperation {
    [*] --> ValidateUniqueness
    ValidateUniqueness --> AcceptingBatches: commit new
    ValidateUniqueness --> Error: commit exists
    AcceptingBatches --> AcceptingBatches: submitBatch()
}" %}
```

**Explanations**:

* The Gateway is uninitialized upon deployment.
* The first `submitBatch` with zero parent transitions it to “Initialized” with `currentForkId = 1`.
* When active, normal operation means handling new batches. If a batch’s commit hash is found in `_usedCommits`, we go to an error path.
* We can move from active to “Paused” by calling `pause()`.

## 2. Fork Management

{% @mermaid/diagram content="stateDiagram-v2
\[\*] --> ActiveFork

```
state ForkStates {
    ActiveFork --> ValidateUniqueness: forkChain()
    ValidateUniqueness --> NewFork: commit new
    ValidateUniqueness --> Error: commit exists
    NewFork --> ActiveFork
    
    state ActiveFork {
        [*] --> GrowingChain
        GrowingChain --> GrowingChain: submitBatch()
    }
    
    state NewFork {
        RestoreLowerForks --> AbandonHigherForks
        AbandonHigherForks --> CreateNewForkId
    }
}

state fork_transitions <<fork>>
    ActiveFork --> fork_transitions
    fork_transitions --> Abandoned: forkChain() to different fork
    fork_transitions --> Restored: forkChain() below fork height" %}
```

**Explanations**:

* Once forks exist, the chain can diverge from any valid commit.
* The system checks for commit uniqueness before creating a new fork.
* If the fork ID is higher than the target, it’s abandoned. If older abandoned forks are needed, they are restored.

## 3. Access Control State

{% @mermaid/diagram content="stateDiagram-v2
\[\*] --> RoleConfiguration

```
state RoleConfiguration {
    [*] --> DefaultAdmin
    DefaultAdmin --> RoleAssignment
    
    state RoleAssignment {
        [*] --> ManageRoles
        ManageRoles --> ManageRoles: grantRole()
        ManageRoles --> ManageRoles: revokeRole()
        ManageRoles --> ManageRoles: renounceRole()
    }
    
    state AdminConfiguration {
        [*] --> ConfigureAdmins
        ConfigureAdmins --> ConfigureAdmins: setRoleAdmin()
    }
}" %}
```

**Explanation**:

* There is a default admin that can configure who has which roles.
* Roles can be granted, revoked, or self-renounced.
* `setRoleAdmin` changes the admin role of a particular role.

## 4. Pausable State

{% @mermaid/diagram content="stateDiagram-v2
\[\*] --> Running
Running --> Paused: pause()
Paused --> Running: unpause()

```
state Running {
    [*] --> AcceptingTransactions
}

state Paused {
    [*] --> RejectingTransactions
}" %}
```

**Explanation**:

* A binary state: either running or paused.
* If paused, no batch or fork operations can proceed. Only unpause is allowed.

## 5. Batch Canonicality

{% @mermaid/diagram content="stateDiagram-v2
\[\*] --> BatchExists

```
state BatchExists {
    [*] --> InCurrentFork
    [*] --> InPreviousFork
    
    InCurrentFork --> Canonical
    
    state InPreviousFork {
        [*] --> CheckForwardForks
        CheckForwardForks --> CheckAncestry: No lower branches
        CheckForwardForks --> NonCanonical: Lower branch exists
        CheckAncestry --> Canonical: In tip ancestry
        CheckAncestry --> NonCanonical: Not in tip ancestry
    }
}

BatchExists --> NonExistent: Batch not found" %}
```

**Explanation**:

* If the batch doesn’t exist or references an invalid commit hash, it’s non-existent.
* If it’s in the current fork, it’s canonical.
* Otherwise, we check forward forks (none can branch below this batch) and backward ancestry to confirm it is part of the current chain’s lineage.


---

# Agent Instructions: 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/state-transition-diagrams.md?ask=<question>
```

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.