From 26902b340b9cf814fa9cc53d018929b24463aafa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20Zdyba=C5=82?= Date: Mon, 13 Jan 2025 13:34:42 +0100 Subject: [PATCH 1/8] docs: ADR-010 Execution API - initial draft --- specs/lazy-adr/adr-010-exec-api.md | 157 +++++++++++++++++++++++++++++ 1 file changed, 157 insertions(+) create mode 100644 specs/lazy-adr/adr-010-exec-api.md diff --git a/specs/lazy-adr/adr-010-exec-api.md b/specs/lazy-adr/adr-010-exec-api.md new file mode 100644 index 0000000000..4666339ce1 --- /dev/null +++ b/specs/lazy-adr/adr-010-exec-api.md @@ -0,0 +1,157 @@ +# ADR 10: Execution API + +## Changelog + +- 2025.01.13: Initial draft + +## Context + +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. + +## Alternative Approaches + +1. Maintain current state: keep ABCI interface and implement other VMs inside ABCI application. +2. Migrate to Engine API. +3. Create new API generic enough to handle any arbitrary VM. + +## Decision + +New generic Execution API is proposed. +It was designed to accommodate ABCI, Engine API, and any other VM / execution environment. + +## Detailed Design + +> This section does not need to be filled in at the start of the ADR, but must be completed prior to the merging of the implementation. +> +> Here are some common questions that get answered as part of the detailed design: +> +> - What are the user requirements? +> +> - What systems will be affected? +> +> - What new data structures are needed, what data structures will be changed? +> +> - What new APIs will be needed, what APIs will be changed? +> +> - What are the efficiency considerations (time/space)? +> +> - What are the expected access patterns (load/throughput)? +> +> - Are there any logging, monitoring or observability needs? +> +> - Are there any security considerations? +> +> - Are there any privacy considerations? +> +> - How will the changes be tested? +> +> - If the change is large, how will the changes be broken up for ease of review? +> +> - Will these changes require a breaking (major) release? +> +> - Does this change require coordination with the LazyLedger fork of the SDK or lazyledger-app? + +### API + +Execution API consist of 4 methods defined in [go-execution](https://github.com/rollkit/go-execution) repository. + +```go +// Executor defines a common interface for interacting with the execution client. +type Executor interface { + // InitChain initializes the blockchain with genesis information. + InitChain(ctx context.Context, genesisTime time.Time, initialHeight uint64, chainID string) (stateRoot types.Hash, maxBytes uint64, err error) + + // GetTxs retrieves all available transactions from the execution client's mempool. + GetTxs(ctx context.Context) ([]types.Tx, error) + + // ExecuteTxs executes a set of transactions to produce a new block header. + ExecuteTxs(ctx context.Context, txs []types.Tx, blockHeight uint64, timestamp time.Time, prevStateRoot types.Hash) (updatedStateRoot types.Hash, maxBytes uint64, err error) + + // SetFinal marks a block at the given height as final. + SetFinal(ctx context.Context, blockHeight uint64) error +} +``` + +### API Methods + +#### `InitChain` + +#### `GetTxs` + +#### `ExecuteTxs` + +#### `SetFinal` + +### Sequence Diagrams + +#### Block production +```mermaid +sequenceDiagram + participant D as DA layer + participant S as sequencer + participant R as Rollkit + participant E as exec-env + + R ->> +E: InitChain + E -->> -R: stateRoot, maxBytes + loop Every block time + R ->> +E: GetTxs + E -->> -R: txs + loop For each tx in txs + R ->> S: SubmitRollupTransaction + end + R ->> +S: GetNextBatch + S -->> -R: batch, time + R ->> +E: ExecuteTxs + E -->> -R: stateRoot, maxBytes + R ->> +D: Submit + D -->> -R: IDs + R ->> E: SetFinal + end +``` + +#### Block sync from P2P network or DA +```mermaid +sequenceDiagram + participant P as P2P network / DA + participant S as sequencer + participant R as Rollkit + participant E as exec-env + + R ->> +E: InitChain + E -->> -R: stateRoot, maxBytes + loop Every block time + P ->> R: next batch + R ->> +S: VerifyBatch + S -->> -R: success, error + R ->> +E: ExecuteTxs + E -->> -R: stateRoot, maxBytes + R ->> E: SetFinal + end +``` + +## Status + +Accepted + +## Consequences + +### Positive + +1. Simplification of rollkit's logic. +2. Better separation of concerns. +3. Removal of ABCI dependencies. + +### Negative + +1. More difficult deployment (another binary is needed). +2. Need to reimplement ABCI execution environment. + +### Neutral + +1. Need to introduce new API exposed by rollkit. + +## References + +- https://github.com/rollkit/rollkit/issues/1802 From 8d3d3d4ac990f09a447e93932ea9ccc69ea39188 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20Zdyba=C5=82?= Date: Wed, 15 Jan 2025 10:42:07 +0100 Subject: [PATCH 2/8] docs: execution API methods description --- .markdownlint.yaml | 3 +- specs/lazy-adr/adr-010-exec-api.md | 103 +++++++++++++++++++++++++++-- 2 files changed, 101 insertions(+), 5 deletions(-) diff --git a/.markdownlint.yaml b/.markdownlint.yaml index 6369b8d993..b2eaf6d838 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -3,4 +3,5 @@ MD010: code_blocks: false MD013: false MD024: - allow_different_nesting: true + siblings_only: true + diff --git a/specs/lazy-adr/adr-010-exec-api.md b/specs/lazy-adr/adr-010-exec-api.md index 4666339ce1..0a900c941a 100644 --- a/specs/lazy-adr/adr-010-exec-api.md +++ b/specs/lazy-adr/adr-010-exec-api.md @@ -73,19 +73,113 @@ type Executor interface { } ``` -### API Methods +### API Methods specification #### `InitChain` +##### Description + +Initializes the blockchain's state based on genesis information. This method is invoked at the beginning of the blockchain's lifecycle to prepare the execution environment for subsequent operations. + +##### Inputs + +- `ctx` (`context.Context`): Context for managing request timeouts and cancellations. +- `genesisTime` (`time.Time`): The initial timestamp of the rollup. +- `initialHeight` (`uint64`): The starting height of the rollup. +- `chainID` (`string`): A unique identifier of the rollup network. + +##### Outputs + +- `stateRoot` (`types.Hash`): The resulting state root after initializing the chain. +- `maxBytes` (`uint64`): Maximum block size in bytes, as defined by the genesis configuration. +- `err` (`error`): An error, if the initialization process fails. + +##### Expected Behavior + +- Initialize rollup according to the genesis. +- Generate an initial `stateRoot` representing the genesis state of the rollup. +- Return the maximum allowable block size (`maxBytes`). + #### `GetTxs` +##### Description + +Fetches all pending transactions from the execution client's mempool. +Transactions returned by execution client will be passed by rollkit to sequencer. + +##### Inputs + +- `ctx` (`context.Context`): Context for managing request timeouts and cancellations. + +##### Outputs + +- `txs` (`[]types.Tx`): Slice of transactions retrieved from the execution client's mempool; ordering doesn't matter. +- `err` (`error`): An error, if any, while retrieving transactions. + +##### Expected Behavior + +- 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. + #### `ExecuteTxs` +##### Description + +Executes a given set of transactions, updating the blockchain state. + +##### Inputs + +- `ctx` (`context.Context`): Context for managing request timeouts and cancellations. +- `txs` (`[]types.Tx`): A slice of transactions to be executed. +- `blockHeight` (`uint64`): The height of the block these transactions belong to. +- `timestamp` (`time.Time`): The block's timestamp. +- `prevStateRoot` (`types.Hash`): The state root of the rollup before applying the transactions. + +##### Outputs + +- `updatedStateRoot` (`types.Hash`): The resulting state root after applying the transactions. +- `maxBytes` (`uint64`): Maximum block size in bytes, as allowed for the block being produced. +- `err` (`error`): An error, if any, during the execution process. + +##### Expected Behavior + +- Validate and apply the provided transactions to the current blockchain state. +- Generate an updated `stateRoot` reflecting changes introduced by the transactions. +- 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. + #### `SetFinal` -### Sequence Diagrams +##### Description + +Marks a block at the specified height as final, guaranteeing immutability for consensus purposes. + +##### Inputs + +- `ctx` (`context.Context`): Context for managing request timeouts and cancellations. +- `blockHeight` (`uint64`): The height of the block to be finalized. + +##### Outputs + +- `err` (`error`): An error, if any, during the finalization process. + +##### Expected Behavior + +- 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. + +#### 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. + +### Sequence Diagrams #### Block production + ```mermaid sequenceDiagram participant D as DA layer @@ -112,6 +206,7 @@ sequenceDiagram ``` #### Block sync from P2P network or DA + ```mermaid sequenceDiagram participant P as P2P network / DA @@ -146,7 +241,7 @@ Accepted ### Negative 1. More difficult deployment (another binary is needed). -2. Need to reimplement ABCI execution environment. +2. Need to reimplement ABCI execution environment. ### Neutral @@ -154,4 +249,4 @@ Accepted ## References -- https://github.com/rollkit/rollkit/issues/1802 +- [Rollkit EPIC for Execution API](https://github.com/rollkit/rollkit/issues/1802) From 6a22a2329c8282edca06dfa8ad7382731fd32eb6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20Zdyba=C5=82?= Date: Wed, 15 Jan 2025 11:16:54 +0100 Subject: [PATCH 3/8] docs: ADR-010 - description of changes in rollkit --- specs/lazy-adr/adr-010-exec-api.md | 31 ++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/specs/lazy-adr/adr-010-exec-api.md b/specs/lazy-adr/adr-010-exec-api.md index 0a900c941a..8d3f58d0ea 100644 --- a/specs/lazy-adr/adr-010-exec-api.md +++ b/specs/lazy-adr/adr-010-exec-api.md @@ -226,6 +226,37 @@ 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. + ## Status Accepted From c4335a170671b44acad0a41f02e5b856bda7821d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20Zdyba=C5=82?= Date: Wed, 15 Jan 2025 11:38:38 +0100 Subject: [PATCH 4/8] docs: ADR-010 - more sections --- specs/lazy-adr/adr-010-exec-api.md | 42 +++++++++--------------------- 1 file changed, 12 insertions(+), 30 deletions(-) diff --git a/specs/lazy-adr/adr-010-exec-api.md b/specs/lazy-adr/adr-010-exec-api.md index 8d3f58d0ea..a7cd061c5e 100644 --- a/specs/lazy-adr/adr-010-exec-api.md +++ b/specs/lazy-adr/adr-010-exec-api.md @@ -22,36 +22,6 @@ It was designed to accommodate ABCI, Engine API, and any other VM / execution en ## Detailed Design -> This section does not need to be filled in at the start of the ADR, but must be completed prior to the merging of the implementation. -> -> Here are some common questions that get answered as part of the detailed design: -> -> - What are the user requirements? -> -> - What systems will be affected? -> -> - What new data structures are needed, what data structures will be changed? -> -> - What new APIs will be needed, what APIs will be changed? -> -> - What are the efficiency considerations (time/space)? -> -> - What are the expected access patterns (load/throughput)? -> -> - Are there any logging, monitoring or observability needs? -> -> - Are there any security considerations? -> -> - Are there any privacy considerations? -> -> - How will the changes be tested? -> -> - If the change is large, how will the changes be broken up for ease of review? -> -> - Will these changes require a breaking (major) release? -> -> - Does this change require coordination with the LazyLedger fork of the SDK or lazyledger-app? - ### API Execution API consist of 4 methods defined in [go-execution](https://github.com/rollkit/go-execution) repository. @@ -255,8 +225,20 @@ Removal of this logic from Rollkit enables further refactoring, for example remo 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 From c5cdc208ec75b3eff6f8b0308ae7157607f48005 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20Zdyba=C5=82?= Date: Wed, 15 Jan 2025 13:00:26 +0100 Subject: [PATCH 5/8] chore: remove empty lines from .markdownlint.yaml --- .markdownlint.yaml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.markdownlint.yaml b/.markdownlint.yaml index b2eaf6d838..c899638775 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -3,5 +3,4 @@ MD010: code_blocks: false MD013: false MD024: - siblings_only: true - + siblings_only: true \ No newline at end of file From 49ce4ac4d46dac8d1352796686fec4bcdd895007 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20Zdyba=C5=82?= Date: Tue, 4 Feb 2025 15:03:14 +0100 Subject: [PATCH 6/8] docs: add type definitions to adr-010 exec-api Included explanations for new abstract types `types.Hash` and `types.Tx` in the Execution API. --- specs/lazy-adr/adr-010-exec-api.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/specs/lazy-adr/adr-010-exec-api.md b/specs/lazy-adr/adr-010-exec-api.md index a7cd061c5e..7875ec1549 100644 --- a/specs/lazy-adr/adr-010-exec-api.md +++ b/specs/lazy-adr/adr-010-exec-api.md @@ -146,6 +146,15 @@ Marks a block at the specified height as final, guaranteeing immutability for co 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. +### Types + +The Execution API was designed to be highly generic. As a result, the types introduced in the API are intentionally abstract to ensure compatibility across various virtual machines and execution environments. + +1. `types.Hash` represents a cryptographic hash. To maintain generality, it is implemented as an alias for `[]byte`. +2. `types.Tx` represents a transaction in the most basic form. It is also defined as an alias for `[]byte`. + +This design choice ensures maximum flexibility and allows the API to remain independent of specific implementations or formats. It facilitates interoperability across different execution environments while keeping the API lightweight and adaptable. + ### Sequence Diagrams #### Block production From 6c9e530e4b0bb9d2dd667d31ac1f93f99db04dfe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20Zdyba=C5=82?= Date: Mon, 10 Feb 2025 11:55:50 +0100 Subject: [PATCH 7/8] chore: add newline at the end of .markdownlint.yaml --- .markdownlint.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.markdownlint.yaml b/.markdownlint.yaml index c899638775..15540d5ce9 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -3,4 +3,4 @@ MD010: code_blocks: false MD013: false MD024: - siblings_only: true \ No newline at end of file + siblings_only: true From 163eed11c78e3f1ebb4a0740e91e031b3f20c493 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20Zdyba=C5=82?= Date: Mon, 10 Feb 2025 11:58:17 +0100 Subject: [PATCH 8/8] docs: address review comments --- specs/lazy-adr/adr-010-exec-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/lazy-adr/adr-010-exec-api.md b/specs/lazy-adr/adr-010-exec-api.md index 7875ec1549..366ced4038 100644 --- a/specs/lazy-adr/adr-010-exec-api.md +++ b/specs/lazy-adr/adr-010-exec-api.md @@ -61,7 +61,7 @@ Initializes the blockchain's state based on genesis information. This method is ##### Outputs - `stateRoot` (`types.Hash`): The resulting state root after initializing the chain. -- `maxBytes` (`uint64`): Maximum block size in bytes, as defined by the genesis configuration. +- `maxBytes` (`uint64`): Maximum block size in bytes, as defined by the execution client's genesis configuration. - `err` (`error`): An error, if the initialization process fails. ##### Expected Behavior