Running Scroll SDK on an ARM64 Mac

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 and have access to the scroll-sdk github repo 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 (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
      • brew install --cask docker
    • kubectl
      • brew install kubectl
    • minikube
      • brew install minikube
    • Helm
      • brew install helm
    • docker-mac-net-connect
      • brew install chipmk/tap/docker-mac-net-connect
  3. Optional: Install dependencies for example helper scripts
    • yq
      • brew install yq
    • Foundry
      • 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:

minikube start --driver=docker

Getting minikube to work with custom DNS names on MacOS

Now run the following commands:

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.

    git clone git@github.com:scroll-tech/scroll-sdk.git
  2. 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-sdk/values.yaml (view on Github) and config.toml (view on Github).

  3. Bootstrap

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

    make bootstrap
  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.

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.

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-sdk 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 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:

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:

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

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

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
}'
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