bsc-stack/stack-orchestrator/stacks/bsc-node/README.md

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

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

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

* Build the container images:

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

## Create a deployment

* Create a spec file for the deployment:

  ```bash
  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:

  ```bash
  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`):

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

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

  # 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

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

## Check status

* To list down and monitor the running containers:

  ```bash
  # With status
  docker ps -a

  # Check logs for a container
  docker logs -f <CONTAINER_ID>
  ```

* Check Synchronization:

  ```bash
  # Start geth console
  laconic-so deployment --dir bsc-node-deployment exec bsc "geth attach ipc:/data/geth.ipc"

  >eth.syncing
  ```

* Check geth logs:

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

## Clean up

* Stop all services running in the background:

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

* To stop all services and also delete data:

  ```bash
  # 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](`stack-orchestrator/container-build/cerc-bsc-geth/Dockerfile`)
* Update the release assets URL used for fetching config files in [docker-entrypoint.sh](stack-orchestrator/config/bsc-node/docker-entrypoint.sh)