host

package
v1.6.3 Latest Latest
Warning

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

 Go to latest Published: Jun 3, 2022 License: MIT Imports: 45 Imported by: 0

README

Host

The host takes local disk storage and makes it available to the ScPrime 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")

	// ErrZeroAccountID occurs when an account is opened with the ZeroAccountID.
	ErrZeroAccountID = errors.New("can't open an account with an empty account id")
)
View Source 
var (
	// ErrBadContractOutputCounts is returned if the presented file contract
	// revision has the wrong number of outputs for either the valid or the
	// missed proof outputs.
	ErrBadContractOutputCounts = ErrorCommunication("rejected for having an unexpected number of outputs")

	// ErrBadContractParent is returned when a file contract revision is
	// presented which has a parent id that doesn't match the file contract
	// which is supposed to be getting revised.
	ErrBadContractParent = ErrorCommunication("could not find contract's parent")

	// ErrBadFileMerkleRoot is returned if the renter incorrectly updates the
	// file merkle root during a file contract revision.
	ErrBadFileMerkleRoot = ErrorCommunication("rejected for bad file merkle root")

	// ErrBadFileSize is returned if the renter incorrectly download and
	// changes the file size during a file contract revision.
	ErrBadFileSize = ErrorCommunication("rejected for bad file size")

	// ErrBadModificationIndex is returned if the renter requests a change on a
	// sector root that is not in the file contract.
	ErrBadModificationIndex = ErrorCommunication("renter has made a modification that points to a nonexistent sector")

	// ErrBadParentID is returned if the renter incorrectly download and
	// provides the wrong parent id during a file contract revision.
	ErrBadParentID = ErrorCommunication("rejected for bad parent id")

	// ErrBadPayoutUnlockHashes is returned if the renter incorrectly sets the
	// payout unlock hashes during contract formation.
	ErrBadPayoutUnlockHashes = ErrorCommunication("rejected for bad unlock hashes in the payout")

	// ErrBadRevisionNumber number is returned if the renter incorrectly
	// download and does not increase the revision number during a file
	// contract revision.
	ErrBadRevisionNumber = ErrorCommunication("rejected for bad revision number")

	// ErrBadSectorSize is returned if the renter provides a sector to be
	// inserted that is the wrong size.
	ErrBadSectorSize = ErrorCommunication("renter has provided an incorrectly sized sector")

	// ErrBadUnlockConditions is returned if the renter incorrectly download
	// and does not provide the right unlock conditions in the payment
	// revision.
	ErrBadUnlockConditions = ErrorCommunication("rejected for bad unlock conditions")

	// ErrBadUnlockHash is returned if the renter incorrectly updates the
	// unlock hash during a file contract revision.
	ErrBadUnlockHash = ErrorCommunication("rejected for bad new unlock hash")

	// ErrBadWindowEnd is returned if the renter incorrectly download and
	// changes the window end during a file contract revision.
	ErrBadWindowEnd = ErrorCommunication("rejected for bad new window end")

	// ErrBadWindowStart is returned if the renter incorrectly updates the
	// window start during a file contract revision.
	ErrBadWindowStart = ErrorCommunication("rejected for bad new window start")

	// ErrEarlyWindow is returned if the file contract provided by the renter
	// has a storage proof window that is starting too near in the future.
	ErrEarlyWindow = ErrorCommunication("rejected for a window that starts too soon")

	// ErrEmptyObject is returned if the renter sends an empty or nil object
	// unexpectedly.
	ErrEmptyObject = ErrorCommunication("renter has unexpectedly send an empty/nil object")

	// ErrHighRenterMissedOutput is returned if the renter incorrectly download
	// and deducts an insufficient amount from the renter missed outputs during
	// a file contract revision.
	ErrHighRenterMissedOutput = ErrorCommunication("rejected for high paying renter missed output")

	// ErrHighRenterValidOutput is returned if the renter incorrectly download
	// and deducts an insufficient amount from the renter valid outputs during
	// a file contract revision.
	ErrHighRenterValidOutput = ErrorCommunication("rejected for high paying renter valid output")

	// ErrIllegalOffsetAndLength is returned if the renter tries perform a
	// modify operation that uses a troublesome combination of offset and
	// length.
	ErrIllegalOffsetAndLength = ErrorCommunication("renter is trying to do a modify with an illegal offset and length")

	// ErrInvalidPayoutSums is returned if a revision doesn't sum up to the same
	// total payout as the previous revision or contract.
	ErrInvalidPayoutSums = ErrorCommunication("renter provided a revision with an invalid total payout")

	// ErrLargeSector is returned if the renter sends a RevisionAction that has
	// data which creates a sector that is larger than what the host uses.
	ErrLargeSector = ErrorCommunication("renter has sent a sector that exceeds the host's sector size")

	// ErrLateRevision is returned if the renter is attempting to revise a
	// revision after the revision deadline. The host needs time to submit the
	// final revision to the blockchain to guarantee payment, and therefore
	// will not accept revisions once the window start is too close.
	ErrLateRevision = ErrorCommunication("renter is requesting revision after the revision deadline")

	// ErrLongDuration is returned if the renter proposes a file contract with
	// an expiration that is too far into the future according to the host's
	// settings.
	ErrLongDuration = ErrorCommunication("renter proposed a file contract with a too-long duration")

	// ErrLowHostMissedOutput is returned if the renter incorrectly updates the
	// host missed proof output during a file contract revision.
	ErrLowHostMissedOutput = ErrorCommunication("rejected for low paying host missed output")

	// ErrLowHostValidOutput is returned if the renter incorrectly updates the
	// host valid proof output during a file contract revision.
	ErrLowHostValidOutput = ErrorCommunication("rejected for low paying host valid output")

	// ErrLowTransactionFees is returned if the renter provides a transaction
	// that the host does not feel is able to make it onto the blockchain.
	ErrLowTransactionFees = ErrorCommunication("rejected for including too few transaction fees")

	// ErrLowVoidOutput is returned if the renter has not allocated enough
	// funds to the void output.
	ErrLowVoidOutput = ErrorCommunication("rejected for low value void output")

	// ErrMismatchedHostPayouts is returned if the renter incorrectly sets the
	// host valid and missed payouts to different values during contract
	// formation.
	ErrMismatchedHostPayouts = ErrorCommunication("rejected because host valid and missed payouts are not the same value")

	// ErrSmallWindow is returned if the renter suggests a storage proof window
	// that is too small.
	ErrSmallWindow = ErrorCommunication("rejected for small window size")

	// ErrUnknownModification is returned if the host receives a modification
	// action from the renter that it does not understand.
	ErrUnknownModification = ErrorCommunication("renter is attempting an action that the host does not understand")

	// ErrValidHostOutputAddressChanged is returned when the host's valid output
	// address changed even though it shouldn't.
	ErrValidHostOutputAddressChanged = ErrorCommunication("valid host output address changed")

	// ErrMissedHostOutputAddressChanged is returned when the host's missed
	// payout address changed even though it shouldn't.
	ErrMissedHostOutputAddressChanged = ErrorCommunication("missed host output address changed")

	// ErrVoidAddressChanged is returned if the void output address changed.
	ErrVoidAddressChanged = ErrorCommunication("lost collateral address was changed")

	// ErrValidRenterPayoutChanged is returned if the renter's valid payout
	// changed even though it shouldn't.
	ErrValidRenterPayoutChanged = ErrorCommunication("valid renter payout changed")

	// ErrMissedRenterPayoutChanged is returned if the renter's missed payout
	// changed even though it shouldn't.
	ErrMissedRenterPayoutChanged = ErrorCommunication("missed renter payout changed")

	// ErrValidHostPayoutChanged is returned if the host's valid payout changed
	// even though it shouldn't.
	ErrValidHostPayoutChanged = ErrorCommunication("valid host payout changed")

	// ErrVoidPayoutChanged is returned if the void payout changed even though
	// it wasn't expected to.
	ErrVoidPayoutChanged = ErrorCommunication("void payout shouldn't change")
)
View Source 
var (
	// ErrPriceTableNotFound is returned when the price table for a certain UID
	// can not be found in the tracked price tables
	ErrPriceTableNotFound = errors.New("Price table not found")

	// ErrPriceTableExpired is returned when the specified price table has
	// expired
	ErrPriceTableExpired = errors.New("Price table requested is expired")
)
View Source 
var (

	// ErrNoStorageObligation is returned if the requested storage obligation
	// is not found in the database.
	ErrNoStorageObligation = errors.New("storage obligation not found in database")
)
View Source 
var (
	// ErrObligationLocked is returned if the file contract being requested is
	// currently locked. The lock can be in place if there is a storage proof
	// being submitted, if there is another renter altering the contract, or if
	// there have been network connections with have not resolved yet.
	ErrObligationLocked = errors.New("the requested file contract is currently locked")
)

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, persistDir string, hostAPIListener net.Listener, checkTokenExpirationFrequency time.Duration) (*Host, error)

