Skip to main content

Run Local SP Network

This guide helps you to set up a local Greenfield Storage Provider network for testing and other development related purposes.

The following lists the recommended hardware requirements:

  • VPS running recent versions of Mac OS X, Linux, or Windows；
  • 16 cores of CPU, 64 GB of memory(RAM);
  • At least 100GB disk space for backend storage;
  • 10GB+ SQL Database.

Quickly setup local Greenfield blockchain network​

  1. Build Greenfield Blockchain

Note Greenfield blockchain uses a lib which uses cgo, so you should set cgo env var; in addition, you should install gcc compiler in your OS.

git clone https://github.com/bnb-chain/greenfield.git
cd greenfield/
export CGO_ENABLED=1
make build

If you encountered the following error messages while compiling greenfield blockchain, you should install glibc-static and libstdc++-static.

# command-line-arguments
/usr/local/go/pkg/tool/linux_amd64/link: running gcc failed: exit status 1
/bin/ld: cannot find -lstdc++
collect2: error: ld returned 1 exit status

make: *** [build] Error 1
  1. Start Greenfield Blockchain
# 1 validator and 8 storage providers
bash ./deployment/localup/localup.sh all 1 8
  1. Export the keys of SPs
bash ./deployment/localup/localup.sh export_sps 1 8

# result example
# {
#   "sp0": {
#     "OperatorAddress": "0x14539343413EB47899B0935287ab1111Df891d04",
#     "FundingAddress": "0x21c6ff21DD7012DE1CCf9055f2eB234A44a1d3fB",
#     "SealAddress": "0x8e424c6Db42Ad9A5d91b24e20b5f603eC70abbA3",
#     "ApprovalAddress": "0x7Aa5C8B50696f1D15B3A60d6629f7318c605bb4C",
#     "GcAddress": "0xfa238a4B262e1dc35c4970A2296A2444B956c9Ca",
#     "MaintenanceAddress": "0xbE03316B1D7c3FCB69136e47e02442d6Fb3396dB",
#     "OperatorPrivateKey": "ba6e97958d9c43d1ad54923eba99f8d59f54a0c66c78a5dcbc004c5c3ec72f8c",
#     "FundingPrivateKey": "bd9d9e7823cd2dc7bc20f1b6676c3025cdda6cf5a8df9b04597fdff42c29af01",
#     "SealPrivateKey": "aacd6b834627fdbc5de2bfdb1db31be0ea810a941854787653814c8040a9dd39",
#     "ApprovalPrivateKey": "32108ed1a47c0af965824f84ac2162c029f347eec6d0988e642330b0ac264c85",
#     "GcPrivateKey": "2fad16031b4fd9facb7dacda3da4ca4dd5f005f4166891bf9f7be13e02abb12d",
#     "MaintenancePrivateKey": "cc38f4c004f73a810223776376a37a8ab3ed8204214f5a3a0a2f77f7bb5e2dc1",
#     "BlsPrivateKey": "6f349866f18413abb1a78cab947933459042044649686f354e941a646b9ed6e7"
#   }
#   ...
# }

These JSON data will be used for setup local SP network, so you'd better save it as a json file:

bash ./deployment/localup/localup.sh export_sps 1 8 > sp.json

Setup local SP network​

  1. Compile SP

Users who want to compile SP can refer this doc.

  1. Generate localup env

Use the following instruction to generate template config file, sp.info and db.info in seven different directories. This command is used for generating sp env the first time or regenerating sp env.

# This command accepts four args, the first arg is json file path that only supports absolute path, the second arg is db user name,
# the third arg is db password and the fourth arg is db address.
cd greenfield-storage-provider/
bash ./deployment/localup/localup.sh --generate json_file_path db_username db_password db_address

The json file path accepted for the first arg is generated by quickly setup local greenfield blockchain network step3.

View directory structure:

ls deployment/localup/local_env/sp0
├── sp0
│   ├── config.toml   # generated template config file
│   ├── db.info       # generated db.info is used for config.toml
│   ├── gnfd-sp0      # gnfd-sp binary
│   └── sp.info       # generated sp.info is used for config.toml
├── sp1
├── ...
# An example for generating local sp env
cd greenfield-storage-provider/
bash ./deployment/localup/localup.sh --generate /root/sp.json root greenfield localhost:3306

[root@yourmachine sp0]# cat db.info
#!/usr/bin/env bash
USER="root"                     # database username
PWD="greenfield"                # database password
ADDRESS="localhost:3306"        # db endpoint, e.g. "localhost:3306"
DATABASE="sp_0"                 # database name

