> 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/state-transition-rules-and-invariants.md).

# State Transition Rules and Invariants

## State Transition Rules and Invariants

1. **Initialization**:
   * A single path from **Uninitialized** → **Initialized** is allowed on the first batch (`prevBatchHash == 0`).
   * `currentForkId` set to 1, marking the genesis commit’s creation.
2. **Batch Submission**:
   * Only **unpaused** state allows new batches.
   * Must build on the last commit hash (unless genesis).
   * `commitHash` must be unique or revert with `DuplicateCommit`.
3. **Fork Management**:
   * A new fork increments `currentForkId`.
   * Ties old forks above `targetForkId` as abandoned; can restore older forks if they become canonical again.
   * The first commit in a new fork references the chosen parent’s commit.
4. **Access Control**:
   * `DEFAULT_ADMIN_ROLE` can assign or remove roles.
   * `APPENDER_ROLE` needed to submit a batch.
   * `FORKER_ROLE` required for forking.
   * `PAUSER_ROLE` / `UNPAUSER_ROLE` for toggling pause.
5. **Pause Control**:
   * Paused or unpaused are the two states.
   * Mutating operations revert if paused.
   * The unpauser can resume normal operations.
6. **Commit Registry**:
   * `_usedCommits[commitHash]` tracks usage.
   * Once set, a commit can never be reused or deleted.
   * This ensures global uniqueness across all forks.

**Invariants** (must always hold true):

* **Fork Integrity**: `currentForkId` monotonically increases. Fork ancestry must remain traceable.
* **Commit Integrity**: Each commit has a valid parent (except genesis) and a strictly higher height than its parent.
* **Canonical Batches**: Must lie on the chain that leads from the current fork tip to genesis without encountering any fork that branches lower.
* **Access Control**: Roles are strictly enforced for each operation.
* **Pausable**: If `paused`, no new commits or forks can be created.


---

# 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, and the optional `goal` query parameter:

```
GET https://docs.eclipse.xyz/architecture/eclipse-architecture/eclipse-l1-gateway/state-transition-rules-and-invariants.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.