Updated architecture docs are now live!

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

spinner

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

spinner

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

spinner

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

spinner

Explanation:

  • A binary state: either running or paused.

  • If paused, no batch or fork operations can proceed. Only unpause is allowed.

5. Batch Canonicality

spinner

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.

Last updated

Was this helpful?