BTFS

The BTFS Developer Hub

Welcome to the BTFS developer hub. You'll find comprehensive guides and documentation to help you start working with BTFS as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Run a BTFS Host

Run a BTFS file storage host on the BTFS network

Introduction

Hosts play a vital part in the BTFS network. As a host, your participation enables the decentralization of vast file storage network, while at the same time capitalizes your spare resources by rewarding you with BTT.

How It Works

When a renter uploads a file, the file is split into 30 shards, with each shard being stored in a host under contract. By default, each contract produces a payout to the host every 30 calendar days. File shards are "pinned" in a hosts' storage for the contract duration, ensuring that as long as the host remains available, the file shards are guaranteed to be stored.

Command Line Setup

You may also choose to configure Host settings via the terminal. First set up your BTFS daemon. Then enable the BTFS host config settings:

btfs config profile apply storage-host

This command updates your BTFS config settings to enable storage hosting. You can verify this by viewing your config file:

btfs config show


// Under "Experimental", the StorageHostEnabled setting is set to true

"StorageHostEnabled": true,

Host Dashboard

The BTFS Host Dashboard lets hosts conveniently adjust the storage size allocation, monitor BTT earned-to-date, calculate future potential BTT earnings, and much more. Once your BTFS daemon has been launched and is running, simply paste the URL http://127.0.0.1:5001/hostui into your browser to access the Host Dashboard.

Once the Host Dashboard launches, the first screen prompts for hosts to adjust storage size commitment:

Upon launching the Host Dashboard, you will be greeted with a prompt to select your dedicated host storage space.


After committing the storage space, your Host daemon commences the syncing process with the BTFS network. Please be patient, as the syncing process may take some time for completion.


If the syncing process is taking longer than 45 minutes, please make sure you enabled host profile:
btfs config profile apply storage-host

Once network syncing completes, you will see the complete hosting dashboard:

Dashboard Components

  • Status: This tells you if your BTFS host is online or offline.
  • Score: This score reflects your hosting ability. The higher your score, the more likely you will receive hosting contracts. To improve your score, ensure that your host is running and connected to the network at all times.
  • Uptime: The percentage of time your BTFS host is running and connected to the network.
  • Contracts: The number of file contracts your host is currently entered into.
  • Earnings To-Date: The amount of BTT your BTFS host daemon has earned to date.
  • Future potential earnings: Your maximum potential earnings, based on the storage space committed.
  • Next payment date: The closest date in which a contract will produce a host payment.
  • Current host pricing: The current price set by the Host for hosting 1 TB/month, in BTT.
  • Host storage size: The proportion of used storage space vs. available storage space.

Configure Host Settings

The btfs storage announce command allows hosts to configure and update their preferred storage host settings. The following host configuration options are available:

Option

Description

Flag

Minimum Host Storage Time

Min number of days for storage.

-d, --host-storage-time-min

Maximum Host Storage Capacity

Max number of GB this host provides for storage.

-m, --host-storage-max

Set Host Collateral Price

Max collateral stake per GiB per hour in BTT.

--cl, --host-collateral-price

Host Bandwidth Limit

Max bandwidth limit per MB/s.

-l, --host-bandwidth-limit

Minimum Host Storage Time

Min number of days for storage.

-d, --host-storage-time-min

Maximum Host Storage Capacity

Max number of GB this host provides for storage.

-m, --host-storage-max

Minimum Host Storage Time

btfs storage announce --host-storage-time-min=5

Maximum Host Storage Capacity

btfs storage announce --host-storage-max=5

// Under "Datastore" in your BTFS config, the Storage Max is set to 5 GB

"StorageMax": "5.0 GB"

📘

Withdrawing BTT

If you need to withdraw your BTT earnings, please refer to https://docs.btfs.io/docs/requirements#section-installing-go-btfs. Please note, currently, we only accept withdraw inquiries for earnings at 1,000 BTT or more.


Viewing Contract Details

As a host in the BTFS network, you can view a list of all active contracts. In the terminal, run the btfs storage contracts list host command:

// Retrieve list of contracts your node stores as a host

btfs storage contracts list host


// Output

{
  "contracts": [
    {
      "contract_id": "3223022b-8aa6-482d-84fa-1cecffdaa765,249e3a07-6734-42e8-8105-09b3f3503d16",
      "host_id": "16Uiu2HAm3Sdp1234XcSAz1234oHBM4321gHbS112345Gsb1nN6hj",
      "renter_id": "16Uiu212345Ga3p12345mWAKs12345Nt554321d6uAuTUrJRxxQ5B",
      "status": 0,
      "start_time": "2020-04-25T23:02:33.167313Z",
      "end_time": "2020-05-25T23:02:33.167313Z",
      "next_escrow_time": "0001-01-01T00:00:00Z",
      "compensation_paid": 0,
      "compensation_outstanding": 0,
      "unit_price": 250000,
      "shard_size": 17179,
      "shard_hash": "QmRACVKCvPtvpq77cxSekTEgPPCKJULSDvbxCAzoYyhQEU",
      "file_hash": "QmZdatooDNrAvQ8CSvdBsnXjnbhffw8wAgn9sRyvYPwqaq"
    },
   
   ...
   
    {
      "contract_id": "3223022b-8aa6-482d-84fa-1cecffdaa765,ee9545c7-d686-4d00-bd8d-1718dbaa80b1",
      "host_id": "16Uiu2HAmEQu5R829qwziii9HgS9tydfH7WsKvG3V1ZGbpiM36LEn",
      "renter_id": "16Uiu2HAmEaGa3pxCqKSmWAKsZVgQJNt5V4nkMd6uAuTUrJRxxQ5B",
      "status": 0,
      "start_time": "2020-04-25T23:17:32.656925Z",
      "end_time": "2020-05-25T23:17:32.656925Z",
      "next_escrow_time": "0001-01-01T00:00:00Z",
      "compensation_paid": 0,
      "compensation_outstanding": 0,
      "unit_price": 250000,
      "shard_size": 17179,
      "shard_hash": "QmfP4qbuLo32ra8u48JwzTJJ14ipvjfkyoJwyLgZQxe6Bs",
      "file_hash": "QmZdatooDNrAvQ8CSvdBsnXjnbhffw8wAgn9sRyvYPwqaq"
    }
  ]
}

The output parameters contain the following details:

  • contract_id: The ID for the file shard contract.
  • host_id: The peer ID for the BTFS host storing the file shard.
  • renter_id: The peer ID for the BTFS renter who uploaded the file shard.
  • start_time: The contract start time.
  • end_time: The contract completion time.
  • next_escrow_time: The next payment time.
  • compensation_paid: Total BTT paid in contract.
  • compensation_outstanding: Outstanding BTT payments remaining in the contract.
  • unit_price: The price in μBTT (10^-6 BTT) of renting 1 TB/month of storage space.
  • shard_size: The size of the file shard, in bytes.
  • shard_hash: The SHA-256 hash value of the file shard.
  • file_hash: The SHA-256 hash value of the file.

Updated 4 months ago

Run a BTFS Host


Run a BTFS file storage host on the BTFS network

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.