host

package
v1.4.5-antfarm Latest Latest
Warning

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

 Go to latest Published: Aug 26, 2020 License: MIT Imports: 37 Imported by: 5

README

Host

The host takes local disk storage and makes it available to the Sia network. It will do so by announcing itself, and its settings, to the network. Renters transact with the host through a number of RPC calls.

In order for data to be uploaded and stored, the renter and host must agree on a file contract. Once they have negotiated the terms of the file contract, it is signed and put on chain. Any further action related to the data is reflected in the file contract by means of contract revisions that get signed by both parties. The host is responsible for managing these contracts, and making sure the data is safely stored. The host proves that it is storing the data by providing a segment of the file and a list of hashes from the file's merkletree.

Aside from storage, the host offers another service called ephemeral accounts. These accounts serve as an alternative payment method to file contracts. Users can deposit money into them and then later use those funds to transact with the host. The most common transactions are uploading and downloading data, however any RPC that requires payment will support receiving payment from an ephemeral account.

Submodules

ContractManager

The ContractManager is responsible for managing contracts that the host has with renters, including storing the data, submitting storage proofs, and deleting the data when a contract is complete.

Subsystems

The Host has the following subsystems that help carry out its responsibilities.

AccountManager Subsystem

Key Files

The AccountManager subsystem manages all of the ephemeral accounts on the host.

Ephemeral accounts are a service offered by hosts that allow users to connect a balance to a pubkey. Users can deposit funds into an ephemeral account with a host and then later use the funds to transact with the host.

The account owner fully entrusts the money with the host, they have no recourse at all if the host decides to steal the funds. For this reason, users should only keep tiny balances in ephemeral accounts and users should refill the ephemeral accounts frequently, even on the order of multiple times per minute.

To increase performance, the host will allow a user to withdraw from an ephemeral account without requiring the user to wait until the host has persisted the withdrawal to complete a transaction. This allows the user to perform actions such as downloading with significantly less latency. This also means that if the host loses power at that exact moment, the host will forget that the user has spent money and the user will be able to spend that money again. The host can configure the amount of money it is willing to risk due to this asynchronous persist model through the maxephemeralaccountrisk setting.

Ephemeral accounts that have been inactive for a long period of time will be pruned from the account list. This will effectively expire the account, along with all the money that was associated to it. The host can configure this period through the ephemeralaccountexpiry setting. The default is set to a period of 7 days.

AccountsPersister Subsystem

Key Files

The AccountsPersister subsystem will persist all ephemeral account data to disk. This data consists of two parts, the account balance and the fingerprints. Fingerprints are derived from the withdrawal message the user used to perform a withdrawal. They ensure that the same withdrawal can not be withdrawn twice, thus preventing a replay attack on the host.

The account balances together with the corresponding publickey are persisted in a single accounts file. The fingerprints are persisted across two files, the current and the next fingerprint bucket. The expiry blockheight of the withdrawal message decide if the fingerprint belongs to either the current or the next bucket.

Documentation

Overview

Package host is an implementation of the host module, and is responsible for participating in the storage ecosystem, turning available disk space an internet bandwidth into profit for the user.

Index

Constants

View Source 
const (
	// AlertMSGHostInsufficientCollateral indicates that a host has insufficient
	// collateral budget remaining
	AlertMSGHostInsufficientCollateral = "host has insufficient collateral budget"
)

Constants related to the host's alerts.

Variables

View Source 
var (
	// ErrAccountPersist occurs when an ephemeral account could not be persisted
	// to disk.
	ErrAccountPersist = errors.New("ephemeral account could not be persisted to disk")

	// ErrAccountExpired occurs when a blocked action can not complete because
	// the account has expired in the meantime.
	ErrAccountExpired = errors.New("ephemeral account expired")

	// ErrBalanceInsufficient occurs when a withdrawal could not be successfully
	// completed because the account balance was insufficient.
	ErrBalanceInsufficient = errors.New("ephemeral account balance was insufficient")

	// ErrBalanceMaxExceeded occurs when a deposit would push the account's
	// balance over the maximum allowed ephemeral account balance.
	ErrBalanceMaxExceeded = errors.New("ephemeral account maximam balance exceeded")

	// ErrDepositCancelled occurs when the host was willingly or unwillingly
	// stopped in the midst of a deposit process.
	ErrDepositCancelled = errors.New("ephemeral account deposit cancelled due to a shutdown")

	// ErrWithdrawalCancelled occurs when the host was willingly or unwillingly
	// stopped in the midst of a withdrawal process.
	ErrWithdrawalCancelled = errors.New("ephemeral account withdrawal cancelled due to a shutdown")

	// ErrWithdrawalSpent occurs when a withdrawal is requested using a
	// withdrawal message that has been spent already.
	ErrWithdrawalSpent = errors.New("withdrawal message was already spent")
)

Functions

This section is empty.

Types

type ErrorCommunication added in v1.0.3 

type ErrorCommunication string

ErrorCommunication errors are meant to be returned if the host and the renter seem to be miscommunicating. For example, if the renter attempts to pay an insufficient price, there has been a communication error.

func (ErrorCommunication) Error added in v1.0.3 

func (ec ErrorCommunication) Error() string

Error satisfies the Error interface for the ErrorCommunication type.

type ErrorConnection added in v1.0.3 

type ErrorConnection string

ErrorConnection is meant to be used on errors where the network is returning unexpected errors. For example, sudden disconnects or connection write failures.

func (ErrorConnection) Error added in v1.0.3 

func (ec ErrorConnection) Error() string

Error satisfies the Error interface for the ErrorConnection type.

type ErrorConsensus added in v1.0.3 

type ErrorConsensus string

ErrorConsensus errors are meant to be used when there are problems related to consensus, such as an inability to submit a storage proof to the blockchain, or an inability to get a file contract revision on to the blockchain.

func (ErrorConsensus) Error added in v1.0.3 

func (ec ErrorConsensus) Error() string

Error satisfies the Error interface for the ErrorConsensus type.

type ErrorInternal added in v1.0.3 

type ErrorInternal string

ErrorInternal errors are meant to be used if an internal process in the host is malfunctioning, for example if the disk is failing.

func (ErrorInternal) Error added in v1.0.3 

func (ec ErrorInternal) Error() string

Error satisfies the Error interface for the ErrorInternal type.

type Host 

type Host struct {
	modules.StorageManager
	// contains filtered or unexported fields
}

A Host contains all the fields necessary for storing files for clients and performing the storage proofs on the received files.

func New 

func New(cs modules.ConsensusSet, g modules.Gateway, tpool modules.TransactionPool, wallet modules.Wallet, mux *siamux.SiaMux, address string, persistDir string) (*Host, error)

New returns an initialized Host.

func NewCustomHost added in v1.4.2 

func NewCustomHost(deps modules.Dependencies, cs modules.ConsensusSet, g modules.Gateway, tpool modules.TransactionPool, wallet modules.Wallet, mux *siamux.SiaMux, address string, persistDir string) (*Host, error)

NewCustomHost returns an initialized Host using the provided dependencies.

func NewCustomTestHost added in v1.4.2 

func NewCustomTestHost(deps modules.Dependencies, smDeps modules.Dependencies, cs modules.ConsensusSet, g modules.Gateway, tpool modules.TransactionPool, wallet modules.Wallet, mux *siamux.SiaMux, address string, persistDir string) (*Host, error)

NewCustomTestHost allows passing in both host dependencies and storage manager dependencies. Used solely for testing purposes, to allow dependency injection into the host's submodules.

func (*Host) Alerts added in v1.4.2 

func (h *Host) Alerts() (crit, err, warn []modules.Alert)

Alerts implements the modules.Alerter interface for the host.

func (*Host) Announce 

func (h *Host) Announce() error

Announce creates a host announcement transaction.

func (*Host) AnnounceAddress added in v1.0.0 

func (h *Host) AnnounceAddress(addr modules.NetAddress) error

AnnounceAddress submits a host announcement to the blockchain to announce a specific address. If there is no error, the host's address will be updated to the supplied address.

func (*Host) BandwidthCounters added in v1.4.3 

func (h *Host) BandwidthCounters() (uint64, uint64, time.Time, error)

BandwidthCounters returns the Hosts's upload and download bandwidth

func (*Host) BlockHeight added in v1.4.2 

func (h *Host) BlockHeight() types.BlockHeight

BlockHeight returns the host's current blockheight.

func (*Host) Close added in v1.0.0 

