contractor

package
v1.5.7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 21, 2021 License: MIT Imports: 27 Imported by: 0

README

Contractor

The Contractor is responsible for forming and renewing file contracts with hosts. Its goal is to manage the low-level details of the negotiation, revision, and renewal protocols, such that the renter can operate at a higher level of abstraction. Ideally, the renter should be mostly ignorant of the Sia protocol, instead focusing on file management, redundancy, and upload/download algorithms.

The Contractor is also responsible for various forms of contract maintenance including contract recovery, utility checking, archiving, and monitoring its own contracts using the watchdog subsystem.

Design Challenges

The primary challenge of the Contractor is that it must be smart enough for the user to feel comfortable allowing it to spend their money. Because contract renewal is a background task, it is difficult to report errors to the user and defer to their decision. For example, what should the Contractor do in the following scenarios?

  • The contract set is up for renewal, but the average host price has increased, and now the allowance is not sufficient to cover all of the user's uploaded data.

  • The user sets an allowance of 10 hosts. The Contractor forms 5 contracts, but the rest fail, and the remaining hosts in the HostDB are too expensive.

  • After contract formation succeeds, 2 of 10 hosts become unresponsive. Later, another 4 become unresponsive.

Waiting for user input is dangerous because if the contract period elapses, data is permanently lost. The Contractor should treat this as the worst-case scenario, and take steps to prevent it, so long as the allowance is not exceeded. However, since the Contractor has no concept of redundancy, it is not well-positioned to determine which sectors to sacrifice and which to preserve. The Contractor also lacks the ability to reupload data; it can download sectors, but it does not know the decryption keys or erasure coding metadata required to reconstruct the original data. It follows that these responsibilities must be delegated to the renter.

Alerts

WalletLockedDuringMaintenance is registered if the wallet is locked while the contractor is attempting to create contracts.

AllowanceLowFunds is registered if the contractor lacks the necessary fund to renew or form contracts.

TODOs

  • (watchdog) Perform action when storage proof is found and when missing at the end of the window.
  • (watchdog) Add renter dependencies in sweepContractInputs if necessary.

Subsystems

The Contractor is split up into the following subsystems:

Allowance Subsystem

Key Files

The allowance subsystem is used for setting and cancelling allowances. A change in allowance does not necessarily cause changes in contract formation.

Exports
  • SetAllowance is exported by the Contractor and allows the caller to dictate the contract spendings of the Renter.
Outbound Complexities
  • callInterruptContractMaintenance is used when setting the allowance to stop and restart contract maintenance with the new allowance settings in place.

Contract Maintenance Subsystem

Key Files

The contract maintenance subsystem is responsible for forming and renewing contracts, and for other general maintenance tasks.

Contract Formation

Contract formation does not begin until the user first calls SetAllowance. An allowance dictates how much money the Contractor is allowed to spend on file contracts during a given period. When the user calls SetAllowance the Allowance subsystem updates the allowance and restarts the Maintenance subsystem so that it will form new contracts with the changed settings. New contracts will only be formed if needed and if the allowance is sufficiently greater than the previous allowance, where "sufficiently greater" currently means "enough money to pay for at least one additional sector on every host." This allows the user to increase the amount of available storage immediately, at the cost of some complexity.

The Contractor forms many contracts in parallel with different host, and tries to keep all the contracts "consistent" -- that is, they should all have the same storage capacity, and they should all end at the same height. Hosts are selected from the HostDB. There is no support for manually specifying hosts, but the Contractor will not form contracts with multiple hosts within the same subnet.

Contract Renewal

Contracts are automatically renewed by the Contractor at a safe threshold before they are set to expire. This value is set in the allowance. When contracts are renewed, they are renewed with the current allowance, which may differ from the allowance that was used to form the initial contracts. In general, this means that allowance modifications only take effect upon the next "contract cycle".

Other Maintenance Checks
  • Check the contract set for duplicate contracts and remove them.
  • Prune hosts that are no longer used for any contracts and hosts that violate rules about address ranges
  • Check the utility of opened contracts by figuring out which contracts are still useful for uploading or for renewing
  • Archive contracts which have expired by placing them in a historic contract set.
