layer 3 Blockchain Deployment Kit

instructions are somewhat specific to Ubuntu 22.04LTS

requirements

go1.21.6 install on Ubuntu Linux 22.04LTS for amd64 using bash

#get wget
sudo apt install wget
#wget go
wget https://go.dev/dl/go1.21.6.linux-amd64.tar.gz
#remove existing go
sudo rm -rf /usr/local/go
# possibly necessary
sudo apt remove golang $$ autoremove
#extract verbosely with force
sudo tar -xvf go1.21.6.linux-amd64.tar.gz -C /usr/local/
#add go path to ./bashrc current user with default Ubuntu 22 bash shell
echo 'export PATH="$PATH:/usr/local/go/bin"' | sudo tee -a ./bashrc
#refresh your bash shell
source $HOME/.bashrc
# verify correct version install
go version

nodejs install

nodejs -v
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install nodejs -y
nodejs -v

docker install

# docker install https://docs.docker.com/engine/install/ubuntu/
for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do sudo apt-get remove $pkg; done
sudo groupadd docker
sudo usermod -aG docker $USER
newgrp docker
docker ps

kurtosis install

https://docs.kurtosis.com/install/

echo "deb [trusted=yes] https://apt.fury.io/kurtosis-tech/ /" | sudo tee /etc/apt/sources.list.d/kurtosis.list
sudo apt update
sudo apt install kurtosis-cli

polygon-cli install blockchain swiss army knife source build

snap install yq
sudo apt install bc protoc
git clone https://github.com/maticnetwork/polygon-cli.git
cd polygon-cli
make install

foundry instatll

curl -L https://foundry.paradigm.xyz | bash
source $HOME/.bashrc
foundryup
cd BDK2
git config --global user.email "codephreak@dmg.finance"
git config --global user.name "Professor-Codephreak"
forge init --force

sudo apt install postgresql-client-common

foundry creates script and src folders

The LAIR3-BDK2 Layer 3 Blockchain Development Kit is designed to facilitate the deployment and management of advanced blockchain solutions specifically supporting zkEVM Rollup and Validium technologies. Merging the best of the Kurtosis SDK, polygon-cli, avalanche subnet-evm and ignite with Starlark the Blockchain Deployment Kit facilitates the creation and deployment of customized blockchain environments with enhanced observability and testing capabilities.

The primary goal is to to make blockchain deployment a sane operation accessiable to regular developers interested in dapplications development.

set PostgreSQL master password

export POSTGRES_MASTER_PASSWORD="your_secure_password"

Set Validator PostgreSQL Password

Log into PostgreSQL

sudo -u postgres psql
ALTER USER validator1 WITH PASSWORD 'new_validator1_password';
\q

check postgresql installation

sudo apt install postgresql-client-common
psql -U master_user -h 127.0.0.1 -p 5432 -d master
\dx
SELECT * FROM pg_extension WHERE extname = 'vectorscale';

optional upggrade PostgreSQL modify pgvectorscale as docker build using toolbox.Dockerfile

docker build -t blockchaindeploymentkit/bdk-toolbox-postgres-pgvectorscale -f docker/toolbox.Dockerfile .
docker login
docker tag blockchaindeploymentkit/bdk-toolbox-postgres-pgvectorscale blockchaindeploymentkit/bdk-toolbox-postgres-pgvectorscale
docker push blockchaindeploymentkit/bdk-toolbox-postgres-pgvectorscale

remove bdk-toolbox-postgres-pgvectorscale

docker rmi blockchaindeploymentkit/bdk-toolbox-postgres-pgvectorscale
docker system prune -a
docker compose version

reference links

manualchunks
lighthouse
pgvectorscale timescale

troubleshoot

kurtosis logs directory error

Create Missing Directories: If directories /var/log/kurtosis/ and similar are missing you can manually create these directories to resolve the issue

sudo mkdir -p /var/log/kurtosis/2024/31
sudo chown -R $USER:docker /var/log/kurtosis

Verify Docker Permissions:

sudo chmod -R 755 /var/log/kurtosis

Restart Kurtosis and Docker:

kurtosis engine restart
sudo systemctl restart docker

requirements include but not limited to

zkevm_bridge logs ./lib/zkevm_bridge.star

kurtosis service logs cdk-v1 zkevm-bridge-ui-001

run the bridge UI standalone

docker run -it --rm -p 8080:80 leovct/zkevm-bridge-ui:multi-network

