Boost comes with a client executable, boost, that can be used to send a deal proposal to a Boost server.

The client is intentionally minimal meant for developer testing. It is not a full featured client and is not intended to be so. It does not require a daemon process, and can be pointed at any public Filecoin API for on-chain operations. This means that users of the client do not need to run a Filecoin node that syncs the chain.

Set the API endpoint environment variable

export FULLNODE_API_INFO=<filecoin API endpoint>

Initialize the client

boost -vv init

The init command

• Creates a Boost client repository (at ~/.boost-client by default)

• Generates a libp2p peer ID key

• Generates a wallet for on-chain operations and outputs the wallet address

Add funds to the wallet and to the market actor

To make deals you will need to: a) add funds to the wallet b) add funds to the market actor for that wallet address

Make a storage deal

Currently, we don't distribute binaries, so you will have to build from source.

boost -vv deal --provider=<f00001> \
               --http-url=<https://myserver/my.car> \
               --commp=<commp> \
               --car-size=<car-size> \
               --piece-size=<piece-size> \
               --payload-cid=<payload-cid>

When a storage provider accepts the deal, you should see output of the command similar to:

sent deal proposal
  deal uuid: 9e68fb16-ff9a-488e-ad0a-1289b512d176
  storage provider: f0127896
  client wallet: f1sw5zjcyo4mff5cbvgsgmm8uoko6gcr4tptvtkhy
  payload cid: bafyaa6qshafcmalqudsbeidrunclaep6mdbipm2gjfvuosjfd6cbqd6th7bshy5hi5npxe727yjaagelucbyabasgafcmalqudsaeieapsxspo2i36no36n7yitswsxdazvziwvgj4vbp2scuxasrc6n4ejaage3r7m3saykcqeaegeavdllsbzaqcaibaaeecakrvvzam
  url: https://webserver/file.car
  commp: baga6ea4seaqh5prrl6ykov4t64k6m5giijsc44dcxtdnzsp4izjakqhs7twauiq
  start epoch: 1700711
  end epoch: 2219111
  provider collateral: 358.687 μFIL

Check deal status

You can check the deal status with the following command:

boost deal-status --provider=<provider> --deal-uuid=<deal-uuid>

got deal status response
  deal uuid: 9e68fb16-ff8a-488e-ad0a-1289b512d176
  deal status: Transfer Queued
  deal label: bafyaa6qsgafcmalqudsaeidrunclaep6mdbipm2gjfvuosjfd6cbqd6th7bshy5hi5npxe727yjaagelucbyabasgafcmalqudsaeieapsxspo2i36no36n7yitswsxdazvziwvgj4vbp2scuxasrc6n4ejaage3r7m3saykcqeaegeavdllsbzaqcaibaaeecakrvvzam
  publish cid: <nil>
  chain deal id: 0

Initialization and Running

1. Make sure you have a Lotus node and miner running

2. Create and send funds to two new wallets on the lotus node to be used for Boost

Boost currently uses two wallets for storage deals:

• The publish storage deals wallet - This wallet pays the gas cost when Boost sends the PublishStorageDeals message.

• The deal collateral wallet - When the Storage Provider accepts a deal, they must put collateral for the deal into escrow. Boost moves funds from this wallet into escrow with the StorageMarketActor.

export PUBLISH_STORAGE_DEALS_WALLET=`lotus wallet new bls`
export COLLAT_WALLET=`lotus wallet new bls`
lotus send --from mywallet $PUBLISH_STORAGE_DEALS_WALLET 10
lotus send --from mywallet $COLLAT_WALLET 10

3. Set the publish storage deals wallet as a control wallet.

lotus-miner actor control set --really-do-it $PUBLISH_STORAGE_DEALS_WALLET

4. Create and initialize the Boost repository

Boost keeps all data in a directory called the repository. By default the repository is at ~/.boost. To use a different location pass the --boost-repo parameter (must precede any particular command verb, e.g. boostd --boost-repo=/path init).

Export the environment variables needed for boostd init to connect to the lotus daemon and lotus miner.

export $(lotus auth api-info --perm=admin)
export $(lotus-miner auth api-info --perm=admin)

Export environment variables that point to the API endpoints for the sealing and mining processes. They will be used by the boost node to make JSON-RPC calls to the mining/sealing/proving node.

export APISEALER=`echo $MINER_API_INFO`
export APISECTORINDEX=`echo $MINER_API_INFO`