New returns an initialized Host.

func NewCustomHost added in v1.5.0 

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

NewCustomHost returns an initialized Host using the provided dependencies.

func NewCustomTestHost added in v1.5.0 

func NewCustomTestHost(deps modules.Dependencies, smDeps modules.Dependencies, cs modules.ConsensusSet, g modules.Gateway, tpool modules.TransactionPool, wallet modules.Wallet, mux *siamux.SiaMux, address, persistDir string, hostAPIListener net.Listener, checkTokenExpirationFrequency time.Duration) (*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.5.0 

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) Announcement added in v1.6.0 

func (h *Host) Announcement() []byte

Announcement returns host announcement. For use as ghost.

func (*Host) AuditStorageObligations added in v1.5.2 

func (h *Host) AuditStorageObligations()

AuditStorageObligations locks the host, fetches the set of storage obligations in the host and checks if any old storage obligations are not marked correctly and removed if expired along with stale contract removal

func (*Host) BandwidthCounters added in v1.5.0 

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

BandwidthCounters returns the Hosts's upload and download bandwidth

func (*Host) BlockHeight added in v1.5.0 

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) ManagedExternalSettings added in v1.6.0 

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

ManagedExternalSettings returns the host's 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) MoveTokenSectorsToStorageObligation added in v1.6.0 

func (h *Host) MoveTokenSectorsToStorageObligation(fcID types.FileContractID, renterRevision types.FileContractRevision, sectorsWithTokens []types.SectorWithToken, renterSig []byte) ([]byte, error)

MoveTokenSectorsToStorageObligation moves sectors from temporary storage to storage obligation object and returns host signature.

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) ProcessPayment added in v1.5.0 

func (h *Host) ProcessPayment(stream siamux.Stream) (modules.PaymentDetails, error)

ProcessPayment reads a payment request from the stream. Depending on the type of payment it will either update the file contract or call upon the ephemeral account manager to process the payment. It will return the account id, the amount paid and an error in case of failure. The account id will only be valid if the payment method is PayByEphemeralAccount, it will be an empty string otherwise.

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) StorageObligation added in v1.5.2 

func (h *Host) StorageObligation(obligationID types.FileContractID) (modules.StorageObligation, error)

StorageObligation returns the storage obligation matching the id or an error if it does not exist.

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) 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 HostMock added in v1.6.0 

type HostMock struct {
	Mux *siamux.SiaMux

	CS           modules.ConsensusSet
	Gateway      modules.Gateway
	Miner        modules.TestMiner
	Tpool        modules.TransactionPool
	HostWallet   modules.Wallet
	RenterWallet modules.Wallet

	Host *Host
}

HostMock is almost full copy of the hostTester.

func NewHostMock added in v1.6.0 

func NewHostMock(d modules.Dependencies, dirName string) (*HostMock, error)

NewHostMock creates new public host mock based on private therefore do not affect old tests.

func (*HostMock) Close added in v1.6.0 

func (hm *HostMock) Close() error

Close closes all host mock entities.

type StorageObligationSnapshot added in v1.5.0 

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 ZeroStorageObligationSnapshot added in v1.5.0 

func ZeroStorageObligationSnapshot() StorageObligationSnapshot

ZeroStorageObligationSnapshot returns the storage obligation snapshot of an empty contract. All fields are set to the defaults.

func (StorageObligationSnapshot) ContractSize added in v1.5.0 

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.5.0 

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) ProofDeadline added in v1.5.0 

func (sos StorageObligationSnapshot) ProofDeadline() types.BlockHeight

ProofDeadline returns the proof deadline of the underlying contract.

func (StorageObligationSnapshot) RecentRevision added in v1.5.0 

func (sos StorageObligationSnapshot) RecentRevision() types.FileContractRevision

RecentRevision returns the recent revision at the time the snapshot was taken.

func (StorageObligationSnapshot) RevisionTxn added in v1.5.0 

func (sos StorageObligationSnapshot) RevisionTxn() types.Transaction

RevisionTxn returns the txn containing the filecontract revision.

func (StorageObligationSnapshot) SectorRoots added in v1.5.0 

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

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

func (StorageObligationSnapshot) UnallocatedCollateral added in v1.5.0 

func (sos StorageObligationSnapshot) UnallocatedCollateral() types.Currency

UnallocatedCollateral returns the remaining collateral within the contract that hasn't been allocated yet. This means it is not yet moved to the void in case of a missed storage proof.

Source Files

View all Source files

Directories

Path Synopsis
api
gen
tokenstate

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.