Inbound Complexities
  • threadedContractMaintenance is called by the Allowance subsystem when setting allowances, when CancelContract is called from the Contractor, and also with every ConsensusChange by the Contractor in the ProcessConsensusChange when the Contractor is synced.
  • callInterruptContractMaintenance is used by Allowance subsystem when setting the allowance to stop and restart contract maintenance with the new allowance settings in place.
  • callNotifyDoubleSpend is a Contract Maintenance call used by the watchdog to indicate that a contract is double-spent and triggers actions from the Contractor.
Outbound Complexities
  • callInitRecoveryScan in the Recovery subsystem is called to scan blocks for recoverable contracts.
  • save is called to persist the contractor whenever the Contractor's state is updated during maintenance.
  • Funds established by the Allowance subsystem are used and deducted appropriately during maintenance to form and renew contracts.
  • callNotifyChurnedContract is used when a contract utility changes from GFR to !GFR.
  • threadedSendMostRecentRevision in the Watchdog subsystem is called when a contract is renewed and no new revisions are expected.

Churn Limiter Subsystem

Key Files

The Churn Limiter is responsible for decreasing contract churn. It keeps track of the aggregate size of all contracts churned in the current period. Churn is limited by keeping contracts with low-scoring hosts around if the maximum aggregate for the period has been reached.

Exports
  • SetMaxPeriodChurn is exported by the Contractor and allows the caller to set the maximum allowed churn in bytes per period.
Inbound Complexities
  • callNotifyChurnedContract is used when contracts are marked GFR after previously being !GFR.
  • callBumpChurnBudget is used to increase the churn budget when new blocks are processed.
  • callResetAggregateChurn resets the aggregate churn and is called every time the contractor enters a new period.
  • callPersistData is called whenever the contractor's persistData is called.

Recovery Subsystem

Key Files

The Contractor is also responsible for scanning the Sia blockchain and recovering all unexpired contracts which belong to the current wallet seed. The relevant contracts are found by examining the contract identifier attached to every file contract. Recovery scans are initiated whenever the wallet is unlocked or when a new seed is imported.

A recoverable contract is recovered by reinitiating a session with the relevant host and by getting the most recent revision from the host using this session.

Inbound Complexities

Session Subsystem

Key Files

The Session subsystem provides an interface for communication with hosts. It allows the contractor to modify its contracts through the renter-host protocol. Sessions are used to initiate uploads, downloads, and file modifications. This subsystem exports several methods used outside of the Contractor for this purpose.

The session subsystem will watch out for certain host behaviors that indicate the host is permanently unusable. If this happens, the session subsystem will call 'MarkBadContract', which will prevent the contract from being considered a part of the usable contracts, and allow the repair process to happen.

Pre-v1.4.0 contracts using an older version of the renter-host protocol use the Editor and Downloader interfaces to interact with hosts.

Pre-v1.4.0 Contract Modification

Modifications to file contracts are mediated through the Editor interface. An Editor maintains a network connection to a host, over which is sends modification requests, such as "delete sector 12." After each modification, the Editor revises the underlying file contract and saves it to disk.

Exports

The following Session methods are all exported by the Contractor:

  • Address
  • Close
  • ContractID
  • Download
  • DownloadIndex
  • EndHeight
  • Upload
  • Replace

Persistence Subsystem

Key Files

The Persistence subsystem is used to persist Contractor data across sessions. Currently it uses the Sia persist package. Prior to v1.3.0 the persistence subsystem used a journal system which is no longer used. If, on startup, this old journal system is found, the Contractor will convert it into the new Persistence subsystem.

Inbound Complexities
  • save is called from the Allowance, and Maintenance subsystems to persist the Contractor when its internal state is updated.
Outbound Complexities

The persist system is also responsible for persisting the Watchdog subsystem.

Watchdog Subsystem

Key Files

The watchdog is responsible for monitoring the blockchain for file contracts, revisions, and storage proofs that are relevant to the contractor.

To scan for revisions, the watchdog is used during the Contractor's ProcessConsensusChange method and during the recovery subsystem's ProcessConsensusChange method.

