Merge branch 'main' into nadim/pos

Author: nadimkobeissi

README.md

@@ -1,22 +1,61 @@
-# polygon-docs
+# Polygon docs
 
-Polygon Docs website, built using [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/).
+Welcome to the Polygon Docs website, built with [the Material theme for MkDocs](https://squidfunk.github.io/mkdocs-material/).
 
 ## Instructions for use
 
-Please open a branch and we will approve each other's work for now.
+Work on a local branch and request a review from a teammate.
 
-## Running Locally
+## How to run the site locally
 
-### Python
+### Clone the repo
 
-You must have Python 3.11, `pip3` and the `virtualenv` Python package installed. Then, simply run:
+```sh
+git clone https://github.com/0xPolygon/polygon-docs.git
+cd polygon-docs
+```
+
+### Run with Python
+
+1. Download and install Python 3.11: https://www.python.org/downloads/
+
+2. Install the `virtualenv` package:
+
+```sh
+pip install virtualenv
+```
+
+3. Build and serve the html
 
-```bash
+```sh
 ./run.sh
 ```
 
-### Docker
+The site runs at: http://127.0.0.1:8000/
+
+### Run with Docker
+
+1. Run the following commands from the project root:
+
+```sh
+docker build -t polygon-docs .
+docker compose up
+```
+
+### Run manually
+
+1. Download and install Python, as above, and ensure you have installed all the packages listed in `requirements.txt`, e.g.:
+
+```sh
+pip install markdown-include==0.8.1
+```
+
+2. Run the following from the project root to bring up the site:
+
+```sh
+mkdocs serve --strict
+```
+
+## Questions
 
-* `docker build -t polygon-docs .`
-* `docker compose up`
+Feel free to contact the team any time: `#disc_tkd_techdocs`

docs/cdk/concepts/dac.md

@@ -1,15 +1,31 @@
-!!! note
-    fix this: https://medium.com/coinmonks/what-is-data-availability-and-why-do-we-need-it-7993c039fc44
+Data availability in blockchain technology refers to whether or not transaction data is available on-chain or off-chain. 
 
+If data is available on-chain, then each node has to store every piece of data related to every transaction. This can be costly for node operators as hardware and storage requirements are high. Moving data off-chain streamlines node architecture and operations.
 
-A data availability committee (DAC) is an optional offchain network of nodes that provides data to a blockchain network. The advantages are:
+!!! info "Recommended resource"
+    See Ethereum.org's discussion on [data availability](https://ethereum.org/en/developers/docs/data-availability/).
 
-- **Lower transaction fees**: Reduced computational requirements lead to lower fees.
-- **State privacy**: A secure copy of state transitions ensures data integrity and privacy.
+## What is a validium?
 
-DACs store the data required to reconstruct the state of the blockchain and make that data accessible so that, if the blockchain goes down, users can still access their assets and data.
+Validiums are blockchain solutions that do not store transaction data. 
 
-Delegating blockchain data to a DAC in this way can be costly. However, a DAC improves finality and thus supports Enterprise use cases which require cheap and fast transactions with a private and secure data layer.
+!!! info "Recommended resource"
+    See Ethereum.org's glossary [definition of validiums](https://ethereum.org/en/developers/docs/scaling/validium/).
+
+## What is a DAC?
+
+Polygon's CDK validium has an optional data availability committee (DAC).
+
+A DAC is an off-chain network of nodes that implements a data storage layer in a modular chain architecture like CDK. Some advantages are:
+
+- **Lower transaction fees**: Reduced computational requirements lead to lower fees and faster finality on the main network.
+- **Privacy and security**: The DAC stores secure and private transaction data.
+- **Trustless**: Data owners do not have to trust the blockchain operator.
+- **Scalable**: Decoupling data storage from the main chain supports more scalable networks. 
+
+DACs store the data required to reconstruct the state of the blockchain and make that data accessible so that, if the main blockchain network goes down, users can still access their assets and data.
+
+Setting up a DAC can be costly and therefore DACs mostly support Enterprise use cases which require cheap and fast transactions with a private and secure data layer.
 
 The CDK validium DAC is a secure consortium of nodes that ensures off-chain data access. 
 
@@ -31,5 +47,4 @@ The DAC works together with the sequencer to control the flow of data. The proce
 
 6. **Verification on Ethereum**: A designated smart contract on Ethereum verifies the submitted signatures against a list of valid DAC members 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 Ethereum. This proof confirms the validity of the batch's transactions without revealing their details. The chain state updates on Ethereum.
-
+7. **Final settlement with zero-knowledge proof**: The aggregator prepares a proof for the batch via the prover and submits it to Ethereum. This proof confirms the validity of the batch's transactions without revealing their details. The chain state updates on Ethereum.

docs/cdk/edge-suggestion.md

@@ -0,0 +1,10 @@
+!!! note "Recommendation"
+    Follow the [quickstart](quickstart-rollup.md) for a hands-on introduction to CDK in rollup mode.
+
+## Deploy a CDK rollup locally
+
+The [zkEVM deployment quickstart documentation](../..//zkEVM/step1-fullzkevm.md) shows you how to deploy a zkEVM rollup on your local machine.
+
+!!! question
+    What makes this CDK?
+

docs/cdk/get-started/deploy-rollup.md

@@ -1,5 +1,5 @@
 !!! important "Recommendation"
-    Follow the [Quickstart](quickstart-validium.md) for a hands-on introduction to CDK in validium mode.
+    Follow the [quickstart](quickstart-validium.md) for a hands-on introduction to CDK in validium mode.
 
 Follow the steps below to deploy a CDK validium instance.
 
@@ -21,4 +21,7 @@ Follow the instructions in the [CDK validium node repository's README](https://g
 
     Finally, once the CDK validium node is operational, set up and run the data availability node. 
 
-    Instructions for this can be found in the [<ins>CDK DA Node GitHub repository's README</ins>](https://github.com/0xPolygon/cdk-data-availability).
+    Instructions for this can be found in the [<ins>CDK DA Node GitHub repository's README</ins>](https://github.com/0xPolygon/cdk-data-availability).
+
+!!! question
+    What makes this CDK?

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

@@ -12,8 +12,8 @@ CDK users choose a chain architecture specific to their needs and use cases.
 !!! info
     For the latest updates, follow our official GitHub repositories.
 
-    - [Rollup node](https://github.com/0xPolygonHermez/zkevm-node)
-    - [Validium node](https://github.com/0xPolygon/cdk-validium-node)
-    - [Data availability committee](https://github.com/0xPolygon/cdk-data-availability)
-    - [zkEVM smart contracts](https://github.com/0xPolygonHermez/zkevm-contracts)
-    - [Validium smart contracts](https://github.com/0xPolygon/cdk-validium-contracts)
+    - [Rollup node](https://github.com/0xPolygonHermez/zkevm-node).
+    - [Validium node](https://github.com/0xPolygon/cdk-validium-node).
+    - [Data availability committee](https://github.com/0xPolygon/cdk-data-availability).
+    - [zkEVM smart contracts](https://github.com/0xPolygonHermez/zkevm-contracts).
+    - [Validium smart contracts](https://github.com/0xPolygon/cdk-validium-contracts).

docs/cdk/get-started/overview.md

@@ -1,3 +1,8 @@
-Spin up an zkEVM ...
+## Run a CDK rollup locally
 
-Then ...
+The following documentation is a quickstart guide for deploying a CDK rollup on your local machine.
+
+[https://github.com/0xPolygonHermez/zkevm-node/blob/develop/docs/running_local.md](https://github.com/0xPolygonHermez/zkevm-node/blob/develop/docs/running_local.md)
+
+!!! question
+    What makes this CDK?

docs/cdk/get-started/quickstart-rollup.md

@@ -1,8 +1,5 @@
 This quickstart guides you through the process of setting up a CDK validium on your local machine.
 
-!!! danger "Is it true?"
-    Please note that the current Data Availability (DA) configuration in Polygon CDK is using a Data Availability Committee (DAC) node with a local Geth client as the L1. However, the integration with Layer 1 testnets, including Sepoilla, is actively being pursued.
-
 ## Prerequisites
 
 ### System requirements
@@ -12,7 +9,7 @@ This quickstart guides you through the process of setting up a CDK validium on y
 - An AMD64 architecture system.
 
 !!! warning
-    CDK does not support ARM-based Macs
+    CDK does not support ARM-based Macs.
 
 ### Software requirements
 
@@ -41,7 +38,7 @@ cp .env.example .env
 sudo docker-compose pull
 ```
 
-2.2 After pulling the images, start your local CDK Validium:
+2.2 After pulling the images, start your local CDK validium:
 
 ```bash
 sudo make run
@@ -98,7 +95,7 @@ zkevm-bridge-ui                  /bin/sh /app/scripts/deploy.sh   Up
 ```
 </details>
 
-2.3.1 If a service isn't running (i.e. it is in Exit 1 state), investigate further using the logs:
+2.3.1 If a service isn't running (i.e. it is in `Exit 1` state), investigate further using the logs:
 
 ```bash
 sudo docker-compose logs <container_name>
@@ -121,6 +118,9 @@ To restart all services:
 sudo make restart
 ```
 
+!!! note
+    This local deployment runs on an L1 Geth instance.
+
 ## 3. Test validium
 
 3.1 Verify the block explorer is running by navigating to [localhost:4001](http://localhost:4001/). 
@@ -131,7 +131,7 @@ You should see a page similar to this:
   <img src="/img/cdk/cdk-block-explorer-empty.png" alt="bridge" width="90%" height="30%" />
 </div>
 
-### 4. Add the network to a Web3 wallet
+## 4. Add the network to a Web3 wallet
 
 4.1 Follow MetaMask's instructions on [how to set up a network manually](https://support.metamask.io/hc/en-us/articles/360043227612-How-to-add-a-custom-network-RPC).
 
@@ -159,6 +159,9 @@ You should see a page similar to this:
   <img src="/img/cdk/cdk-metamask-import-account.png" alt="bridge" width="90%" height="30%" />
 </div>
 
+!!! danger
+    Today, 21/11, I got stuck here with pending transfers that weren't picked up by blockexplorer.
+
 4.4 Transfer some tokens to another account:
 
 <div align="center">
@@ -181,55 +184,55 @@ You should see a page similar to this:
 
 CDK has a native bridge with UI that allows you to transfer funds between the L1 and the L2 validium.
 
-### L1 to L2
+### 5.1 L1 to L2
 
-5.1 Add the L1 RPC to MetaMask:
+5.1.1 Add the L1 RPC to MetaMask:
 
 <div align="center">
   <img src="/img/cdk/cdk-metamask-add-l1.png" alt="bridge" width="90%" height="30%" />
 </div>
 
-5.2 Switch to the L1 network and you will see the previously imported account with ~999 POL on the L1 chain.
+5.1.2 Switch to the L1 network and you will see the previously imported account with ~999 POL on the L1 chain.
 
-5.3 Verify the bridge UI by navigating to [localhost:8088](http://localhost:8088/). 
+5.1.3 Verify the bridge UI by navigating to [localhost:8088](http://localhost:8088/). 
 
-5.4 Click on **Connect a wallet > MetaMask**.
+5.1.4 Click on **Connect a wallet > MetaMask**.
 
 <div align="center">
   <img src="/img/cdk/cdk-bridge.png" alt="bridge" width="90%" height="30%" />
 </div>
 
-5.5 Select the previously imported account (0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266). Once you are connected, you should see a page like this:
+5.1.5 Select the previously imported account (0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266). Once you are connected, you should see a page like this:
 
 <div align="center">
   <img src="/img/cdk/cdk-bridge-connected.png" alt="bridge" width="90%" height="30%" />
 </div>
 
-5.6 Enter the amount (e.g. 5) to bridge and click **Continue**, you will see the **Confirm Bridge** page. 
+5.1.6 Enter the amount (e.g. 5) to bridge and click **Continue**, you will see the **Confirm Bridge** page. 
 
-5.7 Click **Bridge** and approve the transaction on the MetaMask pop-up:
+5.1.7 Click **Bridge** and approve the transaction on the MetaMask pop-up:
 
 <div align="center">
   <img src="/img/cdk/cdk-bridge-confirm.png" alt="bridge" width="90%" height="30%" />
 </div>
 
-5.8 Once bridging is complete, you should see the **Activity** page:
+5.1.8 Once bridging is complete, you should see the **Activity** page:
 
 <div align="center">
   <img src="/img/cdk/cdk-bridge-completed-l1-to-l2.png" alt="bridge" width="90%" height="30%" />
 </div>
 
-### L2 to L1
+### 5.2 L2 to L1
 
-5.9 Switch network on MetaMask to your validium chain and navigate back to [localhost:8088](http://localhost:8088/). 
+5.2.1 Switch network on MetaMask to your validium chain and navigate back to [localhost:8088](http://localhost:8088/). 
 
-5.10 You should see both the updated L1 and L2 balances:
+5.2.2 You should see both the updated L1 and L2 balances:
 
 <div align="center">
   <img src="/img/cdk/cdk-bridge-l2-to-l1.png" alt="bridge" width="90%" height="30%" />
 </div>
 
-5.11 Enter an amount and follow the same process to bridge the fund back to the L1.
+5.2.3 Enter an amount and follow the same process to bridge the fund back to the L1.
 
 !!! note
     You cannot bridge back fund more than what you have previously bridged from L1 to the L2.
@@ -240,12 +243,15 @@ The L2->L1 bridging is slightly different than L1->L2 and you will see the **Act
   <img src="/img/cdk/cdk-bridge-l2-to-l1-on-hold.png" alt="bridge" width="90%" height="30%" />
 </div>
 
-5.12 Click **Finalise** and approve the transaction (Note: MetaMask will pop up a window to ask you to switch to the L1 network first). Then you will see this once the bridging is completed:
+5.2.4 Click **Finalise** and approve the transaction (Note: MetaMask will pop up a window to ask you to switch to the L1 network first). Then you will see this once the bridging is completed:
 
 <div align="center">
   <img src="/img/cdk/cdk-bridge-l2-to-l1-completed.png" alt="bridge" width="90%" height="30%" />
 </div>
 
 !!! urgent
     - First time, I had an error on step 5.12 -> cannot estimate gas.
-    - Second time, I had an error much earlier on, but that's probably because I didn't clear the images up, even though I restarted. 
+    - Second time, I had an error much earlier on, but that's probably because I didn't clear the images up, even though I restarted. 
+
+!!! question
+    What makes this CDK?

docs/cdk/get-started/quickstart-validium.md

@@ -0,0 +1,40 @@
+
+:::caution Risks
+
+Check the list of potential risks associated with the use of Polygon zkEVM in the [<ins>Risks FAQ</ins>](/zkevm/risk-disclosure.md) section.
+
+:::
+
+
+## Get Started with Web3Modal
+
+:::caution Content disclaimer
+
+Please view the third-party content disclaimer [<ins>here</ins>](https://github.com/0xPolygon/wiki/blob/master/CONTENT_DISCLAIMER.md).
+
+:::
+
+### Overview
+
+[<ins>Web3Modal</ins>](https://web3modal.com/) is a simple and intuitive SDK that provides a drop-in UI to enable users of any wallet to seamlessly log in to applications, offering a unified and smooth experience. It features a streamlined wallet selection interface with automatic detection of various wallet types, including mobile, extension, desktop, and web app wallets.
+
+### Code Sandbox for Polygon
+
+The Web3Modal team has prepared a [<ins>Polygon Code Sandbox</ins>](https://codesandbox.io/p/sandbox/web3modal-v3-polygon-7264l5?file=/src/main.tsx:9,19-9,50). It’s a straightforward way for developers to integrate and get hands-on experience with Polygon.
+
+### How to Integrate
+
+1. **Visit Web3Modal:** Go to [<ins>Web3Modal's official website</ins>](https://web3modal.com/) to explore its features and capabilities.
+2. **Explore the Code Sandbox:** Utilize the [<ins>Polygon Code Sandbox</ins>](https://codesandbox.io/p/sandbox/web3modal-v3-polygon-7264l5?file=/src/main.tsx:9,19-9,50) to demo and understand the integration process.
+3. **Follow the Documentation:** Refer to the provided documentation and instructions to integrate Web3Modal into your projects and leverage its features effectively.
+
+## zkEVM Support
+
+If you need help with anything related to the Polygon zkEVM, you can raise a ticket on the [Polygon Support](https://support.polygon.technology/support/tickets/new) portal, and check out the [Knowledge base](https://support.polygon.technology/support/solutions/folders/82000694871) to view the most common queries about the zkEVM. Additionally, you can reach out to the support team available on the **#zkevm-support** channel on the [Polygon Discord server](https://discord.com/invite/XvpHAxZ). Instructions for raising a zkEVM support ticket are as follows:
+
+1. Join the **Polygon Discord** server [here](https://discord.gg/0xPolygon).
+2. Accept the invite sent via DM.
+3. Take the **Member** role under **#roles**.
+4. Navigate to the **#zkevm-support** channel.
+
+You can now contact the zkEVM support staff with your questions and concerns. We will actively monitor for issues and work to resolve them as soon as possible.