github.com/avahowell/sia@v0.5.1-beta.0.20160524050156-83dcc3d37c94/modules/renter/contractor/doc.go (about)

     1  /*
     2  Package contractor is responsible for forming and renewing file contracts with
     3  hosts. Its goal is to manage the low-level details of the negotiation,
     4  revision, and renewal protocols, such that the renter can operate at a higher
     5  level of abstraction. Ideally, the renter should be mostly ignorant of the Sia
     6  protocol, instead focusing on file management, redundancy, and upload/download
     7  algorithms.
     8  
     9  Contract formation does not begin until the user first calls SetAllowance. An
    10  allowance dictates how much money the contractor is allowed to spend on file
    11  contracts during a given period. When the user calls SetAllowance for the
    12  first time, the call will block until contracts have been negotiated with the
    13  specified number of hosts. Upon subsequent calls, new contracts will only be
    14  formed if the allowance is sufficiently greater than the previous allowance,
    15  where "sufficiently greater" currently means "enough money to pay for at least
    16  one additional sector on every host." This allows the user to increase the
    17  amount of available storage immediately, at the cost of some complexity.
    18  
    19  The contractor forms many contracts in parallel with different host, and tries
    20  to keep all the contracts "consistent" -- that is, they should all have the
    21  same storage capacity, and they should all end at the same height. Hosts are
    22  selected from the HostDB; there is no support for manually specifying hosts.
    23  
    24  Contracts are automatically renewed by the contractor at a safe threshold
    25  before they are set to expire. The contractor maintains a renewHeight variable
    26  that indicates when its current set of contracts will expire. When contracts
    27  are renewed, they are renewed with the current allowance, which may differ
    28  from the allowance that was used to form the initial contracts. In general,
    29  this means that allowance modifications only take effect upon the next
    30  "contract cycle" (the exception being "sufficiently greater" modifications, as
    31  defined above).
    32  
    33  As an example, imagine that the user first sets an allowance that will cover
    34  10 contracts of 10 sectors each for 100 blocks. The contractor will
    35  immediately form contracts with 10 hosts, paying each host enough to cover 10
    36  sectors for 100 blocks. Then, 20 blocks later, the user increases the
    37  allowance, such that it now covers 10 contracts of 20 sectors for 200 blocks.
    38  The contractor will immediately form contracts as follows:
    39  
    40  - 10 contracts will be formed with the current hosts, each covering 10 sectors
    41    for 80 blocks.
    42  
    43  - 10 contracts will be formed with new hosts, each covering 20 sectors for 80
    44    blocks.
    45  
    46  Note that these newly-formed contracts are timed to expire in sync with the
    47  existing contracts. This becomes the new "contract set," totaling 30
    48  contracts, but only 20 hosts, with 20 sectors per host. When it comes time to
    49  renew these contracts, only one contract will be renewed per host, and the
    50  contracts will be renewed for the full 200-block duration. The new contract
    51  set will thus consist of 20 contracts, 20 hosts, 20 sectors, 200 blocks.
    52  
    53  On the other hand, if the allowance is decreased, no immediate action is
    54  taken. Why? Because the contracts have already been paid for. The new
    55  allowance will only take effect upon the next renewal.
    56  
    57  Modifications to file contracts are mediated through the Editor interface. An
    58  Editor maintains a network connection to a host, over which is sends
    59  modification requests, such as "delete sector 12." After each modification,
    60  the Editor revises the underlying file contract and saves it to disk.
    61  
    62  The primary challenge of the contractor is that it must be smart enough for
    63  the user to feel comfortable allowing it to spend their money. Because
    64  contract renewal is a background task, it is difficult to report errors to the
    65  user and defer to their decision. For example, what should the contractor do
    66  in the following scenarios?
    67  
    68  - The contract set is up for renewal, but the average host price has
    69    increased, and now the allowance is not sufficient to cover all of the
    70    user's uploaded data.
    71  
    72  - The user sets an allowance of 10 hosts. The contractor forms 5 contracts,
    73    but the rest fail, and the remaining hosts in the HostDB are too expensive.
    74  
    75  - After contract formation succeeds, 2 of 10 hosts become unresponsive. Later,
    76    another 4 become unresponsive.
    77  
    78  Waiting for user input is dangerous because if the contract period elapses,
    79  data is permanently lost. The contractor should treat this as the worst-case
    80  scenario, and take steps to prevent it, so long as the allowance is not
    81  exceeded. However, since the contractor has no concept of redundancy, it is
    82  not well-positioned to determine which sectors to sacrifice and which to
    83  preserve. The contractor also lacks the ability to reupload data; it can
    84  download sectors, but it does not know the decryption keys or erasure coding
    85  metadata required to reconstruct the original data. It follows that these
    86  responsibilities must be delegated to the renter.
    87  
    88  */
    89  package contractor