When processing a newly added block the watchdog checks if any contracts, revision, or storage proofs for a monitored contract have appeared on-chain. For file contracts being monitored that haven't yet appeared on-chain, the watchdog also monitors all the parent Siacoin outputs used in the creation of the contract. It will update the dependency set of that contract as blocks are added and reverted. If a contract's inputs are ever double-spent, the watchdog notifies the Contractor. The Contractor returns the contract's funds to the allowance, and marks the contract as !GoodForUpload and !GoodForRenew,

The watchdog will also check if any monitored contracts revisions or storage proofs were removed in a reverted blocks and marks them as such. Note that once a the storage proof window for a file contract elapses for the first time, the watchdog will no longer monitor that contract. This is acceptable because even if the storage proof is reorged out, the host has at least proven they fulfilled their storage obligation once. It is up to the host to re-post storage proofs if they are reorged out, if they want to claim valid proof outputs afterwards.

When the watchdog is synced to the consensusset it will do all of its checks on monitored contracts in managedCheckContracts. It waits until being synced, rather than taking action in the middle of a ProcessConsensusChange call to avoid taking actions that would be prevented if e.g. the next block in a ConsensusChange was checked. For example, a formation transaction may be reverted and re-applied in the same consensus change. In this case, the watchdog should not take any actions.

The watchdog does the following checks on monitored contracts.

  • check that monitored file contract formation transaction sets appeared on-chain in the expected number of blocks.
  • re-send the transaction set if not, and double-spend the inputs used with the set if much more time has elapsed.
  • check if any monitored contracts should have a more recent revision on-chain already. If not, the watchdog will send the latest revision transaction out.
  • Check if storage proofs for a contract were found at the end of the expiration window

Inbound Complexities

  • threadedSendMostRecentRevision is called in a go-routine from the Contract Maintenance subsystem when a contract is renewed and no new revisions are expected.
  • callMonitorContract is called from the Contract Maintenance and Recovery subsystems whenever contracts are formed, renewed, or recovered.
  • callScanConsensusChangeis used in the ProcessConsensusChange method of the contractor to let the watchdog scan blocks.
  • callPersistData is called whenever the contractor's persistData is called.

Outbound Complexities

  • callNotifyDoubleSpend is a Contract Maintenance call used by the watchdog to indicate that a contract is double-spent and triggers actions from the Contractor.

State Complexities

All state updates from the watchdog are driven by changes observed in ProcessConsensusChange and from contract formation and renewal which cause a file contract to be monitored. Therefore, the watchdog persist needs to be synced with the most recent consensus change.

Why The Watchdog Should Sweep Renter Inputs

If the watchdog fails to find a monitored file contract on-chain before its formationSweepHeight the watchdog will sweep the inputs used by the renter to create the file contract. This action must take place to prevent the renter from overspending its allowance.

If the contractor were to simply create new contracts while other contracts were still unconfirmed, it would be possible to overspend the set allowance. When the watchdog sweeps its inputs successfully, the contract will be marked as double-spent in which case the allowance funds are returned for further use.

Documentation

Index

Constants

View Source 
const MaxCriticalRenewFailThreshold = 0.2

MaxCriticalRenewFailThreshold is the maximum number of contracts failing to renew as fraction of the total hosts in the allowance before renew alerts are made critical.

Variables

