Host + Renter API
Here's my proposal:
Host
Queries:
- /host [GET]
- /host/announce [POST]
- /host/settings [GET]
- /host/settings [POST]
/host [GET]
Function: Returns basic information about the host, including the number of file contracts, the amount of storage remaining, and the host's profit to date.
Parameters: none
Response:
struct {
storageremaining int64
numcontracts int
profit int
potentialprofit int
competition int
unlockhash string
ipaddress string
}
/host/announce [POST]
Function: Announces the host to the network as a source of storage. Generally only needs to be called once.
Parameters: none
Response: standard
/host/settings [GET]
Function: Returns the current host configuration.
Parameters: none
Response:
struct {
totalstorage int
minfilesize int
maxfilesize int
minduration int
maxduration int
windowsize int
price int
collateral int
}
totalstorage
is how much storage (in bytes) the host will rent to the
network.
minfilesize
is the minimum allowed file size.
maxfilesize
is the maximum allowed file size.
minduration
is the minimum amount of time a contract is allowed to last.
maxduration
is the maximum amount of time a contract is allowed to last.
windowsize
is the number of blocks a host has to prove they are holding the
file.
price
is the cost (in hastings per byte) of data stored.
collateral
is the amount of collateral the host will offer (in hastings per
byte per block) for losing files on the network.
/host/settings [POST]
Function: Sets the host configuration.
Parameters:
totalstorage int
minfilesize int
maxfilesize int
minduration int
maxduration int
windowsize int
price int
collateral int
See the corresponding GET call for a description of each parameter.
Response: standard
The biggest change here is that settings
is now symmetrical. Also, the old configure
call would only modify supplied parameters; in the new scheme, all parameters are mandatory. This means that if you want to modify one field, you have to GET the old values and then POST the full updated version.
I also suggest two new endpoints, to be added some time in the future:
- /host/contracts [GET]
- /host/contracts/$(id) [GET]
contracts
would return a list of ids, which could be used to fetch a specific contract. (Alternatively, all contracts could be returned in one call.) There isn't much use for this right now, but I think eventually we'll want access to this information.