Running Scroll SDK Devnet

Overview

This guide should get you started with running a local Scroll SDK devnet. Additionally, it has specific asides for running on macOS and Ubuntu.

We’ve written this guide because local deployments of Kubernetes clusters can be finicky. Even the prerequisites can be tricky without help.

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. These are all accessible to wallets, browsers, and applications running on your local machine.

Updates to the Guide
  • October 30, 2024
    • Updated for Scroll SDK v0.1.0

Prerequisites

  1. Install dependencies (using brew is strongly recommended):

    • Brew (optional)
      • /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
    • Docker (Docker Desktop)
      • brew install --cask docker
    • kubectl
      • brew install kubectl
    • minikube
      • brew install minikube
    • Helm
      • brew install helm
    • docker-mac-net-connect (macOS ARM64 only)
      • brew install chipmk/tap/docker-mac-net-connect
  2. Optional: Install dependencies for support CLI tool:

    • node >=18
      • brew install nvm
      • nvm install node
    • scroll-sdk-cli (Experimental, APIs may change)
      • npm install -g @scroll-tech/scroll-sdk-cli
  3. You should now be able to open a terminal and run the following:

    • docker -v
    • kubectl version
    • minikube status
    • helm version
    • node -v
    • scrollsdk
    • Or, in one step: scrollsdk test dependencies --dev

Starting minikube

First, we need to allow minikube sufficient resources to run the devnet.

minikube config set cpus 8
minikube config set memory 8192

Next, we start minikube.

Mac requires extra commands as a work-around for ingress-dns not working correctly on arm64 MacOS. Hopefully the issue will be resolved in later versions of minikube.

minikube start --driver=docker
minikube addons enable ingress
minikube addons enable ingress-dns
# Additional steps for MacOS DNS resolution
minikube ssh "sudo apt-get update && sudo apt-get -y install qemu-user-static"
sudo brew services start chipmk/tap/docker-mac-net-connect

Installing Scroll SDK

  1. Clone the scroll-sdk repo and find devnet directory

    git clone git@github.com:scroll-tech/scroll-sdk.git
    cd scroll-sdk/devnet
  2. Bootstrap

    Now we’ll install Helm chart dependencies, generate additional config files for our services, and create our genesis.json file.

    make bootstrap
  3. Optional: Configure values.yaml and config.toml

    This is the time to adjust what services run on your stack and their configuration. We suggest not altering these on your first installation, but see charts/scroll-sdk/values.yaml (view on Github) and config.toml (view on Github).

    If you do make changes, you’ll need to run make config after to regenerate the additional configuration files. No services directly read from the config.toml file.

  4. Launch the chain!

    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.

    The install process for the various containers can take several minutes as new docker images are downloaded and services wait on others to be online to start.

After Launching the Stack

Configuring DNS

Running kubectl get ingress should show all the domains setup within the cluster, like the following:

➜ scroll-sdk git:(develop) ✗ kubectl get ingress
NAME CLASS HOSTS ADDRESS PORTS AGE
admin-system-dashboard nginx admin-system-dashboard.scrollsdk 192.168.49.2 80 5h3m
blockscout-backend-ingress nginx blockscout-backend.scrollsdk 192.168.49.2 80 5h3m
blockscout-frontend-ingress 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-blockscout-ingress nginx l1-explorer-backend.scrollsdk 192.168.49.2 80 5h3m
l1-explorer-frontend-ingress nginx l1-explorer.scrollsdk 192.168.49.2 80 5h3m
l2-rpc nginx l2-rpc.scrollsdk 192.168.49.2 80 5h3m
l2-rpc-websocket nginx l2-rpc-ws.scrollsdk 192.168.49.2 80 5h3m
rollup-explorer-backend nginx rollup-explorer-backend.scrollsdk 192.168.49.2 80 5h3m

To resolve the ingress domains, we need to add the minikube IP and our service hostnames to the hosts file.

  1. Get your minikube IP address:

    minikube ip

    This should return something like 192.168.49.2.

  2. Add this IP and our service hostnames to the hosts file:

    # Open the hosts file in nano
    sudo nano /etc/hosts
  3. Add the following entries to the file, replacing 192.168.49.2 with your minikube IP if different:

    192.168.49.2 admin-system-dashboard.scrollsdk
    192.168.49.2 blockscout-backend.scrollsdk
    192.168.49.2 blockscout.scrollsdk
    192.168.49.2 bridge-history-api.scrollsdk
    192.168.49.2 frontends.scrollsdk
    192.168.49.2 grafana.scrollsdk
    192.168.49.2 l1-devnet.scrollsdk
    192.168.49.2 l1-explorer-backend.scrollsdk
    192.168.49.2 l1-explorer.scrollsdk
    192.168.49.2 l2-rpc.scrollsdk
    192.168.49.2 l2-rpc-ws.scrollsdk
    192.168.49.2 rollup-explorer-backend.scrollsdk
  4. Save the file by pressing Ctrl+X, then Y, then Enter.