View Source 
var (

	// ErrAllowanceZeroFunds is returned if the allowance funds are being set to
	// zero when not cancelling the allowance
	ErrAllowanceZeroFunds = errors.New("funds must be non-zero")
	// ErrAllowanceZeroPeriod is returned if the allowance period is being set
	// to zero when not cancelling the allowance
	ErrAllowanceZeroPeriod = errors.New("period must be non-zero")
	// ErrAllowanceZeroWindow is returned if the allowance renew window is being
	// set to zero when not cancelling the allowance
	ErrAllowanceZeroWindow = errors.New("renew window must be non-zero")
	// ErrAllowanceNoHosts is returned if the allowance hosts are being set to
	// zero when not cancelling the allowance
	ErrAllowanceNoHosts = errors.New("hosts must be non-zero")
	// ErrAllowanceZeroExpectedStorage is returned if the allowance expected
	// storage is being set to zero when not cancelling the allowance
	ErrAllowanceZeroExpectedStorage = errors.New("expected storage must be non-zero")
	// ErrAllowanceZeroExpectedUpload is returned if the allowance expected
	// upload is being set to zero when not cancelling the allowance
	ErrAllowanceZeroExpectedUpload = errors.New("expected upload  must be non-zero")
	// ErrAllowanceZeroExpectedDownload is returned if the allowance expected
	// download is being set to zero when not cancelling the allowance
	ErrAllowanceZeroExpectedDownload = errors.New("expected download  must be non-zero")
	// ErrAllowanceZeroExpectedRedundancy is returned if the allowance expected
	// redundancy is being set to zero when not cancelling the allowance
	ErrAllowanceZeroExpectedRedundancy = errors.New("expected redundancy must be non-zero")
	// ErrAllowanceZeroMaxPeriodChurn is returned if the allowance max period
	// churn is being set to zero when not cancelling the allowance
	ErrAllowanceZeroMaxPeriodChurn = errors.New("max period churn must be non-zero")
)
View Source 
var (
	// AlertCauseInsufficientAllowanceFunds indicates that the cause for the
	// alert was insufficient allowance funds remaining
	AlertCauseInsufficientAllowanceFunds = "Insufficient allowance funds remaining"

	// AlertMSGAllowanceLowFunds indicates that forming/renewing a contract during
	// contract maintenance isn't possible due to the allowance being low on
	// funds.
	AlertMSGAllowanceLowFunds = "At least one contract formation/renewal failed due to the allowance being low on funds"

	// AlertMSGFailedContractRenewal indicates that the contract renewal failed
	AlertMSGFailedContractRenewal = "Contractor is attempting to renew/refresh contracts but failed"

	// AlertMSGWalletLockedDuringMaintenance indicates that forming/renewing a
	// contract during contract maintenance isn't possible due to a locked wallet.
	AlertMSGWalletLockedDuringMaintenance = "At least one contract failed to form/renew due to the wallet being locked"
)

Constants related to the contractor's alerts.

View Source 
var (
	// ContractFeeFundingMulFactor is the multiplying factor for contract fees
	// to determine the funding for a new contract
	ContractFeeFundingMulFactor = uint64(10)

	// MaxInitialContractFundingDivFactor is the dividing factor for determining
	// the maximum amount of funds to put into a new contract
	MaxInitialContractFundingDivFactor = uint64(3)

	// MaxInitialContractFundingMulFactor is the multiplying factor for
	// determining the maximum amount of funds to put into a new contract
	MaxInitialContractFundingMulFactor = uint64(2)

	// MinInitialContractFundingDivFactor is the dividing factor for determining
	// the minimum amount of funds to put into a new contract
	MinInitialContractFundingDivFactor = uint64(20)

	// MinContractFundRenewalThreshold defines the ratio of remaining funds to
	// total contract cost below which the contractor will prematurely renew a
	// contract.
	//
	// This number is deliberately a little higher than the
	// minContractFundUploadThreshold because we want to make sure that renewals
	// will kick in before uploading stops.
	MinContractFundRenewalThreshold = float64(0.06) // 6%

	// minContractFundUploadThreshold is the percentage of contract funds
	// remaining at which the contract gets marked !GoodForUpload. The number is
	// high so that there is plenty of money available for downloading, so that
	// urgent repairs can be performed and also so that user file access is not
	// interrupted until after uploading progress is interrupted. Structuring
	// things this way essentially allows the user to experience the failure
	// mode of 'can't store additional stuff' before the user experiences the
	// failure mode of 'can't retrieve stuff already uploaded'.
	MinContractFundUploadThreshold = float64(0.05) // 5%

)

Constants related to contract formation parameters.

View Source 
var ErrContractRenewing = errors.New("currently renewing that contract")

ErrContractRenewing is returned by operations that can't be completed due to the contract being renewed.

View Source 
var (
	// ErrInsufficientAllowance indicates that the renter's allowance is less
	// than the amount necessary to store at least one sector
	ErrInsufficientAllowance = errors.New("allowance is not large enough to cover fees of contract creation")
)
View Source 
var (

	// PersistFilename is the filename to be used when persisting contractor
	// information to a JSON file
	PersistFilename = "contractor.json"
)

