Commit 40f0ab37 authored by David Vorick's avatar David Vorick

Merge branch 'new-api-docs' into 'master'

New API documentation

See merge request !3363
parents 8a8e3504 a2f20593
Pipeline #40681065 failed with stages
in 82 minutes and 42 seconds
This diff is collapsed.
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)
The Sia API documentation can be found here:
[Sia API](https://sia.tech/docs/ "Sia API")
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/blocks](#consensusblocks-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],
// The difficulty of the current block target.
"difficulty": "1234" // arbitrary-precision integer
}
```
#### /consensus/blocks [GET]
Returns the block for a given id or height.
###### Query String Parameters
One of the following parameters can be specified.
```
// BlockID of the requested block.
id
// BlockHeight of the requested block.
height
```
###### Response
The JSON formatted block or a standard error response.
```
{
"height": 20032,
"id": "00000000000033b9eb57fa63a51adeea857e70f6415ebbfe5df2a01f0d0477f4",
"minerpayouts": [
{
"unlockhash": "c199cd180e19ef7597bcf4beecdd4f211e121d085e24432959c42bdf9030e32b9583e1c2727c",
"value": "279978000000000000000000000000"
}
],
"nonce": [4,12,219,7,0,0,0,0],
"parentid": "0000000000009615e8db750eb1226aa5e629bfa7badbfe0b79607ec8b918a44c",
"timestamp": 1444516982,
"transactions": [
{
// ...
},
{
"arbitrarydata": [],
"filecontractrevisions": [],
"filecontracts": [],
"id": "3c98ec79b990461f353c22bb06bcfb10e702f529ad7d27a43c4448273553d90a",
"minerfees": [],
"siacoininputs": [
{
"parentid": "24cbeb9df7eb2d81d0025168fc94bd179909d834f49576e65b51feceaf957a64",
"unlockconditions": {
"publickeys": [
{
"algorithm": "ed25519",
"key": "QET8w7WRbGfcnnpKd1nuQfE3DuNUUq9plyoxwQYDK4U="
}
],
"signaturesrequired": 1,
"timelock": 0
}
}
],
"siacoinoutputs": [
{
"id": "1f9da81e23522f79590ac67ac0b668828c52b341cbf04df4959bb7040c072f29",
"unlockhash": "d54f500f6c1774d518538dbe87114fe6f7e6c76b5bc8373a890b12ce4b8909a336106a4cd6db",
"value": "1010000000000000000000000000"
},
{
"id": "14978a4c54f5ebd910ea41537de014f8423574c13d132e8713fab5af09ec08ca",
"unlockhash": "48a56b19bd0be4f24190640acbd0bed9669ea9c18823da2645ec1ad9652f10b06c5d4210f971",
"value": "5780000000000000000000000000"
}
],
"siafundinputs": [],
"siafundoutputs": [],
"storageproofs": [],
"transactionsignatures": [
{
"coveredfields": {
"arbitrarydata": [],
"filecontractrevisions": [],
"filecontracts": [],
"minerfees": [],
"siacoininputs": [],
"siacoinoutputs": [],
"siafundinputs": [],
"siafundoutputs": [],
"storageproofs": [],
"transactionsignatures": [],
"wholetransaction": true
},
"parentid": "24cbeb9df7eb2d81d0025168fc94bd179909d834f49576e65b51feceaf957a64",
"publickeyindex": 0,
"signature": "pByLGMlvezIZWVZmHQs/ynGETETNbxcOY/kr6uivYgqZqCcKTJ0JkWhcFaKJU+3DEA7JAloLRNZe3PTklD3tCQ==",
"timelock": 0
}
]
},
{
// ...
}
]
}
```
#### /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).
Updates to the API documentation can be made here:
[Sia API markdown](./index.html.md "Sia API markdown")
\ No newline at end of file
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)
The Sia API documentation can be found here:
[Sia API](https://sia.tech/docs/ "Sia API")
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
// Farthest a block's timestamp can be in the future before the block is
// rejected outright.
"extremefuturethreshold": 10800, // seconds
// 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.
"maxtargetadjustmentup": "5/2",
// Smallest allowed ratio between the old difficulty and the new difficulty.
"maxtargetadjustmentdown": "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"
}
```
Updates to the API documentation can be made here:
[Sia API markdown](./index.html.md "Sia API markdown")
\ No newline at end of file
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)
The Sia API documentation can be found here:
[Sia API](https://sia.tech/docs/ "Sia API")
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-get-info) |
| [/gateway](#gateway-post-example) | POST | [Gateway info](#gateway-post-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-get-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,
// local is true if the peer's IP address belongs to a local address
// range such as 192.168.x.x or 127.x.x.x
"local": Boolean
}
}
```
#### /gateway [POST] [(example)](#gateway-get-info)
modify settings that control the gateway's behavior.
###### Query String Parameters
// Max download speed permitted, speed provide in bytes per second
maxdownloadspeed
// Max upload speed permitted, speed provide in bytes per second
maxuploadspeed
###### Response
standard success or error response. See
[API.md#standard-responses](/doc/API.md#standard-responses).
#### /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
```
Updates to the API documentation can be made here:
[Sia API markdown](./index.html.md "Sia API markdown")
\ No newline at end of file
This diff is collapsed.
This diff is collapsed.
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)
The Sia API documentation can be found here:
[Sia API](https://sia.tech/docs/ "Sia API")
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.
Updates to the API documentation can be made here:
[Sia API markdown](./index.html.md "Sia API markdown")
\ No newline at end of file
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment