Merge branch 'main' of https://github.com/0xPolygon/polygon-docs into cdk/native-gas-token

Author: kmurphypolygon

README.md

@@ -1,14 +1,44 @@
 # Polygon Knowledge Layer
 
-Welcome to the Polygon Knowledge Layer! This documentation is built using [the Material theme for MkDocs](https://squidfunk.github.io/mkdocs-material/). Our goal is to establish a high-quality, curated, and comprehensive "source of truth" for technical knowledge surrounding Polygon's main technology. This includes detailed sections on:
+Welcome to the Polygon Knowledge Layer.
+
+These docs use [the Material theme for MkDocs](https://squidfunk.github.io/mkdocs-material/). Our goal is to establish a high-quality, curated, and comprehensive "source of truth" for Polygon's technology. 
+
+This includes sections on:
 
 - Polygon CDK
 - Polygon zkEVM
 - Polygon PoS
 - Polygon Miden
-- Dev Tools 
+- Developer tools 
+
+## Run locally
+
+### Prerequisites
+
+1. [Python 3.12](https://www.python.org/downloads/).
+2. [`virtualenv`](https://pypi.org/project/virtualenv/): Install using `pip3 install virtualenv`.
+
+### Setup
+
+1. Clone the repository.
+2. `cd` to the root.
+3. Run the `run.sh` script. You may need to make the script executable: `chmod +x run.sh`
+
+```sh
+./run.sh
+```
+
+The site comes up at http://127.0.0.1:8000/ 
+
+### Docker 
 
-In addition, we include top-level sections for Tools and Tutorials to support developers in their journey with Polygon technology.
+If you prefer Docker, you can build and run the site using the following commands:
+
+```sh
+docker build -t polygon-docs .
+docker compose up
+```
 
 ## Contributing
 
@@ -34,58 +64,12 @@ In addition, we include top-level sections for Tools and Tutorials to support de
 - **Engage with the community**: Participate in discussions and provide feedback on other contributions.
 - **Stay consistent**: Ensure your contributions are coherent with the rest of the documentation and do not overlap or contradict existing content.
 
-
-## Running locally
-
-### Prerequisites
-
-Before running the site locally, you need to have the following installed:
-
-1. [Python 3](https://www.python.org/downloads/).
-2. [`virtualenv`](https://pypi.org/project/virtualenv/): Install using `pip3 install virtualenv`.
-
-### Setup
-
-1. **Clone repository**: Clone the Polygon Knowledge Layer repository to your local machine.
-2. **Create a virtual environment**: Run `virtualenv venv; source venv/bin/activate` in the root directory.
-3. **Install dependencies**: Install required Python packages with `pip3 install -r requirements.txt`.
-
-### Running the website
-
-Before running the website, you'll need to first load the Python virtual environment in your current shell. To do this, type the following (depending on your shell):
-
-- **Bash**, **zsh** (most common): `virtualenv venv; source venv/bin/activate`
-- **Fish**: `virtualenv venv; source venv/bin/activate.fish`
-- **Nu**: `virtualenv venv; source venv/bin/activate.nu`
-
-You only need to do the above once per shell session. Then, pick one of the following:
-
-1. **MkDocs in strict mode**: Use `mkdocs serve --strict` for a production-like environment.
-2. **MkDocs in normal mode**: Use `mkdocs serve` for a less strict, more forgiving environment, suitable for debugging.
-
-### Docker alternative
-
-If you prefer Docker, you can build and run the site using the following commands:
-
-```sh
-docker build -t polygon-docs .
-docker compose up
-```
-
-## Automated deployments
-
-This repository uses GitHub Actions to automate some deployments from certain branches, which is useful for testing:
-
-- **`main`**: Staging branch. Changes are deployed per-commit to https://docs-staging.polygon.technology.
-- **`dev`**: Experimental branch. Updates with `main` every 24 hours. Changes are deployed per-commit to https://docs-dev.polygon.technology.
-
-Whenever we are happy with `main`, a trigger can be manually done through GitHub Actions which deploys staging to production at https://docs.polygon.technology.
-
 ## Contact and support
 
-For any queries or support, please open a ticket at https://support.polygon.technology/support/home. 
+- For docs issues (technical or language) open an issue here.
+- For technical issues with the software, either raise an issue here and we will follow up, or check https://support.polygon.technology/support/home. 
 
-## Current Technical Knowledge Documentation (TKD) team members
+## The team
 
 - Anthony Matlala (@EmpieichO)
 - Katharine Murphy (@kmurphypolygon)

docs/_site_essentials/stylesheets/extra.css

@@ -72,6 +72,9 @@
 	.md-icon {
 		color: var(--gray);
 	}
+	.flex-card-item:hover {
+		background-color: var(--gray);
+	}
 }
 /** END OF COLOR SCHEMES **/
 

docs/cdk/architecture/cdk-validium-option.md

@@ -0,0 +1,48 @@
+The Polygon CDK validium is one of two configuration options of the Polygon CDK, the other being the Polygon zkEVM rollup.
+
+As per [the definition](https://ethereum.org/developers/docs/scaling/validium), the Polygon CDK validium uses validity proofs to enforce integrity of state transitions, but it does not store transaction data on the Ethereum network.
+
+The Polygon CDK validium is in fact a _zero-knowledge validium_ (zkValidium) because it utilises the Polygon zkEVM's off-chain prover to produce zero-knowledge proofs, which are published as _validity proofs_.
+
+The use of the above-mentioned prover, to a certain extent, adds trustlessness to the Polygon CDK validium.
+
+The validium mode inherits, not just the prover, but all the Polygon zkEVM's components and their functionalities, except that it does not publish transaction data on L1.
+
+The validium configuration has one major advantage over the zkEVM rollup option: And that is, reduced gas fees due to the off-chain storage of transaction data, where only a hash of the transaction data gets stored on the Ethereum network.
+
+## Data availability committee (DAC)
+
+In relation to storing transaction data off-chain, the CDK validium comes with the requirement to manage the data.
+
+- First of all, the transaction data is not published to the L1 but only the hash of the data.
+- Secondly, a trusted-sequencer collects transactions from the pool DB, puts them into batches and computes the hash of the transaction data. 
+
+It is due to the above two points that the Polygon CDK validium has to have a set of _trusted actors_, who can monitor and even authenticate the hash values that the sequencer proposes to be published on the L1. 
+
+The hash values need to be verified as true _footprints_ of the transaction data corresponding to all transactions in the sequenced batches.
+
+These _trusted actors_ are collectively called the Data Availability Committee (DAC). 
+
+After verifying the proposed hash values individually, each DAC member signs them and sends the signature to the sequencer.
+
+The sequencer uses a _multi-sig_, which is a custom-specified _m-out-of-n multi-party protocol_, to attach the required _m_ signatures to the hash of the transaction data. The _multi-sig_ contract lives on the L1 network. 
+
+Architecturally speaking, the Polygon CDK validium is therefore nothing but a zkEVM with a DAC. That is, **Polygon CDK validium =  Polygon zkEVM + DAC**.
+
+## Validium data flow
+
+The DAC works together with the sequencer to control the flow of data and state changes. 
+
+The diagram below depicts a simplified outline of the Polygon CDK validium architecture. It particularly shows how the DAC and the sequencer relate in the overall data flow.
+
+![CDK validium data availability dataflow](../../img/cdk/cdk-val-dac-02.png)
+
+The entire process can be broken down as follows:
+
+1. **Batch formation**: The sequencer collects user transactions, adds them to blocks, and puts the blocks in batches while recursively computing their hash values.
+2. **Batch authentication**: Once the batches are assembled, and their hash values computed, they need to be authenticated by the DAC. The sequencer therefore forwards the batch data, and their corresponding hash values to the DAC, as a way to request for signatures.
+3. **Data validation and storage**: The DAC nodes independently validate the batch data against the hash values received from the sequencer. Once validated, each hash value is stored in each DAC node's local database for future reference.
+4. **Signature generation**: Each DAC node generates a signature for each batch hash. This serves as an endorsement of the batch's integrity and authenticity.
+5. **Communication with Ethereum**: The sequencer collects the DAC members' signatures and the original batch hash, and submits them to the Ethereum network for verification.
+6. **Verification on Ethereum**: A designated _multi-sig_ smart contract on Ethereum verifies the submitted signatures against each DAC member's known signatures, and confirms that sufficient approval has been provided for the batch hash.
+7. **Final settlement with zero-knowledge proof**: The aggregator prepares a proof for the batch via the prover and submits it to the Ethereum network. This proof confirms the validity of the transactions in the batch without revealing transaction details. The chain's state gets updated on Ethereum.

docs/cdk/architecture/cdk-zkevm-option.md

@@ -0,0 +1,24 @@
+Polygon zkEVM is a zero-knowledge rollup (or zk-rollup) designed to emulate the Ethereum Virtual Machine.
+
+It is a scaling-solution to Ethereum as it rolls up many transactions into one batch. 
+
+These batches are submitted to the L1, where their integrity is proved and verified before being included in the L1 state.
+
+Proving, verification of batches, and state changes are all controlled by smart contracts.
+
+Most important to understand is the primary path taken by transactions from when users submit these transactions to the zkEVM network up until they are finalized and incorporated in the L1 State. 
+
+Polygon zkEVM achieves this by utilizing several actors. The diagram below depicts the various actors and how they interact.
+
+![zkEVM option architecture](../../img/cdk/cdk-zkevm-arch-overview.png)
+
+Here is an outline of the most prominent rollup components:
+
+- The **users**, who connect to the zkEVM network by means of an RPC node (e.g., Infura or Alchemy), submit their transactions to a database called the pool DB.
+- The **pool DB** is the storage for transactions submitted by users. These are kept in the pool waiting to be put in a batch by the sequencer.
+- The **sequencer** is a node responsible for fetching transactions from the pool DB, checking if the transactions are valid, then putting valid ones into a batch. The sequencer submits all batches to the L1 and then sequences the batches. This process proposes the sequence of batches to be included in the L1 state.
+- The **state DB** is a database for permanently storing state data (but not the Merkle trees).
+- The **synchronizer** is the component that updates the state DB by fetching data from Ethereum through the Etherman.
+- The **Etherman** is a low-level component that implements methods for all interactions with the L1 network and smart contracts.
+- The **aggregator** is another node whose role is to produce proofs attesting to the integrity of the sequencer's proposed state-change. These proofs are zero-knowledge proofs (or ZK-proofs) and the aggregator employs a cryptographic component called the prover for this purpose.
+- The **prover** is a complex cryptographic tool capable of producing ZK-proofs of hundreds of batches, and aggregating these into a single ZK-proof which is published as the validity proof.

docs/cdk/architecture/dac.md

@@ -1,3 +1,7 @@
+---
+comments: true
+---
+
 ## Stavanger
 
 The [CDK Stavanger testnet](https://polygon.technology/cdk-stavanger-testnet) is a validium testnet based on Sepolia.

docs/cdk/get-started/connect-testnet.md

@@ -1,13 +1,16 @@
+---
+comments: true
+---
+
 ## Configure deployment parameters
 
-1. `cd` to the `deployment/` directory and create a new `deploy_parameters.json` by copying the example
+1. Navigate to the contracts deployment directory.
 
-    ```bash
-    cd deployment/
-    cp deploy_parameters.json.example deploy_parameters.json
+    ```sh
+    cd ~/cdk-validium/cdk-validium-contracts-0.0.2/deployment
     ```
 
-2. Run the following `jq` script to streamline the process of replacing these fields:
+2. Run the following `jq` script to streamline the process of replacing the fields with the `/tmp/cdk/.env` data:
 
     ```bash
     source /tmp/cdk/.env
@@ -55,7 +58,7 @@ This is a factory contract that deploys the deterministic contracts required by
 
 The address of the contracts it creates depends on the salt and the `initialCDKValidiumDeployerOwner` inside `deploy_parameters.json`.
 
-1. From the same `deployment` directory, run the deploy script.
+1. From the same `deployment` directory you were already in, run the deploy script.
 
     ```bash 
     npm run deploy:deployer:CDKValidium:sepolia
@@ -144,10 +147,10 @@ If you would rather use a different node provider than Infura, modify the conten
 For example, using Alchemy:
 
 ```bash
-MNEMONIC="island debris exhaust typical clap debate exhaust little verify mean sausage entire"
-INFURA_PROJECT_ID="" # or blank if not using Infura
-ETHERSCAN_API_KEY="1234567890abcdefghijklmnopqr" # or blank if not verify contracts
-ALCHEMY_PROJECT_ID="dGPpsDzM9KpFTEnqMO44rvIXcc0fmgxr" # add this line
+MNEMONIC="test test test test test test test test test test test junk"
+INFURA_PROJECT_ID="" # leave blank when not using Infura
+ETHERSCAN_API_KEY="" # or blank if not verifying contracts
+ALCHEMY_PROJECT_ID="" # add the Alchemy data here
 ```
 
 ```bash

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

@@ -1,3 +1,7 @@
+---
+comments: true
+---
+
 ## Hardware
 
 Make sure you have the following minimum hardware requirements.
@@ -17,10 +21,12 @@ Make sure you have the following minimum software requirements.
 | [Foundry](https://book.getfoundry.sh/getting-started/installation) | ^0.2 | `forge --version` |
 | [jq](https://jqlang.github.io/jq/download/) | ^1.6 | `jq -V` |
 
-## Sepolia access
+## Access to a Sepolia node
+
+Use a node provider like Infura or Alchemy. We use Infura throughout but you can [use a different node provider](deploy-contracts.md#use-a-different-node-provider) if you want.
 
-!!! 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.
+!!! important
+    We recommend running your own Sepolia node for a production set up. 
 
 You will need the following:
 
@@ -35,32 +41,13 @@ Use a public faucet to get Sepolia test ETH.
 - [Chainstack faucet](https://chainstack.com/sepolia-faucet/).
 - [Quicknode faucet](https://faucet.quicknode.com/ethereum/sepoli).
 
-## Configuration files
-
-We will be working with two separate `.env` files.
+## Configuration with environment variables
 
-- 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.
+We will be working with two separate `.env` files to manage the contracts and node configurations.
 
-Create a folder `/tmp/cdk/` to store the shared `.env` file which will be used by all running processes.
-
-```bash
-mkdir /tmp/cdk/
-```
+- One `.env` file resides in the contracts project directory. We will set this up in the [contracts environment variables set up](set-up.md#create-the-contracts-env-configuration) section.
+- Another `.env` resides in a shared system directory, `/tmp/cdk/`, which is accessible to the node and all running processes. We set this up in the [system-wide environment variables set up](set-up.md#create-the-shared-system-env-configuration) section. This shared `.env` file allows us to use `jq` and `tomlq` to easily setup the configuration for the node and running processes.
 
 !!! 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.
-
-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
-    Don't forget: The system removes this file on shutdown.
+    - For this reason, we recommend that you copy this folder and paste it into your home directory once the shared configuration set up is complete. That way, you can just add it back when you need to.