Merge pull request 0xPolygon#223 from 0xPolygon/km/update-validium-deploy

Updating CDK validium deploy flow after review

Author: EmpieichO

docs/cdk/get-started/deploy-validium/contracts/deploy-contracts.md

@@ -160,4 +160,8 @@ sepolia: {
         count: 20,
       },
     },
-```
+```
+
+## Steps to run the node and services
+
+You are now ready to begin the [CDK validum node and services deployment steps](../node/prerequisites.md).

docs/cdk/get-started/deploy-validium/contracts/prerequisites.md

@@ -1,14 +1,16 @@
 ## Hardware
 
+Make sure you have the following minimum hardware requirements.
+
 - A Linux-based OS (e.g., Ubuntu Server 22.04 LTS).
 - At least 8GB RAM with a 2-core CPU.
 - An AMD64 architecture system.
 
 ## Software
 
-Make sure you have the following software:
+Make sure you have the following minimum software requirements.
 
-| Download link | Version | Check version |
+| Download link | Version | Check version | 
 | --- | --- | --- |
 | [Node](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) | ^20 | `node --version` |
 | npm | ^10 | `npm --version` |
@@ -17,10 +19,13 @@ Make sure you have the following software:
 
 ## Sepolia access
 
+!!! info    
+    You can run your own Sepolia node if you wish and we recommend this for a production set up. However, for simplicity and brevity, we demonstrate by using a node provider.
+
 You will need the following:
 
-- A Sepolia node RPC URL: e.g. https://sepolia.infura.io/v3/YOUR-INFURA-API-KEY
-- An account holding minimum 2 Sepolia ETH that you can send to a generated address within CDK.
+- A Sepolia node RPC URL: e.g. https://sepolia.infura.io/v3/YOUR-INFURA-API-KEY.
+- An account holding a minimum of 2 Sepolia ETH that you must send to a generated address to make for contract calls.
 
 ### Faucets
 
@@ -32,19 +37,31 @@ Use a public faucet to get Sepolia test ETH.
 
 ## Configuration files
 
