From 5295d37d6aa3d2d288a328ac310438ce5bfe265e Mon Sep 17 00:00:00 2001 From: Daniel Helm Date: Mon, 26 Aug 2024 13:21:05 -0500 Subject: [PATCH] first adjustment for prod readiness --- .../docs/en/sdk/guides/devnet-deployment.mdx | 323 ++++++++++++++++++ .../docs/en/sdk/guides/run-on-arm64-mac.mdx | 4 + .../en/sdk/technical-stack/configuration.mdx | 4 + .../docs/en/sdk/technical-stack/contracts.mdx | 9 +- .../docs/en/sdk/technical-stack/index.mdx | 145 +++++++- .../docs/en/sdk/technical-stack/services.mdx | 4 + 6 files changed, 472 insertions(+), 17 deletions(-) create mode 100644 src/content/docs/en/sdk/guides/devnet-deployment.mdx diff --git a/src/content/docs/en/sdk/guides/devnet-deployment.mdx b/src/content/docs/en/sdk/guides/devnet-deployment.mdx new file mode 100644 index 000000000..12593f8a7 --- /dev/null +++ b/src/content/docs/en/sdk/guides/devnet-deployment.mdx @@ -0,0 +1,323 @@ +--- +section: sdk +date: Last Modified +title: "Running Scroll SDK Devnet" +lang: "en" +permalink: "sdk/guides/devnet-deploymnet" +excerpt: "Run the Scroll SDK devnet locally to get started." +--- + +import Aside from "../../../../../components/Aside.astro" +import ToggleElement from "../../../../../components/ToggleElement.astro" +import Steps from '../../../../../components/Steps/Steps.astro'; + +TODO: MODIFY ALL OF THIS TO NOT BE ARCH SPECIFIC!! + + + +## Overview + +This guide should get you started with running a local Scroll SDK devnet on your mac laptop with an `arm64` processor. + +This guide assumes you’ve taken a look at the [Early Access document](https://www.notion.so/Scroll-SDK-Early-Access-Feedback-Request-74272ce6a0ae4c1d8f5c1d836df1f410?pvs=21) and have access to the [scroll-sdk github repo](https://github.com/scroll-tech/scroll-sdk) using your local machine. + +We’ve written this guide because local deployments for Kubernetes clusters can be finicky. + +By the end of the guide, you should have a Scroll SDK running with a block explorer, RPC, webUI, monitoring and metrics, and a local L1 — all accessible to wallets, browsers, and applications running on your local machine. + + + + + + +
Updates to the Guide
+ + + - July 31, 2024 + - Adding additional `make` commands and `minikube` config + - June 26, 2024 + - Minor typography fixes i.e. `docker v` to `docker -v` + - June 19, 2024 + - Removed external `bjw-s` dependency and prerequisite + - Removed manual modification of `.env.frontends` + - Updated docker image name used in generating config files + - June 18, 2024 + - Fixed `minikube addons enable` commands (missing “addons”) + + + + +## Prerequisites + +1. Clone the repo onto your local machine. +2. Install dependencies (using `brew` is strongly recommended): + - [Brew](https://brew.sh/) (optional) + - `/bin/bash -c "$(curl -fsSL [https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh](https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh))"` + - [Docker Desktop](https://docs.docker.com/desktop/install/mac-install/) + - `brew install --cask docker` + - [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl-macos/) + - `brew install kubectl` + - [minikube](https://minikube.sigs.k8s.io/docs/start/?arch=%2Fmacos%2Farm64%2Fstable%2Fhomebrew) + - `brew install minikube` + - [Helm](https://helm.sh/docs/intro/install/#from-homebrew-macos) + - `brew install helm` + - [docker-mac-net-connect](https://github.com/chipmk/docker-mac-net-connect) + - `brew install chipmk/tap/docker-mac-net-connect` +3. *Optional:* Install dependencies for example helper scripts + - [yq](https://mikefarah.gitbook.io/yq) + - `brew install yq` + - [Foundry](https://getfoundry.sh/) + - `curl -L https://foundry.paradigm.xyz | bash` +4. You should now be able to open a terminal and run the following: + - `docker -v` + - `kubectl version` + - `minikube status` + - `helm version` + + + + +### Starting minikube + +To start minikube, run: + +```bash +minikube start --driver=docker +``` + +#### Getting minikube to work with custom DNS names on MacOS + +Now run the following commands: + +```bash +minikube ssh "sudo apt-get update && sudo apt-get -y install qemu-user-static" +minikube addons enable ingress +minikube addons enable ingress-dns +sudo brew services start chipmk/tap/docker-mac-net-connect +``` + + + +## Installing Scroll SDK + + +1. **Clone the `scroll-sdk` repo** + + *You’ll need If you need repo access, reach out to `@dghelm` on Telegram.* + + ```bash + git clone git@github.com:scroll-tech/scroll-sdk.git + ``` + +1. **Configure `values.yaml` and `config.toml`** + + This is the time to adjust what services run on your stack and their configuration. I’d suggest not altering these on your first installation, but see `charts/scroll-stack/values.yaml` ([view on Github](https://github.com/scroll-tech/scroll-sdk/blob/develop/charts/scroll-stack/values.yaml)) and `config.toml` ([view on Github](https://github.com/scroll-tech/scroll-sdk/blob/develop/charts/scroll-stack/config.toml)). + +1. **Bootstrap** + + Now we'll install Helm chart dependencies, generate additional config files for our services, and create our `genesis.json` file. + + ```bash + make bootstrap + ``` + + + +1. **Launch the chain!** + + ```bash + make install + ``` + + Your chain is now starting! Run `kubectl get pods` to check in on their progress. In the next section we’ll expose the chain to your local machine so you can interact with the stack. + + + + +## After Launching the Stack + +### Funding SDK Addresses + +You will need to provide funds to the following accounts: + + - `DEPLOYER_ADDR` *(only needs funded on L1)* + - `L1_COMMIT_SENDER_ADDR` + - `L1_FINALIZE_SENDER_ADDR` + - `L1_GAS_ORACLE_SENDER_ADDR` + - `L2_GAS_ORACLE_SENDER_ADDR` *(funded after L2 chain deployment)* + +If you installed the necessary prerequisites, you can run the example script from the repo's base directory. + +```bash +chmod +x examples/*.sh +./example/anvil-fund-accounts.sh +``` + +### Other Useful Commands + +`kubectl get pods` will show all the active pods and their status. + +`kubectl get ingress` will show all the exposed services and URIs. + +`make uninstall` will stop all services. + +`minikube dashboard` launches a WebUI for exploring the kubernetes cluster and the various pods, volumes and ingresses without learning all the CLI commands. + +Other example scripts can be used to generate traffic on the L1 or L2 to produce blocks more quickly. Try `./examples/l2-generate-txs.sh`. + +If you need to update a specific service's config file: + 1. Make any necessary changes to the config or helm charts + 2. Run `make upgrade` + 3. Delete the running pod by running `kubectl delete pod [pod-name]` + +### Pointing DNS Requests to the Cluster + +Running `kubectl get ingress` should show all the domains setup within the cluster, like the following: + +``` +➜ scroll-stack git:(develop) ✗ kubectl get ingress +NAME CLASS HOSTS ADDRESS PORTS AGE +blockscout nginx blockscout.scrollsdk 192.168.49.2 80 5h3m +bridge-history-api nginx bridge-history-api.scrollsdk 192.168.49.2 80 5h3m +frontends nginx frontends.scrollsdk 192.168.49.2 80 5h3m +grafana nginx grafana.scrollsdk 192.168.49.2 80 5h3m +l1-devnet nginx l1-devnet.scrollsdk 192.168.49.2 80 5h3m +l1-explorer nginx l1-devnet-explorer.scrollsdk 192.168.49.2 80 5h3m +l2-rpc nginx l2-rpc.scrollsdk 192.168.49.2 80 5h3m +rollup-explorer-backend nginx rollup-explorer-backend.scrollsdk 192.168.49.2 80 5h3m +rpc-gateway nginx l2-rpc-gateway.scrollsdk 192.168.49.2 80 5h3m +``` + +Now, we’ll follow the instructions from [the minikube docs](https://minikube.sigs.k8s.io/docs/handbook/addons/ingress-dns/#Mac) for setting up our local machine to use our cluster to resolve all `.scrollsdk` domain requests. + +Take note of the `ADDRESS` in your output (it should match the result of running `minikube ip`). + +You’ll want to create the following file at `/etc/resolver/minikube-scrollsdk` (will require `sudo` access). + +``` +domain scrollsdk +nameserver +search_order 1 +timeout 5 +``` + +If you prefer, this can be done in one command that creates the directory and file and then outputs the required info: + +```bash +sudo mkdir -p /etc/resolver && sudo touch /etc/resolver/minikube-scrollsdk && sudo sudo sh -c "cat >>/etc/resolver/minikube-scrollsdk" <<-EOF + + domain scrollsdk + nameserver $(minikube ip) + search_order 1 + timeout 5 +EOF +``` + +Lastly, flush your DNS: + +```bash +sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder +``` + +#### Testing Ingress DNS + +Try running: + +1. `nslookup frontends.scrollsdk $(minikube ip)` +2. `curl frontends.scrollsdk` +3. If those work, visit [`http://frontends.scrollsdk`](http://frontends.scrollsdk) in your browser. + 1. If those do not work, try resetting your machine and running through the instructions in [Getting minikube to work with custom DNS names on MacOS](https://www.notion.so/Getting-minikube-to-work-with-custom-DNS-names-on-MacOS-e40ae30777ec4dd083e71d37ead1a185?pvs=21) and above again. It may help to run `minikube stop` and `minikube start` again. + +## Interacting with the Chain + + + +### Web UIs + +You should now be able to explore the stack on your local machine and using your web browser. All links below assume default configuration and working Ingress DNS. + +- Block Explorers (Blockscout) + - [L2 Explorer](http://blockscout.scrollsdk/) + - [L1 Explorer](http://l1-devnet-explorer.scrollsdk/) (this is scanning Anvil and can be a bit buggy) +- [Bridge](http://frontends.scrollsdk/bridge) + - Bridging UI has a gas bug as of June 13, 2024 +- [Rollup Explorer](http://frontends.scrollsdk/rollupscan?page=1&per_page=10) + - Shows committed batches and finalized batches +- [Granfana Dashboards](http://grafana.scrollsdk/) + - Login + - User: `admin` + - Pass: `scroll-stack` + - See “Scroll” dashboards on [this page](http://grafana.scrollsdk/dashboards). + +### Connecting to the RPC using a Wallet + +To connect directly to an RPC or using MetaMask, use: + +| Network | Scroll SDK Chain | Scroll SDK L1 | +|-------------|-------------|-------------| +| RPC URL | `http://l2-rpc.scrollsdk` | `http://l1-devnet.scrollsdk` | +| Chain ID | `221122` | `111111` | +| Currency Symbol | `ETH` | `ETH` | +| Block Explorer URL | [`http://blockscout.scrollsdk`](http://blockscout.scrollsdk/) | [`http://l1-devnet-explorer.scrollsdk`](http://l1-devnet-explorer.scrollsdk/) | + + + +### Helpful Commands + +Anvil has a lot of [useful methods](https://book.getfoundry.sh/reference/anvil/#custom-methods) that can manipulate the L1. Proper documentation for using them is available in the [Hardhat docs](https://hardhat.org/hardhat-network/docs/reference#hardhat-network-methods) (replacing `hardhat_` with `anvil_`) + +#### Set L1 Token Balance of an Account + +In params, change first item to a wallet, and second to hex of wei. This config uses 1000 ETH. + +See [docs](https://hardhat.org/hardhat-network/docs/reference#hardhat_setbalance) for details. + +```bash +curl --location 'http://l1-devnet.scrollsdk/' \ +--header 'Content-Type: application/json' \ +--data '{ + "jsonrpc":"2.0", + "method":"anvil_setBalance", + "params":["0x98110937b5D6C5FCB0BA99480e585D2364e9809C","0x3635C9ADC5DEA00000"], + "id":0 +}' +``` + +#### Mine some L1 Block + +See [docs](https://hardhat.org/hardhat-network/docs/reference#hardhat_mine) for details. + +```bash +curl --location 'http://l1-devnet.scrollsdk/' \ +--header 'Content-Type: application/json' \ +--data '{ + "jsonrpc":"2.0", + "method":"anvil_mine", + "params":["0x10000000", "0xc"], + "id":0 +}' +``` \ No newline at end of file diff --git a/src/content/docs/en/sdk/guides/run-on-arm64-mac.mdx b/src/content/docs/en/sdk/guides/run-on-arm64-mac.mdx index 921be3070..95d26afc1 100644 --- a/src/content/docs/en/sdk/guides/run-on-arm64-mac.mdx +++ b/src/content/docs/en/sdk/guides/run-on-arm64-mac.mdx @@ -11,6 +11,10 @@ import Aside from "../../../../../components/Aside.astro" import ToggleElement from "../../../../../components/ToggleElement.astro" import Steps from '../../../../../components/Steps/Steps.astro'; + + ## Overview This guide should get you started with running a local Scroll SDK devnet on your mac laptop with an `arm64` processor. diff --git a/src/content/docs/en/sdk/technical-stack/configuration.mdx b/src/content/docs/en/sdk/technical-stack/configuration.mdx index fea7cda6b..327ef93ff 100644 --- a/src/content/docs/en/sdk/technical-stack/configuration.mdx +++ b/src/content/docs/en/sdk/technical-stack/configuration.mdx @@ -9,6 +9,10 @@ excerpt: "Information on configuring and customizing a Scroll SDK deployment." import Aside from "../../../../../components/Aside.astro" + + Initial change configuration is made by modifying `config.toml`. All other config files are auto-generated from this file. To modify which services to run, see [Services](/en/sdk/technical-stack/services). In the future, we'll also provide and examples folder for various configurations. diff --git a/src/content/docs/en/sdk/technical-stack/contracts.mdx b/src/content/docs/en/sdk/technical-stack/contracts.mdx index 967e3dd58..85ff3bb45 100644 --- a/src/content/docs/en/sdk/technical-stack/contracts.mdx +++ b/src/content/docs/en/sdk/technical-stack/contracts.mdx @@ -55,11 +55,12 @@ During deployment, a simulation is first done to determine what address a contra {/* */} -{/* Then, after the `scroll-stack` chart is installed during `make install`, you will need to fund your SDK accounts and run `make deploy-contracts` to deploy all contracts on L1 and L2 using actual transactions. */} +Then, before the `contracts` chart is installed, you will need to fund your SDK `DEPLOYER` account to deploy all contracts on L1 and L2 using actual transactions. -Then, during `make install`, the `contracts` pod will connect to the cluster's RPCs and deploy the necessary contracts. +The `contracts` pod will connect to the cluster's RPCs and deploy the necessary contracts. -To view the complete logs from the deployment process, see the `broadcast` folder in `/charts/scroll-stack/`. +{/* TODO: is this still true? */} +{/* To view the complete logs from the deployment process, see the `broadcast` folder in `/charts/scroll-stack/`. */} {/* TODO: check again once we do this. */}