diff --git a/.vitepress/config.ts b/.vitepress/config.ts index 276fba0fa..3c88390a4 100644 --- a/.vitepress/config.ts +++ b/.vitepress/config.ts @@ -257,11 +257,15 @@ function sidebarHome() { items: [ { text: "Overview", - link: "/guides/deploy-overview", + link: "/guides/deploy/overview", }, { - text: "Docker Compose", - link: "/guides/docker-compose", + text: "Local (dev)", + link: "/guides/deploy/local", + }, + { + text: "Testnet", + link: "/guides/deploy/testnet", }, ], }, diff --git a/guides/deploy-overview.md b/guides/deploy-overview.md index ea16c8a48..4e4f54421 100644 --- a/guides/deploy-overview.md +++ b/guides/deploy-overview.md @@ -16,4 +16,4 @@ In this section, you'll see a few examples of how you can deploy your rollup env These examples are for educational purposes only. Before deploying your rollup for production use you should fully understand the services you are deploying and your choice in deployment method. ::: -* [Deploy with Docker Compose](/guides/docker-compose.md) +* [Deploy with Docker Compose](/guides/deploy/local.md) diff --git a/guides/docker-compose.md b/guides/deploy/local.md similarity index 95% rename from guides/docker-compose.md rename to guides/deploy/local.md index 2baf4b7c2..a7008d784 100644 --- a/guides/docker-compose.md +++ b/guides/deploy/local.md @@ -1,4 +1,4 @@ -# 🐳 Docker Compose +# 🏠 Local This tutorial is going to show you how to deploy the [gm-world chain](/guides/gm-world.md) using Docker Compose. @@ -6,8 +6,8 @@ You can learn more about Docker Compose [here](https://docs.docker.com/compose/) :::tip @@ -61,7 +61,7 @@ RUN apt update && \ ca-certificates \ curl -RUN curl -sSL https://rollkit.dev/install.sh | bash +RUN curl -sSL https://rollkit.dev/install.sh | bash # Install rollkit # Install ignite @@ -71,8 +71,8 @@ RUN curl https://get.ignite.com/cli! | bash WORKDIR /app # cache dependencies. -COPY ./go.mod . -COPY ./go.sum . +COPY ./go.mod . +COPY ./go.sum . RUN go mod download # Copy all files from the current directory to the container @@ -80,8 +80,8 @@ COPY . . # Build the chain RUN ignite app install -g github.com/ignite/apps/rollkit -RUN ignite chain build -y -RUN ignite rollkit init +RUN ignite chain build -y +RUN ignite rollkit init # Stage 2: Set up the runtime environment FROM debian:bookworm-slim diff --git a/guides/deploy/overview.md b/guides/deploy/overview.md new file mode 100644 index 000000000..aee4dc3dc --- /dev/null +++ b/guides/deploy/overview.md @@ -0,0 +1,47 @@ +--- +description: This page provides an overview of some common ways to deploy rollups. +--- + +# 🚀 Deploying Your Rollup + +One of the benefits of building rollups with Rollkit is the flexibility you have as a developer to choose things like the DA layer, the settlement scheme, and the execution environment. + +You can learn more about Rollkit architecture [here](/learn/specs/overview.md). + +The challenge that comes with this flexibility is that there are more services that now need to be deployed and managed while running your rollup. + +In the tutorials so far, you've seen various helper scripts used to make things easier. While great for tutorials, there are better ways to deploy and manage rollups than using various bash scripts. + +## 🏗️ Deployment Scales + +Depending on your needs and the stage of your rollup development, there are different deployment approaches you can take: + +### 🏠 Local Development +For development and testing purposes, you can deploy your rollup locally using containerized environments. This approach provides: +- Quick iteration and testing +- No external dependencies +- Full control over the environment +- Cost-effective development + +### 🌐 Testnet Deployment +When you're ready to test with real network conditions, you can deploy to testnet environments. This includes: +- Integration with testnet DA networks +- Real network latency and conditions +- Multi-node testing scenarios +- Pre-production validation + + +## 📚 Available Deployment Guides + +Choose the deployment approach that matches your current needs: + +* [🏠 Local Development with Docker Compose](./local.md) - Deploy locally for development and testing +* [🌐 Testnet Deployment](./testnet.md) - Deploy on testnet with external DA networks + +:::warning Disclaimer +These examples are for educational purposes only. Before deploying your rollup for production use you should fully understand the services you are deploying and your choice in deployment method. +::: + +## 🎉 Next Steps + +For production mainnet deployments, consider additional requirements such as monitoring, security audits, infrastructure hardening, and operational procedures that go beyond the scope of these tutorials. diff --git a/guides/deploy/testnet.md b/guides/deploy/testnet.md new file mode 100644 index 000000000..6eee67055 --- /dev/null +++ b/guides/deploy/testnet.md @@ -0,0 +1,288 @@ +# 🚀 Rollkit EVM Deployment Guide + +This tutorial is going to show you how to deploy a Rollkit testnet, focusing on the architecture choices and components that make up a complete EVM-based chain deployment. + +You can learn more about Rollkit EVM architecture [here](/learn/execution.md). + + + + +:::tip + +::: + + +## 🏗️ Architecture Overview + +The following diagram illustrates the complete deployment architecture with component interactions: + +```mermaid +graph TB + subgraph "Sequencer Stack" + SEQ_RETH[RETH Service] + SEQ_ROLLKIT[ROLLKIT Service
--aggregator=true] + SEQ_RETH <--> SEQ_ROLLKIT + end + + subgraph "Full Node Stack 1" + FN1_RETH[RETH Service] + FN1_ROLLKIT[ROLLKIT Service
--aggregator=false] + FN1_RETH <--> FN1_ROLLKIT + end + + subgraph "Full Node Stack 2" + FN2_RETH[RETH Service] + FN2_ROLLKIT[ROLLKIT Service
--aggregator=false] + FN2_RETH <--> FN2_ROLLKIT + end + + subgraph "Full Node Stack 3" + FN3_RETH[RETH Service] + FN3_ROLLKIT[ROLLKIT Service
--aggregator=false] + FN3_RETH <--> FN3_ROLLKIT + end + + subgraph "Celestia DA Stack" + CELESTIA_APP[Celestia-App
Consensus Layer] + CELESTIA_NODE[Celestia-Node
DA Sampling & API] + CELESTIA_APP <--> CELESTIA_NODE + end + + %% P2P connections between Rollkit nodes + SEQ_ROLLKIT <--> FN1_ROLLKIT + SEQ_ROLLKIT <--> FN2_ROLLKIT + SEQ_ROLLKIT <--> FN3_ROLLKIT + FN1_ROLLKIT <--> FN2_ROLLKIT + FN2_ROLLKIT <--> FN3_ROLLKIT + FN1_ROLLKIT <--> FN3_ROLLKIT + + %% DA connections + SEQ_ROLLKIT -->|Post Blobs
Auth Token| CELESTIA_NODE + FN1_ROLLKIT -->|Retrieve Blobs
Auth Token| CELESTIA_NODE + FN2_ROLLKIT -->|Retrieve Blobs
Auth Token| CELESTIA_NODE + FN3_ROLLKIT -->|Retrieve Blobs
Auth Token| CELESTIA_NODE + + %% User interactions + USERS[Users/Applications] --> FN1_RETH + USERS --> FN2_RETH + USERS --> FN3_RETH + + classDef sequencer fill:#e1f5fe + classDef fullnode fill:#f3e5f5 + classDef celestia fill:#fff3e0 + classDef user fill:#e8f5e8 + + class SEQ_RETH,SEQ_ROLLKIT sequencer + class FN1_RETH,FN1_ROLLKIT,FN2_RETH,FN2_ROLLKIT,FN3_RETH,FN3_ROLLKIT fullnode + class CELESTIA_APP,CELESTIA_NODE celestia + class USERS user +``` + +**Key Interactions:** +- **Engine API**: RETH ↔ ROLLKIT communication within each stack +- **P2P Network**: ROLLKIT nodes sync blocks and share chain state +- **Data Availability**: Sequencer posts blobs, full nodes retrieve blobs from Celestia +- **User Access**: Applications connect to full node RETH services for JSON-RPC access + +## 💻 Pre-requisites {#prerequisites} + +Make sure you understand the sequencing topology you want to use by reading the [Sequencing Overview](/learn/sequencing/overview.md). + +## 🛠️ Dependencies {#dependencies} + +### 🔄 Choosing Your Sequencing Topology {#choosing-sequencing-topology} + +First, you need to choose a sequencing topology for your Rollkit EVM chain. The sequencing topology determines how transactions are ordered and blocks are produced in your chain. + +Currently, Rollkit supports one sequencing implementation: + +### 🔄 Single Sequencer +- **Description**: The simplest sequencing architecture where one node is responsible for ordering transactions and producing blocks +- **Use Cases**: Development, testing, and production deployments requiring simplicity and low latency +- **Advantages**: Easy setup, fast block production, independence from DA block time +- **Requirements**: One sequencer node, multiple optional full nodes + +For detailed information about sequencing topologies, see the [Sequencing Overview](/learn/sequencing/overview.md) and [Single Sequencer](/learn/sequencing/single.md) documentation. + +## 🏗️ Deployment Architecture {#deployment-architecture} + +### 🔄 Single Sequencer Topology + +In a single sequencer deployment, you will run: + +1. **One Sequencer Node** (Required) + - Handles transaction ordering and block production + - Posts data to the Data Availability layer + - Serves as the primary source of truth for the chain + +2. **Multiple Full Nodes** (Optional, but recommended) + - Sync blocks from the sequencer + - Provide redundancy and decentralization + - Can serve user queries and transactions + - Scale horizontally based on demand + +## 🛠️ Setting up your environment {#setting-up-your-environment} + +In addition to choosing your sequencing topology, we need to understand the components that make up your deployment. + +We will use a combination of RETH and ROLLKIT services for this tutorial and run them together to create your EVM chain. + +Each node in your Rollkit EVM deployment (whether sequencer or full node) consists of two primary services working together: + +### ⚡ RETH Service +- **Purpose**: Provides the Ethereum Virtual Machine (EVM) execution environment +- **Technology**: Rust-based Ethereum client (Reth) that handles transaction execution +- **Responsibilities**: + - Processing EVM transactions + - Maintaining the EVM state + - Providing Ethereum JSON-RPC API endpoints + - Managing the execution layer consensus + +### 🔗 ROLLKIT Service +- **Purpose**: Handles chain-specific functionality and consensus +- **Technology**: Rollkit node implementation +- **Responsibilities**: + - Block production and validation + - Data availability integration + - P2P networking between chain nodes + - Chain consensus mechanisms + - Communication with the execution layer (RETH) + +### 🔄 Service Interaction + +The two services work together through well-defined interfaces: + +1. **Engine API**: Rollkit communicates with RETH using the Engine API (typically on port 8551) +2. **JWT Authentication**: Secure communication between services using shared JWT secrets +3. **Block Coordination**: Rollkit orchestrates block production while RETH executes transactions + +## ⚙️ Node Configurations {#node-configurations} + +### 🎯 Sequencer Node Configuration +The single sequencer node runs both RETH and ROLLKIT services with specific settings: +- **RETH**: Configured to accept blocks from the Rollkit sequencer +- **ROLLKIT**: Configured with `--rollkit.node.aggregator=true` to enable block production +- **Role**: Produces blocks, orders transactions, posts to DA layer + +### 📡 Full Node Configuration +Each full node also runs both RETH and ROLLKIT services but in sync mode: +- **RETH**: Configured to process blocks received from the network +- **ROLLKIT**: Configured with `--rollkit.node.aggregator=false` to sync from the sequencer +- **Role**: Syncs blocks, serves queries, provides redundancy + +### 🔑 Key Integration Points + +All nodes require: +- Shared JWT secret for Engine API authentication +- Matching genesis configuration between ROLLKIT nodes +- Proper network configuration for service communication +- Coordinated startup sequence (typically RETH first, then ROLLKIT) + +### ⏰ Block Time Configuration + +You can customize timing parameters for your chain. While there are many configuration arguments available for the Rollkit binary, two important timing-related flags are: + +#### 🎯 Sequencer Block Time +- **Flag**: `--rollkit.node.block_time` +- **Default**: 1s (1 block per second) +- **Purpose**: Controls how frequently the sequencer produces new blocks +- **Customization**: Can be adjusted based on throughput requirements and latency preferences + +#### 📊 Data Availability Block Time +- **Flag**: `--rollkit.da.block_time` +- **Default**: 6s +- **Purpose**: Controls how frequently blobs are posted to the Celestia chain +- **Function**: Each 6 seconds (by default), batched block data is submitted to Celestia for data availability + +## 🌌 Data Availability Layer: Celestia {#celestia-da} + +Your Rollkit EVM chain connects to Celestia as the Data Availability (DA) layer. The Rollkit EVM Celestia DA stack consists of two key services: + +### 🏛️ Celestia-App Service +- **Purpose**: Provides the consensus layer for the Celestia network +- **Responsibilities**: + - Processing and ordering transactions on the Celestia network + - Maintaining the canonical state of the DA layer + - Participating in Tendermint consensus + +### 🌐 Celestia-Node Service +- **Purpose**: Provides data availability sampling and networking +- **Responsibilities**: + - Data availability sampling (DAS) to verify data availability + - P2P networking for block and data propagation + - Light client functionality for resource-constrained environments + - API endpoints for chains to submit and retrieve data + +### 🔗 Celestia Integration + +Both sequencer and full node Rollkit services need to communicate with the celestia-node service, but for different purposes: + +#### 📤 Sequencer Node Communication +- **Purpose**: Batch posting of block data (blobs) to Celestia +- **Operation**: The sequencer Rollkit service submits batched block data to Celestia via the celestia-node API +- **Frequency**: Occurs regularly as new blocks are produced and need to be made available + +#### 📥 Full Node Communication +- **Purpose**: Retrieving block data (blobs) from Celestia +- **Operation**: Full node Rollkit services query and download historical block data via the celestia-node API +- **Frequency**: Occurs during initial sync and ongoing block validation + +#### 🔑 Common Integration Points +1. **Authentication**: Rollkit requires an auth token generated by the celestia-node so that Rollkit can send transactions on its behalf. Both sequencer and full node types use these JWT tokens for secure communication with celestia-node +2. **Namespace Isolation**: Data is organized using Celestia namespaces +3. **API Endpoints**: Both sequencer and full nodes use the same celestia-node API interface +4. **Network Configuration**: All nodes must be configured to connect to the same Celestia network + +### 🛠️ Deployment Considerations + +When deploying with Celestia DA: +- **Light Node**: Most chains run a celestia-node in light mode for cost efficiency +- **Network Selection**: Choose between Arabica (devnet), Mocha (testnet), or Mainnet Beta +- **Funding**: Ensure your celestia-node wallet has sufficient TIA tokens for data submission + +We now have all we need to understand the components for deploying a Rollkit EVM chain. + +### 🚀 Run your Rollkit EVM chain {#run-rollkit-evm-chain} + +A complete Rollkit EVM chain deployment consists of: + +1. **One Sequencer Node**: RETH + ROLLKIT (aggregator mode) +2. **N Full Nodes**: RETH + ROLLKIT (sync mode) - scale as needed +3. **Celestia Connection**: celestia-node service for data availability + +You can deploy your chain by running the sequencer and full nodes with the proper configuration. + +Congratulations! You have successfully understood how to deploy a Rollkit EVM chain. + +## 🐳 Simplified Deployment with Docker Compose {#docker-compose-deployment} + +The deployment of sequencer and full nodes requires running multiple processes and providing specific variables so they can effectively interact with each other. Managing these configurations manually can be complex and error-prone, especially when coordinating JWT secrets, genesis configurations, network settings, and service dependencies across multiple node stacks. + +To save time, we can use ready-to-use Docker Compose stacks that can be customized based on specific needs. These pre-configured stacks handle the complexity of service orchestration, environment variable management, and inter-service communication automatically. + +To make this deployment process easy and painless for node operators, you can use the example implementation available at: [https://github.com/rollkit/ops-toolbox/tree/main/ev-stacks](https://github.com/rollkit/ops-toolbox/tree/main/ev-stacks/) + +This solution provides: +- Pre-configured Docker Compose files for sequencer and full node deployments +- Automated handling of JWT secrets and genesis file distribution +- Simplified configuration through environment variables +- Easy scaling of full node instances +- Integrated Celestia node configuration + +:::warning +This deployment approach is suitable for testnets and development environments, but is not suitable for production-grade mainnet deployments, which require additional security considerations, monitoring, backup strategies, and infrastructure hardening. +::: + +## 🎉 Next steps + +Congratulations again! You now know how to deploy Rollkit EVM chains and understand the architecture and components needed. + +For detailed setup instructions, see: +- [Single Sequencer Setup Guide](/guides/evm/single.md) - Step-by-step deployment instructions +- [RETH Backup Guide](/guides/evm/reth-backup.md) - Data protection and backup procedures +- [Celestia DA Guide](/guides/da/celestia-da.md) - Connecting to Celestia networks + +You can also learn more about local deployments in our [Docker Compose guide](/guides/deploy/local.md).