Skip to content

bnb-chain/bsc-docker

Repository files navigation

BNB Smart Chain Private Cluster

Create a private BNB Smart Chain cluster and run bep20 truffle test in local docker.

Prerequisites

  • Install make, docker and docker-compose on your local machine. If you are using Docker Desktop, please make sure to set Resources at least 2 CPU cores and 6GB memory

  • Edit docker-compose.bsc.yml:

    • set GIT_SOURCE point to bsc repository source (default: https://github.com/bnb-chain/bsc).
    • set GIT_CHECKOUT_REF point to (commit / branch / tag) that you want to build (default: master).
  • (Optional):

    • Edit .env, modify BSC_CHAIN_ID and other attributes
    • Edit docker-compose.simple.bootstrap.yml, modify INIT_HOLDER_BALANCE
    • Edit docker-compose.cluster.bootstrap.yml, modify INIT_HOLDER_BALANCE

Account & Private Keys

Account 1: 0xb75573a04648535Bddc52adf6fBc887149624253, private key: 0x953dbe85f02d84377f90a6eb6d8a6dd128aa50f69c4671d32414b139040be24b
Account 2: 0xA2bC4Cf857f3D7a22b29c71774B4d8f25cc7edD0, private key: 0xa568b36fca21714f879e3cf157f021a4c5dccd6229ef6e6eee7fb7888193c026
Account 3: 0x59b02D4d2F94ea5c55230715a58EBb0b703bCD4B, private key: 0xc484de1ef84e998869d59752d1f09bffa161673d54250ea152ec82d684e2f154
Account 4: 0xBb46AbbCC95213754f549E0CFa2B13bef0aBFaB6, private key: 0x4d5211ccb78c977d7ae7094b27b561458274a1c2df8be5f3c66479fe33ea8838
Account 5: 0x8E1Ad6FaC6ea5871140594ABEF5b1D503385e936, private key: 0x3c6efff45290e2204cc19b091cdefffcead5757b074b1723e9cf8973e6337ba4
Account 6: 0xC8D063A7e0A118432721daE5e059404b5598BD76, private key: 0x81f43b0303746bfacbaae64947850e86deca412d3b39b1f8d3c89bf483d615f3
Account 7: 0xc32ec0115BCB6693d4b4854531cA5e6a99217ABF, private key: 0xeca0930606860b8ae4a7f2b9a56ee62c4e11f613a894810b7642cabef689cf09
Account 8: 0x7fd60C817837dCFEFCa6D0A52A44980d12F70C59, private key: 0x68ef711b398fa47f22fbc44a972efbd2c2e25338e7c6afb92dc84b569bf784a5
  • (Optional) Below are commands to generate above account & keys from init-holders folder.

    # install web3
    pip3 install web3
    
    # generate account & private keys from "init-holders" folder
    python3 private-key.py
    
    • You can add more key files (with empty decoded password) into init-holders folder and re-run above command.

Simple Validator Node Cluster

  • Execute below commands to build & start a simple cluster with only 1 validator and 1 rpc node (refer to Makefile for details):

    # Build all docker images
    make build-simple
    
    # Generate genesis.json, validators & bootstrap cluster data
    # Once finished, all cluster bootstrap data are generated at ./storage
    make bootstrap-simple
    
    # Start cluster
    make start-simple
  • Go to http://localhost:3000/ verify all nodes gradually connected to each other and block start counting.

  • Run make run-test-simple to start bep20 truffle test.

Three Validator Node Cluster

  • Reset existing simple cluster data

    make reset
  • Execute below commands to build & start 3 validators cluster with 1 rpc node (refer to Makefile for details):

    # Build all docker images
    make build-cluster
    
    # Generate genesis.json, validators & bootstrap cluster data
    # Once finished, all cluster bootstrap data are generated at ./storage
    make bootstrap-cluster
    
    # Start cluster
    make start-cluster
  • Go to http://localhost:3000/ verify all nodes gradually connected to each other and block start counting.

  • Run make run-test-cluster to start bep20 truffle test.

Development Configuration

You may need to rebuild BSC docker image, reset data or start cluster with new configuration.

[Optional] Rebuild BSC Docker Image:

  • Edit docker-compose.bsc.yml:
  • Modify GIT_SOURCE point to your own private repo.
  • Modify GIT_CHECKOUT_REF point to related (branch / tags / commit).
  • Execute: make build-simple or make build-cluster to rebuild bsc docker

[Optional] Reset Data:

  • Execute make reset to remove all data
  • Execute: make bootstrap-simple or make bootstrap-cluster to generate new bsc data

[Optional] Start Cluster With New Configuration:

  • Edit below config files to adjust rpc & validators options:
    • config/config-bsc-rpc.toml
    • config/config-bsc-validator.toml
  • Edit below script files to adjust rpc & validators run command:
    • scripts/bsc-rpc.sh
    • scripts/bsc-validator.sh
  • Finally, execute either make start-simple and make start-cluster to start

Bootnode Configuration

The bsc-rpc act as a bootstrap endpoint with config/bootstrap.key and its corresponding BOOTSTRAP_PUB_KEY (as in .env).

If you want to generate a new bootstrap.key and BOOTSTRAP_PUB_KEY, just execute below commands:

# this ./bootnode binary only applicable for MacOS
chmod +x ./bootnode

# Generate bootstrap.key
./bootnode -genkey bootstrap.key

# Create a new BOOTSTRAP_PUB_KEY from bootstrap.key
./bootnode -nodekey bootstrap.key -writeaddress
  • Then, copy bootstrap.key over config directory
  • Finally, edit .env set BOOTSTRAP_PUB_KEY to new created value.
    • It will be used to construct bootnode endpoint enode://${BOOTSTRAP_PUB_KEY}@${BOOTSTRAP_IP}:30311 for peer discovery mechanism.