Skip to content

Commit

Permalink
first adjustment for prod readiness
Browse files Browse the repository at this point in the history
  • Loading branch information
@dghelm
dghelm committed Aug 26, 2024
1 parent fe94ea8 commit 5295d37
Show file tree
Hide file tree
Showing 6 changed files with 472 additions and 17 deletions.
323 changes: 323 additions & 0 deletions src/content/docs/en/sdk/guides/devnet-deployment.mdx
View file
Original file line number Diff line number Diff line change
@@ -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!!

<Aside type="danger">
This information may not reflect the refactor from 08/26/2024. We intend to update this information soon.
</Aside>

## 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.

<Aside type="tip" title="Experimental Software!">
We’d appreciate any feedback about this document, the codebase, or additional features.
</Aside>

<Aside type="caution">
This guide does not include running the coordinator or a prover. The coordinator currently requires 20GB of RAM to run, so we disable it by default, and provers need dedicated machines to run and require additional configuration.
</Aside>

<ToggleElement anchor="Guide Updates">
<div slot="title">Updates to the Guide</div>
<span>

- 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”)

</span>
</ToggleElement>

## Prerequisites
<Steps>
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`
</Steps>

<Aside type="tip" note="Setting Default Resources for `minikube`">
By default, minikube is allocated 2 CPU and 4GB RAM. For best performance, you can set higher resource limits before starting minikube.

```bash
minikube config set cpus 8
minikube config set memory 8192
```

</Aside>

### 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
```

<Aside type="danger" title="This is a hack!">
These are all a work-around for ingress-dns not working on arm MacOS and hopefully will change in later fixes to minikube. This work gets relied on in [Pointing DNS Requests to the Cluster](https://www.notion.so/Pointing-DNS-Requests-to-the-Cluster-b6dd4f519697432cb9835e2d5eead731?pvs=21)
</Aside>

## Installing Scroll SDK

<Steps>
1. **Clone the `scroll-sdk` repo**

*You’ll need If you need repo access, reach out to `@dghelm` on Telegram.*

```bash
git clone [email protected]: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
```

<Aside note="caution" title="Command changes frequently!">
The behavior of this command can change frequently since it refers to a specific docker image.
</Aside>

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.

<Aside>
Right now (July 22, 2024), the whole start process for the various containers can take up to 10 minutes. We’ll be looking to reduce this.
</Aside>
</Steps>

## 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 <minikube_ip>
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

<Aside>
We’re working to get more interesting testing tools added to the stack, so let us know if you want to be told when we update this section.
</Aside>

### 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/) |

<Aside type="caution">
Until we setup `https` you need to manually set these up in MetaMask and the WebUI buttons will not work.
</Aside>

### 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
}'
```
4 changes: 4 additions & 0 deletions src/content/docs/en/sdk/guides/run-on-arm64-mac.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,10 @@ import Aside from "../../../../../components/Aside.astro"
import ToggleElement from "../../../../../components/ToggleElement.astro"
import Steps from '../../../../../components/Steps/Steps.astro';

<Aside type="danger">
This information may not reflect the refactor from 08/26/2024. We intend to update this information soon.
</Aside>

## Overview

This guide should get you started with running a local Scroll SDK devnet on your mac laptop with an `arm64` processor.
Expand Down
4 changes: 4 additions & 0 deletions src/content/docs/en/sdk/technical-stack/configuration.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,10 @@ excerpt: "Information on configuring and customizing a Scroll SDK deployment."

import Aside from "../../../../../components/Aside.astro"

<Aside type="danger">
This information may not reflect the refactor from 08/26/2024. We intend to update this information soon.
</Aside>

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.
Expand Down
9 changes: 5 additions & 4 deletions src/content/docs/en/sdk/technical-stack/contracts.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,11 +55,12 @@ During deployment, a simulation is first done to determine what address a contra

{/* <!-- TODO: modify URL to develop branch --> */}

{/* 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. */}
<Aside type="tip">
Expand Down Expand Up @@ -115,7 +116,7 @@ cast send --rpc-url https://rpc2.sepolia.org --private-key "$PRIVATE_KEY" "$L1_

In the table below, we document every contract deployed for Scroll, including a link to the deployment for Scroll's mainnet. Not all of these are used by default for Scroll SDK.

{/* <!-- TODO: Modify table here for only post-Curie Scroll SDK contracts. --> */}
{/* <!-- TODO: Modify table here for only post-Darwin Scroll SDK contracts. --> */}

| Contract Name | Description |
| -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
Expand Down
Loading

0 comments on commit 5295d37

Please sign in to comment.