Testing Ingress DNS

Now, test ingress and your access to the services by running scrollsdk test ingress.

If you aren’t using the CLI tool, you can manually test the ingress DNS by running:

  1. nslookup frontends.scrollsdk $(minikube ip)

  2. curl frontends.scrollsdk

  3. If those work, visit http://frontends.scrollsdk in your browser.

  4. If those do not work:

    • For MacOS: Try resetting your machine and running through the DNS setup instructions again. It may help to run minikube stop and minikube start again.
    • For Ubuntu: Double check that your minikube IP matches what’s in your /etc/hosts file by running minikube ip.

Funding SDK Addresses

You will need to provide funds to the following accounts:

  • DEPLOYER_ADDR (only needs funded on L1)
    • In the default configuration, this account is pre-funded by Anvil. If changed, you’ll need to relaunch the contracts pod after funding to deploy the contracts.
  • 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 CLI helper command to fund the accounts.

cd scroll-sdk
scrollsdk helper fund-accounts --dev

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 delete will stop all services. You wil also need to run kubectl delete pvc data-l2-rpc-0 to delete the remaining pvc.

minikube dashboard launches a WebUI for exploring the kubernetes cluster and the various pods, volumes and ingresses without learning all the CLI commands. k9s is also a CLI great tool for exploring running pods and quickly looking at their logs.

If you need to update a specific service’s config file (not the original config.toml):

  1. Make any necessary changes to the config files or helm charts
  2. Run make install
  3. Delete the running pod by running kubectl delete pod [pod-name]. Kubernetes will restart the pod with the updated config.

Testing & Interacting with the Chain

scroll-sdk-cli

The scroll-sdk-cli tool has many helper commands. Run it in the same directory as your config.toml file in the ./devnet/scroll-sdk folder.

  • scrollsdk test ingress will test if your ingress is configured correctly and host urls are accessible from your machine.
  • scrollsdk test contracts will check that essential contracts are deployed, initialized and have the correct owner.
  • scrollsdk helper fund-accounts --dev -a [account-address] will fund any account.
  • scrollsdk helper activity -o -t will generate activity on both layer one and layer two to help produce blocks and batches.

End-To-End Test

The scrollsdk test e2e command will walk you through generating the following tests on your chain:

  • Generate a new wallet
  • Fund it from the Deployer address on L1
  • Deposit funds to the L2
  • Deploying an ERC20 and depositing them to the L2
  • Deploying an ERC20 on the L2
  • Bridging ETH and ERC20 from L2 back to L1
  • Executing the withdrawal claim on L1

If any step fails, you can restart where you left off by adding the --resume flag.

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.

Connecting to the RPC using a Wallet

To connect directly to an RPC or using MetaMask, use:

NetworkScroll SDK ChainScroll SDK L1
RPC URLhttp://l2-rpc.scrollsdkhttp://l1-devnet.scrollsdk
Chain ID221122111111
Currency SymbolETHETH
Block Explorer URLhttp://blockscout.scrollsdkhttp://l1-devnet-explorer.scrollsdk

What’s Next?

If you’re a developer, you might want to try customizing specific sdk components.

If you’re looking to learn more about running a public testnet, try out a production deployment with our Digital Ocean guide or our AWS guide.

Helpful Commands

Anvil has a lot of useful methods that can manipulate the L1. Proper documentation for using them is available in the Hardhat docs (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 for details.

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 for details.

curl --location 'http://l1-devnet.scrollsdk/' \
--header 'Content-Type: application/json' \
--data '{
"jsonrpc":"2.0",
"method":"anvil_mine",
"params":["0x10000000", "0xc"],
"id":0
}'

Troubleshooting

ingress-dns issues

Getting ingress-dns can be tricky across different machines, operating systems and network configurations.

Directly editing etc/hosts has worked for some users, adding all ingress hosts pointing to the minikube IP address.

Follow the template below, being sure to create one value for every ingress in your configuration. Also, be sure to try the IP of your minikube deployment.

For VPN users, we’ve seen the following work:

  1. Execute command sudo minikube tunnel

  2. Open file /etc/hosts and add:

    127.0.0.1 l1-devnet.scrollsdk
    127.0.0.1 bridge-history.scrollsdk
    127.0.0.1 frontends.scrollsdk
    127.0.0.1 grafana.scrollsdk
    127.0.0.1 l1-devnet-explorer.scrollsdk
    127.0.0.1 l2-rpc.scrollsdk
    127.0.0.1 blockscout.scrollsdk
    127.0.0.1 bridge-history-api.scrollsdk
  3. Turn off VPN when visiting in browser

Stay up-to-date on the latest Scroll Developer news
Roadmap updates, virtual and live events, ecosystem opportunities and more
Thank you for subscribing!

Resources

Follow Us