Run boostd init to create and initialize the repository:

boostd --vv init \
       --api-sealer=$APISEALER \
       --api-sector-index=$APISECTORINDEX \
       --wallet-publish-storage-deals=$PUBLISH_STORAGE_DEALS_WALLET \
       --wallet-deal-collateral=$COLLAT_WALLET \
       --max-staging-deals-bytes=50000000000

• --api-sealer is the API info for the lotus-miner instance that does sealing

• --api-sector-index is the API info for the lotus-miner instance that provides storage

• --max-staging-deals-bytes is the maximum amount of storage to be used for downloaded files (once the limit is reached Boost will reject subsequent incoming deals)

5. Update ulimit file descriptor limit if necessary. Boost deals will fail if the file descriptor limit for the process is not set high enough. This limit can be raised temporarily before starting the Boost process by running the command ulimit -n 1048576. We recommend setting it permanently by following the Permanently Setting Your ULIMIT System Value guide.

6. Make sure that the correct <PEER_ID> and <MULTIADDR> for your SP is set on chain, given that boost init generates a new identity. Use the following commands to update the values on chain:

lotus-miner actor set-addrs <MULTIADDR>
lotus-miner actor set-peer-id <PEER_ID>

7. Run the boostd service, which will start:

• libp2p listeners for storage and retrieval

• the JSON RPC API

• the graphql interface (used by the react front-end)

• the web server for the react front-end

boostd --vv run

Web UI

1. Build the React frontend

cd react

# Download and install npm packages needed by the React frontend
npm install --legacy-peer-deps

# Build the optimized JavaScript and CSS in boost/react/build
npm run build

1. Open the Web UI

Open http://localhost:8080 in your browser.

ssh -L 8080:localhost:8080 myserver

API Access

Boost API can be accessed by setting the environment variable BOOST_API_INFO same as LOTUS_MARKET_INFO.

boostd auth api-info --perm=admin

export BOOST_API_INFO=<TOKEN>:<API Address>

You can also directly evaluate the boostd auth command with:

export $(boostd auth api-info --perm=admin)

The Boost source code repository is hosted at github.com/filecoin-project/boost

Boost and Lotus compatibility Matrix

Building and installing

Prerequisites

Environment Variables in Boost

BOOST_CLIENT_REPO         - repo directory for Boost client
BOOSTER_BITSWAP_REP       - repo directory for Booster bitswap
BOOST_PATH                - boost repo path
FULLNODE_API_INFO         - Lotus daemon node API connection string

Linux / Ubuntu

curl -sL https://deb.nodesource.com/setup_16.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo apt install mesa-opencl-icd ocl-icd-opencl-dev gcc git bzr jq pkg-config curl clang build-essential hwloc libhwloc-dev wget -y

MacOS

brew install node@16
brew install bzr jq pkg-config hwloc coreutils

Linux

export RUSTFLAGS="-C target-cpu=native -g"
export FFI_BUILD_FROM_SOURCE=1

git clone https://github.com/filecoin-project/boost
cd boost
git checkout <Stable tag or branch>
make clean build
sudo make install

Please ignore any output or onscreen instruction during the npm build unless there is an error.

MacOS

export LIBRARY_PATH=$LIBRARY_PATH:/opt/homebrew/lib
git clone https://github.com/filecoin-project/boost
cd boost
git checkout <Stable tag or branch>
make clean build
sudo make install

Please ignore any output or onscreen instruction during the npm build unless there is an error.

Calibration Network

To build boost for calibnet, please complete the above pre-requisites and build using the following commands.

git clone https://github.com/filecoin-project/boost
cd boost
git checkout <Stable tag or branch>
make clean calibnet

Upgrading Boost

Linux

1. Make sure that Boost daemon is not running. Run the below commands to upgrade the binary.

cd boost
git checkout main
git pull
git checkout <New release>
make clean build
sudo make install

2. Please ignore any onscreen instruction during the npm build unless there is an error.

3. Start the boost daemon.

MacOS

1. Make sure that Boost daemon is not running. Run the below commands to upgrade the binary.

export LIBRARY_PATH=$LIBRARY_PATH:/opt/homebrew/lib
cd boost
git checkout main
git pull
git checkout <New release>
make clean build
sudo make install

2. Please ignore any onscreen instruction during the npm build unless there is an error.

3. Start the boost daemon.