465 lines
16 KiB
Markdown
465 lines
16 KiB
Markdown
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](/doc/API.md#host-db).
|
|
For an overview of all API routes, see [API.md](/doc/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](#hostdbactive-get-example) | GET | [Active hosts](#active-hosts) |
|
|
| [/hostdb/all](#hostdball-get-example) | GET | [All hosts](#all-hosts) |
|
|
| [/hostdb/hosts/___:pubkey___](#hostdbhosts-get-example) | GET | [Hosts](#hosts) |
|
|
|
|
#### /hostdb/active [GET] [(example)](#active-hosts)
|
|
|
|
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
|
|
```javascript
|
|
{
|
|
"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)](#all-hosts)
|
|
|
|
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
|
|
```javascript
|
|
{
|
|
"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/hosts/___:pubkey___ [GET] [(example)](#hosts)
|
|
|
|
fetches detailed information about a particular host, including metrics
|
|
regarding the score of the host within the database. It should be noted that
|
|
each renter uses different metrics for selecting hosts, and that a good score on
|
|
in one hostdb does not mean that the host will be successful on the network
|
|
overall.
|
|
|
|
###### Path Parameters
|
|
```
|
|
// The public key of the host. Each public key identifies a single host.
|
|
//
|
|
// Example Pubkey: ed25519:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
|
|
|
|
:pubkey
|
|
```
|
|
|
|
###### JSON Response
|
|
```javascript
|
|
{
|
|
"entry": {
|
|
// 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="
|
|
},
|
|
|
|
// The string representation of the full public key, used when calling
|
|
// /hostdb/hosts.
|
|
"publickeystring": "ed25519:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
|
|
},
|
|
|
|
// A set of scores as determined by the renter. Generally, the host's final
|
|
// final score is all of the values multiplied together. Modified renters may
|
|
// have additional criteria that they use to judge a host, or may ignore
|
|
// certin criteia. In general, these fields should only be used as a loose
|
|
// guide for the score of a host, as every renter sees the world differently
|
|
// and uses different metrics to evaluate hosts.
|
|
"scorebreakdown": {
|
|
// The multiplier that gets applied to the host based on how long it has
|
|
// been a host. Older hosts typically have a lower penalty.
|
|
"ageadjustment": 0.1234,
|
|
|
|
// The multiplier that gets applied to the host based on how much
|
|
// proof-of-burn the host has performed. More burn causes a linear increase
|
|
// in score.
|
|
"burnadjustment": 23.456,
|
|
|
|
// The multiplier that gets applied to a host based on how much collateral
|
|
// the host is offering. More collateral is typically better, though above
|
|
// a point it can be detrimental.
|
|
"collateraladjustment": 23.456,
|
|
|
|
// The multiplier that gets applied to a host based on the host's price.
|
|
// Lower prices are almost always better. Below a certain, very low price,
|
|
// there is no advantage.
|
|
"priceadjustment": 0.1234,
|
|
|
|
// The multiplier that gets applied to a host based on how much storage is
|
|
// remaining for the host. More storage remaining is better, to a point.
|
|
"storageremainingadjustment": 0.1234,
|
|
|
|
// The multiplier that gets applied to a host based on the uptime percentage
|
|
// of the host. The penalty increases extremely quickly as uptime drops
|
|
// below 90%.
|
|
"uptimeadjustment": 0.1234,
|
|
|
|
// The multiplier that gets applied to a host based on the version of Sia
|
|
// that they are running. Versions get penalties if there are known bugs,
|
|
// scaling limitations, performance limitations, etc. Generally, the most
|
|
// recent version is always the one with the highest score.
|
|
"versionadjustment": 0.1234
|
|
}
|
|
}
|
|
```
|
|
|
|
Examples
|
|
--------
|
|
|
|
#### Active hosts
|
|
|
|
###### Request
|
|
```
|
|
/hostdb/active?numhosts=2
|
|
```
|
|
|
|
###### Expected Response Code
|
|
```
|
|
200 OK
|
|
```
|
|
|
|
###### Example JSON Response
|
|
```javascript
|
|
{
|
|
"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="
|
|
}
|
|
"publickeystring": "ed25519:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
|
|
},
|
|
{
|
|
"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="
|
|
}
|
|
"publickeystring": "ed25519:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
#### All hosts
|
|
|
|
###### Request
|
|
```
|
|
/hostdb/all
|
|
```
|
|
|
|
###### Expected Response Code
|
|
```
|
|
200 OK
|
|
```
|
|
|
|
###### Example JSON Response
|
|
```javascript
|
|
{
|
|
"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="
|
|
}
|
|
"publickeystring": "ed25519:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
|
|
},
|
|
{
|
|
"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="
|
|
}
|
|
"publickeystring": "ed25519:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
|
|
},
|
|
{
|
|
"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="
|
|
}
|
|
"publickeystring": "ed25519:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
#### Hosts
|
|
|
|
###### Request
|
|
```
|
|
/hostdb/hosts/ed25519:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
|
|
```
|
|
|
|
###### Expected Response Code
|
|
```
|
|
200 OK
|
|
```
|
|
|
|
###### Example JSON Response
|
|
```javascript
|
|
{
|
|
"entry": {
|
|
"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="
|
|
}
|
|
"publickeystring": "ed25519:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
|
|
},
|
|
"scorebreakdown": {
|
|
"ageadjustment": 0.1234,
|
|
"burnadjustment": 0.1234,
|
|
"collateraladjustment": 23.456,
|
|
"priceadjustment": 0.1234,
|
|
"storageremainingadjustment": 0.1234,
|
|
"uptimeadjustment": 0.1234,
|
|
"versionadjustment": 0.1234,
|
|
}
|
|
}
|
|
```
|