Merge branch 'main' of https://github.com/0xPolygon/polygon-docs into km/more-sharon-updates

Author: kmurphypolygon

docs/cdk/architecture/type-1-prover/intro-t1-prover.md

@@ -1,5 +1,8 @@
 The Polygon Type 1 Prover is a zk-evm proving component used for creating proofs on your ZK-EVM chain. It has been developed in collaboration with the Toposware team.
 
+!!! info
+    The Polygon Type 1 Prover is not yet ready for full implementation into a CDK stack.
+
 ## Get started
 
 If you want to get up and running quickly, follow the [how to deploy the Type 1 Prover guide](../../how-to/deploy-t1-prover.md).

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,30 @@ Use a public faucet to get Sepolia test ETH.
 
 ## Configuration files
 
-Create a folder `/tmp/cdk/` to store configuration files.
+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-contracts-env-configuration) section.
+- Another `.env` resides in a shared system directory so that it is accessible to the node and all running processes.
+
+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.
+After adding a few variables to this file in the next [set up section](set-up.md#create-the-shared-system-env-configuration), this file is populated with more environment variables during the [node set up step](../node/set-up.md) and is then accessed by the system throughout the [deploy node configuration step](../node/configure-deployment.md) and [node and services run step](../node/run-node-services.md).
 
 ```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.
 
@@ -30,15 +29,9 @@
 npm install
 ```
 
-## Create the .env configuration
-
-1. Copy the environment configuration example file into a new `.env` file.
-
-    ```bash
-    cp .env.example .env
-    ```
+## Create the contracts `.env` configuration
 
-2. Generate a new mnemonic using `cast`.
+1. Generate a mnemonic, address, and private key using `cast`.
 
     ```bash
     cast wallet new-mnemonic --words 12
@@ -58,29 +51,65 @@ npm install
     Private key: 0x3b01870a8449ada951f59c0275670bea1fc145954ee7cb1d46f7d21533600726
     ```
 
-3. Add the environment variables to the `.env` file.
+2. Copy the contract environment configuration example file into a new `.env` file.
+
+    !!! important
+        You should still be in the `cdk-validium-contracts-0.0.2/` directory from the previous step.
 
     ```bash
-    nano .env
-    MNEMONIC="<generated mnemonic>"  # copy/paste the generated Phrase
-    INFURA_PROJECT_ID="<INFURA_PROJECT_ID>"  # Generate a project id on [Infura](https://www.infura.io/)
+    cp .env.example .env
+    ```
+
+3. Open the `.env` file.
+
+    !!! important
+        You should still be in the `cdk-validium-contracts-0.0.2/` directory from the previous step.
+
+    ```sh
+    nano `.env`
+    ```
+
+4. This is what the `.env` file will more or less look like, although you may see actual data in there from a previous run. 
+
+    ```txt 
+    MNEMONIC="<GENERATED_MNEMONIC>"  # copy/paste the generated Phrase from cast
+    INFURA_PROJECT_ID="<YOUR_INFURA_API_KEY>"  # Generate a project id on [Infura](https://www.infura.io/)
     ETHERSCAN_API_KEY="<ETHERSCAN_API_KEY>" # Generate an API key on [Etherscan](https://etherscan.io)
     ```
 
+    Replace the variables as follows:
+
+    - `GENERATED_MNEMONIC` is the generated mnemonic phrase from the cast step above.
+    - `YOUR_INFURA_API_KEY` is a project id you have already created on Infura Sepolia.
+    - `ETHERSCAN_API_KEY` is an API key you have already generated on Etherscan. This variable is optional.    
+
     !!! 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.
+## Create the shared system `.env` configuration
 
-5. Add the following variables to `/var/tmp/cdk/.env`. 
+1.  Now open the *other* `.env` file residing in `/tmp/cdk/.env` which we created in the prerequisite steps.
 
-    ```bash
+    ```sh
     nano /tmp/cdk/.env
-    TEST_ADDRESS="<the address generated by cast>"
-    TEST_PRIVATE_KEY="<the private key generated by cast>" 
-    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.
 
+2.  Below is what the `.env` file will more or less look like, although you may see actual data in there from a previous run. 
+
+    ```sh
+    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_API_KEY>" # same as in the other env file
+    L1_WS_URL="wss://sepolia.infura.io/ws/v3/<YOUR_INFURA_API_KEY>" # same as in the other env file
+    ```
+
+    Replace the following variables:
+
+    - `TEST_ADDRESS` is the address generated by cast above.
+    - `TEST_PRIVATE_KEY` is the private key generated by cast above.
+    - `L1_URL` is your Infura Sepolia RPC URL, for example: https://sepolia.infura.io/v3/<YOUR_INFURA_API_KEY>  
+    - `L1_WS_URL` is your Infura Sepolia wss URL, for example: wss://sepolia.infura.io/ws/v3/<YOUR_INFURA_API_KEY>
+
+## Send Sepolia
+
+Send 2 Sepolia ETH to the cast generated address called `TEST_ADDRESS` in the shared `.env` file above.

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:
 
@@ -330,8 +330,12 @@ Now let’s configure the Data Availability Committee.
 			$TEST_ADDRESS
 	```
 
-!!!	note
-	This can take a few minutes.
+	!!!	note
+		This can take a few minutes.
+	
+	You should see something like this:
+
+	![DAC configuration output](../../../../img/cdk/dac-output.png)
 
 ## Configure bridge service
 

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.