bsc-stack/stack-orchestrator/stacks/bsc-node

bsc-node

Instructions for running a BSC node

Setup

• (Optional) Download the snapshot for BSC network (mainnet | testnet) by following instructions from https://github.com/bnb-chain/bsc-snapshots

  # Example (mainnet)
  wget -O geth.tar.lz4 https://pub-c0627345c16f47ab858c9469133073a8.r2.dev/geth-pbss-pebble-20240514.tar.lz4
  
  # Example (testnet)
  wget -O geth.testnet.tar.lz4 https://pub-c0627345c16f47ab858c9469133073a8.r2.dev/testnet-geth-pbss-20240307.tar.lz4
  

• Clone the stack repo:

  laconic-so fetch-stack git.vdb.to/cerc-io/bsc-stack
  

• Build the container images:

  laconic-so --stack ~/cerc/bsc-stack/stack-orchestrator/stacks/bsc-node build-containers
  

Create a deployment

• Create a spec file for the deployment:

  laconic-so --stack ~/cerc/bsc-stack/stack-orchestrator/stacks/bsc-node deploy init --map-ports-to-host any-same --output bsc-node-spec.yml
  

• Edit network in the spec file to map container ports to host ports as required

• Create a deployment directory from the spec file:

  laconic-so --stack ~/cerc/bsc-stack/stack-orchestrator/stacks/bsc-node deploy create --spec-file bsc-node-spec.yml --deployment-dir bsc-node-deployment
  

• (Optional) Copy over the snapshot file (*.tar.lz4 or *.tar.zst) in snapshot data directory in the deployment (bsc-node-deployment/data/snapshot):

  # Example
  cp geth.tar.lz4 bsc-node-deployment/data/snapshot/
  

Configuration

• Environment variables for BSC node can be configured by setting them in config.env inside the deployment directory:

  # All optional
  # Runs a full node syncing from genesis if none are set
  
  # BSC network to run (mainnet | testnet) (default: mainnet)
  CERC_BSC_NETWORK=
  
  # Whether to sync from a snapshot (true | false) (default: false)
  # Requires snapshot file with extension .tar.lz4 or .tar.zst to be placed in the snapshot directory
  CERC_USE_SNAPSHOT=
  
  # Path where geth dir is located in the snapshot archive
  # Required when using a snapshot; example: "server/data-seed/geth"
  CERC_SNAPSHOT_GETH_PATH=
  
  # Whether to run as a fast node (true | false) (default: false)
  # Fast node does not generate trie data when syncing
  CERC_FAST_NODE=
  
  # Garbage collection mode (full | archive) (default: full)
  # Set to archive for archive node
  CERC_GETH_GCMODE=
  
  # Logging verbosity (default: 3)
  # 0=silent, 1=error, 2=warn, 3=info, 4=debug, 5=detail
  CERC_GETH_VERBOSITY=
  

Start the deployment

laconic-so deployment --dir bsc-node-deployment up

Check status

• To list down and monitor the running containers:

  # With status
  docker ps -a
  
  # Check logs for a container
  docker logs -f <CONTAINER_ID>
  

• Check Synchronization:

  # Start geth console
  laconic-so deployment --dir bsc-node-deployment exec bsc "geth attach ipc:/data/geth.ipc"
  
  >eth.syncing
  

• Check geth logs:

  laconic-so deployment --dir bsc-node-deployment exec bsc "tail -f /data/bsc.log"
  

Clean up

• Stop all services running in the background:

  # Stop the docker containers
  laconic-so deployment --dir bsc-node-deployment down
  

• To stop all services and also delete data:

  # Stop the docker containers
  laconic-so deployment --dir bsc-node-deployment down --delete-volumes
  
  # Remove deployment directory (deployment will have to be recreated for a re-run)
  rm -r bsc-node-deployment
  

Upgrading

To upgrade the BSC release being used:

• Upgrade the base Docker image used in Dockerfile
• Update the release assets URL used for fetching config files in docker-entrypoint.sh