docs: move to mkdocs-material platform, editorial, and later import i…

…nto the Knowledge Layer (0xPolygon#54)

* first commit

* finish user flow

* last chunk of first draft

* Update docs/quickstart/mac-troubles.md

Co-authored-by: Léo Vincent <[email protected]>

* Update docs/quickstart/mac-troubles.md

Co-authored-by: Léo Vincent <[email protected]>

* Update docs/quickstart/breakdown-deployment.md

Co-authored-by: Léo Vincent <[email protected]>

* Update docs/quickstart/deploy-stack.md

Co-authored-by: Léo Vincent <[email protected]>

* Update docs/quickstart/deploy-stack.md

Co-authored-by: Léo Vincent <[email protected]>

* doc: move trigger-a-reorg section to docs-draft

* chore: move serve docs script to scripts folder

* fix: shellcheck issue

* updating the stages steps

* fix script move requirements

---------

Co-authored-by: Léo Vincent <[email protected]>
Co-authored-by: leovct <[email protected]>

.gitignore

@@ -2,3 +2,19 @@
 bridge-deposits.json
 claimable-txs.json
 proof.json
+
+# docs
+.vscode
+.code
+.idea
+site/
+venv/
+env/
+*.out
+node_modules/
+.DS_Store
+**/.DS_Store
+*.iml
+temp_dir/
+package-lock.json
+package.json

docs/README.md

@@ -0,0 +1,38 @@
+# Kurtosis CDK documentation
+
+Welcome to the Kurtosis docs.
+
+## Running 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 `scripts/serve_docs.sh` script. You may need to make the script executable: `chmod +x scripts/serve_docs.sh`
+
+```sh
+sh scripts/serve_docs.sh
+```
+
+The site comes up at http://127.0.0.1:8000/
+
+## Style guide
+
+We are using the [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/).
+
+## Contributing
+
+1. Add your draft documentation to `doc-drafts` and test it there.
+2. When you're happy with it, raise a ticket on our [slack channel](https://slack.com/shortcuts/Ft0613JADARL/ea28ee64d7fcc12fd40b0eb310b583d3), or [JIRA board](https://polygon.atlassian.net/jira/software/projects/DOCS/boards/79) to let us know, and we'll incorporate it into the docs.
+
+## Contact
+
+- For technical issues, join our [Discord](https://discord.gg/0xpolygondevs).
+- For documentation issues, raise an issue on the published live doc at [our main repo](https://github.com/0xPolygon/polygon-docs).
+
+</br>

docs/overview.md

@@ -0,0 +1,21 @@
+---
+hide:
+- toc
+---
+
+# Overview
+
+The architectural diagram below shows how CDK stack components may interact with each other and a layer 1 blockchain.
+
+</br>
+
+![Architecture](img/architecture.png)
+
+<br/>
+
+The [quick start documents](quickstart/deploy-stack.md) show you how to deploy a private, portable, and modular Polygon CDK developer stack with [Kurtosis](https://github.com/kurtosis-tech/kurtosis).
+
+The deployment document is aimed at users and developers who do not necessarily want to run the latest CDK versions, or follow the full tutorials, and are happy to play around with an experimental set up.
+
+<br/>
+

docs/quickstart/breakdown-deployment.md

@@ -0,0 +1,92 @@
+Rather than executing the deployment process as a monolithic operation, you can break it down into stages and run each stage separately.
+
+### Enable or disable stages
+
+You can enable a stage by setting the boolean value to `true` and disable it by setting it to `false`, in the [`params.yml`](https://github.com/0xPolygon/kurtosis-cdk/blob/main/params.yml) file.
+
+!!! important
+    - By default, all stages are executed.
+
+## Deployment stages
+
+Currently, the deployment process includes the following stages:
+
+  1. Deploy Local L1.
+  2. Deploy zkEVM contracts on L1.
+  3. Deploy zkEVM node and CDK peripheral databases.
+  4. Deploy CDK central/trusted environment.
+  5. Deploy CDK/bridge infrastructure.
+  6. Deploy permissionless node.
+
+## Specifying stages
+
+The example scripts below show you how to deploy the stack to enable various stage permutations. 
+
+!!! tip
+    To run the scripts, you need to have [yq](https://pypi.org/project/yq/) installed.
+
+### Disable all deployment steps
+
+```sh
+yq -Yi '.deploy_l1 = false' params.yml
+yq -Yi '.deploy_zkevm_contracts_on_l1 = false' params.yml
+yq -Yi '.deploy_databases = false' params.yml
+yq -Yi '.deploy_cdk_central_environment = false' params.yml
+yq -Yi '.deploy_cdk_bridge_infra = false' params.yml
+yq -Yi '.deploy_zkevm_permissionless_node = false' params.yml
+```
+
+### Deploy L1
+
+```sh
+yq -Yi '.deploy_l1 = true' params.yml
+kurtosis run --enclave cdk-v1 --args-file params.yml .
+yq -Yi '.deploy_l1 = false' params.yml # reset
+# Perform additional tasks...
+```
+
+### Deploy zkEVM contracts on L1
+
+```sh
+yq -Yi '.deploy_zkevm_contracts_on_l1 = true' params.yml
+kurtosis run --enclave cdk-v1 --args-file params.yml --image-download always .
+yq -Yi '.deploy_zkevm_contracts_on_l1 = false' params.yml # reset
+# Perform additional tasks...
+```
+
+### Deploy zkEVM node and CDK peripheral databases
+
+```sh
+yq -Yi '.deploy_databases = true' params.yml
+kurtosis run --enclave cdk-v1 --args-file params.yml .
+yq -Yi '.deploy_databases = false' params.yml # reset
+# Perform additional tasks...
+```
+
+### Deploy CDK central environment
+
+```sh
+yq -Yi '.deploy_cdk_central_environment = true' params.yml
+kurtosis run --enclave cdk-v1 --args-file params.yml .
+yq -Yi '.deploy_cdk_central_environment = false' params.yml # reset
+# Perform additional tasks...
+```
+
+### Deploy CDK bridge infrastructure
+
+```sh
+yq -Yi '.deploy_cdk_bridge_infra = true' params.yml
+kurtosis run --enclave cdk-v1 --args-file params.yml .
+yq -Yi '.deploy_cdk_bridge_infra = false' params.yml # reset
+# Perform additional tasks...
+```
+
+### Deploy zkEVM permissionless node
+
+```sh
+yq -Yi '.deploy_zkevm_permissionless_node = true' params.yml
+kurtosis run --enclave cdk-v1 --args-file params.yml .
+yq -Yi '.deploy_zkevm_permissionless_node = false' params.yml # reset
+```
+
+<br/>

docs/quickstart/deploy-stack.md

@@ -0,0 +1,181 @@
+## 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. 
+
+!!! tip
+    - Please follow the [MacOS troubleshooting instructions](mac-troubles.md) to avoid issues that may occur when running the stack on MacOS.
+
+## Prerequisites
+
+1. Install [Kurtosis](https://docs.kurtosis.com/install/).
+
+2. Install the [Foundry toolchain](https://book.getfoundry.sh/getting-started/installation).
+
+3. Run the following script to check you have the remaining required tools and install where missing.
+
+    ```sh
+    curl -s https://raw.githubusercontent.com/0xPolygon/kurtosis-cdk/main/scripts/tool_check.sh | bash
+    ``` 
+
+## Set up 
+
+1. Clone the repo and `cd` into it.
+
+    ```sh
+    git clone https://github.com/0xPolygon/kurtosis-cdk.git
+    cd kurtosis-cdk
+    ```
+
+2. Make sure Docker is running.
+
+3. Run the Kurtosis enclave.
+
+    ```
+    kurtosis run --enclave cdk-v1 --args-file params.yml --image-download always .
+    ```
+
+    This command takes a few minutes to complete and steps up and runs an entire local CDK deployment. 
+
+When everything is set up and running, we can play around with the test CDK. 
+
+## Simple RPC calls
+
+### Inspect the stack
+
+```sh
+kurtosis enclave inspect cdk-v1
+```
+
+You should see a long output that starts like this:
+
+```sh
+Name:            cdk-v1
+UUID:            47d8679066a6
+Status:          RUNNING
+Creation Time:   Wed, 10 Apr 2024 13:58:13 CEST
+Flags:           
+
+========================================= Files Artifacts =========================================
+UUID   Name
+```
+
+### Check port mapping
+
+To see the port mapping within the `cdk-v1` enclave for the `zkevm-node-rpc` service and the
+`trusted-rpc` port, run the following command:
+
+```sh
+kurtosis port print cdk-v1 zkevm-node-rpc-001 http-rpc
+```
+
+You should see output that looks something like this (but won't necessarily be the same):
+
+```sh
+http://127.0.0.1:65240
+```
+
+### Set an environment variable
+
+Let's map the output from the previous step to an environment variable that we can use throughout these instructions.
+
+```sh
+export ETH_RPC_URL="$(kurtosis port print cdk-v1 zkevm-node-rpc-001 http-rpc)"
+```
+
+### Test cast commands
+
+This is the same environment variable that `cast` uses, so you should now be able to run the following command:
+
+```sh
+cast block-number
+```
+
+You should see something like this:
+
+```sh
+890
+```
+
+### Pre-funded account
+
+By default, the CDK is configured in test mode, and this means there is some pre-funded ETH in the admin account that has address: `0xE34aaF64b29273B7D567FCFc40544c014EEe9970`.
+
+Check the balance with the following: 
+
+```sh
+cast balance --ether 0xE34aaF64b29273B7D567FCFc40544c014EEe9970
+```
+
+You should see something like this:
+
+```txt
+100000.000000000000000000
+```
+
+### Send transaction with cast
+
+```sh
+cast send --legacy --private-key 0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625 --value 0.01ether 0x0000000000000000000000000000000000000000
+```
+
+You should see something like this as output:
+
+```sh
+blockHash               0xc467523f297a9c0b859bedc8feaf44c3e7462de56f7d7899b2039d9a3cfc421d
+blockNumber             70
+contractAddress         
+cumulativeGasUsed       21000
+effectiveGasPrice       1000000000
+from                    0xE34aaF64b29273B7D567FCFc40544c014EEe9970
+gasUsed                 21000
+logs                    []
+logsBloom               0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+root                    
+status                  1
+transactionHash         0xa58b3383c1b1f53369723fdc537c88daa03585cb6a89aa49ebd493953d519fdf
+transactionIndex        0
+type                    0
+to                      0x0000000000000000000000000000000000000000
+```
+
+### Send transactions with `polygon-cli`
+
+```sh
+polycli loadtest --requests 500 --legacy --rpc-url $ETH_RPC_URL --verbosity 700 --rate-limit 5 --mode t --private-key 0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625
+polycli loadtest --requests 500 --legacy --rpc-url $ETH_RPC_URL --verbosity 700 --rate-limit 10 --mode t --private-key 0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625
+polycli loadtest --requests 500 --legacy --rpc-url $ETH_RPC_URL --verbosity 700 --rate-limit 10 --mode 2 --private-key 0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625
+polycli loadtest --requests 500 --legacy --rpc-url $ETH_RPC_URL --verbosity 700 --rate-limit 3 --mode uniswapv3 --private-key 0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625
+cast nonce 0xE34aaF64b29273B7D567FCFc40544c014EEe9970
+```
+
+### Check the logs
+
+```sh
+kurtosis service logs cdk-v1 zkevm-agglayer-001
+```
+
+You can open a shell on any service.
+
+```sh
+kurtosis service shell cdk-v1 zkevm-node-sequencer-001
+```
+
+Another common way to check the status of the system is to make sure that batches go through the normal progression of `trusted`, `virtual`, and `verified`. To check this run:
+
+```sh
+cast rpc zkevm_batchNumber
+cast rpc zkevm_virtualBatchNumber
+cast rpc zkevm_verifiedBatchNumber
+```
+
+### Clean up
+
+When everything is done, you might want to clean up with this command which stops everything and deletes it.
+
+```sh
+kurtosis clean -a
+```
+
+</br>