From 8c23cbc83d6336bf11f20ee4247577142d5cb46e Mon Sep 17 00:00:00 2001 From: Matthew Sevey <15232757+MSevey@users.noreply.github.com> Date: Fri, 15 Nov 2024 16:07:47 -0500 Subject: [PATCH] feat: update sequencing section to include local sequencer and steps to connect sequencers with rollups --- .vitepress/config.ts | 14 ++- .vitepress/constants/constants.js | 1 + tutorials/astria.md | 3 - tutorials/based.md | 3 - tutorials/centralized.md | 39 ------ tutorials/sequencing/astria.md | 5 + tutorials/sequencing/based.md | 5 + tutorials/sequencing/centralized.md | 118 ++++++++++++++++++ .../forced-inclusion.md} | 0 tutorials/sequencing/local.md | 66 ++++++++++ .../{sequencing.md => sequencing/overview.md} | 27 +++- 11 files changed, 225 insertions(+), 56 deletions(-) delete mode 100644 tutorials/astria.md delete mode 100644 tutorials/based.md delete mode 100644 tutorials/centralized.md create mode 100644 tutorials/sequencing/astria.md create mode 100644 tutorials/sequencing/based.md create mode 100644 tutorials/sequencing/centralized.md rename tutorials/{forced.md => sequencing/forced-inclusion.md} (100%) create mode 100644 tutorials/sequencing/local.md rename tutorials/{sequencing.md => sequencing/overview.md} (69%) diff --git a/.vitepress/config.ts b/.vitepress/config.ts index 39bc9dfc4..b977e3b79 100644 --- a/.vitepress/config.ts +++ b/.vitepress/config.ts @@ -239,23 +239,27 @@ function sidebarHome() { items: [ { text: "Overview", - link: "/tutorials/sequencing", + link: "/tutorials/sequencing/overview", + }, + { + text: "Local", + link: "/tutorials/sequencing/local", }, { text: "Centralized", - link: "/tutorials/centralized", + link: "/tutorials/sequencing/centralized", }, { text: "Based", - link: "/tutorials/based", + link: "/tutorials/sequencing/based", }, { text: "Forced Inclusion", - link: "/tutorials/forced", + link: "/tutorials/sequencing/forced-inclusion", }, { text: "Astria", - link: "/tutorials/astria", + link: "/tutorials/sequencing/astria", }, ], }, diff --git a/.vitepress/constants/constants.js b/.vitepress/constants/constants.js index da60e0ca0..9741cf5c5 100644 --- a/.vitepress/constants/constants.js +++ b/.vitepress/constants/constants.js @@ -11,6 +11,7 @@ const constants = Object.freeze({ localDALatestTag: "v0.3.1", goSequencingLatestTag: "v0.4.1", + centralizedSequencerLatestTag: "v0.4.0", igniteVersionTag: "v28.5.3", }); export default constants; diff --git a/tutorials/astria.md b/tutorials/astria.md deleted file mode 100644 index 37d894216..000000000 --- a/tutorials/astria.md +++ /dev/null @@ -1,3 +0,0 @@ -# Astria Sequencing - -Coming soon ... \ No newline at end of file diff --git a/tutorials/based.md b/tutorials/based.md deleted file mode 100644 index 93e3c250f..000000000 --- a/tutorials/based.md +++ /dev/null @@ -1,3 +0,0 @@ -# Based Sequencing - -Coming soon ... \ No newline at end of file diff --git a/tutorials/centralized.md b/tutorials/centralized.md deleted file mode 100644 index eeb3909d6..000000000 --- a/tutorials/centralized.md +++ /dev/null @@ -1,39 +0,0 @@ -# Centralized Sequencer - -A centralized sequencer is a sequencing middleware that receives rollup transactions and provides a local sequencing capabilities. Meaning, the transactions are ordered in the order they are received by the sequencer without any censorship. Further, the sequenced batches are made available in the DA network (such as Celestia). Under the hood, the centralized sequencer is a GRPC server that implements `go-sequencing` interface and the server is hosted by the same node that is running the aggregator for the Rollkit rollup. - -![Rollkit with Centralized Sequencer](/public/img/sequencing.jpg) - -### Installation and Use - -```sh -git clone https://github.com/rollkit/centralized-sequencer.git -cd centralized-sequencer -make build -./build/centralized-sequencer -h -``` - - -```sh -Usage: - -host string - centralized sequencer host (default "localhost") - -port string - centralized sequencer port (default "50051") - -listen-all - listen on all network interfaces (0.0.0.0) instead of just localhost - -rollup-id string - rollup id (default "rollupId") - -batch-time duration - time in seconds to wait before generating a new batch (default 2s) - -da_address string - DA address (default "http://localhost:26658") - -da_auth_token string - auth token for the DA - -da_namespace string - DA namespace where the sequencer submits transactions - -db_path string - path to the database -``` - -As shown by the help command, a centralized sequencer is configured to serve a rollup (via `rollup_id`). The DA network to persist the sequenced batches are specified using `da_address`, `da_auth_token` and `da_namespace`. \ No newline at end of file diff --git a/tutorials/sequencing/astria.md b/tutorials/sequencing/astria.md new file mode 100644 index 000000000..b3113c848 --- /dev/null +++ b/tutorials/sequencing/astria.md @@ -0,0 +1,5 @@ +# Astria Sequencing + +Coming soon ... + +Track progress on the [GitHub](https://github.com/rollkit/astria-sequencer) diff --git a/tutorials/sequencing/based.md b/tutorials/sequencing/based.md new file mode 100644 index 000000000..4de32946c --- /dev/null +++ b/tutorials/sequencing/based.md @@ -0,0 +1,5 @@ +# Based Sequencing + +Coming soon ... + +Track progress on the [GitHub](https://github.com/rollkit/based-sequencer) diff --git a/tutorials/sequencing/centralized.md b/tutorials/sequencing/centralized.md new file mode 100644 index 000000000..15430f8da --- /dev/null +++ b/tutorials/sequencing/centralized.md @@ -0,0 +1,118 @@ +# Centralized Sequencer + + + + +A centralized sequencer is a sequencing middleware that receives rollup transactions and provides a local sequencing capabilities. Meaning, the transactions are ordered in the order they are received by the sequencer without any censorship. Further, the sequenced batches are made available in the DA network (such as Celestia). Under the hood, the centralized sequencer is a GRPC server that implements `go-sequencing` interface and the server is hosted by the same node that is running the aggregator for the Rollkit rollup. + +![Rollkit with Centralized Sequencer](/public/img/sequencing.jpg) + +## Prerequisites {#prerequisites} + +This tutorial serves as a comprehensive guide for using the [centralized-sequencer](https://github.com/rollkit/centralized-sequencer) with your chain. + +Before proceeding, ensure that you have completed the [quick start](/tutorials/quick-start) or [build a chain](/tutorials/wordle) tutorial, which covers installing the rollkit CLI, building your chain, and running your chain. + +:::tip +It is important to note that the centralized sequencer expects a DA layer to be running when it starts. This means that you need to launch your DA Layer before starting the centralized sequencer. +::: + +Additionally, you should have completed one of the [DA Layer tutorials](../da/overview) and have your DA layer ready to use with the centralized sequencer. This tutorial will use the [local-da layer](../da/local) as an example. + +## Installation the Centralized Sequencer {#installation-centralized-sequencer} + +```sh-vue +git clone --depth 1 --branch {{constants.centralizedSequencerLatestTag}} https://github.com/rollkit/centralized-sequencer.git +cd centralized-sequencer +make build +./build/centralized-sequencer -h +``` + +```sh +Usage: + -host string + centralized sequencer host (default "localhost") + -port string + centralized sequencer port (default "50051") + -listen-all + listen on all network interfaces (0.0.0.0) instead of just localhost + -rollup-id string + rollup id (default "rollupId") + -batch-time duration + time in seconds to wait before generating a new batch (default 2s) + -da_address string + DA address (default "http://localhost:26658") + -da_auth_token string + auth token for the DA + -da_namespace string + DA namespace where the sequencer submits transactions + -db_path string + path to the database +``` + +As shown by the help command, a centralized sequencer is configured to serve a rollup (via `rollup_id`). The DA network to persist the sequenced batches are specified using `da_address`, `da_auth_token` and `da_namespace`. + + +## Run the centralized sequencer {#run-the-centralized-sequencer} + +:::tip +As mentioned in the prerequisities, you should have your DA layer running. These steps assume the local-da is running on `http://localhost:7980`. +::: + +Start your centralized sequencer with the following command: + +::: code-group + +```sh [Quick Start] +./build/centralized-sequencer -rollup-id my-rollup -da_address http://localhost:7980 +``` + +```sh [Build a Chain] +./build/centralized-sequencer -rollup-id wordle -da_address http://localhost:7980 +``` +::: + + +## Run your chain {#run-your-chain} + +To connect your chain to the centralized sequencer, you need to pass the `--rollkit.sequencer_address` flag with the local sequencer address and the `--rollkit.sequencer_rollup_id` to ensure your rollup id matches what the sequencer is expecting. + +Start your chain with the following command, ensuring to include the sequencer flag: + +::: code-group + +```sh [Quick Start] +rollkit start \ + --rollkit.da_address http://localhost:7980 \ + --rollkit.sequencer_address localhost:50051 \ + --rollkit.sequencer_rollup_id my-rollup +``` + +```sh [Wordle Chain] +rollkit start \ + --rollkit.aggregator \ + --rollkit.da_address http://localhost:7980 \ + --rollkit.sequencer_address localhost:50051 \ + --rollkit.sequencer_rollup_id wordle +``` + +::: + +You should see the following log messages indicating that your chain is connected to the local sequencer: + +```sh +I[2024-11-15|15:22:33.636] sequencer already running module=main address=localhost:50051 +I[2024-11-15|15:22:33.636] make sure your rollupID matches your sequencer module=main rollupID=my-rollup +``` + +Then after a few blocks you should see this message confirming that your sequencer is successfully submitting batches to the DA layer: + +```sh +I[2024-11-15|16:04:07.698] successfully submitted Rollkit headers to DA layer module=BlockManager gasPrice=-1 daHeight=1 headerCount=14 +``` + +## Summary {#summary} + +By following these steps, you will have successfully set up and connected your chain to the centralized sequencer. You can now start submitting transactions to your chain. diff --git a/tutorials/forced.md b/tutorials/sequencing/forced-inclusion.md similarity index 100% rename from tutorials/forced.md rename to tutorials/sequencing/forced-inclusion.md diff --git a/tutorials/sequencing/local.md b/tutorials/sequencing/local.md new file mode 100644 index 000000000..660d12f5e --- /dev/null +++ b/tutorials/sequencing/local.md @@ -0,0 +1,66 @@ +# Local Sequencer + + + + +## Introduction {#introduction} + +This tutorial serves as a comprehensive guide for using the [local-sequencer](https://github.com/rollkit/go-sequencing) with your chain. + +Before proceeding, ensure that you have completed the [quick start](/tutorials/quick-start) or [build a chain](/tutorials/wordle) tutorial, which covers installing the rollkit CLI, building your chain, and running your chain. + +## Setting Up a Local Local Sequencer + +To set up a local sequencer on your machine, run the following script to install and start the local sequencer: + +::: code-group + +```bash-vue [Quick Start] +curl -sSL https://rollkit.dev/install-local-sequencer.sh | bash -s {{constants.goSequencingLatestTag}} my-rollup +``` + +```bash-vue [Build a Chain] +curl -sSL https://rollkit.dev/install-local-sequencer.sh | bash -s {{constants.goSequencingLatestTag}} wordle +``` + +::: + +This script will build and run the sequencer, which will then listen on port `50051` with the `rollup-id` of your chain. + +## Configuring your chain to connect to the local sequencer + +To connect your chain to the local sequencer, you need to pass the `--rollkit.sequencer_address` flag with the centralized sequencer address and the `--rollkit.sequencer_rollup_id` to ensure your rollup id matches what the sequencer is expecting. + +## Run your chain + +Start your chain with the following command, ensuring to include the sequencer flag: + +::: code-group + +```sh [Quick Start] +rollkit start \ + --rollkit.sequencer_address localhost:50051 \ + --rollkit.sequencer_rollup_id my-rollup +``` + +```sh [Wordle Chain] +rollkit start \ + --rollkit.aggregator \ + --rollkit.sequencer_address localhost:50051 \ + --rollkit.sequencer_rollup_id wordle +``` + +::: + +You should see the following log messages indicating that your chain is connected to the local sequencer: + +```sh +I[2024-11-15|15:22:33.636] sequencer already running module=main address=localhost:50051 +I[2024-11-15|15:22:33.636] make sure your rollupID matches your sequencer module=main rollupID=my-rollup +``` + +## Summary + +By following these steps, you will have successfully set up and connected your chain to the local sequencer. You can now start submitting transactions to your chain. diff --git a/tutorials/sequencing.md b/tutorials/sequencing/overview.md similarity index 69% rename from tutorials/sequencing.md rename to tutorials/sequencing/overview.md index 20e96650d..17a76e1e4 100644 --- a/tutorials/sequencing.md +++ b/tutorials/sequencing/overview.md @@ -1,9 +1,11 @@ # Sequencing +The next step after choosing your DA layer is to choose your sequencing scheme. + ## Rollkit prior to Sequencing Rollkit's aggregator node was responsible for selecting and ordering transactions for including in the rollup blocks. The Rollkit aggregator used to follow a FCFS strategy, where every transaction submitted gets included in the block in order without any censorship. Use of a different sequencing strategy or connecting to a sequencing network (e.g., Astria) was not possible. Rollkit [v0.14.0](https://github.com/rollkit/rollkit/releases/tag/v0.14.0) onwards makes it possible for rollkit to connect to a sequencing network and communicate via grpc. -### Sequencing Interface +## Sequencing Interface {#sequencing-interface} [go-sequencing](https://github.com/rollkit/go-sequencing) defines a sequencing interface for communicating between any sequencing network and Rollkit. The key functions of the interface are defined as shown below. @@ -20,12 +22,25 @@ It mainly consists of: * `GetNextBatch` returns the next batch of transactions along with a deterministic timestamp * `VerifyBatch` validates the sequenced batch -### Sequencing Implementations +## Mock Sequencer {#mock-sequencer} + +You might have noticed that we did not define a specific sequencer during the [quick start](../quick-start.md) or [build a chain](../wordle.md) tutorials. This is because we used a mock sequencer 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:54:19.843] Starting mock sequencer module=main address=localhost:50051 rollupID=test-rollup-a736683c +``` + +The mock sequencer is a simple in-memory sequencer that is great for testing and development. It is not suitable for production use. + +## 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, [centralized-sequencer](https://github.com/rollkit/centralized-sequencer) is the refactored functionality from the Rollkit prior to `v0.14.0`. The centralized sequencer is the middleware run by the aggregator node of the Rollkit rollup. The aggregator node relays rollup transactions to centralized sequencer which then submits them to the DA network (such as Celestia). The header producer node then retrieves (via `GetNextBatch`) the batched transaction from the centralized 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. The sequencing implementations that are currently work in progress: -* [centralized-sequencer](https://github.com/rollkit/centralized-sequencer) -* [based-sequencer](https://github.com/rollkit/based-sequencer) -* [forced-inclusion-sequencer]() -* [astria-sequencer](https://github.com/rollkit/astria-sequencer) +* [local-sequencer](local) +* [centralized-sequencer](centralized) +* [based-sequencer](based) +* [forced-inclusion-sequencer](forced-inclusion) +* [astria-sequencer](astria)