BlockStorage/siadrive
Archived
1
0
Fork 0
Code Activity

CEF changes

Browse Source
This commit is contained in:
Scott E. Graves
2017-03-17 18:57:20 -05:00
parent f647c45712
commit 5eecff152c
127 changed files with 1106 additions and 2210 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
3rd_party/Sia-v1.1.1-windows-amd64/doc/api/Consensus.md vendored Normal file
View File

@@ -0,0 +1,61 @@
Consensus API
=============
This document contains detailed descriptions of the consensus's API routes. For
an overview of the consensus' API routes, see
[API.md#consensus](/doc/API.md#consensus). 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 consensus set manages everything related to consensus and keeps the
blockchain in sync with the rest of the network. The consensus set's API
endpoint returns information about the state of the blockchain.
Index
-----
| Route | HTTP verb |
| --------------------------------------------------------------------------- | --------- |
| [/consensus](#consensus-get) | GET |
| [/consensus/validate/transactionset](#consensusvalidatetransactionset-post) | POST |
#### /consensus [GET]
returns information about the consensus set, such as the current block height.
###### JSON Response
```javascript
{
// True if the consensus set is synced with the network, i.e. it has downloaded the entire blockchain.
"synced": true,
// Number of blocks preceding the current block.
"height": 62248,
// Hash of the current block.
"currentblock": "00000000000008a84884ba827bdc868a17ba9c14011de33ff763bd95779a9cf1",
// An immediate child block of this block must have a hash less than this
// target for it to be valid.
"target": [0,0,0,0,0,0,11,48,125,79,116,89,136,74,42,27,5,14,10,31,23,53,226,238,202,219,5,204,38,32,59,165]
}
```
#### /consensus/validate/transactionset [POST]
validates a set of transactions using the current utxo set.
###### Request Body Bytes
Since transactions may be large, the transaction set is supplied in the POST
body, encoded in JSON format.
###### Response
standard success or error response. See
[#standard-responses](#standard-responses).

100
3rd_party/Sia-v1.1.1-windows-amd64/doc/api/Daemon.md vendored Normal file
View File

@@ -0,0 +1,100 @@
Daemon API
===========
This document contains detailed descriptions of the daemon's API routes. For an
overview of the daemon's API routes, see [API.md#daemon](/doc/API.md#daemon).
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 daemon is responsible for starting and stopping the modules which make up
the rest of Sia. It also provides endpoints for viewing build constants.
Index
-----
| Route | HTTP verb |
| ----------------------------------------- | --------- |
| [/daemon/constants](#daemonconstants-get) | GET |
| [/daemon/stop](#daemonstop-get) | GET |
| [/daemon/version](#daemonversion-get) | GET |
#### /daemon/constants [GET]
returns the set of constants in use.
###### JSON Response
```javascript
{
// Timestamp of the genesis block.
"genesistimestamp": 1433600000, // Unix time
// Maximum size, in bytes, of a block. Blocks larger than this will be
// rejected by peers.
"blocksizelimit": 2000000, // bytes
// Target for how frequently new blocks should be mined.
"blockfrequency": 600, // seconds per block
// Height of the window used to adjust the difficulty.
"targetwindow": 1000, // blocks
// Duration of the window used to adjust the difficulty.
"mediantimestampwindow": 11, // blocks
// How far in the future a block can be without being rejected. A block
// further into the future will not be accepted immediately, but the daemon
// will attempt to accept the block as soon as it is valid.
"futurethreshold": 10800, // seconds
// Total number of siafunds.
"siafundcount": "10000",
// Fraction of each file contract payout given to siafund holders.
"siafundportion": "39/1000",
// Number of children a block must have before it is considered "mature."
"maturitydelay": 144, // blocks
// Number of coins given to the miner of the first block. Note that elsewhere
// in the API currency is typically returned in hastings and as a bignum.
// This is not the case here.
"initialcoinbase": 300000, // Siacoins.
// Minimum number of coins paid out to the miner of a block (the coinbase
// decreases with each block). Note that elsewhere in the API currency is
// typically returned in hastings and as a bignum. This is not the case
// here.
"minimumcoinbase": 30000, // Siacoins
// Initial target.
"roottarget": [0,0,0,0,32,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
// Initial depth.
"rootdepth": [255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255],
// Largest allowed ratio between the old difficulty and the new difficulty.
"maxadjustmentup": "5/2",
// Smallest allowed ratio between the old difficulty and the new difficulty.
"maxadjustmentdown": "2/5",
// Number of Hastings in one siacoin.
"siacoinprecision": "1000000000000000000000000" // hastings per siacoin
}
```
#### /daemon/stop [GET]
cleanly shuts down the daemon. May take a few seconds.
###### Response
standard success or error response. See
[#standard-responses](#standard-responses).
#### /daemon/version [GET]
returns the version of the Sia daemon currently running.
###### JSON Response
```javascript
{
// Version number of the running Sia Daemon. This number is visible to its
// peers on the network.
"version": "1.0.0"
}
```

159
3rd_party/Sia-v1.1.1-windows-amd64/doc/api/Gateway.md vendored Normal file
View File

@@ -0,0 +1,159 @@
Gateway API
===========
This document contains detailed descriptions of the gateway's API routes. For
an overview of the gateway's API routes, see
[API.md#gateway](/doc/API.md#gateway). 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 gateway maintains a peer to peer connection to the network and provides a
method for calling RPCs on connected peers. The gateway's API endpoints expose
methods for viewing the connected peers, manually connecting to peers, and
manually disconnecting from peers. The gateway may connect or disconnect from
peers on its own.
Index
-----
| Route | HTTP verb | Examples |
| ---------------------------------------------------------------------------------- | --------- | ------------------------------------------------------- |
| [/gateway](#gateway-get-example) | GET | [Gateway info](#gateway-info) |
| [/gateway/connect/___:netaddress___](#gatewayconnectnetaddress-post-example) | POST | [Connecting to a peer](#connecting-to-a-peer) |
| [/gateway/disconnect/___:netaddress___](#gatewaydisconnectnetaddress-post-example) | POST | [Disconnecting from a peer](#disconnecting-from-a-peer) |
#### /gateway [GET] [(example)](#gateway-info)
returns information about the gateway, including the list of connected peers.
###### JSON Response
```javascript
{
// netaddress is the network address of the gateway as seen by the rest of
// the network. The address consists of the external IP address and the
// port Sia is listening on. It represents a `modules.NetAddress`.
"netaddress": String,
// peers is an array of peers the gateway is connected to. It represents
// an array of `modules.Peer`s.
"peers": []{
// netaddress is the address of the peer. It represents a
// `modules.NetAddress`.
"netaddress": String,
// version is the version number of the peer.
"version": String,
// inbound is true when the peer initiated the connection. This field
// is exposed as outbound peers are generally trusted more than inbound
// peers, as inbound peers are easily manipulated by an adversary.
"inbound": Boolean
}
}
```
#### /gateway/connect/{netaddress} [POST] [(example)](#connecting-to-a-peer)
connects the gateway to a peer. The peer is added to the node list if it is not
already present. The node list is the list of all nodes the gateway knows
about, but is not necessarily connected to.
###### Path Parameters
```
// netaddress is the address of the peer to connect to. It should be a
// reachable ip address and port number, of the form 'IP:port'. IPV6 addresses
// must be enclosed in square brackets.
//
// Example IPV4 address: 123.456.789.0:123
// Example IPV6 address: [123::456]:789
:netaddress
```
###### Response
standard success or error response. See
[API.md#standard-responses](/doc/API.md#standard-responses).
#### /gateway/disconnect/{netaddress} [POST] [(example)](#disconnecting-from-a-peer)
disconnects the gateway from a peer. The peer remains in the node list.
Disconnecting from a peer does not prevent the gateway from automatically
connecting to the peer in the future.
###### Path Parameters
```
// netaddress is the address of the peer to connect to. It should be a
// reachable ip address and port number, of the form 'IP:port'. IPV6 addresses
// must be enclosed in square brackets.
//
// Example IPV4 address: 123.456.789.0:123
// Example IPV6 address: [123::456]:789
:netaddress
```
###### Response
standard success or error response. See
[API.md#standard-responses](/doc/API.md#standard-responses).
Examples
--------
#### Gateway info
###### Request
```
/gateway
```
###### Expected Response Code
```
200 OK
```
###### Example JSON Response
```json
{
"netaddress":"333.333.333.333:9981",
"peers":[
{
"netaddress":"222.222.222.222:9981",
"version":"1.0.0",
"inbound":false
},
{
"netaddress":"111.111.111.111:9981",
"version":"0.6.0",
"inbound":true
}
]
}
```
#### Connecting to a peer
###### Request
```
/gateway/connect/123.456.789.0:123
```
###### Expected Response Code
```
204 No Content
```
#### Disconnecting from a peer
###### Request
```
/gateway/disconnect/123.456.789.0:123
```
###### Expected Response Code
```
204 No Content
```

536
3rd_party/Sia-v1.1.1-windows-amd64/doc/api/Host.md vendored Normal file
View File

@@ -0,0 +1,536 @@
Host API
--------
This document contains detailed descriptions of the host's API routes. For an
overview of the host's API routes, see [API.md#host](/doc/API.md#host). 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 host provides storage from local disks to the network. The host negotiates
file contracts with remote renters to earn money for storing other users'
files. The host's endpoints expose methods for viewing and modifying host
settings, announcing to the network, and managing how files are stored on disk.
Index
-----
| Route | HTTP verb |
| ------------------------------------------------------------------------------------- | --------- |
| [/host](#host-get) | GET |
| [/host](#host-post) | POST |
| [/host/announce](#hostannounce-post) | POST |
| [/host/storage](#hoststorage-get) | GET |
| [/host/storage/folders/add](#hoststoragefoldersadd-post) | POST |
| [/host/storage/folders/remove](#hoststoragefoldersremove-post) | POST |
| [/host/storage/folders/resize](#hoststoragefoldersresize-post) | POST |
| [/host/storage/sectors/delete/___:merkleroot___](#hoststoragesectorsdeletemerkleroot) | POST |
#### /host [GET]
fetches status information about the host.
###### JSON Response
```javascript
{
// The settings that get displayed to untrusted nodes querying the host's
// status.
"externalsettings": {
// Whether or not the host is accepting new contracts.
"acceptingcontracts": true,
// The maximum size of a single download request from a renter. Each
// download request has multiple round trips of communication that
// exchange money. Larger batch sizes mean fewer round trips, but more
// financial risk for the host - the renter can get a free batch when
// downloading by refusing to provide a signature.
"maxdownloadbatchsize": 17825792, // bytes
// The maximum duration 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.
"maxduration": 25920, // blocks
// The maximum size of a single batch of file contract revisions. The
// renter can perform DoS attacks on the host by uploading a batch of
// data then refusing to provide a signature to pay for the data. The
// host can reduce this exposure by limiting the batch size. Larger
// batch sizes allow for higher throughput as there is significant
// communication overhead associated with performing a batch upload.
"maxrevisebatchsize": 17825792, // bytes
// The IP address or hostname (including port) that the host should be
// contacted at.
"netaddress": "123.456.789.0:9982",
// The amount of unused storage capacity on the host in bytes. It
// should be noted that the host can lie.
"remainingstorage": 35000000000, // bytes
// The smallest amount of data in bytes that can be uploaded or
// downloaded when performing calls to the host.
"sectorsize": 4194304, // bytes
// The total amount of storage capacity on the host. It should be noted
// that the host can lie.
"totalstorage": 35000000000, // bytes
// The unlock hash is the address at which the host can be paid when
// forming file contracts.
"unlockhash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab",
// The 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, // blocks
// The maximum amount of money that the host will put up as collateral
// for storage that is contracted by the renter.
"collateral": "57870370370", // hastings / byte / block
// The maximum amount of collateral that the host will put into a
// single file contract.
"maxcollateral": "100000000000000000000000000000", // hastings
// The price that a renter has to pay to create a contract with the
// host. The payment is intended to cover transaction fees
// for the file contract revision and the storage proof that the host
// will be submitting to the blockchain.
"contractprice": "30000000000000000000000000", // hastings
// The price that a renter has to pay when downloading data from the
// host.
"downloadbandwidthprice": "250000000000000", // hastings / byte
// The price that a renter has to pay to store files with the host.
"storageprice": "231481481481", // hastings / byte / block
// The price that a renter has to pay when uploading data to the host.
"uploadbandwidthprice": "100000000000000", // hastings / byte
// The revision number indicates to the renter what iteration of
// settings the host is currently at. Settings are generally signed.
// If the renter has multiple conflicting copies of settings from the
// host, the renter can expect the one with the higher revision number
// to be more recent.
"revisionnumber": 0,
// The version of external settings being used. This field helps
// coordinate updates while preserving compatibility with older nodes.
"version": "1.0.0"
},
// The financial status of the host.
"financialmetrics": {
// Number of open file contracts.
"contractcount": 2,
// The amount of money that renters have given to the host to pay for
// file contracts. The host is required to submit a file contract
// revision and a storage proof for every file contract that gets created,
// and the renter pays for the miner fees on these objects.
"contractcompensation": "123", // hastings
// The amount of money that renters have given to the host to pay for
// file contracts which have not been confirmed yet. The potential
// compensation becomes compensation after the storage proof is
// submitted.
"potentialcontractcompensation": "123", // hastings
// The amount of storage collateral which the host has tied up in file
// contracts. The host has to commit collateral to a file contract even
// if there is no storage, but the locked collateral will be returned
// even if the host does not submit a storage proof - the collateral is
// not at risk, it is merely set aside so that it can be put at risk
// later.
"lockedstoragecollateral": "123", // hastings
// The amount of revenue, including storage revenue and bandwidth
// revenue, that has been lost due to failed file contracts and
// failed storage proofs.
"lostrevenue": "123", // hastings
// The amount of collateral that was put up to protect data which has
// been lost due to failed file contracts and missed storage proofs.
"loststoragecollateral": "123", // hastings
// The amount of revenue that the host stands to earn if all storage
// proofs are submitted corectly and in time.
"potentialstoragerevenue": "123", // hastings
// The amount of money that the host has risked on file contracts. If
// the host starts missing storage proofs, the host can forfeit up to
// this many coins. In the event of a missed storage proof, locked
// storage collateral gets returned, but risked storage collateral
// does not get returned.
"riskedstoragecollateral": "123", // hastings
// The amount of money that the host has earned from storing data. This
// money has been locked down by successful storage proofs.
"storagerevenue": "123", // hastings
// The amount of money that the host has spent on transaction fees when
// submitting host announcements, file contract revisions, and storage
// proofs.
"transactionfeeexpenses": "123", // hastings
// The amount of money that the host has made from renters downloading
// their files. This money has been locked in by successsful storage
// proofs.
"downloadbandwidthrevenue": "123", // hastings
// The amount of money that the host stands to make from renters that
// downloaded their files. The host will only realize this revenue if
// the host successfully submits storage proofs for the related file
// contracts.
"potentialdownloadbandwidthrevenue": "123", // hastings
// The amount of money that the host stands to make from renters that
// uploaded files. The host will only realize this revenue if the host
// successfully submits storage proofs for the related file contracts.
"potentialuploadbandwidthrevenue": "123", // hastings
// The amount of money that the host has made from renters uploading
// their files. This money has been locked in by successful storage
// proofs.
"uploadbandwidthrevenue": "123" // hastings
},
// The settings of the host. Most interactions between the user and the
// host occur by changing the internal settings.
"internalsettings": {
// When set to true, the host will accept new file contracts if the
// terms are reasonable. When set to false, the host will not accept new
// file contracts at all.
"acceptingcontracts": true,
// The maximum size of a single download request from a renter. Each
// download request has multiple round trips of communication that
// exchange money. Larger batch sizes mean fewer round trips, but more
// financial risk for the host - the renter can get a free batch when
// downloading by refusing to provide a signature.
"maxdownloadbatchsize": 17825792, // bytes
// The maximum duration of a file contract that the host will accept.
// The storage proof window must end before the current height +
// maxduration.
"maxduration": 25920, // blocks
// The maximum size of a single batch of file contract revisions. The
// renter can perform DoS attacks on the host by uploading a batch of
// data then refusing to provide a signature to pay for the data. The
// host can reduce this exposure by limiting the batch size. Larger
// batch sizes allow for higher throughput as there is significant
// communication overhead associated with performing a batch upload.
"maxrevisebatchsize": 17825792, // bytes
// The IP address or hostname (including port) that the host should be
// contacted at. If left blank, the host will automatically figure out
// its ip address and use that. If given, the host will use the address
// given.
"netaddress": "123.456.789.0:9982",
// The 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, // blocks
// The maximum amount of money that the host will put up as collateral
// per byte per block of storage that is contracted by the renter.
"collateral": "57870370370", // hastings / byte / block
// The total amount of money that the host will allocate to collateral
// across all file contracts.
"collateralbudget": "2000000000000000000000000000000", // hastings
// The maximum amount of collateral that the host will put into a
// single file contract.
"maxcollateral": "100000000000000000000000000000", // hastings
// The minimum price that the host will demand from a renter when
// forming a contract. Typically this price is to cover transaction
// fees on the file contract revision and storage proof, but can also
// be used if the host has a low amount of collateral. The price is a
// minimum because the host may automatically adjust the price upwards
// in times of high demand.
"mincontractprice": "30000000000000000000000000", // hastings
// The minimum price that the host will demand from a renter when the
// renter is downloading data. If the host is saturated, the host may
// increase the price from the minimum.
"mindownloadbandwidthprice": "250000000000000", // hastings / byte
// The minimum price that the host will demand when storing data for
// extended periods of time. If the host is low on space, the price of
// storage may be set higher than the minimum.
"minstorageprice": "231481481481", // hastings / byte / block
// The minimum price that the host will demand from a renter when the
// renter is uploading data. If the host is saturated, the host may
// increase the price from the minimum.
"minuploadbandwidthprice": "100000000000000" // hastings / byte
},
// Information about the network, specifically various ways in which
// renters have contacted the host.
"networkmetrics": {
// The number of times that a renter has attempted to download
// something from the host.
"downloadcalls": 0,
// The number of calls that have resulted in errors. A small number of
// errors are expected, but a large number of errors indicate either
// buggy software or malicious network activity. Usually buggy
// software.
"errorcalls": 1,
// The number of times that a renter has tried to form a contract with
// the host.
"formcontractcalls": 2,
// The number of times that a renter has tried to renew a contract with
// the host.
"renewcalls": 3,
// The number of times that the renter has tried to revise a contract
// with the host.
"revisecalls": 4,
// The number of times that a renter has queried the host for the
// host's settings. The settings include the price of bandwidth, which
// is a price that can adjust every few minutes. This value is usually
// very high compared to the others.
"settingscalls": 5,
// The number of times that a renter has attempted to use an
// unrecognized call. Larger numbers typically indicate buggy software.
"unrecognizedcalls": 6
}
}
```
#### /host [POST]
configures hosting parameters. All parameters are optional; unspecified
parameters will be left unchanged.
###### Query String Parameters
```
// When set to true, the host will accept new file contracts if the
// terms are reasonable. When set to false, the host will not accept new
// file contracts at all.
acceptingcontracts // Optional, true / false
// The maximum size of a single download request from a renter. Each
// download request has multiple round trips of communication that
// exchange money. Larger batch sizes mean fewer round trips, but more
// financial risk for the host - the renter can get a free batch when
// downloading by refusing to provide a signature.
maxdownloadbatchsize // Optional, bytes
// The maximum duration of a file contract that the host will accept.
// The storage proof window must end before the current height +
// maxduration.
maxduration // Optional, blocks
// The maximum size of a single batch of file contract revisions. The
// renter can perform DoS attacks on the host by uploading a batch of
// data then refusing to provide a signature to pay for the data. The
// host can reduce this exposure by limiting the batch size. Larger
// batch sizes allow for higher throughput as there is significant
// communication overhead associated with performing a batch upload.
maxrevisebatchsize // Optional, bytes
// The IP address or hostname (including port) that the host should be
// contacted at. If left blank, the host will automatically figure out
// its ip address and use that. If given, the host will use the address
// given.
netaddress // Optional
// The 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 // Optional, blocks
// The maximum amount of money that the host will put up as collateral
// per byte per block of storage that is contracted by the renter.
collateral // Optional, hastings / byte / block
// The total amount of money that the host will allocate to collateral
// across all file contracts.
collateralbudget // Optional, hastings
// The maximum amount of collateral that the host will put into a
// single file contract.
maxcollateral // Optional, hastings
// The minimum price that the host will demand from a renter when
// forming a contract. Typically this price is to cover transaction
// fees on the file contract revision and storage proof, but can also
// be used if the host has a low amount of collateral. The price is a
// minimum because the host may automatically adjust the price upwards
// in times of high demand.
mincontractprice // Optional, hastings
// The minimum price that the host will demand from a renter when the
// renter is downloading data. If the host is saturated, the host may
// increase the price from the minimum.
mindownloadbandwidthprice // Optional, hastings / byte
// The minimum price that the host will demand when storing data for
// extended periods of time. If the host is low on space, the price of
// storage may be set higher than the minimum.
minstorageprice // Optional, hastings / byte / block
// The minimum price that the host will demand from a renter when the
// renter is uploading data. If the host is saturated, the host may
// increase the price from the minimum.
minuploadbandwidthprice // Optional, hastings / byte
```
###### Response
standard success or error response. See
[#standard-responses](#standard-responses).
#### /host/announce [POST]
Announce the host to the network as a source of storage. Generally only needs
to be called once.
###### Query String Parameters
```
// The address to be announced. If no address is provided, the automatically
// discovered address will be used instead.
netaddress string // Optional
```
###### Response
standard success or error response. See
[#standard-responses](#standard-responses).
#### /host/storage [GET]
gets a list of folders tracked by the host's storage manager.
###### JSON Response
```javascript
{
"folders": [
{
// Absolute path to the storage folder on the local filesystem.
"path": "/home/foo/bar",
// Maximum capacity of the storage folder. The host will not store more
// than this many bytes in the folder. This capacity is not checked
// against the drive's remaining capacity. Therefore, you must manually
// ensure the disk has sufficient capacity for the folder at all times.
// Otherwise you risk losing renter's data and failing storage proofs.
"capacity": 50000000000, // bytes
// Unused capacity of the storage folder.
"capacityremaining": 100000, // bytes
// Number of failed disk read & write operations. A large number of
// failed reads or writes indicates a problem with the filesystem or
// drive's hardware.
"failedreads": 0,
"failedwrites": 1,
// Number of successful read & write operations.
"successfulreads": 2,
"successfulwrites": 3
}
]
}
```
#### /host/storage/folders/add [POST]
adds a storage folder to the manager. The manager may not check that there is
enough space available on-disk to support as much storage as requested
###### Query String Parameters
```
// Local path on disk to the storage folder to add.
path // Required
// Initial capacity of the storage folder. This value isn't validated so it is
// possible to set the capacity of the storage folder greater than the capacity
// of the disk. Do not do this.
size // bytes, Required
```
###### Response
standard success or error response. See
[#standard-responses](#standard-responses).
#### /host/storage/folders/remove [POST]
remove a storage folder from the manager. All storage on the folder will be
moved to other storage folders, meaning that no data will be lost. If the
manager is unable to save data, an error will be returned and the operation
will be stopped.
###### Query String Parameters
```
// Local path on disk to the storage folder to remove.
path // Required
// If `force` is true, the storage folder will be removed even if the data in
// the storage folder cannot be moved to other storage folders, typically
// because they don't have sufficient capacity. If `force` is true and the data
// cannot be moved, data will be lost.
force // bool, Optional, default is false
```
###### Response
standard success or error response. See
[#standard-responses](#standard-responses).
#### /host/storage/folders/resize [POST]
grows or shrink a storage folder in the manager. The manager may not check that
there is enough space on-disk to support growing the storage folder, but should
gracefully handle running out of space unexpectedly. When shrinking a storage
folder, any data in the folder that needs to be moved will be placed into other
storage folders, meaning that no data will be lost. If the manager is unable to
migrate the data, an error will be returned and the operation will be stopped.
###### Query String Parameters
```
// Local path on disk to the storage folder to resize.
path // Required
// Desired new size of the storage folder. This will be the new capacity of the
// storage folder.
newsize // bytes, Required
```
###### Response
standard success or error response. See
[#standard-responses](#standard-responses).
#### /host/storage/sectors/delete/___*merkleroot___ [POST]
deletes a sector, meaning that the manager will be unable to upload that sector
and be unable to provide a storage proof on that sector. This endpoint is for
removing the data entirely, and will remove instances of the sector appearing
at all heights. The primary purpose is to comply with legal requests to remove
data.
###### Path Parameters
```
// Merkleroot of the sector to delete.
:merkleroot
```
###### Response
standard success or error response. See
[#standard-responses](#standard-responses).

464
3rd_party/Sia-v1.1.1-windows-amd64/doc/api/HostDB.md vendored Normal file
View File

@@ -0,0 +1,464 @@
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,
}
}
```

124
3rd_party/Sia-v1.1.1-windows-amd64/doc/api/Miner.md vendored Normal file
View File

@@ -0,0 +1,124 @@
Miner API
=========
This document contains detailed descriptions of the miner's API routes. For an
overview of the miner's API routes, see [API.md#miner](/doc/API.md#miner). 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 miner provides endpoints for getting headers for work and submitting solved
headers to the network. The miner also provides endpoints for controlling a
basic CPU mining implementation.
Index
-----
| Route | HTTP verb |
| ---------------------------------- | --------- |
| [/miner](#miner-get) | GET |
| [/miner/start](#minerstart-get) | GET |
| [/miner/stop](#minerstop-get) | GET |
| [/miner/header](#minerheader-get) | GET |
| [/miner/header](#minerheader-post) | POST |
#### /miner [GET]
returns the status of the miner.
###### JSON Response
```javascript
{
// Number of mined blocks. This value is remembered after restarting.
"blocksmined": 9001,
// How fast the cpu is hashing, in hashes per second.
"cpuhashrate": 1337,
// true if the cpu miner is active.
"cpumining": false,
// Number of mined blocks that are stale, indicating that they are not
// included in the current longest chain, likely because some other block at
// the same height had its chain extended first.
"staleblocksmined": 0,
}
```
#### /miner/start [GET]
starts a single threaded cpu miner. Does nothing if the cpu miner is already
running.
###### Response
standard success or error response. See
[API.md#standard-responses](/doc/API.md#standard-responses).
#### /miner/stop [GET]
stops the cpu miner. Does nothing if the cpu miner is not running.
###### Response
standard success or error response. See
[API.md#standard-responses](/doc/API.md#standard-responses).
#### /miner/header [GET]
provides a block header that is ready to be grinded on for work.
###### Byte Response
For efficiency the header for work is returned as a raw byte encoding of the
header, rather than encoded to JSON.
Blocks are mined by repeatedly changing the nonce of the header, hashing the
header's bytes, and comparing the resulting hash to the target. The block with
that nonce is valid if the hash is less than the target. If none of the 2^64
possible nonces result in a header with a hash less than the target, call
`/miner/header [GET]` again to get a new block header with a different merkle
root. The above process can then be repeated for the new block header.
The other fields can generally be ignored. The parent block ID field is the
hash of the parent block's header. Modifying this field will result in an
orphan block. The timestamp is the time at which the block was mined and is set
by the Sia Daemon. Modifying this field can result in invalid block. The merkle
root is the merkle root of a merkle tree consisting of the timestamp, the miner
outputs (one leaf per payout), and the transactions (one leaf per transaction).
Modifying this field will result in an invalid block.
| Field | Byte range within response | Byte range within header |
| --------------- | -------------------------- | ------------------------ |
| target | [0-32) | |
| header | [32-112) | |
| parent block ID | [32-64) | [0-32) |
| nonce | [64-72) | [32-40) |
| timestamp | [72-80) | [40-48) |
| merkle root | [80-112) | [48-80) |
```
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (returned bytes)
tttttttttttttttttttttttttttttttt (target)
hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh (header)
pppppppppppppppppppppppppppppppp (parent block ID)
nnnnnnnn (nonce)
ssssssss (timestamp)
mmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmm (merkle root)
```
#### /miner/header [POST]
submits a header that has passed the POW.
###### Request Body Bytes
For efficiency headers are submitted as raw byte encodings of the header in the
body of the request, rather than as a query string parameter or path parameter.
The request body should contain only the 80 bytes of the encoded header. The
encoding is the same encoding used in `/miner/header [GET]` endpoint. Refer to
[#byte-response](#byte-response) for a detailed description of the byte
encoding.

327
3rd_party/Sia-v1.1.1-windows-amd64/doc/api/Renter.md vendored Normal file
View File

@@ -0,0 +1,327 @@
Renter API
==========
This document contains detailed descriptions of the renter's API routes. For an
overview of the renter's API routes, see [API.md#renter](/doc/API.md#renter). 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 renter manages the user's files on the network. The renter's API endpoints
expose methods for managing files on the network and managing the renter's
allocated funds.
Index
-----
| Route | HTTP verb |
| ------------------------------------------------------------- | --------- |
| [/renter](#renter-get) | GET |
| [/renter](#renter-post) | POST |
| [/renter/contracts](#rentercontracts-get) | GET |
| [/renter/downloads](#renterdownloads-get) | GET |
| [/renter/files](#renterfiles-get) | GET |
| [/renter/prices](#renter-prices-get) | GET |
| [/renter/delete/___*siapath___](#renterdeletesiapath-post) | POST |
| [/renter/download/___*siapath___](#renterdownloadsiapath-get) | GET |
| [/renter/rename/___*siapath___](#renterrenamesiapath-post) | POST |
| [/renter/upload/___*siapath___](#renteruploadsiapath-post) | POST |
#### /renter [GET]
returns the current settings along with metrics on the renter's spending.
###### JSON Response
```javascript
{
// Settings that control the behavior of the renter.
"settings": {
// Allowance dictates how much the renter is allowed to spend in a given
// period. Note that funds are spent on both storage and bandwidth.
"allowance": {
// Amount of money allocated for contracts. Funds are spent on both
// storage and bandwidth.
"funds": "1234", // hastings
// Number of hosts that contracts will be formed with.
"hosts":24,
// Duration of contracts formed, in number of blocks.
"period": 6048, // blocks
// If the current blockheight + the renew window >= the height the
// contract is scheduled to end, the contract is renewed automatically.
// Is always nonzero.
"renewwindow": 3024 // blocks
}
},
// Metrics about how much the Renter has spent on storage, uploads, and
// downloads.
"financialmetrics": {
// How much money, in hastings, the Renter has spent on file contracts,
// including fees.
"contractspending": "1234", // hastings
// Amount of money spent on downloads.
"downloadspending": "5678", // hastings
// Amount of money spend on storage.
"storagespending": "1234", // hastings
// Amount of money spent on uploads.
"uploadspending": "5678", // hastings
// Amount of money in the allowance that has not been spent.
"unspent": "1234" // hastings
}
}
```
#### /renter [POST]
modify settings that control the renter's behavior.
###### Query String Parameters
```
// Number of hastings allocated for file contracts in the given period.
funds // hastings
// Number of hosts that contracts should be formed with. Files cannot be
// uploaded to more hosts than you have contracts with, and it's generally good
// to form a few more contracts than you need.
hosts
// Duration of contracts formed. Must be nonzero.
period // block height
// Renew window specifies how many blocks before the expriation of the current
// contracts the renter will wait before renewing the contracts. A smaller
// renew window means that Sia must be run more frequently, but also means
// fewer total transaction fees. Storage spending is not affected by the renew
// window size.
renewwindow // block height
```
###### Response
standard success or error response. See
[API.md#standard-responses](/doc/API.md#standard-responses).
#### /renter/contracts [GET]
returns active contracts. Expired contracts are not included.
###### JSON Response
```javascript
{
"contracts": [
{
// Block height that the file contract ends on.
"endheight": 50000, // block height
// ID of the file contract.
"id": "1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
// Address of the host the file contract was formed with.
"netaddress": "12.34.56.78:9",
// A signed transaction containing the most recent contract revision.
"lasttransaction": {},
// Remaining funds left for the renter to spend on uploads & downloads.
"renterfunds": "1234", // hastings
// Size of the file contract, which is typically equal to the number of
// bytes that have been uploaded to the host.
"size": 8192 // bytes
}
]
}
```
#### /renter/downloads [GET]
lists all files in the download queue.
###### JSON Response
```javascript
{
"downloads": [
{
// Siapath given to the file when it was uploaded.
"siapath": "foo/bar.txt",
// Local path that the file will be downloaded to.
"destination": "/home/users/alice",
// Size, in bytes, of the file being downloaded.
"filesize": 8192, // bytes
// Number of bytes downloaded thus far.
"received": 4096, // bytes
// Time at which the download was initiated.
"starttime": "2009-11-10T23:00:00Z" // RFC 3339 time
}
]
}
```
#### /renter/files [GET]
lists the status of all files.
###### JSON Response
```javascript
{
"files": [
{
// Path to the file in the renter on the network.
"siapath": "foo/bar.txt",
// Size of the file in bytes.
"filesize": 8192, // bytes
// true if the file is available for download. Files may be available
// before they are completely uploaded.
"available": true,
// true if the file's contracts will be automatically renewed by the
// renter.
"renewing": true,
// Average redundancy of the file on the network. Redundancy is
// calculated by dividing the amount of data uploaded in the file's open
// contracts by the size of the file. Redundancy does not necessarily
// correspond to availability. Specifically, a redundancy >= 1 does not
// indicate the file is available as there could be a chunk of the file
// with 0 redundancy.
"redundancy": 5,
// Percentage of the file uploaded, including redundancy. Uploading has
// completed when uploadprogress is 100. Files may be available for
// download before upload progress is 100.
"uploadprogress": 100, // percent
// Block height at which the file ceases availability.
"expiration": 60000
}
]
}
```
#### /renter/prices [GET]
lists the estimated prices of performing various storage and data operations.
###### JSON Response
```javascript
{
// The estimated cost of downloading one terabyte of data from the
// network.
"downloadterabyte": "1234", // hastings
// The estimated cost of forming a set of contracts on the network. This
// cost also applies to the estimated cost of renewing the renter's set of
// contracts.
"formcontracts": "1234", // hastings
// The estimated cost of storing one terabyte of data on the network for
// a month, including accounting for redundancy.
"storageterabytemonth": "1234", // hastings
// The estimated cost of uploading one terabyte of data to the network,
// including accounting for redundancy.
"uploadterabyte": "1234", // hastings
}
```
#### /renter/delete/___*siapath___ [POST]
deletes a renter file entry. Does not delete any downloads or original files,
only the entry in the renter.
###### Path Parameters
```
// Location of the file in the renter on the network.
*siapath
```
###### Response
standard success or error response. See
[API.md#standard-responses](/doc/API.md#standard-responses).
#### /renter/download/___*siapath___ [GET]
downloads a file to the local filesystem. The call will block until the file
has been downloaded.
###### Path Parameters
```
// Location of the file in the renter on the network.
*siapath
```
###### Query String Parameters
```
// Location on disk that the file will be downloaded to.
destination
```
###### Response
standard success or error response. See
[API.md#standard-responses](/doc/API.md#standard-responses).
#### /renter/rename/___*siapath___ [POST]
renames a file. Does not rename any downloads or source files, only renames the
entry in the renter. An error is returned if `siapath` does not exist or
`newsiapath` already exists.
###### Path Parameters
```
// Current location of the file in the renter on the network.
*siapath
```
###### Query String Parameters
```
// New location of the file in the renter on the network.
newsiapath
```
###### Response
standard success or error response. See
[API.md#standard-responses](/doc/API.md#standard-responses).
#### /renter/upload/___*siapath___ [POST]
uploads a file to the network from the local filesystem.
###### Path Parameters
```
// Location where the file will reside in the renter on the network.
*siapath
```
###### Query String Parameters
```
// The number of data pieces to use when erasure coding the file.
datapieces // int
// The number of parity pieces to use when erasure coding the file. Total
// redundancy of the file is (datapieces+paritypieces)/datapieces.
paritypieces // int
// Location on disk of the file being uploaded.
source // string - a filepath
```
###### Response
standard success or error response. See
[API.md#standard-responses](/doc/API.md#standard-responses).

521
3rd_party/Sia-v1.1.1-windows-amd64/doc/api/Wallet.md vendored Normal file
View File

@@ -0,0 +1,521 @@
Wallet
======
This document contains detailed descriptions of the wallet's API routes. For an
overview of the wallet's API routes, see [API.md#wallet](/doc/API.md#wallet).
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 wallet stores and manages siacoins and siafunds. The wallet's API endpoints
expose methods for creating and loading wallets, locking and unlocking, sending
siacoins and siafunds, and getting the wallet's balance.
You must create a wallet before you can use the wallet's API endpoints. You can
create a wallet with the `/wallet/init` endpoint. Wallets are always encrypted
on disk. Calls to some wallet API endpoints will fail until the wallet is
unlocked. The wallet can be unlocked with the `/wallet/unlock` endpoint. Once
the wallet is unlocked calls to the API endpoints will succeed until the wallet
is locked again with `/wallet/lock`, or Siad is restarted. The host and renter
require the miner to be unlocked.
Index
-----
| Route | HTTP verb |
| --------------------------------------------------------------- | --------- |
| [/wallet](#wallet-get) | GET |
| [/wallet/033x](#wallet033x-post) | POST |
| [/wallet/address](#walletaddress-get) | GET |
| [/wallet/addresses](#walletaddresses-get) | GET |
| [/wallet/backup](#walletbackup-get) | GET |
| [/wallet/init](#walletinit-post) | POST |
| [/wallet/lock](#walletlock-post) | POST |
| [/wallet/seed](#walletseed-post) | POST |
| [/wallet/seeds](#walletseeds-get) | GET |
| [/wallet/siacoins](#walletsiacoins-post) | POST |
| [/wallet/siafunds](#walletsiafunds-post) | POST |
| [/wallet/siagkey](#walletsiagkey-post) | POST |
| [/wallet/transaction/___:id___](#wallettransactionid-get) | GET |
| [/wallet/transactions](#wallettransactions-get) | GET |
| [/wallet/transactions/___:addr___](#wallettransactionsaddr-get) | GET |
| [/wallet/unlock](#walletunlock-post) | POST |
#### /wallet [GET]
returns basic information about the wallet, such as whether the wallet is
locked or unlocked.
###### JSON Response
```javascript
{
// Indicates whether the wallet has been encrypted or not. If the wallet
// has not been encrypted, then no data has been generated at all, and the
// first time the wallet is unlocked, the password given will be used as
// the password for encrypting all of the data. 'encrypted' will only be
// set to false if the wallet has never been unlocked before (the unlocked
// wallet is still encryped - but the encryption key is in memory).
"encrypted": true,
// Indicates whether the wallet is currently locked or unlocked. Some calls
// become unavailable when the wallet is locked.
"unlocked": true,
// Number of siacoins, in hastings, available to the wallet as of the most
// recent block in the blockchain.
"confirmedsiacoinbalance": "123456", // hastings, big int
// Number of siacoins, in hastings, that are leaving the wallet according
// to the set of unconfirmed transactions. Often this number appears
// inflated, because outputs are frequently larger than the number of coins
// being sent, and there is a refund. These coins are counted as outgoing,
// and the refund is counted as incoming. The difference in balance can be
// calculated using 'unconfirmedincomingsiacoins' - 'unconfirmedoutgoingsiacoins'
"unconfirmedoutgoingsiacoins": "0", // hastings, big int
// Number of siacoins, in hastings, are entering the wallet according to
// the set of unconfirmed transactions. This number is often inflated by
// outgoing siacoins, because outputs are frequently larger than the amount
// being sent. The refund will be included in the unconfirmed incoming
// siacoins balance.
"unconfirmedincomingsiacoins": "789", // hastings, big int
// Number of siafunds available to the wallet as of the most recent block
// in the blockchain.
"siafundbalance": "1", // big int
// Number of siacoins, in hastings, that can be claimed from the siafunds
// as of the most recent block. Because the claim balance increases every
// time a file contract is created, it is possible that the balance will
// increase before any claim transaction is confirmed.
"siacoinclaimbalance": "9001", // hastings, big int
}
```
#### /wallet/033x [POST]
loads a v0.3.3.x wallet into the current wallet, harvesting all of the secret
keys. All spendable addresses in the loaded wallet will become spendable from
the current wallet. An error will be returned if the given `encryptionpassword`
is incorrect.
###### Query String Parameters
```
// Path on disk to the v0.3.3.x wallet to be loaded.
source
// Encryption key of the wallet.
encryptionpassword
```
###### Response
standard success or error response. See
[API.md#standard-responses](/doc/API.md#standard-responses).
#### /wallet/address [GET]
gets a new address from the wallet generated by the primary seed. An error will
be returned if the wallet is locked.
###### JSON Response
```javascript
{
// Wallet address that can receive siacoins or siafunds. Addresses are 76 character long hex strings.
"address": "1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab"
}
```
#### /wallet/addresses [GET]
fetches the list of addresses from the wallet.
###### JSON Response
```javascript
{
// Array of wallet addresses owned by the wallet.
"addresses": [
"1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab",
"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
]
}
```
#### /wallet/backup [GET]
creates a backup of the wallet settings file. Though this can easily be done
manually, the settings file is often in an unknown or difficult to find
location. The /wallet/backup call can spare users the trouble of needing to
find their wallet file. The destination file is overwritten if it already
exists.
###### Query String Parameters
```
// path to the location on disk where the backup file will be saved.
destination
```
###### Response
standard success or error response. See
[API.md#standard-responses](/doc/API.md#standard-responses).
#### /wallet/init [POST]
initializes the wallet. After the wallet has been initialized once, it does not
need to be initialized again, and future calls to /wallet/init will return an
error. The encryption password is provided by the api call. If the password is
blank, then the password will be set to the same as the seed.
###### Query String Parameters
```
// Password that will be used to encrypt the wallet. All subsequent calls
// should use this password. If left blank, the seed that gets returned will
// also be the encryption password.
encryptionpassword
// Name of the dictionary that should be used when encoding the seed. 'english'
// is the most common choice when picking a dictionary.
dictionary // Optional, default is english.
```
###### JSON Response
```javascript
{
// Wallet seed used to generate addresses that the wallet is able to spend.
"primaryseed": "hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello"
}
```
#### /wallet/seed [POST]
gives the wallet a seed to track when looking for incoming transactions. The
wallet will be able to spend outputs related to addresses created by the seed.
The seed is added as an auxiliary seed, and does not replace the primary seed.
Only the primary seed will be used for generating new addresses.
###### Query String Parameters
```
// Key used to encrypt the new seed when it is saved to disk.
encryptionpassword
// Name of the dictionary that should be used when encoding the seed. 'english'
// is the most common choice when picking a dictionary.
dictionary
// Dictionary-encoded phrase that corresponds to the seed being added to the
// wallet.
seed
```
###### Response
standard success or error response. See
[API.md#standard-responses](/doc/API.md#standard-responses).
#### /wallet/seeds [GET]
returns a list of seeds in use by the wallet. The primary seed is the only seed
that gets used to generate new addresses. This call is unavailable when the
wallet is locked.
A seed is an encoded version of a 128 bit random seed. The output is 15 words
chosen from a small dictionary as indicated by the input. The most common
choice for the dictionary is going to be 'english'. The underlying seed is the
same no matter what dictionary is used for the encoding. The encoding also
contains a small checksum of the seed, to help catch simple mistakes when
copying. The library
[entropy-mnemonics](https://github.com/NebulousLabs/entropy-mnemonics) is used
when encoding.
###### Query String Parameters
```
// Name of the dictionary that should be used when encoding the seed. 'english'
// is the most common choice when picking a dictionary.
dictionary
```
###### JSON Response
```javascript
{
// Seed that is actively being used to generate new addresses for the wallet.
"primaryseed": "hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello",
// Number of addresses that remain in the primary seed until exhaustion has
// been reached. Once exhaustion has been reached, new addresses will
// continue to be generated but they will be more difficult to recover in the
// event of a lost wallet file or encryption password.
"addressesremaining": 2500,
// Array of all seeds that the wallet references when scanning the blockchain
// for outputs. The wallet is able to spend any output generated by any of
// the seeds, however only the primary seed is being used to generate new
// addresses.
"allseeds": [
"hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello",
"foo bar foo bar foo bar foo bar foo bar foo bar foo bar foo bar foo bar foo bar foo bar foo bar foo bar foo bar foo",
]
}
```
#### /wallet/siacoins [POST]
Function: Send siacoins to an address. The outputs are arbitrarily selected
from addresses in the wallet.
###### Query String Parameters
```
// Number of hastings being sent. A hasting is the smallest unit in Sia. There
// are 10^24 hastings in a siacoin.
amount // hastings
// Address that is receiving the coins.
destination // address
```
###### JSON Response
```javascript
{
// Array of IDs of the transactions that were created when sending the coins.
// The last transaction contains the output headed to the 'destination'.
// Transaction IDs are 64 character long hex strings.
transactionids [
"1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
]
}
```
#### /wallet/siafunds [POST]
sends siafunds to an address. The outputs are arbitrarily selected from
addresses in the wallet. Any siacoins available in the siafunds being sent (as
well as the siacoins available in any siafunds that end up in a refund address)
will become available to the wallet as siacoins after 144 confirmations. To
access all of the siacoins in the siacoin claim balance, send all of the
siafunds to an address in your control (this will give you all the siacoins,
while still letting you control the siafunds).
###### Query String Parameters
```
// Number of siafunds being sent.
amount // siafunds
// Address that is receiving the funds.
destination // address
```
###### JSON Response
```javascript
{
// Array of IDs of the transactions that were created when sending the coins.
// The last transaction contains the output headed to the 'destination'.
// Transaction IDs are 64 character long hex strings.
"transactionids": [
"1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
]
}
```
#### /wallet/siagkey [POST]
Function: Load a key into the wallet that was generated by siag. Most siafunds
are currently in addresses created by siag.
###### Query String Parameters
```
// Key that is used to encrypt the siag key when it is imported to the wallet.
encryptionpassword
// List of filepaths that point to the keyfiles that make up the siag key.
// There should be at least one keyfile per required signature. The filenames
// need to be commna separated (no spaces), which means filepaths that contain
// a comma are not allowed.
keyfiles
```
###### Response
standard success or error response. See
[API.md#standard-responses](/doc/API.md#standard-responses).
#### /wallet/lock [POST]
locks the wallet, wiping all secret keys. After being locked, the keys are
encrypted. Queries for the seed, to send siafunds, and related queries become
unavailable. Queries concerning transaction history and balance are still
available.
###### Response
standard success or error response. See
[API.md#standard-responses](/doc/API.md#standard-responses).
#### /wallet/transaction/___:id___ [GET]
gets the transaction associated with a specific transaction id.
###### Path Parameters
```
// ID of the transaction being requested.
:id
```
###### JSON Response
```javascript
{
"transaction": {
// Raw transaction. The rest of the fields in the resposne are determined
// from this raw transaction. It is left undocumented here as the processed
// transaction (the rest of the fields in this object) are usually what is
// desired.
"transaction": {
// See types.Transaction in https://github.com/NebulousLabs/Sia/blob/master/types/transactions.go
},
// ID of the transaction from which the wallet transaction was derived.
"transactionid": "1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
// Block height at which the transaction was confirmed. If the transaction
// is unconfirmed the height will be the max value of an unsigned 64-bit
// integer.
"confirmationheight": 50000,
// Time, in unix time, at which a transaction was confirmed. If the
// transaction is unconfirmed the timestamp will be the max value of an
// unsigned 64-bit integer.
"confirmationtimestamp": 1257894000,
// Array of processed inputs detailing the inputs to the transaction.
"inputs": [
{
// Type of fund represented by the input. Possible values are
// 'siacoin input' and 'siafund input'.
"fundtype": "siacoin input",
// true if the address is owned by the wallet.
"walletaddress": false,
// Address that is affected. For inputs (outgoing money), the related
// address is usually not important because the wallet arbitrarily
// selects which addresses will fund a transaction.
"relatedaddress": "1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab",
// Amount of funds that have been moved in the input.
"value": "1234", // hastings or siafunds, depending on fundtype, big int
}
],
// Array of processed outputs detailing the outputs of the transaction.
// Outputs related to file contracts are excluded.
"outputs": [
{
// Type of fund is represented by the output. Possible values are
// 'siacoin output', 'siafund output', 'claim output', and 'miner
// payout'. Siacoin outputs and claim outputs both relate to siacoins.
// Siafund outputs relate to siafunds. Miner payouts point to siacoins
// that have been spent on a miner payout. Because the destination of
// the miner payout is determined by the block and not the transaction,
// the data 'maturityheight', 'walletaddress', and 'relatedaddress' are
// left blank.
"fundtype": "siacoin output",
// Block height the output becomes available to be spent. Siacoin
// outputs and siafund outputs mature immediately - their maturity
// height will always be the confirmation height of the transaction.
// Claim outputs cannot be spent until they have had 144 confirmations,
// thus the maturity height of a claim output will always be 144 larger
// than the confirmation height of the transaction.
"maturityheight": 50000,
// true if the address is owned by the wallet.
"walletaddress": false,
// Address that is affected. For outputs (incoming money), the related
// address field can be used to determine who has sent money to the
// wallet.
"relatedaddress": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
// Amount of funds that have been moved in the output.
"value": "1234", // hastings or siafunds, depending on fundtype, big int
}
]
}
}
```
#### /wallet/transactions [GET]
returns a list of transactions related to the wallet.
###### Query String Parameters
```
// Height of the block where transaction history should begin.
startheight // block height
// Height of of the block where the transaction history should end. If
// 'endheight' is greater than the current height, all transactions up to and
// including the most recent block will be provided.
endheight // block height
```
###### JSON Response
```javascript
{
// All of the confirmed transactions appearing between height 'startheight'
// and height 'endheight' (inclusive).
"confirmedtransactions": [
{
// See the documentation for '/wallet/transaction/:id' for more information.
}
],
// All of the unconfirmed transactions.
"unconfirmedtransactions": [
{
// See the documentation for '/wallet/transaction/:id' for more information.
}
]
}
```
#### /wallet/transactions/___:addr___ [GET]
returns all of the transactions related to a specific address.
###### Path Parameters
```
// Unlock hash (i.e. wallet address) whose transactions are being requested.
:addr
```
###### JSON Response
```javascript
{
// Array of processed transactions that relate to the supplied address.
"transactions": [
{
// See the documentation for '/wallet/transaction/:id' for more information.
}
]
}
```
#### /wallet/unlock [POST]
unlocks the wallet. The wallet is capable of knowing whether the correct
password was provided.
###### Query String Parameters
```
// Password that gets used to decrypt the file. Most frequently, the encryption
// password is the same as the primary wallet seed.
encryptionpassword string
```
###### Response
standard success or error response. See
[API.md#standard-responses](/doc/API.md#standard-responses).