-Create a folder `/tmp/cdk/` to store configuration files.
+!!! warning
+    We will be working with two separate `.env` files.
+
+    - One `.env` file resides in the contracts project directory. We will set this up in the [contract set up](set-up.md#create-the-env-configuration) section.
+    - Another `.env` resides in a shared system directory so that it is accessible to the node and all running processes. We will populate this file as we go along.
+
+Create a folder `/tmp/cdk/` to store the shared `.env` file which will be used by all running processes.
 
 ```bash
 mkdir /tmp/cdk/
 ```
 
-## Environment variables
+!!! danger
+    - Any files in the `tmp/` directory are deleted on shutdown.
+    - For this reason, we recommend that you save this folder in your home directory once the shared configuration set up is complete.
+
+### Shared environment variables
+
+Create a `.env` file to store the environment variables that all running processes will share. This shared `.env` file allows us to use `jq` and `tomlq` to easily setup the configuration for the node and running processes.
 
-Create a `.env` file to store environment variables we will use later on.
+This file will be populated throughout the [deploy node](../node/prerequisites.md) instructions.
 
 ```bash
 nano /tmp/cdk/.env
 ```
 
 !!! danger
-    The system removes this file on shutdown.
+    Don't forget, the system removes this file on shutdown.

docs/cdk/get-started/deploy-validium/contracts/set-up.md

@@ -10,12 +10,11 @@
 
 2. Download the `0.0.2` release from the [cdk-validium-contracts github repo](https://github.com/0xPolygon/cdk-validium-contracts/releases/tag/v0.0.2-RC1).
 
-    !!! note
-        The download is available in both `.tar.gz` and `.zip` formats.
-
     ```bash
     curl -L -o cdk-validium-contracts.tar.gz https://github.com/0xPolygon/cdk-validium-contracts/archive/refs/tags/v0.0.2.tar.gz
     ```
+    !!! note
+        The download is available in both `.tar.gz` and `.zip` formats.
 
 3. Extract the files and cd into the repo.
 
@@ -32,7 +31,7 @@ npm install
 
 ## Create the .env configuration
 
-1. Copy the environment configuration example file into a new `.env` file.
+1. Copy the contract environment configuration example file into a new `.env` file.
 
     ```bash
     cp .env.example .env
@@ -68,19 +67,17 @@ npm install
     ```
 
     !!! info
-        Check our documentation if you want to [use a different node provider](deploy-contracts.md#use-a-different-node-provider).
+        Check the documentation if you want to [use a different node provider](deploy-contracts.md#use-a-different-node-provider).
 
 4. Send 2 Sepolia ETH to the generated address.
 
-5. Add the following variables to `/var/tmp/cdk/.env`. 
+5. Add the following variables to the *other* `.env` file residing in `/tmp/cdk/.env`. 
 
     ```bash
     nano /tmp/cdk/.env
-    TEST_ADDRESS="<the address generated by cast>"
-    TEST_PRIVATE_KEY="<the private key generated by cast>" 
+    TEST_ADDRESS="<the address generated by cast above>"
+    TEST_PRIVATE_KEY="<the private key generated by cast above>" 
     L1_URL="https://sepolia.infura.io/v3/<YOUR INFURA PROJECT ID>"
     L1_WS_URL="wss://sepolia.infura.io/ws/v3/<YOUR INFURA PROJECT ID>"
     ```
-!!! important
-    This step allows us to use `jq` and `tomlq` later on to setup our configuration files.
 

docs/cdk/get-started/deploy-validium/index.md

@@ -0,0 +1,34 @@
+This guide takes you through the process of deploying a full CDK validium, EVM-compatible network on Sepolia.
+
+We have hidden most of the configuration complexity in scripts to make the process straightforward and easy to follow.
+
+## Process steps
+
+The process requires two separate flows with different software requirements. For this reason, we have separated the instructions into two distinct sections.
+
+1. [Deploying the contracts](contracts/prerequisites.md): The node and services require a bunch of [deployed contracts](https://github.com/0xPolygon/cdk-validium-contracts) so we complete this step first.
+2. [Deploying the node and services](node/prerequisites.md): Once the contracts are deployed, we can run the [validium node](https://github.com/0xPolygon/cdk-validium-node), [mock prover](https://github.com/0xPolygonHermez/zkevm-prover), [data availability layer](https://github.com/0xPolygon/cdk-data-availability), and [zkEVM bridge service](https://github.com/0xPolygonHermez/zkevm-bridge-service).
+
+!!! warning
+    - The instructions are subject to frequent updates as the software remains at an early development stage.
+    - Report any technical issue on the relevant [repo](#git-repos-and-running-order).
+    - Report any content issues on our docs repo: https://github.com/0xPolygon/polygon-docs.
+
+## Git repos and running order
+
+These are code bases we used to set everything up for this deployment guide, and in this order.
+
+!!! warning
+    The versions below may not be the most recent.
+
+| Repo | Version |
+| --- | --- |
+| https://github.com/0xPolygon/cdk-validium-contracts/releases/tag/v0.0.2 | v0.0.2 |
+| https://github.com/0xPolygon/cdk-validium-node/releases/tag/v0.0.3 | v0.0.3 |
+| https://github.com/0xPolygonHermez/zkevm-prover | v3.0.2 |
+| https://github.com/0xPolygon/cdk-data-availability | v0.0.3 |
+| https://github.com/0xPolygonHermez/zkevm-bridge-service | v0.3.1 |
+
+## Instructions for deploying contracts
+
+You are now ready to follow the [pre-requisite steps](contracts/prerequisites.md) for setting up the contracts.

docs/cdk/get-started/deploy-validium/intro.md

@@ -225,17 +225,17 @@ jq '.aggregatorClientHost = "127.0.0.1" | .databaseURL = "postgresql://cdk_user:
 
 	The values to append to `genesis.json` are something like:
 
-		```bash
-		#~/cdk-validium/cdk-validium-contracts-0.0.2/deployment/genesis.json
-		"L1Config": {
-		"chainId": 11155111,
-		"maticTokenAddress": "0xd76B50509c1693C7BA35514103a0A156Ca57980c",
-		"polygonZkEVMAddress": "0x52C8f9808246eF2ce992c0e1f04fa54ec3378dD1",
-		"cdkDataCommitteeContract": "0x8346026951978bd806912d0c93FB0979D8E3436a",
-		"polygonZkEVMGlobalExitRootAddress": "0xE3A721c20B30213FEC306dd60f6c7F2fCB8b46D2"
-		},
-		"genesisBlockNumber": 5098088
-		```
+	```bash
+	#~/cdk-validium/cdk-validium-contracts-0.0.2/deployment/genesis.json
+	"L1Config": {
+	"chainId": 11155111,
+	"maticTokenAddress": "0xd76B50509c1693C7BA35514103a0A156Ca57980c",
+	"polygonZkEVMAddress": "0x52C8f9808246eF2ce992c0e1f04fa54ec3378dD1",
+	"cdkDataCommitteeContract": "0x8346026951978bd806912d0c93FB0979D8E3436a",
+	"polygonZkEVMGlobalExitRootAddress": "0xE3A721c20B30213FEC306dd60f6c7F2fCB8b46D2"
+	},
+	"genesisBlockNumber": 5098088
+	```
 
 6. Run the following script that automates the process of appending those values:
 
@@ -249,6 +249,10 @@ jq '.aggregatorClientHost = "127.0.0.1" | .databaseURL = "postgresql://cdk_user:
 	.genesisBlockNumber = $data.deploymentBlockNumber' ~/cdk-validium/cdk-validium-contracts-0.0.2/deployment/genesis.json > /tmp/cdk/genesis.json
 	```
 
+	You should see something like this:
+
+	![DAC configuration output](../../../../img/cdk/dac-output.png)
+
 ## Configure the DAC
 
 At this point we should have setup and provisioned the psql database and configured the zk prover and node. 

docs/cdk/get-started/deploy-validium/node/configure-deployment.md

@@ -93,4 +93,4 @@
     ./version-check.sh
     ```
 
-3. Install any missing or out-of-date software.
+3. Install any missing or out-of-date software using the links provided above.

docs/cdk/get-started/deploy-validium/node/prerequisites.md

@@ -1,3 +1,7 @@
+!!!	warning
+	- Use a separate terminal window to run the node and each service separately.
+	- Whenever you need to restart the process, make sure you stop and delete all running Docker containers and images.
+
 ## Run the prover
 
 Since the prover is large and compute-expensive to build, we will use a docker container.
@@ -57,4 +61,8 @@ cd ~/cdk-validium/cdk-data-availability-0.0.3
 ```bash
 cd ~/cdk-validium/zkevm-bridge-service 
 ./dist/zkevm-bridge run --cfg /tmp/cdk/bridge-config.toml
-```
+```
+
+## Congratulations
+
+You have now set up and deployed a full CDK validium network.

docs/cdk/get-started/deploy-validium/node/run-node-services.md

@@ -3,7 +3,7 @@
 1. Navigate to `cdk-validium-contracts-0.0.2/deployment` and run the following script that inputs the required parameters from `deploy_output.json` into `/tmp/cdk/.env`.
 
     ```bash
-    cd cdk-validium-contracts-0.0.2/deployment
+    cd ~/cdk-validium-contracts-0.0.2/deployment
     echo "GEN_BLOCK_NUMBER=$(jq -r '.deploymentBlockNumber' deploy_output.json)" >> /tmp/cdk/.env
     echo "CDK_VALIDIUM_ADDRESS=$(jq -r '.cdkValidiumAddress' deploy_output.json)" >> /tmp/cdk/.env
     echo "POLYGON_ZKEVM_BRIDGE_ADDRESS=$(jq -r '.polygonZkEVMBridgeAddress' deploy_output.json)" >> /tmp/cdk/.env
@@ -46,17 +46,15 @@
     - `cdk-validium-node`
     - `zkevm-bridge-service-0.3.1`
 
-## Prepare the environment
-
-Navigate to the node directory we cloned at the previous step: `cdk-validium-node/`.
+## Set up the database
 
-```bash
-cd cdk-validium-node/
-```
+1. Navigate to the node directory we cloned at the previous step: `cdk-validium-node/`.
 
-## Set up the database
+    ```bash
+    cd cdk-validium-node/
+    ```
 
-1. Run the docker command below to start an instance of the `psql` database. The database is used for many of the services, such as the node, prover, DAC, and bridge service.
+2. Run the docker command below to start an instance of the `psql` database. The database is used for many of the services, such as the node, prover, DAC, and bridge service.
 
     ```bash
     docker run -e POSTGRES_USER=cdk_user -e POSTGRES_PASSWORD=cdk_password -e POSTGRES_DB=postgres -p 5432:5432 postgres:15
@@ -70,7 +68,7 @@ cd cdk-validium-node/
         kill -9 <PID>
         ```
 
-2.  Use the following command to validate the setup (`\q` to exit).
+3.  Use the following command to validate the setup (`\q` to exit).
 
     ```bash
     PGPASSWORD=cdk_password psql -h localhost -U cdk_user -d postgres -p 5432
@@ -85,10 +83,10 @@ cd cdk-validium-node/
 
 The `cdk-validium-node` directory contains a script called `single_db_server.sql` that provisions all the databases required for the prover, state, and pool to operate. 
 
-1. Run the script to provision all the necessary databases and schemas used for the prover and node:
+1. In a new terminal window, run the script to provision all the necessary databases and schemas used for the prover and node:
 
     ```bash
-    cd /cdk-validium/cdk-validium-node
+    cd cdk-validium/cdk-validium-node
     PGPASSWORD=cdk_password psql -h localhost -U cdk_user -d postgres -p 5432 -a -q -f ./db/scripts/single_db_server.sql
     ```