github.com/Synthesix/Sia@v1.3.3-0.20180413141344-f863baeed3ca/doc/api/Host.md (about) 1 Host API 2 -------- 3 4 This document contains detailed descriptions of the host's API routes. For an 5 overview of the host's API routes, see [API.md#host](/doc/API.md#host). For an 6 overview of all API routes, see [API.md](/doc/API.md) 7 8 There may be functional API calls which are not documented. These are not 9 guaranteed to be supported beyond the current release, and should not be used 10 in production. 11 12 Overview 13 -------- 14 15 The host provides storage from local disks to the network. The host negotiates 16 file contracts with remote renters to earn money for storing other users' 17 files. The host's endpoints expose methods for viewing and modifying host 18 settings, announcing to the network, and managing how files are stored on disk. 19 20 Index 21 ----- 22 23 | Route | HTTP verb | 24 | ------------------------------------------------------------------------------------------ | --------- | 25 | [/host](#host-get) | GET | 26 | [/host](#host-post) | POST | 27 | [/host/announce](#hostannounce-post) | POST | 28 | [/host/estimatescore](#hostestimatescore-get) | GET | 29 | [/host/storage](#hoststorage-get) | GET | 30 | [/host/storage/folders/add](#hoststoragefoldersadd-post) | POST | 31 | [/host/storage/folders/remove](#hoststoragefoldersremove-post) | POST | 32 | [/host/storage/folders/resize](#hoststoragefoldersresize-post) | POST | 33 | [/host/storage/sectors/delete/:___merkleroot___](#hoststoragesectorsdeletemerkleroot-post) | POST | 34 35 36 #### /host [GET] 37 38 fetches status information about the host. 39 40 ###### JSON Response 41 ```javascript 42 { 43 // The settings that get displayed to untrusted nodes querying the host's 44 // status. 45 "externalsettings": { 46 // Whether or not the host is accepting new contracts. 47 "acceptingcontracts": true, 48 49 // The maximum size of a single download request from a renter. Each 50 // download request has multiple round trips of communication that 51 // exchange money. Larger batch sizes mean fewer round trips, but more 52 // financial risk for the host - the renter can get a free batch when 53 // downloading by refusing to provide a signature. 54 "maxdownloadbatchsize": 17825792, // bytes 55 56 // The maximum duration that a host will allow for a file contract. The 57 // host commits to keeping files for the full duration under the threat 58 // of facing a large penalty for losing or dropping data before the 59 // duration is complete. The storage proof window of an incoming file 60 // contract must end before the current height + maxduration. 61 "maxduration": 25920, // blocks 62 63 // The maximum size of a single batch of file contract revisions. The 64 // renter can perform DoS attacks on the host by uploading a batch of 65 // data then refusing to provide a signature to pay for the data. The 66 // host can reduce this exposure by limiting the batch size. Larger 67 // batch sizes allow for higher throughput as there is significant 68 // communication overhead associated with performing a batch upload. 69 "maxrevisebatchsize": 17825792, // bytes 70 71 // The IP address or hostname (including port) that the host should be 72 // contacted at. 73 "netaddress": "123.456.789.0:9982", 74 75 // The amount of unused storage capacity on the host in bytes. It 76 // should be noted that the host can lie. 77 "remainingstorage": 35000000000, // bytes 78 79 // The smallest amount of data in bytes that can be uploaded or 80 // downloaded when performing calls to the host. 81 "sectorsize": 4194304, // bytes 82 83 // The total amount of storage capacity on the host. It should be noted 84 // that the host can lie. 85 "totalstorage": 35000000000, // bytes 86 87 // The unlock hash is the address at which the host can be paid when 88 // forming file contracts. 89 "unlockhash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab", 90 91 // The storage proof window is the number of blocks that the host has 92 // to get a storage proof onto the blockchain. The window size is the 93 // minimum size of window that the host will accept in a file contract. 94 "windowsize": 144, // blocks 95 96 // The maximum amount of money that the host will put up as collateral 97 // for storage that is contracted by the renter. 98 "collateral": "57870370370", // hastings / byte / block 99 100 // The maximum amount of collateral that the host will put into a 101 // single file contract. 102 "maxcollateral": "100000000000000000000000000000", // hastings 103 104 // The price that a renter has to pay to create a contract with the 105 // host. The payment is intended to cover transaction fees 106 // for the file contract revision and the storage proof that the host 107 // will be submitting to the blockchain. 108 "contractprice": "30000000000000000000000000", // hastings 109 110 // The price that a renter has to pay when downloading data from the 111 // host. 112 "downloadbandwidthprice": "250000000000000", // hastings / byte 113 114 // The price that a renter has to pay to store files with the host. 115 "storageprice": "231481481481", // hastings / byte / block 116 117 // The price that a renter has to pay when uploading data to the host. 118 "uploadbandwidthprice": "100000000000000", // hastings / byte 119 120 // The revision number indicates to the renter what iteration of 121 // settings the host is currently at. Settings are generally signed. 122 // If the renter has multiple conflicting copies of settings from the 123 // host, the renter can expect the one with the higher revision number 124 // to be more recent. 125 "revisionnumber": 0, 126 127 // The version of external settings being used. This field helps 128 // coordinate updates while preserving compatibility with older nodes. 129 "version": "1.0.0" 130 }, 131 132 // The financial status of the host. 133 "financialmetrics": { 134 // Number of open file contracts. 135 "contractcount": 2, 136 137 // The amount of money that renters have given to the host to pay for 138 // file contracts. The host is required to submit a file contract 139 // revision and a storage proof for every file contract that gets created, 140 // and the renter pays for the miner fees on these objects. 141 "contractcompensation": "123", // hastings 142 143 // The amount of money that renters have given to the host to pay for 144 // file contracts which have not been confirmed yet. The potential 145 // compensation becomes compensation after the storage proof is 146 // submitted. 147 "potentialcontractcompensation": "123", // hastings 148 149 // The amount of storage collateral which the host has tied up in file 150 // contracts. The host has to commit collateral to a file contract even 151 // if there is no storage, but the locked collateral will be returned 152 // even if the host does not submit a storage proof - the collateral is 153 // not at risk, it is merely set aside so that it can be put at risk 154 // later. 155 "lockedstoragecollateral": "123", // hastings 156 157 // The amount of revenue, including storage revenue and bandwidth 158 // revenue, that has been lost due to failed file contracts and 159 // failed storage proofs. 160 "lostrevenue": "123", // hastings 161 162 // The amount of collateral that was put up to protect data which has 163 // been lost due to failed file contracts and missed storage proofs. 164 "loststoragecollateral": "123", // hastings 165 166 // The amount of revenue that the host stands to earn if all storage 167 // proofs are submitted corectly and in time. 168 "potentialstoragerevenue": "123", // hastings 169 170 // The amount of money that the host has risked on file contracts. If 171 // the host starts missing storage proofs, the host can forfeit up to 172 // this many coins. In the event of a missed storage proof, locked 173 // storage collateral gets returned, but risked storage collateral 174 // does not get returned. 175 "riskedstoragecollateral": "123", // hastings 176 177 // The amount of money that the host has earned from storing data. This 178 // money has been locked down by successful storage proofs. 179 "storagerevenue": "123", // hastings 180 181 // The amount of money that the host has spent on transaction fees when 182 // submitting host announcements, file contract revisions, and storage 183 // proofs. 184 "transactionfeeexpenses": "123", // hastings 185 186 // The amount of money that the host has made from renters downloading 187 // their files. This money has been locked in by successsful storage 188 // proofs. 189 "downloadbandwidthrevenue": "123", // hastings 190 191 // The amount of money that the host stands to make from renters that 192 // downloaded their files. The host will only realize this revenue if 193 // the host successfully submits storage proofs for the related file 194 // contracts. 195 "potentialdownloadbandwidthrevenue": "123", // hastings 196 197 // The amount of money that the host stands to make from renters that 198 // uploaded files. The host will only realize this revenue if the host 199 // successfully submits storage proofs for the related file contracts. 200 "potentialuploadbandwidthrevenue": "123", // hastings 201 202 // The amount of money that the host has made from renters uploading 203 // their files. This money has been locked in by successful storage 204 // proofs. 205 "uploadbandwidthrevenue": "123" // hastings 206 }, 207 208 // The settings of the host. Most interactions between the user and the 209 // host occur by changing the internal settings. 210 "internalsettings": { 211 // When set to true, the host will accept new file contracts if the 212 // terms are reasonable. When set to false, the host will not accept new 213 // file contracts at all. 214 "acceptingcontracts": true, 215 216 // The maximum size of a single download request from a renter. Each 217 // download request has multiple round trips of communication that 218 // exchange money. Larger batch sizes mean fewer round trips, but more 219 // financial risk for the host - the renter can get a free batch when 220 // downloading by refusing to provide a signature. 221 "maxdownloadbatchsize": 17825792, // bytes 222 223 // The maximum duration of a file contract that the host will accept. 224 // The storage proof window must end before the current height + 225 // maxduration. 226 "maxduration": 25920, // blocks 227 228 // The maximum size of a single batch of file contract revisions. The 229 // renter can perform DoS attacks on the host by uploading a batch of 230 // data then refusing to provide a signature to pay for the data. The 231 // host can reduce this exposure by limiting the batch size. Larger 232 // batch sizes allow for higher throughput as there is significant 233 // communication overhead associated with performing a batch upload. 234 "maxrevisebatchsize": 17825792, // bytes 235 236 // The IP address or hostname (including port) that the host should be 237 // contacted at. If left blank, the host will automatically figure out 238 // its ip address and use that. If given, the host will use the address 239 // given. 240 "netaddress": "123.456.789.0:9982", 241 242 // The storage proof window is the number of blocks that the host has 243 // to get a storage proof onto the blockchain. The window size is the 244 // minimum size of window that the host will accept in a file contract. 245 "windowsize": 144, // blocks 246 247 // The maximum amount of money that the host will put up as collateral 248 // per byte per block of storage that is contracted by the renter. 249 "collateral": "57870370370", // hastings / byte / block 250 251 // The total amount of money that the host will allocate to collateral 252 // across all file contracts. 253 "collateralbudget": "2000000000000000000000000000000", // hastings 254 255 // The maximum amount of collateral that the host will put into a 256 // single file contract. 257 "maxcollateral": "100000000000000000000000000000", // hastings 258 259 // The minimum price that the host will demand from a renter when 260 // forming a contract. Typically this price is to cover transaction 261 // fees on the file contract revision and storage proof, but can also 262 // be used if the host has a low amount of collateral. The price is a 263 // minimum because the host may automatically adjust the price upwards 264 // in times of high demand. 265 "mincontractprice": "30000000000000000000000000", // hastings 266 267 // The minimum price that the host will demand from a renter when the 268 // renter is downloading data. If the host is saturated, the host may 269 // increase the price from the minimum. 270 "mindownloadbandwidthprice": "250000000000000", // hastings / byte 271 272 // The minimum price that the host will demand when storing data for 273 // extended periods of time. If the host is low on space, the price of 274 // storage may be set higher than the minimum. 275 "minstorageprice": "231481481481", // hastings / byte / block 276 277 // The minimum price that the host will demand from a renter when the 278 // renter is uploading data. If the host is saturated, the host may 279 // increase the price from the minimum. 280 "minuploadbandwidthprice": "100000000000000" // hastings / byte 281 }, 282 283 // Information about the network, specifically various ways in which 284 // renters have contacted the host. 285 "networkmetrics": { 286 // The number of times that a renter has attempted to download 287 // something from the host. 288 "downloadcalls": 0, 289 290 // The number of calls that have resulted in errors. A small number of 291 // errors are expected, but a large number of errors indicate either 292 // buggy software or malicious network activity. Usually buggy 293 // software. 294 "errorcalls": 1, 295 296 // The number of times that a renter has tried to form a contract with 297 // the host. 298 "formcontractcalls": 2, 299 300 // The number of times that a renter has tried to renew a contract with 301 // the host. 302 "renewcalls": 3, 303 304 // The number of times that the renter has tried to revise a contract 305 // with the host. 306 "revisecalls": 4, 307 308 // The number of times that a renter has queried the host for the 309 // host's settings. The settings include the price of bandwidth, which 310 // is a price that can adjust every few minutes. This value is usually 311 // very high compared to the others. 312 "settingscalls": 5, 313 314 // The number of times that a renter has attempted to use an 315 // unrecognized call. Larger numbers typically indicate buggy software. 316 "unrecognizedcalls": 6 317 }, 318 319 // Information about the health of the host. 320 321 // connectabilitystatus is one of "checking", "connectable", 322 // or "not connectable", and indicates if the host can connect to 323 // itself on its configured NetAddress. 324 "connectabilitystatus": "checking", 325 326 // workingstatus is one of "checking", "working", or "not working" 327 // and indicates if the host is being actively used by renters. 328 "workingstatus": "checking" 329 } 330 ``` 331 332 #### /host [POST] 333 334 configures hosting parameters. All parameters are optional; unspecified 335 parameters will be left unchanged. 336 337 ###### Query String Parameters 338 ``` 339 // When set to true, the host will accept new file contracts if the 340 // terms are reasonable. When set to false, the host will not accept new 341 // file contracts at all. 342 acceptingcontracts // Optional, true / false 343 344 // The maximum size of a single download request from a renter. Each 345 // download request has multiple round trips of communication that 346 // exchange money. Larger batch sizes mean fewer round trips, but more 347 // financial risk for the host - the renter can get a free batch when 348 // downloading by refusing to provide a signature. 349 maxdownloadbatchsize // Optional, bytes 350 351 // The maximum duration of a file contract that the host will accept. 352 // The storage proof window must end before the current height + 353 // maxduration. 354 maxduration // Optional, blocks 355 356 // The maximum size of a single batch of file contract revisions. The 357 // renter can perform DoS attacks on the host by uploading a batch of 358 // data then refusing to provide a signature to pay for the data. The 359 // host can reduce this exposure by limiting the batch size. Larger 360 // batch sizes allow for higher throughput as there is significant 361 // communication overhead associated with performing a batch upload. 362 maxrevisebatchsize // Optional, bytes 363 364 // The IP address or hostname (including port) that the host should be 365 // contacted at. If left blank, the host will automatically figure out 366 // its ip address and use that. If given, the host will use the address 367 // given. 368 netaddress // Optional 369 370 // The storage proof window is the number of blocks that the host has 371 // to get a storage proof onto the blockchain. The window size is the 372 // minimum size of window that the host will accept in a file contract. 373 windowsize // Optional, blocks 374 375 // The maximum amount of money that the host will put up as collateral 376 // per byte per block of storage that is contracted by the renter. 377 collateral // Optional, hastings / byte / block 378 379 // The total amount of money that the host will allocate to collateral 380 // across all file contracts. 381 collateralbudget // Optional, hastings 382 383 // The maximum amount of collateral that the host will put into a 384 // single file contract. 385 maxcollateral // Optional, hastings 386 387 // The minimum price that the host will demand from a renter when 388 // forming a contract. Typically this price is to cover transaction 389 // fees on the file contract revision and storage proof, but can also 390 // be used if the host has a low amount of collateral. The price is a 391 // minimum because the host may automatically adjust the price upwards 392 // in times of high demand. 393 mincontractprice // Optional, hastings 394 395 // The minimum price that the host will demand from a renter when the 396 // renter is downloading data. If the host is saturated, the host may 397 // increase the price from the minimum. 398 mindownloadbandwidthprice // Optional, hastings / byte 399 400 // The minimum price that the host will demand when storing data for 401 // extended periods of time. If the host is low on space, the price of 402 // storage may be set higher than the minimum. 403 minstorageprice // Optional, hastings / byte / block 404 405 // The minimum price that the host will demand from a renter when the 406 // renter is uploading data. If the host is saturated, the host may 407 // increase the price from the minimum. 408 minuploadbandwidthprice // Optional, hastings / byte 409 ``` 410 411 ###### Response 412 standard success or error response. See 413 [#standard-responses](#standard-responses). 414 415 #### /host/announce [POST] 416 417 Announce the host to the network as a source of storage. Generally only needs 418 to be called once. 419 420 Note that even after the host has been announced, it will not accept new 421 contracts unless configured to do so. To configure the host to accept 422 contracts, see [/host](https://github.com/Synthesix/Sia/blob/master/doc/api/Host.md#host-post). 423 424 ###### Query String Parameters 425 ``` 426 // The address to be announced. If no address is provided, the automatically 427 // discovered address will be used instead. 428 netaddress string // Optional 429 ``` 430 431 ###### Response 432 standard success or error response. See 433 [#standard-responses](#standard-responses). 434 435 #### /host/storage [GET] 436 437 gets a list of folders tracked by the host's storage manager. 438 439 ###### JSON Response 440 ```javascript 441 { 442 "folders": [ 443 { 444 // Absolute path to the storage folder on the local filesystem. 445 "path": "/home/foo/bar", 446 447 // Maximum capacity of the storage folder. The host will not store more 448 // than this many bytes in the folder. This capacity is not checked 449 // against the drive's remaining capacity. Therefore, you must manually 450 // ensure the disk has sufficient capacity for the folder at all times. 451 // Otherwise you risk losing renter's data and failing storage proofs. 452 "capacity": 50000000000, // bytes 453 454 // Unused capacity of the storage folder. 455 "capacityremaining": 100000, // bytes 456 457 // Number of failed disk read & write operations. A large number of 458 // failed reads or writes indicates a problem with the filesystem or 459 // drive's hardware. 460 "failedreads": 0, 461 "failedwrites": 1, 462 463 // Number of successful read & write operations. 464 "successfulreads": 2, 465 "successfulwrites": 3 466 } 467 ] 468 } 469 ``` 470 471 #### /host/storage/folders/add [POST] 472 473 adds a storage folder to the manager. The manager may not check that there is 474 enough space available on-disk to support as much storage as requested 475 476 ###### Query String Parameters 477 ``` 478 // Local path on disk to the storage folder to add. 479 path // Required 480 481 // Initial capacity of the storage folder. This value isn't validated so it is 482 // possible to set the capacity of the storage folder greater than the capacity 483 // of the disk. Do not do this. 484 size // bytes, Required 485 ``` 486 487 ###### Response 488 standard success or error response. See 489 [#standard-responses](#standard-responses). 490 491 #### /host/storage/folders/remove [POST] 492 493 remove a storage folder from the manager. All storage on the folder will be 494 moved to other storage folders, meaning that no data will be lost. If the 495 manager is unable to save data, an error will be returned and the operation 496 will be stopped. 497 498 ###### Query String Parameters 499 ``` 500 // Local path on disk to the storage folder to remove. 501 path // Required 502 503 // If `force` is true, the storage folder will be removed even if the data in 504 // the storage folder cannot be moved to other storage folders, typically 505 // because they don't have sufficient capacity. If `force` is true and the data 506 // cannot be moved, data will be lost. 507 force // bool, Optional, default is false 508 ``` 509 510 ###### Response 511 standard success or error response. See 512 [#standard-responses](#standard-responses). 513 514 #### /host/storage/folders/resize [POST] 515 516 grows or shrink a storage folder in the manager. The manager may not check that 517 there is enough space on-disk to support growing the storage folder, but should 518 gracefully handle running out of space unexpectedly. When shrinking a storage 519 folder, any data in the folder that needs to be moved will be placed into other 520 storage folders, meaning that no data will be lost. If the manager is unable to 521 migrate the data, an error will be returned and the operation will be stopped. 522 523 ###### Query String Parameters 524 ``` 525 // Local path on disk to the storage folder to resize. 526 path // Required 527 528 // Desired new size of the storage folder. This will be the new capacity of the 529 // storage folder. 530 newsize // bytes, Required 531 ``` 532 533 ###### Response 534 standard success or error response. See 535 [#standard-responses](#standard-responses). 536 537 #### /host/storage/sectors/delete/___*merkleroot___ [POST] 538 539 deletes a sector, meaning that the manager will be unable to upload that sector 540 and be unable to provide a storage proof on that sector. This endpoint is for 541 removing the data entirely, and will remove instances of the sector appearing 542 at all heights. The primary purpose is to comply with legal requests to remove 543 data. 544 545 ###### Path Parameters 546 ``` 547 // Merkleroot of the sector to delete. 548 :merkleroot 549 ``` 550 551 ###### Response 552 standard success or error response. See 553 [#standard-responses](#standard-responses). 554 555 #### /host/estimatescore [GET] 556 557 returns the estimated HostDB score of the host using its current settings, 558 combined with the provided settings. 559 560 ###### JSON Response 561 ```javascript 562 { 563 // estimatedscore is the estimated HostDB score of the host given the 564 // settings passed to estimatescore. 565 "estimatedscore": "123456786786786786786786786742133", 566 // conversionrate is the likelihood given the settings passed to 567 // estimatescore that the host will be selected by renters forming contracts. 568 "conversionrate": 95 569 } 570 ``` 571 572 ###### Query String Parameters 573 ``` 574 acceptingcontracts // Optional, true / false 575 maxdownloadbatchsize // Optional, bytes 576 maxduration // Optional, blocks 577 maxrevisebatchsize // Optional, bytes 578 netaddress // Optional 579 windowsize // Optional, blocks 580 581 collateral // Optional, hastings / byte / block 582 collateralbudget // Optional, hastings 583 maxcollateral // Optional, hastings 584 585 mincontractprice // Optional, hastings 586 mindownloadbandwidthprice // Optional, hastings / byte 587 minstorageprice // Optional, hastings / byte / block 588 minuploadbandwidthprice // Optional, hastings / byte 589 ``` 590