generic instruction

docker run --name zkevm-bridge-ui -p 80:8080 -v /path/to/.env:/app/.env leovct/zkevm-bridge-ui:multi-network

erigon standalone

docker --version
docker network create erigon-net
docker run -d --name cdk-erigon-sequencer --network erigon-net -p 8123:8123 -p 6900:6900 -p 9091:9091 -p 6060:6060 -v erigon-data:/home/erigon/data -e CDK_ERIGON_SEQUENCER=1 hermeznetwork/cdk-erigon:2.0.0-beta15 sh -c "sleep 10 && cdk-erigon --pprof=true --pprof.addr 0.0.0.0 --config /etc/cdk-erigon/config.yaml"
docker logs -f cdk-erigon-sequencer

recomended diagnostics

sudo apt install netstat hardinfo

run the zkevm-prover standalone

docker run -it --rm -p 50071:50071 -p 50061:50061 hermeznetwork/zkevm-prover:v6.0.2 /bin/bash

ENCLAVES

list enclaves

kurtosis enclave ls

Inspect the Kurtosis enclave

kurtosis enclave inspect bdk-v2

Check the logs of the failing service

kurtosis service logs bdk-v2 zkevm-bridge-ui-001

Open a shell into the service container to manually inspect and debug

kurtosis service shell bdk-v2 zkevm-bridge-ui-001

Environment Setup

Clone the Repository and Install Dependencies

git clone https://github.com/LAIR3/BDK.git
cd BDK
sh scripts/tool_check.sh

Clean Up Previous Environments

kurtosis clean --all

docker remove

stop all running containers

docker stop $(docker ps -aq)

Remove all containers:

docker rm $(docker ps -aq)

Remove all images:

docker rmi -f $(docker images -q)

Remove all volumes:

docker volume rm $(docker volume ls -q)

Remove all networks:

docker network rm $(docker network ls -q)

Prune the system:

docker system prune -a --volumes

docker network ls
docker network inspect NAME

############ START ############

BDK-v3 as Kurtosis Enclave

kurtosis run --enclave BDK-v3 --args-file params.yml --image-download always .

Inspect Enclave for Dashboard Details

kurtosis enclave inspect BDK-v3

Fetch Service Logs

kurtosis service logs bdk-v2 zkevm-agglayer-001

Add Permissionless Node

yq -Y --in-place 'with_entries(if .key == "deploy_zkevm_permissionless_node" then .value = true elif .value | type == "boolean" then .value = false else . end)' params.yml
kurtosis run --enclave cdk-v1 --args-file params.yml --image-download always .

Sync External Permissionless Node

cp /path/to/external/genesis.json templates/permissionless-node/genesis.json
yq -Y --in-place 'with_entries(if .key == "deploy_zkevm_permissionless_node" then .value = true elif .value | type == "boolean" then .value = false else . end)' params.yml
kurtosis run --enclave cdk-v1 --args-file params.yml --image-download always .

Simple RPC Calls

export ETH_RPC_URL="$(kurtosis port print cdk-v1 zkevm-node-rpc-001 http-rpc)"
cast block-number
cast balance --ether 0xE34aaF64b29273B7D567FCFc40544c014EEe9970

chain interactions

Send Transactions

cast send --legacy --private-key 0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625 --value 0.01ether 0x0000000000000000000000000000000000000000

Load Testing with Polygon CLI

polycli loadtest --requests 500 --legacy --rpc-url $ETH_RPC_URL --verbosity 700 --rate-limit 5 --mode t --private-key 0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625

Observability Tools

Prometheus

Prometheus captures all the metrics for the running services. Accessible via: http://127.0.0.1:49678

Prometheus Targets

open http://127.0.0.1:49651/targets

Grafana

Dashboards for visualizing metrics. Accessible via: http://127.0.0.1:49701

run grafana as a standalone

docker run -d --name=grafana-001 -p 49701:3000 grafana/grafana:latest

docker run -d --name=grafana -p 3000:3000 grafana/grafana:latest
docker start grafana
open http://localhost:49701/login
docker logs grafana
docker logs grafana-001
docker stop graphana

View Grafana Dashboard

open http://127.0.0.1:49701/dashboards
open http://127.0.0.1:49701/login

Panoptichain

Monitors on-chain metrics such as blocks, transactions, and smart contract calls. Accessible via: http://127.0.0.1:49651