9.2 KiB
9.2 KiB
Host DB API
This document contains detailed descriptions of the hostdb's API routes. For an overview of the hostdb's API routes, see API.md#host-db. For an overview of all API routes, see API.md
There may be functional API calls which are not documented. These are not guaranteed to be supported beyond the current release, and should not be used in production.
Overview
The hostdb maintains a database of all hosts known to the network. The database identifies hosts by their public key and keeps track of metrics such as price.
Index
| Request | HTTP Verb | Examples |
|---|---|---|
| /hostdb/active | GET | Active hosts |
| /hostdb/all | GET | All hosts |
/hostdb/active [GET] (example)
lists all of the active hosts known to the renter, sorted by preference.
Query String Parameters
// Number of hosts to return. The actual number of hosts returned may be less
// if there are insufficient active hosts. Optional, the default is all active
// hosts.
numhosts
JSON Response
{
"hosts": [
{
// true if the host is accepting new contracts.
"acceptingcontracts": true,
// Maximum number of bytes that the host will allow to be requested by a
// single download request.
"maxdownloadbatchsize": 17825792,
// Maximum duration in blocks that a host will allow for a file contract.
// The host commits to keeping files for the full duration under the
// threat of facing a large penalty for losing or dropping data before
// the duration is complete. The storage proof window of an incoming file
// contract must end before the current height + maxduration.
//
// There is a block approximately every 10 minutes.
// e.g. 1 day = 144 blocks
"maxduration": 25920,
// Maximum size in bytes of a single batch of file contract
// revisions. Larger batch sizes allow for higher throughput as there is
// significant communication overhead associated with performing a batch
// upload.
"maxrevisebatchsize": 17825792,
// Remote address of the host. It can be an IPv4, IPv6, or hostname,
// along with the port. IPv6 addresses are enclosed in square brackets.
"netaddress": "123.456.789.0:9982",
// Unused storage capacity the host claims it has, in bytes.
"remainingstorage": 35000000000,
// Smallest amount of data in bytes that can be uploaded or downloaded to
// or from the host.
"sectorsize": 4194304,
// Total amount of storage capacity the host claims it has, in bytes.
"totalstorage": 35000000000,
// Address at which the host can be paid when forming file contracts.
"unlockhash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab",
// A storage proof window is the number of blocks that the host has to
// get a storage proof onto the blockchain. The window size is the
// minimum size of window that the host will accept in a file contract.
"windowsize": 144,
// Public key used to identify and verify hosts.
"publickey": {
// Algorithm used for signing and verification. Typically "ed25519".
"algorithm": "ed25519",
// Key used to verify signed host messages.
"key": "RW50cm9weSBpc24ndCB3aGF0IGl0IHVzZWQgdG8gYmU="
}
}
]
}
/hostdb/all [GET] (example)
lists all of the hosts known to the renter. Hosts are not guaranteed to be in any particular order, and the order may change in subsequent calls.
JSON Response
{
"hosts": [
{
// true if the host is accepting new contracts.
"acceptingcontracts": true,
// Maximum number of bytes that the host will allow to be requested by a
// single download request.
"maxdownloadbatchsize": 17825792,
// Maximum duration in blocks that a host will allow for a file contract.
// The host commits to keeping files for the full duration under the
// threat of facing a large penalty for losing or dropping data before
// the duration is complete. The storage proof window of an incoming file
// contract must end before the current height + maxduration.
//
// There is a block approximately every 10 minutes.
// e.g. 1 day = 144 blocks
"maxduration": 25920,
// Maximum size in bytes of a single batch of file contract
// revisions. Larger batch sizes allow for higher throughput as there is
// significant communication overhead associated with performing a batch
// upload.
"maxrevisebatchsize": 17825792,
// Remote address of the host. It can be an IPv4, IPv6, or hostname,
// along with the port. IPv6 addresses are enclosed in square brackets.
"netaddress": "123.456.789.0:9982",
// Unused storage capacity the host claims it has, in bytes.
"remainingstorage": 35000000000,
// Smallest amount of data in bytes that can be uploaded or downloaded to
// or from the host.
"sectorsize": 4194304,
// Total amount of storage capacity the host claims it has, in bytes.
"totalstorage": 35000000000,
// Address at which the host can be paid when forming file contracts.
"unlockhash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab",
// A storage proof window is the number of blocks that the host has to
// get a storage proof onto the blockchain. The window size is the
// minimum size of window that the host will accept in a file contract.
"windowsize": 144,
// Public key used to identify and verify hosts.
"publickey": {
// Algorithm used for signing and verification. Typically "ed25519".
"algorithm": "ed25519",
// Key used to verify signed host messages.
"key": "RW50cm9weSBpc24ndCB3aGF0IGl0IHVzZWQgdG8gYmU="
}
}
]
}
Examples
Active hosts
Request
/hostdb/active?numhosts=2
Expected Response Code
200 OK
Example JSON Response
{
"hosts": [
{
"acceptingcontracts": true,
"maxdownloadbatchsize": 17825792,
"maxduration": 25920,
"maxrevisebatchsize": 17825792,
"netaddress": "123.456.789.0:9982",
"remainingstorage": 35000000000,
"sectorsize": 4194304,
"totalstorage": 35000000000,
"unlockhash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab",
"windowsize": 144,
"publickey": {
"algorithm": "ed25519",
"key": "RW50cm9weSBpc24ndCB3aGF0IGl0IHVzZWQgdG8gYmU="
}
},
{
"acceptingcontracts": true,
"maxdownloadbatchsize": 17825792,
"maxduration": 25920,
"maxrevisebatchsize": 17825792,
"netaddress": "123.456.789.1:9982",
"remainingstorage": 314,
"sectorsize": 4194304,
"totalstorage": 314159265359,
"unlockhash": "ba9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210",
"windowsize": 144,
"publickey": {
"algorithm": "ed25519",
"key": "WWVzIEJydWNlIFNjaG5laWVyIGNhbiByZWFkIHRoaXM="
}
}
]
}
All hosts
Request
/hostdb/all
Expected Response Code
200 OK
Example JSON Response
{
"hosts": [
{
"acceptingcontracts": false,
"maxdownloadbatchsize": 17825792,
"maxduration": 25920,
"maxrevisebatchsize": 17825792,
"netaddress": "123.456.789.2:9982",
"remainingstorage": 314,
"sectorsize": 4194304,
"totalstorage": 314159265359,
"unlockhash": "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789",
"windowsize": 144,
"publickey": {
"algorithm": "ed25519",
"key": "SSByYW4gb3V0IG9mIDMyIGNoYXIgbG9uZyBqb2tlcy4="
}
},
{
"acceptingcontracts": true,
"maxdownloadbatchsize": 17825792,
"maxduration": 25920,
"maxrevisebatchsize": 17825792,
"netaddress": "123.456.789.0:9982",
"remainingstorage": 35000000000,
"sectorsize": 4194304,
"totalstorage": 35000000000,
"unlockhash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab",
"windowsize": 144,
"publickey": {
"algorithm": "ed25519",
"key": "RW50cm9weSBpc24ndCB3aGF0IGl0IHVzZWQgdG8gYmU="
}
},
{
"acceptingcontracts": true,
"maxdownloadbatchsize": 17825792,
"maxduration": 25920,
"maxrevisebatchsize": 17825792,
"netaddress": "123.456.789.1:9982",
"remainingstorage": 314,
"sectorsize": 4194304,
"totalstorage": 314159265359,
"unlockhash": "ba9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210",
"windowsize": 144,
"publickey": {
"algorithm": "ed25519",
"key": "WWVzIEJydWNlIFNjaG5laWVyIGNhbiByZWFkIHRoaXM="
}
}
]
}