diff --git a/.vitepress/config.ts b/.vitepress/config.ts index e8052b79b..57c3b3556 100644 --- a/.vitepress/config.ts +++ b/.vitepress/config.ts @@ -193,6 +193,26 @@ function sidebarHome() { items: [ { text: "Rollkit stack", link: "/learn/stack" }, { text: "Transaction flow", link: "/learn/transaction-flow" }, + { text: "Configuration", link: "/learn/config" }, + ], + }, + { + text: "Data Availability", + link: "/learn/data-availability", + }, + { + text: "Sequencing", + collapsed: true, + items: [ + { text: "Overview", link: "/learn/sequencing/overview" }, + { text: "Single", link: "/learn/sequencing/single" }, + ], + }, + { + text: "Execution", + collapsed: true, + items: [ + { text: "ABCI", link: "/learn/execution/abci" }, ], }, { @@ -218,41 +238,15 @@ function sidebarHome() { collapsed: true, items: [ { - text: "Overview", - link: "/guides/da/overview", - }, - { - text: "Local DA", + text: "Deploy A Local DA", link: "/guides/da/local-da", }, { - text: "Celestia", + text: "Connect to Celestia", link: "/guides/da/celestia-da", }, ], }, - { - text: "Sequencing", - collapsed: true, - items: [ - { - text: "Overview", - link: "/guides/sequencing/overview", - }, - { - text: "Single", - link: "/guides/sequencing/single", - }, - { - text: "Based", - link: "/guides/sequencing/based", - }, - { - text: "Forced Inclusion", - link: "/guides/sequencing/forced-inclusion", - }, - ], - }, { text: "Execution", collapsed: true, @@ -274,6 +268,20 @@ function sidebarHome() { }, ], }, + { + text: "EVM", + collapsed: true, + items: [ + { + text: "EVM Single Sequencer", + link: "/guides/evm/single", + }, + { + text: "EVM reth state backup", + link: "/guides/evm/reth-backup", + }, + ] + }, { text: "Run a Full Node", link: "/guides/full-node", @@ -294,22 +302,6 @@ function sidebarHome() { text: "Create genesis for your rollup", link: "/guides/create-genesis", }, - { - text: "Configuration", - link: "/guides/config", - }, - { - text: "EVM Single Sequencer", - link: "/guides/evm-single", - }, - { - text: "EVM Based Sequencer", - link: "/guides/evm-based", - }, - { - text: "EVM reth state backup", - link: "/guides/evm-reth-backup", - }, { text: "Metrics", link: "/guides/metrics", diff --git a/guides/da/overview.md b/guides/da/overview.md deleted file mode 100644 index 05566e6f8..000000000 --- a/guides/da/overview.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -description: This page provides an overview of how rollkit integrates with DA. ---- - - - -# DA - -Now that you have the foundations of running and building a rollup with Rollkit, it is time to start customizing it to fit your needs. - -The first choice you need to make is which data availability (DA) layer to use. The DA layer is a critical component of a blockchain, as it provides the data availability and finality guarantees that your chain needs to operate securely. - -Rollkit uses the [core da interface](https://github.com/rollkit/rollkit/blob/main/core/da/da.go#L11) to communicate to DA layers. Any DA layer that implements this interface can be used with Rollkit. - -## DA {#go-da} - -The [DA interface](https://github.com/rollkit/rollkit/blob/main/core/da/da.go#L11) defines the core functions required to interact with a DA layer. Probably the two most important functions being `Get` and `Submit`. - -```go -// DA defines very generic interface for interaction with Data Availability layers. -type DA interface { - // Get returns Blob for each given ID, or an error. - // - // Error should be returned if ID is not formatted properly, there is no Blob for given ID or any other client-level - // error occurred (dropped connection, timeout, etc). - Get(ctx context.Context, ids []ID, namespace []byte) ([]Blob, error) - - // GetIDs returns IDs of all Blobs located in DA at given height. - GetIDs(ctx context.Context, height uint64, namespace []byte) (*GetIDsResult, error) - - // GetProofs returns inclusion Proofs for Blobs specified by their IDs. - GetProofs(ctx context.Context, ids []ID, namespace []byte) ([]Proof, error) - - // Commit creates a Commitment for each given Blob. - Commit(ctx context.Context, blobs []Blob, namespace []byte) ([]Commitment, error) - - // Submit submits the Blobs to Data Availability layer. - // - // This method is synchronous. Upon successful submission to Data Availability layer, it returns the IDs identifying blobs - // in DA. - Submit(ctx context.Context, blobs []Blob, gasPrice float64, namespace []byte) ([]ID, error) - - // SubmitWithOptions submits the Blobs to Data Availability layer with additional options. - SubmitWithOptions(ctx context.Context, blobs []Blob, gasPrice float64, namespace []byte, options []byte) ([]ID, error) - - // Validate validates Commitments against the corresponding Proofs. This should be possible without retrieving the Blobs. - Validate(ctx context.Context, ids []ID, proofs []Proof, namespace []byte) ([]bool, error) - - // GasPrice returns the gas price for the DA layer. - GasPrice(ctx context.Context) (float64, error) - - // GasMultiplier returns the gas multiplier for the DA layer. - GasMultiplier(ctx context.Context) (float64, error) -} -``` - - DA layers can integrate the `DA` interface directly into their node like [Celestia DA](celestia-da.md). - -## Mock DA {#mock-da} - -You might have noticed that we did not define any DA layer during the [quick start](/guides/quick-start.md) or [build a chain](/guides/gm-world.md) tutorials. This is because we used a mock DA layer that is built into Rollkit. - -If you revisit the logs from those tutorials, you will see one of the first lines being: - -```shell -I[2024-11-15|14:09:41.735] Starting mock DA server module=main address=http://localhost:26658 -``` - -The mock DA layer is a simple in-memory DA layer that is great for testing and development. It is not suitable for production use, as it does not provide the data availability and finality guarantees that a real DA layer would. - -## DA Layers {#da-layers} - -Now that you have a better understanding of what a DA layer is, you can start to explore the different DA layers that are available to use with Rollkit. - -* [Local DA](/guides/da/local-da.md) -* [Celestia DA](/guides/da/celestia-da.md) diff --git a/guides/evm-based.md b/guides/evm-based.md deleted file mode 100644 index b9b230c2c..000000000 --- a/guides/evm-based.md +++ /dev/null @@ -1,182 +0,0 @@ -# Rollkit EVM Based Sequencer Setup Guide - -## Introduction - -This guide covers how to set up and run the Based Sequencer implementation of Rollkit EVM rollups. This implementation provides a DA-based approach to transaction sequencing while using EVM as the execution layer. - -## Prerequisites - -Before starting, ensure you have: - -- Go 1.20 or later -- Docker and Docker Compose -- Access to the go-execution-evm repository (op-geth branch) -- Git - -## Setting Up the Environment - -### 1. Clone the Rollkit Repository - -```bash -git clone https://github.com/rollkit/rollkit.git -cd rollkit -``` - -### 2. Build the Rollkit EVM Based Sequencer Implementation - -```bash -make build-evm-based -make build-da -``` - -This will create the following binaries in the `build` directory: - -- `evm-based` - Based sequencer implementation -- `local-da` - Local data availability node for testing - -## Setting Up the Data Availability (DA) Layer - -### Start the Local DA Node - -```bash -cd build -./local-da start -``` - -This will start a local DA node on the default port (26658). - -## Setting Up the EVM Layer - -### 1. Clone the go-execution-evm Repository - -```bash -git clone https://github.com/rollkit/go-execution-evm.git -cd go-execution-evm -git checkout op-geth -``` - -### 2. Start the EVM Layer Using Docker Compose - -```bash -docker compose up -d -``` - -This will start Reth (Rust Ethereum client) with the appropriate configuration for Rollkit. - -### 3. Note the JWT Secret Path - -The JWT secret is typically located at `go-execution-evm/docker/jwttoken/jwt.hex`. You'll need this path for the sequencer configuration. - -## Running the Based Sequencer Implementation - -### 1. Initialize the Sequencer - -```bash -cd build -./evm-based init --rollkit.node.aggregator=true --rollkit.signer.passphrase secret -``` - -### 2. Start the Sequencer - -```bash -./evm-based start \ - --evm.jwt-secret $(cat /path/to/go-execution-evm/docker/jwttoken/jwt.hex) \ - --evm.genesis-hash 0x0a962a0d163416829894c89cb604ae422323bcdf02d7ea08b94d68d3e026a380 \ - --rollkit.node.block_time 1s \ - --rollkit.node.aggregator=true \ - --rollkit.signer.passphrase secret \ - --based.url http://localhost:26658 \ - --based.namespace 0102030405060708090a \ - --based.start-height 0 \ - --based.max-height-drift 1 \ - --based.gas-multiplier 1.0 \ - --based.gas-price 1.0 -``` - -Replace `/path/to/` with the actual path to your go-execution-evm repository. - -## Setting Up a Full Node - -To run a full node alongside your sequencer, follow these steps: - -### 1. Initialize a New Node Directory - -```bash -./evm-based init --home ~/.rollkit/evm-based-fullnode -``` - -### 2. Copy the Genesis File - -Copy the genesis file from the sequencer node to the full node: - -```bash -cp ~/.rollkit/evm-based/config/genesis.json ~/.rollkit/evm-based-fullnode/config/ -``` - -### 3. Get the Sequencer's P2P Address - -Find the sequencer's P2P address in its logs. It will look similar to: - -```bash -INF listening on address=/ip4/127.0.0.1/tcp/26659/p2p/12D3KooWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -``` - -### 4. Start the Full Node - -```bash -./evm-based start \ - --home ~/.rollkit/evm-based-fullnode \ - --evm.jwt-secret $(cat /path/to/go-execution-evm/docker/jwttoken/jwt.hex) \ - --evm.genesis-hash 0x0a962a0d163416829894c89cb604ae422323bcdf02d7ea08b94d68d3e026a380 \ - --rollkit.node.block_time 1s \ - --rollkit.node.aggregator=false \ - --rollkit.p2p.peers @127.0.0.1:26659 \ - --based.url http://localhost:26658 \ - --based.namespace 0102030405060708090a -``` - -Replace `` with the actual P2P ID from your sequencer's logs. - -## Verifying Node Operation - -After starting your nodes, you should see logs indicating successful block processing: - -```bash -INF block marked as DA included blockHash=XXXX blockHeight=XX module=BlockManager -``` - -## Configuration Reference - -### Common Flags - -| Flag | Description | -|------|-------------| -| `--rollkit.node.aggregator` | Set to true for sequencer mode, false for full node | -| `--rollkit.signer.passphrase` | Passphrase for the signer | -| `--rollkit.node.block_time` | Block time for the Rollkit node | - -### EVM Flags - -| Flag | Description | -|------|-------------| -| `--evm.eth-url` | Ethereum JSON-RPC URL (default `http://localhost:8545`) | -| `--evm.engine-url` | Engine API URL (default `http://localhost:8551`) | -| `--evm.jwt-secret` | JWT secret file path for the Engine API | -| `--evm.genesis-hash` | Genesis block hash of the chain | -| `--evm.fee-recipient` | Address to receive priority fees | - -### Based Sequencer Flags - -| Flag | Description | -|------|-------------| -| `--based.url` | URL for DA endpoint (default `http://localhost:26658`) | -| `--based.auth` | Auth token for based DA layer | -| `--based.namespace` | Hex-encoded namespace ID for submitting rollup transactions | -| `--based.start-height` | Starting DA height for fetching transactions (default `0`) | -| `--based.max-height-drift` | Max number of DA heights to look ahead during batching (default `1`) | -| `--based.gas-multiplier` | Gas multiplier to apply on DA submission (default `1.0`) | -| `--based.gas-price` | Base gas price to use during DA submission (default `1.0`) | - -## Conclusion - -You've now set up and configured the Based Sequencer implementation of Rollkit EVM rollups. This implementation provides a DA-based approach to transaction sequencing while using EVM as the execution layer. diff --git a/guides/evm-reth-backup.md b/guides/evm/reth-backup.md similarity index 100% rename from guides/evm-reth-backup.md rename to guides/evm/reth-backup.md diff --git a/guides/evm-single.md b/guides/evm/single.md similarity index 100% rename from guides/evm-single.md rename to guides/evm/single.md diff --git a/guides/sequencing/based.md b/guides/sequencing/based.md deleted file mode 100644 index 9fcbf573a..000000000 --- a/guides/sequencing/based.md +++ /dev/null @@ -1,3 +0,0 @@ -# Based Sequencing - -Coming soon ... diff --git a/guides/sequencing/forced-inclusion.md b/guides/sequencing/forced-inclusion.md deleted file mode 100644 index baae98546..000000000 --- a/guides/sequencing/forced-inclusion.md +++ /dev/null @@ -1,3 +0,0 @@ -# Forced Inclusion - -Coming soon ... diff --git a/guides/sequencing/single.md b/guides/sequencing/single.md deleted file mode 100644 index 36ab13a10..000000000 --- a/guides/sequencing/single.md +++ /dev/null @@ -1 +0,0 @@ -# Single Sequencer diff --git a/learn/data-availability.md b/learn/data-availability.md new file mode 100644 index 000000000..8ad8e011c --- /dev/null +++ b/learn/data-availability.md @@ -0,0 +1,39 @@ +# Data Availability in Rollkit + +Data availability (DA) is a core of Rollkit's. Rollkit utilize's data availability ensures that all transaction data and block information required to verify the rollup's state is accessible to anyone running a node or light client. + +Learn more about data availability: + +- [What is DA](https://celestia.org/what-is-da/) +- [The importance of DA for Rollups](https://medium.com/zeeve/exploring-data-availability-layer-and-its-importance-in-rollups-0a4fbf2e0ffc) + +## How Rollkit Handles Data Availability + +Rollkit is designed to be DA-agnostic, meaning it can integrate with different data availability layers depending on your needs. The main options are: + +- **Local Data Availability (Local DA):** + - Used for development, testing, and local deployments. + - Not secure for production, as data can be withheld by the node operator. + +- **External Data Availability Layer (DA Interface):** + - Used for production and secure deployments. + - Rollkit can post block data to any external DA layer that implements the Rollkit [DA interface](https://github.com/rollkit/rollkit/blob/main/core/da/da.go#L11) (e.g., Celestia). + - Anyone can verify that the data is available and reconstruct the rollup state, depending on the guarantees of the chosen DA layer. + +## Why Data Availability Matters in Rollkit + +- **Fraud Proofs and Security:** + - Rollkit rollups rely on data availability to enable fraud proofs and ensure that invalid state transitions can be challenged. + - If data is unavailable, users cannot verify the rollup's state or submit fraud proofs. + +## Best Practices + +- **Use Local DA only for development and testing locally.** +- **Alternatively, you can use [Celestia testnets](https://docs.celestia.org/how-to-guides/participate).** +- **For production, always use a decentralized DA layer that implements the Rollkit DA interface.** + +## Learn More + +- [Set up a local DA](/guides/da/local-da.md) +- [Set up Celestia DA](/guides/da/celestia-da.md) +- [Celestia Docs](https://docs.celestia.org/) diff --git a/learn/execution/abci.md b/learn/execution/abci.md new file mode 100644 index 000000000..43754ea97 --- /dev/null +++ b/learn/execution/abci.md @@ -0,0 +1,31 @@ +# ABCI-Compatible Execution Layers in Rollkit + +Rollkit is designed to be modular and flexible, allowing different execution layers to be plugged in via the ABCI (Application Blockchain Interface) protocol. Rollkit defines a general-purpose execution interface ([see execution.go](https://github.com/rollkit/rollkit/blob/main/core/execution/execution.go)) that enables developers to integrate any ABCI-compatible application as the rollup's execution layer. + +This means you can use a variety of ABCI-compatible applications as the execution environment for your rollup. + +## Supported Execution Layers + +### Cosmos SDK App +A Cosmos SDK-based application can serve as the execution layer for a Rollkit rollup. This allows you to leverage the rich ecosystem and features of the Cosmos SDK, including modules for staking, governance, IBC, and more. + +- [Cosmos SDK Documentation](https://docs.cosmos.network/) + +### CosmWasm +CosmWasm is a smart contract platform built for the Cosmos ecosystem. It is ABCI-compatible and can be integrated as the execution layer in Rollkit, enabling your rollup to support WebAssembly (Wasm) smart contracts. + +- [CosmWasm Documentation](https://docs.cosmwasm.com/) + +## How It Works + +- Rollkit acts as the consensus and data availability layer. +- The execution layer (Cosmos SDK app or CosmWasm) processes transactions and maintains application state. +- Communication between Rollkit and the execution layer happens via the ABCI protocol. + +## Benefits + +- **Modularity:** Choose the execution environment that best fits your use case. +- **Interoperability:** Leverage existing Cosmos SDK modules or deploy CosmWasm smart contracts. +- **Extensibility:** Easily upgrade or swap out the execution layer as your rollup evolves. + +For more details on integrating an execution layer with Rollkit, see the respective documentation links above. diff --git a/guides/sequencing/overview.md b/learn/sequencing/overview.md similarity index 62% rename from guides/sequencing/overview.md rename to learn/sequencing/overview.md index c724aafbe..f8b60b285 100644 --- a/guides/sequencing/overview.md +++ b/learn/sequencing/overview.md @@ -22,9 +22,7 @@ It mainly consists of: ## Sequencing Implementations {#sequencing-implementations} -An implementation of the sequencing interface mainly acts as a middleware that connects Rollkit rollup and the sequencing layer. It implements the sequencing interface functions described above. For example, [single-sequencer](https://github.com/rollkit/rollkit/blob/main/sequencers/single/README.md) is the refactored functionality from the Rollkit prior to `v1.0.0`. The single sequencer is the middleware run by the aggregator node of the Rollkit rollup. The aggregator node relays rollup transactions to single sequencer which then submits them to the DA network (Celestia). The header producer node then retrieves (via `GetNextBatch`) the batched transaction from the single sequencer to execute the transactions and produce the updated rollup state. Similarly, there are other sequencing middlewares which can be built for various sequencing strategies or even for connecting to different third-party sequencing networks. +An implementation of the sequencing interface mainly acts as a middleware that connects Rollkit rollup and the sequencing layer. It implements the sequencing interface functions described above. +There are several implementations of the sequencer but for now only one is available in Rollkit. -The sequencing implementations that are currently work in progress: - -* [based-sequencer](/guides/sequencing/based.md) -* [forced-inclusion-sequencer](/guides/sequencing/forced-inclusion.md) +* [single-sequencer](/learn/sequencing/single.md) - The simplest and most widely used sequencing model, where a single node (the sequencer) is responsible for ordering transactions and producing blocks. diff --git a/learn/sequencing/single.md b/learn/sequencing/single.md new file mode 100644 index 000000000..a0d93810f --- /dev/null +++ b/learn/sequencing/single.md @@ -0,0 +1,32 @@ +# Single Sequencer + +A single sequencer is the simplest sequencing architecture for a Rollkit-based rollup. In this model, one node (the sequencer) is responsible for ordering transactions, producing blocks, and submitting data to the data availability (DA) layer. + +## How the Single Sequencer Model Works + +1. **Transaction Submission:** + - Users submit transactions directly to the sequencer node via RPC or other interfaces. +2. **Transaction Ordering:** + - The sequencer collects transactions from users and orders them into blocks according to the rollup's rules. +3. **Block Production:** + - The sequencer produces new blocks at regular intervals or when enough transactions are collected. + - Each block contains a batch of ordered transactions and metadata. + +4. **Data Availability Posting:** + - The sequencer posts the block data to the configured DA layer (e.g., Celestia, Avail, etc.). + - This ensures that anyone can access the data needed to reconstruct the rollup state. + +5. **State Update:** + - The sequencer updates the rollup state based on the new block and makes the updated state available to light clients and full nodes. + +## Advantages + +- **Simplicity:** Easy to set up and operate, making it ideal for development, testing, and small-scale deployments. +- **Low Latency:** Fast block production and transaction inclusion, since there is no consensus overhead among multiple sequencers. + +## Use Cases + +- Production rollups seeking simplicity and performance +- Prototyping and development +- Private or permissioned rollups +- Projects that value deterministic ordering and operational control