Functions

This section is empty.

Types

type Contractor 

type Contractor struct {
	// contains filtered or unexported fields
}

A Contractor negotiates, revises, renews, and provides access to file contracts.

func New 

func New(cs modules.ConsensusSet, wallet modules.Wallet, tpool modules.TransactionPool, hdb modules.HostDB, rl *ratelimit.RateLimit, persistDir string) (*Contractor, <-chan error)

New returns a new Contractor.

func NewCustomContractor added in v1.3.3 

func NewCustomContractor(cs modules.ConsensusSet, w modules.Wallet, tp modules.TransactionPool, hdb modules.HostDB, persistDir string, contractSet *proto.ContractSet, l *persist.Logger, deps modules.Dependencies) (*Contractor, <-chan error)

NewCustomContractor creates a Contractor using the provided dependencies.

func (*Contractor) Alerts added in v1.5.7 

func (c *Contractor) Alerts() (crit, err, warn []modules.Alert)

Alerts implements the modules.Alerter interface for the contractor. It returns all alerts of the contractor.

func (*Contractor) Allowance 

func (c *Contractor) Allowance() modules.Allowance

Allowance returns the current allowance.

func (*Contractor) CancelContract added in v1.3.4 

func (c *Contractor) CancelContract(id types.FileContractID) error

CancelContract cancels the Contractor's contract by marking it !GoodForRenew and !GoodForUpload

func (*Contractor) ChurnStatus added in v1.5.7 

func (c *Contractor) ChurnStatus() modules.ContractorChurnStatus

ChurnStatus returns the current period's aggregate churn and the max churn per period.

func (*Contractor) Close added in v1.1.1 

func (c *Contractor) Close() error

Close closes the Contractor.

func (*Contractor) ContractByPublicKey added in v1.3.4 

func (c *Contractor) ContractByPublicKey(pk types.SiaPublicKey) (modules.RenterContract, bool)

ContractByPublicKey returns the contract with the key specified, if it exists. The contract will be resolved if possible to the most recent child contract.

func (*Contractor) ContractPublicKey added in v1.5.7 

func (c *Contractor) ContractPublicKey(pk types.SiaPublicKey) (crypto.PublicKey, bool)

ContractPublicKey returns the public key capable of verifying the renter's signature on a contract.

func (*Contractor) ContractStatus added in v1.5.7 

func (c *Contractor) ContractStatus(fcID types.FileContractID) (modules.ContractWatchStatus, bool)

ContractStatus returns the status of a contract in the watchdog.

func (*Contractor) ContractUtility added in v1.3.1 

func (c *Contractor) ContractUtility(pk types.SiaPublicKey) (modules.ContractUtility, bool)

ContractUtility returns the utility fields for the given contract.

func (*Contractor) Contracts 

func (c *Contractor) Contracts() []modules.RenterContract

Contracts returns the contracts formed by the contractor in the current allowance period. Only contracts formed with currently online hosts are returned.

func (*Contractor) CurrentPeriod added in v1.1.0 

func (c *Contractor) CurrentPeriod() types.BlockHeight

CurrentPeriod returns the height at which the current allowance period began.

func (*Contractor) Downloader 

func (c *Contractor) Downloader(pk types.SiaPublicKey, cancel <-chan struct{}) (_ Downloader, err error)

Downloader returns a Downloader object that can be used to download sectors from a host.

func (*Contractor) Editor 

func (c *Contractor) Editor(pk types.SiaPublicKey, cancel <-chan struct{}) (_ Editor, err error)

Editor returns a Editor object that can be used to upload, modify, and delete sectors on a host.

func (*Contractor) InitRecoveryScan added in v1.4.0 

func (c *Contractor) InitRecoveryScan() (err error)

InitRecoveryScan starts scanning the whole blockchain for recoverable contracts within a separate thread.

func (*Contractor) IsOffline added in v1.1.0 

func (c *Contractor) IsOffline(pk types.SiaPublicKey) bool

IsOffline indicates whether a contract's host should be considered offline, based on its scan metrics.

func (*Contractor) MarkContractBad added in v1.5.7 

func (c *Contractor) MarkContractBad(id types.FileContractID) error