[root@yourmachine sp0]# cat sp.info
#!/usr/bin/env bash
SP_ENDPOINT="127.0.0.1:9033"                                                              # gateway endpoint, e.g. "127.0.0.1:9033"
OPERATOR_ADDRESS="0x14539343413EB47899B0935287ab1111Df891d04"                             # OperatorAddr is generated in setup local Greenfield blockchain step 3.
OPERATOR_PRIVATE_KEY="ba6e97958d9c43d1ad54923eba99f8d59f54a0c66c78a5dcbc004c5c3ec72f8c"   # OperatorPrivKey is generated in setup local Greenfield blockchain step 3.
FUNDING_PRIVATE_KEY="bd9d9e7823cd2dc7bc20f1b6676c3025cdda6cf5a8df9b04597fdff42c29af01"    # FundingPrivKey is generated in setup local Greenfield blockchain step 3.
SEAL_PRIVATE_KEY="aacd6b834627fdbc5de2bfdb1db31be0ea810a941854787653814c8040a9dd39"       # SealPrivKey is generated in setup local Greenfield blockchain step 3.
APPROVAL_PRIVATE_KEY="32108ed1a47c0af965824f84ac2162c029f347eec6d0988e642330b0ac264c85"   # ApprovalPrivKey is generated in setup local Greenfield blockchain step 3.
GC_PRIVATE_KEY="2fad16031b4fd9facb7dacda3da4ca4dd5f005f4166891bf9f7be13e02abb12d"         # GcPrivateKey is generated in setup local Greenfield blockchain step 3.
BLS_PRIVATE_KEY="6f349866f18413abb1a78cab947933459042044649686f354e941a646b9ed6e7"        # BlsPrivateKey is generated in setup local Greenfield blockchain step 3.
  1. Start Eight SPs

Make config.toml according to db.info, sp.info and start eight SPs.

cd greenfield-storage-provider/
bash ./deployment/localup/localup.sh --reset
bash ./deployment/localup/localup.sh --start

The environment directory is as follows:

deployment/localup/local_env/
├── sp0
│   ├── config.toml    # real config
│   ├── data/          # piecestore data directory
│   ├── db.info
│   ├── gnfd-sp0
│   ├── gnfd-sp.log    # gnfd-sp log file
│   ├── log.txt
│   └── sp.info
├── sp1
├── ...
Recompile SP

If you want to modify config.toml in different sp directories or recompile gnfd-sp binary file, you can use the following commands to reset and start local sp:

cd greenfield-storage-provider/
bash ./deployment/localup/localup.sh --reset
bash ./deployment/localup/localup.sh --start
  1. Supported commands
# this command should be executed in greenfield-storage-provider/ directory.
bash ./deployment/localup/localup.sh --help

Usage: deployment/localup/localup.sh [option...] {help|generate|reset|start|stop|print}

   --help            display help info
   --generate        generate sp.info and db.info that accepts four args: the first arg is json file path, the second arg is db username, the third arg is db password and the fourth arg is db address
   --reset           reset env
   --start           start storage providers
   --stop            stop storage providers
   --clean           clean local sp env
   --print           print sp local env work directory

Operate With SP​

If you have already started Greenfield blockchain and Greenfield SP successfully in local, you can use Greenfield Cmd to operate with SP such as CreateBucket, PutObject and GetObject. Detailed info about Greenfield Cmd can be found here.

tip

We strongly recommend you reading Greenfield Cmd. It will help you explore the functions of Greenfield blockchain and SP.

Next, We provide you a hand by hand tutorial to operate with chain and SP.

1. Generate your test account​

We firstly need to generate a test account and private key:

cd greenfield/
# this command will generate a test account whose name is testkey, you can change its name
./build/bin/gnfd keys add testkey --keyring-backend os
# export the private key of test account
./build/bin/gnfd keys export testkey --unarmored-hex --unsafe --keyring-backend os

2. Transefer some BNB tokens to test account​

After generating test account, there are no any tokens in this account. We should transefer some BNB tokens:

cd greenfield/
# transefer 5000 BNB tokens
./gnfd tx bank send validator0 {generated_test_account_address} 500000000000000000000BNB --home /{your_greenfield_path}/greenfield/deployment/localup/.local/validator0 --keyring-backend test --node http://localhost:26750 -y
# query your account balances
./gnfd q bank balances {generated_test_account_address} --node http://localhost:26750

3. Use cmd to send requests​

If you come in this step, congratulations, you can operate with your own private chain and SP.

First, we need to configure cmd:

cd greenfield-cmd/
make build
cd build/
# generate a keystore file to manage private key information
touch key.txt & echo ${TEST_ACCOUNT_PRIVATE_KEY} > key.txt
touch password.txt & echo "test_sp_function" > password.txt
./gnfd-cmd --home ./  --passwordfile password.txt account import key.txt 

# construct config.toml
touch config.toml
{
   echo rpcAddr = \"http://localhost:26750\"
   echo chainId = \"greenfield_9000-121\"
} > config.toml

Second, you can do some operations with SP:

  1. Create bucket
# list current available SPs
./gnfd-cmd -c ./config.toml --home ./ sp ls
# random choose one SP to create bucket
./gnfd-cmd -c ./config.toml --home ./ bucket create gnfd://${BUCKET_NAME}
# head bucket info
./gnfd-cmd -c ./config.toml --home ./ bucket head gnfd://${BUCKET_NAME}
# choose one sp to create bucket, operator_address is shown in sp ls result
./gnfd-cmd -c ./config.toml --home ./ bucket create --primarySP ${operator_address} gnfd://${BUCKET_NAME}
  1. PutObject & GetObject
# generate a 17MB random file
dd if=/dev/urandom of=./random_file bs=17M count=1
# put object
./gnfd-cmd -c ./config.toml --home ./ object put --contentType "application/octet-stream" ./random_file gnfd://${BUCKET_NAME}/random_file
# get object
./gnfd-cmd -c ./config.toml --home ./ object get gnfd://${BUCKET_NAME}/random_file ./new_random_file

Users can use md5 to compare your generated file and downloaded file whether is the same.

You can explore other functions of Greenfield Cmd.