Improve guides section (#41)

* Start working on the guides section

* docs: enhance L1 deployment guide for clarity and detail

* docs: update deployment guides for clarity and structure

* docs: add further reading section for Based Rollups with helpful resources

* docs: remove redundant "What's Next?" section from L1 deployment guide

* docs: update L2 genesis preparation instructions for clarity

Author: jmadibekov

docs/about/architecture.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 5
+sidebar_position: 4
 title: Surge Architecture
 ---
 
@@ -28,15 +28,9 @@ The Taiko Client consists of several sub-components:
 Surge has customized aspects of the Taiko architecture to enhance performance and remove any reliance on new tokens:
 
 1. **Token-Free Design:** Surge removes token dependencies, allowing the use of Ether as a bond for block proposals.
-
 2. **Execution Client Upgrade:** Replaced TaikoGeth with the Nethermind Execution Client (NMC) to achieve better performance. [NMC Documentation](https://github.com/NethermindEth/nethermind).
-
 3. **Time-Locked Owner:** Modified the multisig implementation to feature a 45-day timelock, aligning with Stage 2 requirements by L2Beat.
-
 4. **Verification Streak Checks:** Owner operations via the multisig are blocked if there has been a liveness disruption of 7 days or more within the past 45 days.
-
 5. **Disabled Pausing:** The owner cannot pause the protocol or peripheral contracts.
-
 6. **2/3 Proof Verifier:** There are three proof systems (SGX, SP1, and Risc0). At least two of these must agree on a state transition for it to be accepted.
-
 7. **No Contestation Window:** As Surge employs a single ZK approach (no optimistic fallback), it does not require a contestation window. This design choice makes Surge a pure ZK-Rollup rather than an Optimistic Rollup.

docs/about/based-rollups.md

@@ -36,3 +36,12 @@ Surge fully embraces this model for its rollup architecture. By integrating with
 - **Conventional Rollups**: A centralized sequencer has the final say on transaction order before batches go to L1, introducing potential risks of manipulation or censorship.
 
 ![Conventional Non-Based Rollups: A centralized sequencer decides transaction ordering before submitting them to L1.](./images/conventional-rollups.png)
+
+## Further Reading
+
+To learn more about Based Rollups, explore these helpful resources:
+
+- **Taiko Documentation: [Based Rollups](https://docs.taiko.xyz/taiko-alethia-protocol/protocol-design/based-rollups)**  
+  Official documentation providing an in-depth understanding of Taiko's Based Rollups design and protocol specifications.
+- **Blog Post: [Understanding Based Rollups](https://taiko.mirror.xyz/7dfMydX1FqEx9_sOvhRt3V8hJksKSIWjzhCVu7FyMZU)**  
+  A clear and informative article by the Taiko team, offering valuable insights into how Based Rollups function and their benefits.

docs/about/no-token.md

@@ -1,5 +1,6 @@
 ---
-sidebar_position: 1
+sidebar_position: 3
+title: Deploying your DApp on Surge
 ---
 
 # Deploying your DApp on Surge

…s/guides/deploy-dapps/deploy-on-surge.md docs/guides/deploy-on-surge.mddocs/guides/deploy-dapps/deploy-on-surge.md renamed to docs/guides/deploy-on-surge.md docs/guides/deploy-dapps/deploy-on-surge.md renamed to docs/guides/deploy-on-surge.md

@@ -1,5 +1,6 @@
 ---
-sidebar_position: 4
+title: Deploy Protocols on L1
+sidebar_position: 2
 ---
 
 import Tabs from '@theme/Tabs';
@@ -8,16 +9,16 @@ import TabItem from '@theme/TabItem';
 # Deploy Protocols on L1
 
 :::note Skip if Using Kurtosis
-If you're using the Kurtosis Package to deploy L1, you can skip this section.
+If you're using the Kurtosis Package to [deploy L1](docs/guides/running-surge/deploy-l1.mdx), you can skip this section.
 :::
 
 ## 1. Deploy Taiko on L1
 
 ### Prerequisites
 
-- L2 Chain ID (e.g. 763374)
-- L2 Genesis Hash (e.g. `0xbeced3738f1246571cccabc82a1e6cbd9ed9d5f7ed2b6c7ded28f9722317bd9e`)
-- L1 Account with funds
+- L2 Chain ID (e.g., `763374`)
+- L2 Genesis Hash (e.g., `0xbeced3738f1246571cccabc82a1e6cbd9ed9d5f7ed2b6c7ded28f9722317bd9e`)
+- L1 Account with sufficient funds
 - L1 RPC URL
 
 ### Set Environment Variables
@@ -197,7 +198,7 @@ docker run \
 - ATTESTATION_ADDRESS: `0xaE37C7A711bcab9B0f8655a97B738d6ccaB6560B`
 - PEM_CERTCHAIN_ADDRESS: `0x303CB317624c74bB20Acbb9E13c8D745C6379826`
 - Quote value (see documentation)
-- L1 Account with funds
+- L1 Account with sufficient funds
 - L1 RPC URL
 
 :::info Full Quote Value

docs/guides/running-surge/deploy-l1-protocols.mdx

@@ -1,68 +1,124 @@
 ---
-sidebar_position: 2
+title: Deploy L1
+sidebar_position: 1
 ---
 
 # Deploy L1
 
-In this guide, we'll walk through the process of deploying the L1 network using Kurtosis. This will also deploy the Taiko protocol on L1.
+This guide explains how to deploy an L1 development network using Kurtosis. This setup includes deploying the Taiko protocol on L1, which is required for launching the Surge L2 development network. By the end, you'll have a fully functional L1 environment running within a Kurtosis enclave.
 
 ## Prerequisites
 
-- Git and Docker installed on your system
-- Terminal access
-- Basic command line knowledge
-
-## Installation Steps
-
 ### 1. Install Kurtosis
 
-First, you'll need to install Kurtosis on your system. Follow the installation guide at:
+First, install Kurtosis by following the official guide:
 
 <div className="flex justify-center my-8">
   <a
     className="button button--primary button--lg"
-    href="https://docs.kurtosis.com/quickstart"
+    href="https://docs.kurtosis.com/install"
     target="_blank"
     rel="noopener noreferrer"
   >
     Kurtosis Installation Guide ↗
   </a>
 </div>
 
-### 2. Clone the Repository
+After installation, verify Kurtosis is correctly installed by checking the engine status:
+
+```bash
+kurtosis engine status
+```
+
+You should see output similar to:
+
+```
+A Kurtosis engine is running with the following info:
+Version:   1.6.0
+```
 
-Clone the Surge devnet package repository and navigate to the directory:
+### 2. Clone Repository
+
+Next, clone the `surge-devnet-package` repository and navigate into the directory:
 
 ```bash
 git clone https://github.com/NethermindEth/surge-devnet-package.git
-
 cd surge-devnet-package
 ```
 
-### 3. Deploy Using Kurtosis
+## Deploy the L1 Network
 
-Run Kurtosis with the following command to deploy the L1 network:
+Once you've installed Kurtosis and cloned the repository, deploy the L1 network with the following command:
 
 ```bash
 kurtosis run --enclave surge-devnet . --args-file network_params.yaml --production
 ```
 
 :::tip
-This command will also automatically deploy the Taiko protocol on L1 for you. Watch closely for the deployment outputs.
+This command not only deploys the L1 network but also automatically deploys the Taiko protocol on L1. Monitor your terminal output for details on the deployment progress.
 :::
 
-## Verification
+## Verify Your Deployment
 
-After running the deployment command, Kurtosis will start setting up your L1 environment. You should see output in your terminal indicating the progress of the deployment.
+After deployment, verify that your environment is correctly set up by inspecting the Kurtosis enclave:
 
-:::info What's Next?
-Once your L1 deployment is complete, you can proceed with setting up your prover or configuring additional network parameters.
-:::
+```bash
+kurtosis enclave inspect surge-devnet
+```
+
+You should see a list of active services confirming that both the L1 network and the Taiko protocol have been successfully deployed.
+
+### Verify the Execution Layer
+
+Check if the Execution Layer is running correctly by sending a simple [`web3_clientVersion`](https://www.quicknode.com/docs/ethereum/web3_clientVersion) JSON-RPC request:
+
+```bash
+curl -X POST -H "Content-Type: application/json" \
+     --data '{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":1}' \
+     http://127.0.0.1:32002
+```
+
+A successful response should look like:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "result": "Nethermind/v1.31.0-unstable+fd87ddb6/linux-x64/dotnet9.0.2",
+  "id": 1
+}
+```
+
+This indicates the Execution Layer is correctly initialized and running.
+
+### Verify the Consensus Layer
+
+Check the Consensus Layer's syncing status by running:
+
+```bash
+curl http://127.0.0.1:33001/eth/v1/node/syncing
+```
+
+A successful response should resemble:
+
+```json
+{
+  "data": {
+    "is_syncing": false,
+    "is_optimistic": false,
+    "el_offline": false,
+    "head_slot": "28046",
+    "sync_distance": "0"
+  }
+}
+```
+
+This confirms the Consensus Layer is successfully running and synchronized.
 
 ## Troubleshooting
 
-If you encounter any issues during deployment:
+If you encounter any issues:
+
+1. Confirm that the `network_params.yaml` file is present in the `surge-devnet-package` directory.
+2. Verify that Kurtosis is properly installed and running with the correct version (`kurtosis engine status`).
 
-1. Ensure all prerequisites are properly installed
-2. Check that the `network_params.yaml` file exists and is properly configured
-3. Make sure Kurtosis is running correctly on your system
+If problems persist, refer to the [Troubleshooting section](docs/troubleshooting/index.mdx) for additional support.

docs/guides/running-surge/deploy-l1.mdx

@@ -1,30 +1,37 @@
 ---
-sidebar_position: 1
+title: Prepare L2 Genesis
+sidebar_position: 3
 ---
 
 # Prepare L2 Genesis
 
-In this guide, we'll walk through the process of preparing the L2 genesis file, chainspec file and genesis hash later required by deploying L1 Network and L2.
+:::note Skip if Using `simple-surge-node`
+If you're using [`simple-surge-node`](https://github.com/NethermindEth/simple-surge-node) to [deploy L2](docs/guides/running-surge/deploy-l2.mdx), you can **skip this section** since `simple-surge-node` repository already includes a ready-to-use [`chainspec.json` file](https://github.com/NethermindEth/simple-surge-node/blob/main/static/chainspec.json).
+:::
+
+This guide walks you through preparing your own L2 genesis file, chainspec file, and genesis hash which are required to deploy an L2 network.
 
 ## Prerequisites
 
-- Foundry, pnpm and jq installed on your system
-- Terminal access
-- Basic command line knowledge
+Before proceeding, ensure the following tools are installed:
+
+- [Foundry](https://github.com/foundry-rs/foundry#installation)
+- [pnpm](https://pnpm.io/installation)
+- [jq](https://jqlang.org/download/)
+- [Docker](https://docs.docker.com/get-docker/)
 
-## Deployment Steps
+## Steps
 
-### 1. Clone Repository
+### 1. Clone the Repository
 
-First, clone the Surge Taiko Mono repository and navigate to the directory:
+Clone the `surge-taiko-mono` repository and navigate into it:
 
 ```bash
 git clone https://github.com/NethermindEth/surge-taiko-mono.git
-
 cd surge-taiko-mono
 ```
 
-### 2. Switch to the Correct Branch
+### 2. Checkout Correct Branch
 
 Checkout the `surge/devnet` branch:
 
@@ -34,48 +41,48 @@ git checkout surge/devnet
 
 ### 3. Install Dependencies
 
-Navigate to the protocol package and install all required dependencies:
+Navigate to the protocol package and install dependencies:
 
 ```bash
 cd packages/protocol
-
-foundryup && pnpm install
+foundryup
+pnpm install
 ```
 
-### 4. Set Environment Variables
+### 4. Configure Environment Variables
 
-Set the following environment variables as needed:
+Set required environment variables:
 
 ```bash
 export CONTRACT_OWNER=0x8943545177806ED17B9F23F0a21ee5948eCaa776
 export L1_CHAINID=3151908
 export L2_CHAINID=763374
 ```
 
-### 5. Generate L2 Genesis
+### 5. Generate L2 Genesis File
 
-Then compile the L2 contracts and generate the genesis block:
+Compile L2 contracts and generate the genesis block:
 
 ```bash
 pnpm compile:l2
 pnpm genesis:gen
 ```
 
 :::tip
-You will find the genesis file in `./test/genesis/data/`.
+The generated files can be found at `./test/genesis/data/`.
 :::
 
-### 6. Download Genesis to Chainspec Converter
+### 6. Download Genesis-to-Chainspec Converter
 
-In order to convert the genesis file to chainspec file, you can download the following tool:
+Download the script used to convert the genesis file to a chainspec file:
 
 ```bash
 curl -O https://raw.githubusercontent.com/NethermindEth/core-scripts/refs/heads/main/gen2spec/gen2spec.jq
 ```
 
 ### 7. Convert Genesis to Chainspec
 
-Then run the following command to convert the genesis file to chainspec file:
+Convert the genesis file into a chainspec file:
 
 ```bash
 cat ./test/genesis/data/genesis.json | jq ". * {
@@ -90,12 +97,12 @@ cat ./test/genesis/data/genesis.json | jq ". * {
 ```
 
 :::tip
-You will find the chainspec file in `./test/genesis/data/`.
+The chainspec file will be created at `./test/genesis/data/chainspec.json`.
 :::
 
 ## Retrieve the Genesis Hash
 
-To retrieve the genesis hash, you can use Nethermind Client:
+Use the Nethermind client Docker container to retrieve the genesis hash:
 
 ```bash
 docker run -d \
@@ -105,9 +112,18 @@ docker run -d \
   --config=none \
   --Init.ChainSpecPath=/chainspec.json
 
+# Wait a few seconds for the container to initialize
+
 docker logs nethermind-genesis-hash 2>/dev/null | grep "Genesis hash" | head -n 1 | sed 's/.*Genesis hash : \(.*\)/\1/'
 ```
 
 :::tip
-You will get the genesis hash in the logs.
+The genesis hash will be printed in the console.
 :::
+
+### Clean Up (Optional)
+
+Stop and remove the Docker container after obtaining the genesis hash:
+
+```bash
+docker rm -f nethermind-genesis-hash