MarkContractBad will mark a specific contract as bad.

func (*Contractor) OldContracts added in v1.3.4 

func (c *Contractor) OldContracts() []modules.RenterContract

OldContracts returns the contracts formed by the contractor that have expired

func (*Contractor) PeriodSpending added in v1.3.1 

func (c *Contractor) PeriodSpending() (modules.ContractorSpending, error)

PeriodSpending returns the amount spent on contracts during the current billing period.

func (*Contractor) ProcessConsensusChange 

func (c *Contractor) ProcessConsensusChange(cc modules.ConsensusChange)

ProcessConsensusChange will be called by the consensus set every time there is a change in the blockchain. Updates will always be called in order.

func (*Contractor) ProvidePayment added in v1.5.7 

func (c *Contractor) ProvidePayment(stream io.ReadWriter, pt *modules.RPCPriceTable, details PaymentDetails) error

ProvidePayment takes a stream and a set of payment details and handles the payment for an RPC by sending and processing payment request and response objects to the host. It returns an error in case of failure.

func (*Contractor) RecoverableContracts added in v1.4.0 

func (c *Contractor) RecoverableContracts() []modules.RecoverableContract

RecoverableContracts returns the contracts that the contractor deems recoverable. That means they are not expired yet and also not part of the active contracts. Usually this should return an empty slice unless the host isn't available for recovery or something went wrong.

func (*Contractor) RecoveryScanStatus added in v1.4.0 

func (c *Contractor) RecoveryScanStatus() (bool, types.BlockHeight)

RecoveryScanStatus returns a bool indicating if a scan for recoverable contracts is in progress and if it is, the current progress of the scan.

func (*Contractor) RefreshedContract added in v1.5.7 

func (c *Contractor) RefreshedContract(fcid types.FileContractID) bool

RefreshedContract returns a bool indicating if the contract was a refreshed contract. A refreshed contract refers to a contract that ran out of funds prior to the end height and so was renewed with the host in the same period. Both the old and the new contract have the same end height

func (*Contractor) RenewContract added in v1.5.7 

func (c *Contractor) RenewContract(conn net.Conn, fcid types.FileContractID, params modules.ContractParams, txnBuilder modules.TransactionBuilder, tpool modules.TransactionPool, hdb modules.HostDB, pt *modules.RPCPriceTable) (modules.RenterContract, []types.Transaction, error)

RenewContract takes an established connection to a host and renews the contract with that host.

func (*Contractor) Session added in v1.4.0 

func (c *Contractor) Session(pk types.SiaPublicKey, cancel <-chan struct{}) (_ Session, err error)

Session returns a Session object that can be used to upload, modify, and delete sectors on a host.

func (*Contractor) SetAllowance 

func (c *Contractor) SetAllowance(a modules.Allowance) error

SetAllowance sets the amount of money the Contractor is allowed to spend on contracts over a given time period, divided among the number of hosts specified. Note that Contractor can start forming contracts as soon as SetAllowance is called; that is, it may block.

In most cases, SetAllowance will renew existing contracts instead of forming new ones. This preserves the data on those hosts. When this occurs, the renewed contracts will atomically replace their previous versions. If SetAllowance is interrupted, renewed contracts may be lost, though the allocated funds will eventually be returned.

If a is the empty allowance, SetAllowance will archive the current contract set. The contracts cannot be used to create Editors or Downloads, and will not be renewed.

NOTE: At this time, transaction fees are not counted towards the allowance. This means the contractor may spend more than allowance.Funds.

func (*Contractor) Synced added in v1.5.7 

func (c *Contractor) Synced() <-chan struct{}

Synced returns a channel that is closed when the contractor is synced with the peer-to-peer network.

func (*Contractor) UpdateWorkerPool added in v1.5.7 

func (c *Contractor) UpdateWorkerPool(wp modules.WorkerPool)

UpdateWorkerPool updates the workerpool currently in use by the contractor.

type Downloader 

type Downloader interface {
	// Download requests the specified sector data.
	Download(root crypto.Hash, offset, length uint32) ([]byte, error)

	// HostSettings returns the settings that are active in the current
	// downloader session.
	HostSettings() modules.HostExternalSettings

	// Close terminates the connection to the host.
	Close() error
}

