Skip to content

docs: enhance Execution API documentation with block size management #2215

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tzdybal merged 3 commits into from
Apr 29, 2025
Merged

docs: enhance Execution API documentation with block size management #2215

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
deb08d4
docs: enhance Execution API documentation with block size management …
tzdybal Apr 24, 2025
3276640
docs: add more details to ADR-010
tzdybal Apr 24, 2025
88586a1
docs: address review comments
tzdybal Apr 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
docs: add more details to ADR-010
  • Loading branch information
@tzdybal
tzdybal committed Apr 28, 2025
commit 3276640068b3a327a9db4cc7198ed78214bf6116
98 changes: 55 additions & 43 deletions specs/lazy-adr/adr-010-exec-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,26 @@
Introduction of the Execution API makes rollkit very generic and execution-environment agnostic.
It removes all ABCI-centric code for full interoperability with other types of VMs.

The Execution API serves as a bridge between Rollkit and various execution environments (VMs),
allowing Rollkit to remain agnostic to the specific implementation details of the execution layer.
This separation enables:

1. Support for multiple VM types (EVM, WASM, etc.)
2. Easier integration with different execution environments
3. Cleaner separation of concerns between consensus and execution
4. More flexible and maintainable architecture

## Alternative Approaches

1. Maintain current state: keep ABCI interface and implement other VMs inside ABCI application.
- Pros: No changes required to existing code
- Cons: ABCI-specific code remains, limiting flexibility
2. Migrate to Engine API.
- Pros: Standard interface for EVM-based chains
- Cons: Too specific to EVM, not suitable for other VMs
3. Create new API generic enough to handle any arbitrary VM.
- Pros: Maximum flexibility, clean separation of concerns
- Cons: Requires significant refactoring
Comment thread
tzdybal marked this conversation as resolved.
Resolved

## Decision

Expand Down Expand Up @@ -70,6 +85,7 @@ Initializes the blockchain's state based on genesis information. This method is
- Initialize rollup according to the genesis.
- Generate an initial `stateRoot` representing the genesis state of the rollup.
- Return the maximum allowable block size (`maxBytes`).
- Ensure all necessary state is initialized for subsequent operations.

#### `GetTxs`

Expand All @@ -92,6 +108,7 @@ Transactions returned by execution client will be passed by rollkit to sequencer
- Access the mempool and retrieve all available transactions.
- If no transactions are available, return an empty slice without error.
- Do not remove ("reap") transactions from mempool.
- Ensure transactions are valid and properly formatted.

#### `ExecuteTxs`

Expand Down Expand Up @@ -120,6 +137,7 @@ Executes a given set of transactions, updating the blockchain state.
- Enforce block size and validity limits, returning errors if constraints are violated.
- Respect the ordering of transactions.
- Update the mempool to remove all executed transactions.
- Ensure atomic execution - either all transactions succeed or none do.

#### `SetFinal`

Expand All @@ -140,12 +158,16 @@ Marks a block at the specified height as final, guaranteeing immutability for co

- Update the execution client's internal state to reflect that the specified block is final and immutable.
- Ensure additional guarantees like cleaning up unnecessary resources associated with blocks deemed final.
- Prevent any modifications to finalized blocks.
- Optimize storage for finalized blocks if possible.

#### General Notes

1. **Thread-Safety**: All methods are not expected to be thread-safe, concurrent calls are not planned.
2. **Error Handling**: All methods should follow robust error handling practices, ensuring meaningful errors are returned when issues occur.
3. **Context Usage**: Methods should respect context-based deadlines and cancellations for long-running operations.
4. **State Management**: The execution environment is responsible for maintaining its own state and ensuring consistency.
5. **Atomicity**: Operations that modify state should be atomic - either fully succeed or fully fail.

### Types

Expand Down Expand Up @@ -186,6 +208,32 @@ The Execution API includes `maxBytes` as a return value in both `InitChain` and
- Helps prevent oversized blocks from being produced
- Enables dynamic adjustment of block size limits without protocol changes

### Implementation Guidelines

1. **State Management**:
- Execution environments must maintain their own state
- State transitions should be atomic
- State should be persisted appropriately
- State should be recoverable after crashes

2. **Error Handling**:
- Return meaningful error messages
- Handle context cancellations gracefully
- Ensure proper cleanup on errors
- Maintain state consistency even after errors

3. **Performance Considerations**:
- Optimize for common operations
- Consider caching where appropriate
- Handle large state sizes efficiently
- Minimize unnecessary state transitions

4. **Security**:
- Validate all inputs thoroughly
- Prevent unauthorized state modifications
- Ensure proper access control
- Handle sensitive data appropriately

### Sequence Diagrams

#### Block production
Expand Down Expand Up @@ -236,49 +284,6 @@ sequenceDiagram
end
```

### Changes in Rollkit

Because of improved separation of concerns, logic related to actual execution can be removed from rollkit.
Rollkit will turn from fully-fledged ABCI client to kind of orchestrator, gluing together multiple modules.
The role of Rollkit is coordination of Sequencer and Execution Environment and recording results in Data Availability layer.

Currently, Rollkit exposes ABCI and CometBFT compatible RPCs, manages genesis processing and mempool.
This logic belongs to Execution Environment, and will be moved to Execution API implementations.

Removal of this logic from Rollkit enables further refactoring, for example removing all CometBFT dependencies.

#### Main changes in Rollkit packages

##### `block`

1. New processing in `Manager` - move from ABCI to Execution API oriented processing.

##### `node`

1. Simplification of `Node` interface.
2. Removal of `LightClient` and `FullClient`.
3. Cleanup/simplification of `FullNode` and `LightNode`.

##### `rpc`

1. Removal of ABCI and CometBFT methods.
2. Introduction of Rollkit specific methods.

##### Other packages

Probably all the packages will be affected by cleanup and refactoring.

### Testing

As there is a lot of logic to be removed, corresponding tests can also be removed.
Some of the other test are very ABCI-oriented and should be fixed or re-created.

Integration tests should be introduced to ensure that entire flow (from `InitChain` to `SetFinal`) works correctly.

### User documentation

All the tutorials needs to be updated to accommodate introduction of new binary (Execution API implementation).

## Status

Accepted
Expand All @@ -290,16 +295,23 @@ Accepted
1. Simplification of rollkit's logic.
2. Better separation of concerns.
3. Removal of ABCI dependencies.
4. Increased flexibility for different execution environments.
5. Cleaner architecture with well-defined boundaries.

### Negative

1. More difficult deployment (another binary is needed).
2. Need to reimplement ABCI execution environment.
3. Additional complexity in coordinating between components.
4. Potential performance overhead from additional abstraction layer.

### Neutral

1. Need to introduce new API exposed by rollkit.
2. Changes to existing deployment procedures.
3. Updates to documentation and tooling required.

## References

- [Rollkit EPIC for Execution API](https://github.com/rollkit/rollkit/issues/1802)
- [go-execution repository](https://github.com/rollkit/go-execution)