func (h *Host) Close() error

Close shuts down the host.

func (*Host) ConnectabilityStatus added in v1.2.0 

func (h *Host) ConnectabilityStatus() modules.HostConnectabilityStatus

ConnectabilityStatus returns the connectability state of the host, whether the host can connect to itself on its configured netaddress.

func (*Host) ExternalSettings added in v1.0.0 

func (h *Host) ExternalSettings() modules.HostExternalSettings

ExternalSettings returns the hosts external settings. These values cannot be set by the user (host is configured through InternalSettings), and are the values that get displayed to other hosts on the network.

func (*Host) FinancialMetrics added in v1.0.0 

func (h *Host) FinancialMetrics() modules.HostFinancialMetrics

FinancialMetrics returns information about the financial commitments, rewards, and activities of the host.

func (*Host) InternalSettings added in v1.0.0 

func (h *Host) InternalSettings() modules.HostInternalSettings

InternalSettings returns the settings of a host.

func (*Host) NetAddress added in v1.0.0 

func (h *Host) NetAddress() modules.NetAddress

NetAddress returns the address at which the host can be reached.

func (*Host) NetworkMetrics added in v1.0.0 

func (h *Host) NetworkMetrics() modules.HostNetworkMetrics

NetworkMetrics returns information about the types of rpc calls that have been made to the host.

func (*Host) ProcessConsensusChange added in v1.0.0 

func (h *Host) ProcessConsensusChange(cc modules.ConsensusChange)

ProcessConsensusChange will be called by the consensus set every time there is a change to the blockchain.

func (*Host) PruneStaleStorageObligations added in v1.4.0 

func (h *Host) PruneStaleStorageObligations() error

PruneStaleStorageObligations will delete storage obligations from the host that, for whatever reason, did not make it on the block chain. As these stale storage obligations have an impact on the host financial metrics, this method updates the host financial metrics to show the correct values.

func (*Host) PublicKey added in v1.1.1 

func (h *Host) PublicKey() types.SiaPublicKey

PublicKey returns the public key of the host that is used to facilitate relationships between the host and renter.

func (*Host) SetInternalSettings added in v1.0.0 

func (h *Host) SetInternalSettings(settings modules.HostInternalSettings) error

SetInternalSettings updates the host's internal HostInternalSettings object.

func (*Host) StorageObligations added in v1.1.2 

func (h *Host) StorageObligations() (sos []modules.StorageObligation)

StorageObligations fetches the set of storage obligations in the host and returns metadata on them.

func (*Host) TryUnregisterInsufficientCollateralBudgetAlert added in v1.4.2 

func (h *Host) TryUnregisterInsufficientCollateralBudgetAlert()

TryUnregisterInsufficientCollateralBudgetAlert will be called when the host updates his collateral budget setting or when the locked storage collateral gets updated (in a way the updated storage collateral is lower).

func (*Host) WorkingStatus added in v1.2.0 

func (h *Host) WorkingStatus() modules.HostWorkingStatus

WorkingStatus returns the working state of the host, where working is defined as having received more than workingStatusThreshold settings calls over the period of workingStatusFrequency.

type StorageObligationSnapshot added in v1.4.5 

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

StorageObligationSnapshot is a snapshot of a StorageObligation. A snapshot is a deep-copy and can be accessed without locking at the cost of being a frozen readonly representation of an SO which only exists in memory. Note that this snapshot only contains the properties required by the MDM to execute a program. This can be extended in the future to support other use cases.

func (StorageObligationSnapshot) ContractSize added in v1.4.5 

func (sos StorageObligationSnapshot) ContractSize() uint64

ContractSize returns the size of the underlying contract, which is static and is the value of the contract size at the time the snapshot was taken.

func (StorageObligationSnapshot) MerkleRoot added in v1.4.5 

func (sos StorageObligationSnapshot) MerkleRoot() crypto.Hash

MerkleRoot returns the merkle root, which is static and is the value of the merkle root at the time the snapshot was taken.

func (StorageObligationSnapshot) SectorRoots added in v1.4.5 

func (sos StorageObligationSnapshot) SectorRoots() []crypto.Hash

SectorRoots returns a static list of the sector roots present at the time the snapshot was taken.

Source Files

View all Source files

Directories

Path Synopsis

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.