An Downloader retrieves sectors from with a host. It requests one sector at a time, and revises the file contract to transfer money to the host proportional to the data retrieved.

type Editor 

type Editor interface {
	// Upload revises the underlying contract to store the new data. It
	// returns the Merkle root of the data.
	Upload(data []byte) (root crypto.Hash, err error)

	// Address returns the address of the host.
	Address() modules.NetAddress

	// ContractID returns the FileContractID of the contract.
	ContractID() types.FileContractID

	// EndHeight returns the height at which the contract ends.
	EndHeight() types.BlockHeight

	// Close terminates the connection to the host.
	Close() error

	// HostSettings returns the host settings that are currently active for the
	// underlying session.
	HostSettings() modules.HostExternalSettings
}

An Editor modifies a Contract by communicating with a host. It uses the contract revision protocol to send modification requests to the host. Editors are the means by which the renter uploads data to hosts.

type PaymentDetails added in v1.5.7 

type PaymentDetails struct {
	// destination details
	Host types.SiaPublicKey

	// payment details
	Amount        types.Currency
	RefundAccount modules.AccountID

	// spending details
	SpendingDetails modules.SpendingDetails
}

PaymentDetails is a helper struct that contains extra information on a payment. Most notably it includes a breakdown of the spending details for a payment, the contractor uses this information to update its spending details accordingly.

type Session added in v1.4.0 

type Session interface {
	// Address returns the address of the host.
	Address() modules.NetAddress

	// Close terminates the connection to the host.
	Close() error

	// ContractID returns the FileContractID of the contract.
	ContractID() types.FileContractID

	// Download requests the specified sector data.
	Download(root crypto.Hash, offset, length uint32) ([]byte, error)

	// DownloadIndex requests data from the sector with the specified index
	// within the contract.
	DownloadIndex(index uint64, offset, length uint32) ([]byte, error)

	// EndHeight returns the height at which the contract ends.
	EndHeight() types.BlockHeight

	// Replace replaces the sector at the specified index with data. The old
	// sector is swapped to the end of the contract data, and is deleted if the
	// trim flag is set.
	Replace(data []byte, sectorIndex uint64, trim bool) (crypto.Hash, error)

	// HostSettings will return the currently active host settings for a
	// session, which allows the workers to check for price gouging and
	// determine whether or not an operation should continue.
	HostSettings() modules.HostExternalSettings

	// Settings calls the Session RPC and updates the active host settings.
	Settings() (modules.HostExternalSettings, error)

	// Upload revises the underlying contract to store the new data. It
	// returns the Merkle root of the data.
	Upload(data []byte) (crypto.Hash, error)
}

A Session modifies a Contract by communicating with a host. It uses the renter-host protocol to send modification requests to the host. Among other things, Sessions are the means by which the renter transfers file data to and from hosts.

type WalletBridge added in v1.3.3 

type WalletBridge struct {
	W walletShim
}

WalletBridge is a bridge for the wallet because wallet is not directly compatible with modules.Wallet (wrong type signature for StartTransaction), we must provide a bridge type.

func (*WalletBridge) NextAddress added in v1.3.3 

func (ws *WalletBridge) NextAddress() (types.UnlockConditions, error)

NextAddress computes and returns the next address of the wallet.

func (*WalletBridge) PrimarySeed added in v1.4.0 

func (ws *WalletBridge) PrimarySeed() (modules.Seed, uint64, error)

PrimarySeed returns the primary wallet seed.

func (*WalletBridge) RegisterTransaction added in v1.5.7 

func (ws *WalletBridge) RegisterTransaction(t types.Transaction, parents []types.Transaction) (transactionBuilder, error)

RegisterTransaction creates a new transactionBuilder from a transaction and parent transactions.

func (*WalletBridge) StartTransaction added in v1.3.3 

func (ws *WalletBridge) StartTransaction() (transactionBuilder, error)

StartTransaction creates a new transactionBuilder that can be used to create and sign a transaction.

func (*WalletBridge) Unlocked added in v1.5.7 

func (ws *WalletBridge) Unlocked() (bool, error)

Unlocked reports whether the wallet bridge is unlocked.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.