fiftysix/bsc repository overview

⁠Fiftysix BSC Docker Image

Maintainer: [email protected]⁠

⁠Overview

This Docker image provides a fully functional BSC (BNB Smart Chain) client built using the Fiftysix base image, downloading BNB Chain's own prebuilt release binary rather than compiling from source. BSC is a fork of go-ethereum with the Parlia (Proof-of-Staked-Authority) consensus engine built directly in - unlike every Ethereum client in this account, there is no separate execution/consensus split and no JWT secret of its own. The code can be viewed on the Fiftysix Github⁠.

⁠Tags

• latest: Points to the latest version of BSC.
• <version>: Points to a specific BSC release, for example 1.7.8.

⁠Why this image downloads a prebuilt binary instead of compiling from source

bnb-chain/bsc publishes a prebuilt, statically-linked Linux binary with every release. This image downloads it directly and verifies it against a sha256sum pinned in the Dockerfile. Note: bnb-chain/bsc does not publish an official checksums file alongside its releases, so the pinned value is this image's own first-recorded checksum for that release, not one verified against an independently-published upstream value - it still protects against a corrupted download or the file changing after this image was built.

⁠What is BSC?

BSC is a fork of go-ethereum - its own go.mod module path is still literally github.com/ethereum/go-ethereum - with the Parlia consensus engine (Proof-of-Staked-Authority) built directly into the same binary. It operates as a single monolithic process: no execution/consensus split, no Engine API, and no JWT secret, unlike every Ethereum client in this account. It processes transactions, executes smart contracts, and maintains BNB Smart Chain's state.

⁠Usage

⁠Prerequisites

BSC has no built-in chain configuration the way Ethereum mainnet/Sepolia do, so this image bundles both mainnet and testnet (Chapel) genesis/config pairs and switches between them at runtime via the NETWORK environment variable - there is no CLI flag for this.

⁠Basic Usage

To run a BSC node:

docker pull fiftysix/bsc
docker run --name bsc -d fiftysix/bsc

This command will start the BSC container on mainnet, exposing the default RPC and P2P ports.

Note: to run testnet (Chapel) instead, set NETWORK=testnet:

docker run --name bsc-testnet -d -e NETWORK=testnet fiftysix/bsc

On first start (no chaindata directory yet), the entrypoint runs geth init against the matching bundled genesis file automatically - no manual init step is needed.

⁠Directory Structure

In this Docker image, the following directories are used:

• Data Directory (/node/bsc/data): This is where BSC stores its chain database. This directory is specified in the Dockerfile and should be mounted if you want to persist data across container restarts.
• Config Directory (/node/bsc/configs): Holds the bundled mainnet/ and testnet/ genesis.json/config.toml pairs, taken directly from bnb-chain/bsc's own published release bundles (mainnet.zip/testnet.zip).
• Scripts Directory (/node/bsc/scripts): Contains the entrypoint script (bsc-entrypoint.sh).

Note: unlike every other client in this account, only /node/bsc/data should be mounted, not the whole /node/bsc tree - the entrypoint script and bundled configs live under /node/bsc/scripts and /node/bsc/configs, and mounting the broader path would shadow them with an empty host directory.

⁠Mounting Directories

Mounting the Data Directory:

To persist BSC data across container restarts, mount a host directory to the container's data directory:

docker run --name bsc -v /path/to/local/data:/node/bsc/data -d fiftysix/bsc

This command mounts the /path/to/local/data directory on your host to /node/bsc/data in the container, ensuring that blockchain data is preserved between container instances.

⁠A real gotcha in the upstream config, fixed here

BNB Chain's own published config.toml files set HTTPHost/WSHost to localhost/127.0.0.1 - fine on bare metal, but this only accepts connections from inside a container. Both of this image's bundled configs (mainnet and testnet) override this to 0.0.0.0 so the exposed ports below actually work. Testnet's own published RPC ports (8575/8576) were also normalized to the usual 8545/8546 so both networks behave identically from the outside.

⁠Logging BSC

docker logs bsc --tail 100

⁠Using BSC

⁠Starting BSC with Custom Options

The entrypoint always injects --config for the selected network; additional flags are appended after it and override the file:

docker run --name bsc -d \
  -p 8545:8545 -p 8546:8546 -p 30311:30311 -p 30311:30311/udp \
  fiftysix/bsc \
  --maxpeers 100

⁠Snapshot Downloading

Syncing BSC mainnet from genesis is impractical. Per BNB Chain's own snapshot repo⁠, download and extract a snapshot into the mounted data volume before starting the container using their fetch-snapshot.sh script - not yet automated by this image.

⁠Exposing Ports

The following ports are commonly used by BSC and are exposed in this Docker image:

• 8545: HTTP-RPC server
• 8546: WebSocket-RPC server
• 30311: P2P communication (TCP and UDP) - BSC's own default, distinct from Ethereum's 30303

⁠Hardware Requirements

Per BNB Chain's own snapshot repo⁠ and community operator guides:

BSC produces blocks roughly every 0.45-0.75 seconds depending on the active hardfork, so sustained write IOPS matters as much as raw capacity.

⁠Support

For support, please contact [email protected]⁠.

⁠About Fiftysix

Fiftysix is committed to making blockchain technology accessible, efficient, and reliable through robust decentralization. Learn more at fiftysix.tech⁠.