Getting started guide

jarrodwatts · jarrodwatts · commit 24bd31946a06 · 2024-06-03T17:30:23.000+10:00
diff --git a/docs/cdk/getting-started.md b/docs/cdk/getting-started.md
@@ -14,7 +14,7 @@ To run the Polygon CDK locally, the following prerequisites are required:
 **Hardware Requirements:**
 
 - A Linux-based Operating System (or [WSL](https://learn.microsoft.com/en-us/windows/wsl/about))
-- 8GB RAM with a 2-core CPU
+- Minimum 8GB RAM and 2-core CPU
 - An AMD64 architecture system
 
 **Software Dependencies:**
@@ -49,14 +49,14 @@ If everything is installed correctly, you should see the following output:
 
 ```bash
 Checking that you have the necessary tools to deploy the Kurtosis CDK package...
-✅ kurtosis 0.89.12 is installed, meets the requirement (=0.89).
-✅ docker 25.0.3 is installed, meets the requirement (>=24.7).
+✅ kurtosis is installed, meets the requirement (=0.89).
+✅ docker is installed, meets the requirement (>=24.7).
 
 You might as well need the following tools to interact with the environment...
-✅ jq 1.7.1 is installed.
-✅ yq 3.2.3 is installed, meets the requirement (>=3.2).
-✅ cast 0.2.0 is installed.
-✅ polycli v0.1.43-5-g73ad3f4 is installed.
+✅ jq is installed.
+✅ yq is installed, meets the requirement (>=3.2).
+✅ cast is installed.
+✅ polycli is installed.
 
 🎉 You are ready to go!
 ```
@@ -70,19 +70,22 @@ To begin understanding the codebase, there are two key files to inspect:
 
 #### main.star
 
-The `main.star` file defines the step-by-step process of the deployment process. It is the main "hub" of the chain setup process; orchestrating the setup of all the components in sequential order by pulling in necessary logic from other files.
+The `main.star` file defines the step-by-step instructions of the deployment process. It is the main "hub" of the chain setup process; orchestrating the setup of all the components in sequential order by pulling in necessary logic from other files.
 
-By default, this script performs the following steps:
+It defines the following steps for the deployment process:
 
-1. Deploy a local layer 1 devnet chain ([ethereum.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/ethereum.star))
-2. Deploy the zkEVM smart contracts on the L1 ([deploy_zkevm_contracts.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/deploy_zkevm_contracts.star))
-3. Deploy the zkEVM node and CDK peripheral databases ([databases.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/databases.star))
-4. Deploy the CDK central environment ([cdk_central_environment.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/cdk_central_environment.star))
-5. Deploy the bridge infrastructure ([cdk_bridge_infrastructure.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/cdk_bridge_infra.star))
-6. Deploy the permissionless node ([zkevm_permissionless_node.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/zkevm_permissionless_node.star))
-7. Deploy the observability stack and block explorer ([observability.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/observability.star) and [blockscout.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/blockscout.star))
-8. Apply a load test to the chain ([load_test.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/workload.star))
-9. Deploy [Blutgang](https://github.com/rainshowerLabs/blutgang) for load balancing & caching ([cdk_blutgang.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/cdk_blutgang.star))
+| Step Number | Deployment Step                                                                            | Relevant Starlark Code                                                                                               | Enabled by Default |
+| ----------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | ------------------ |
+| 1           | Deploy a local layer 1 devnet chain                                                        | [ethereum.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/ethereum.star)                                   | True               |
+| 2           | Deploy the zkEVM smart contracts on the L1                                                 | [deploy_zkevm_contracts.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/deploy_zkevm_contracts.star)       | True               |
+| 3           | Deploy the zkEVM node and CDK peripheral databases                                         | [databases.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/databases.star)                                 | True               |
+| 4           | Deploy the CDK central environment                                                         | [cdk_central_environment.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/cdk_central_environment.star)     | True               |
+| 5           | Deploy the bridge infrastructure                                                           | [cdk_bridge_infrastructure.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/cdk_bridge_infra.star)          | True               |
+| 6           | Deploy the permissionless node                                                             | [zkevm_permissionless_node.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/zkevm_permissionless_node.star) | False              |
+| 7           | Deploy the observability stack                                                             | [observability.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/observability.star)                         | True               |
+| 8           | Deploy the block explorer                                                                  | [blockscout.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/blockscout.star)                               | False              |
+| 9           | Apply a load test to the chain                                                             | [load_test.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/workload.star)                                  | False              |
+| 10          | Deploy [Blutgang](https://github.com/rainshowerLabs/blutgang) for load balancing & caching | [cdk_blutgang.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/cdk_blutgang.star)                           | False              |
 
 You can customize (or skip) the logic for each of these steps by modifying the logic in the respective files.
 
@@ -94,17 +97,137 @@ You can modify each of these parameters to customize the chain to your specific
 
 ## Running the Chain Locally
 
-Use the [kurtosis clean](https://docs.kurtosis.com/clean) and [kurtosis run](https://docs.kurtosis.com/run) commands to begin the deployment process. Run the following commands to begin executing the `main.star` script and start the deployment process:
+First run the [kurtosis clean](https://docs.kurtosis.com/clean) to remove any existing Kurtosis environments:
 
 ```bash
 kurtosis clean --all
-kurtosis run --enclave cdk-v1 --args-file params.yml --image-download always .
 ```
 
-This command typically takes around 10 minutes to complete. It will output the logs of each step in the deployment process, allowing you to monitor the progress of the chain setup.
+Then, in the `kurtosis-cdk` directory, use the [kurtosis run](https://docs.kurtosis.com/run) command to deploy the chain on your local machine by executing the `main.star` script provided with the `params.yml` configuration file:
+
+```bash
+kurtosis run --enclave cdk-v1 --args-file params.yml --image-download always .
+```
 
 !!! info
 
-     - `--encalve cdk-v1` specifies the name of the [enclave](https://docs.kurtosis.com/advanced-concepts/enclaves/) (isolated environment) to use for the deployment process.
+     - `--enclave cdk-v1` specifies the name of the [enclave](https://docs.kurtosis.com/advanced-concepts/enclaves/) (isolated environment) to use for the deployment process.
      - `--args-file params.yml` specifies the configuration file to use for the deployment process.
      - `--image-download always` specifies to always download the latest Docker images for the deployment process.
+
+This command typically takes around 10 minutes to complete and outputs the logs of each step in the deployment process for you to monitor the progress of the chain setup. Once the command is complete, you should see the following output:
+
+```bash
+Starlark code successfully run. No output was returned.
+
+===============================================
+||          Created enclave: cdk-v1          ||
+===============================================
+Name:            cdk-v1
+Status:          RUNNING
+
+========================================= Files Artifacts =========================================
+
+... List of files generated during the deployment process ...
+
+========================================== User Services ==========================================
+
+... List of services with "RUNNING" status - none should be "FAILED"! ...
+
+```
+
+Run `kurtosis enclave inspect cdk-v1` to see the status of the enclave and the services running within it at any time.
+
+## Interacting with the Chain
+
+Now that your chain is running, you can explore and interact with each component!
+
+Below are a few examples of how you can interact with the chain.
+
+### Sending Test Transactions
+
+Let&rsquo;s perform some basic read and write operations on the L2 using Foundry.
+
+Export the RPC URL of your L2 to an environment variable called `ETH_RPC_URL` with the following command:
+
+```bash
+export ETH_RPC_URL="$(kurtosis port print cdk-v1 zkevm-node-rpc-001 http-rpc)"
+```
+
+Then, use `cast` to view information about the chain, such as the latest block number:
+
+```bash
+cast block-number
+```
+
+View the balance of an address, such as the pre-funded admin account:
+
+```bash
+cast balance --ether 0xE34aaF64b29273B7D567FCFc40544c014EEe9970
+```
+
+Send simple transactions to the chain, such as a transfer of some ETH:
+
+```bash
+cast send --legacy --value 0.01ether 0x0000000000000000000000000000000000000000 --private-key "0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625"
+```
+
+!!! info
+
+      The `0xE34...9970` and `0x12d...c625` public-private key pair used in the above commands is the default admin account configured in `params.yml`.
+
+### Load Testing the Chain
+
+Use the [polycli loadtest](https://github.com/maticnetwork/polygon-cli/blob/main/doc/polycli_loadtest.md) command to send multiple transactions at once to the chain to test its performance:
+
+```bash
+polycli loadtest --rpc-url "$ETH_RPC_URL" --legacy --verbosity 700 --requests 500 --rate-limit 5 --mode t --private-key "0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625"
+```
+
+### Viewing Transaction Finality
+
+A common way to check the status of the system is to ensure that batches are being sent and verified on the L1 chain.
+
+Use `cast` to view the progression of batches from trusted, virtual, and verified states:
+
+```bash
+cast rpc zkevm_batchNumber          # Latest batch number on the L2
+cast rpc zkevm_virtualBatchNumber   # Latest batch received on the L1
+cast rpc zkevm_verifiedBatchNumber  # Latest batch verified or "proven" on the L1
+```
+
+### Opening the Bridge UI
+
+To open the bridge interface and bridge tokens across the L1 and L2, run the following command:
+
+```bash
+open $(kurtosis port print cdk-v1 zkevm-bridge-proxy-001 bridge-interface)
+```
+
+### Viewing Chain Metrics
+
+To view information such as how many transactions are being processed, the amount of gas being used, the time since a batch was last verified, how many addresses have bridged, and much more, a Grafana dashboard is included in the deployed observability stack which can be opened by running the following command:
+
+```bash
+open $(kurtosis port print cdk-v1 grafana-001 dashboards)
+```
+
+From the hamburger menu, navigate to `Dashboards` and select the `Panoptichain` dashboard to view all of the metrics.
+
+![Panoptichain Dashboard](../img/cdk/grafana.png)
+
+### Stopping the Chain
+
+If you want to **stop** the chain and remove all the containers, run the following command:
+
+```bash
+kurtosis clean --all
+```
+
+## Going to Production
+
+While it is possible to run a CDK chain on your own, we strongly recommend getting in touch with one of our [Implementation Providers](https://ecosystem.polygon.technology/spn/cdk/) for production deployments.
+
+## Dive Deeper into the CDK
+
+For more detailed information on the CDK&rsquo;s architecture, components, and how to customize your chain, refer to the [CDK architecture documentation](https://docs.polygon.technology/cdk/architecture/cdk-zkevm/).
diff --git a/docs/cdk/overview.md b/docs/cdk/overview.md
@@ -1,16 +1,28 @@
-The Polygon Chain Development Kit (CDK) is an open-source stack to build layer 2 blockchains powered by zero-knowledge (ZK) proofs.
+The Polygon Chain Development Kit (CDK) is an open-source stack to build sovereign layer 2 blockchains powered by zero-knowledge (ZK) proofs.
 
-It consists of several modular components, many of which are used to power the Polygon zkEVM in production today, that are designed to be fully composable; empowering developers to customize each component and build a chain that meets their specific needs.
+It consists of modular components designed to be fully composable; empowering developers to customize each aspect of their chain to meet their specific needs.
 
-## Why Build With the CDK?
+## What is the CDK?
+
+## CDK Features
+
+- **Scalability**: todo
+
+- **Sovereignity**: todo
+
+- **Modularity**: todo
+
+- **Interoperability**: todo
+
+## Why Use the CDK?
 
 The CDK bootstraps the development process of creating a layer 2 blockchain. Developers can easily set up the stack and begin configuring each component&rsquo;s behavior with a fast feedback loop on a local development environment.
 
 As logic is separated into modular components, developers can easily swap out components in a "plug and play" fashion to customize their chain, for example, by replacing entire components such as the data availability layer, or making granular-level configurations to each component; such as modifying the sequencer logic to comply with legal regulations.
 
 ### Tap Into the AggLayer
 
-By default, CDK chains are opted into the Aggregation Layer (AggLayer) which enables cross-chain transactions among other L2 chains that are also opted into the AggLayer including the Polygon zkEVM.
+By default, CDK chains are opted into the Aggregation Layer (AggLayer) which enables cross-chain transactions among other L2 chains that are also opted into the AggLayer, including the [Polygon zkEVM](https://docs.polygon.technology/zkEVM/).
 
 This provides a powerful network effect by enabling users to interact with smart contracts on your chain without having to manually bridge assets to it. This is especially useful for developers looking to bootstrap their chain&rsquo;s ecosystem and have immediate access to a large pool of users and liquidity.
 
diff --git a/docs/img/cdk/grafana.png b/docs/img/cdk/grafana.png
