modules

package
v0.3.3 Latest Latest
Warning

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

 Go to latest Published: Jun 7, 2015 License: MIT Imports: 8 Imported by: 6

Documentation

Index

Constants

View Source 
const (
	AcceptTermsResponse = "accept"
	HostDir             = "host"
)
View Source 
const (
	GatewayDir = "gateway"
)
View Source 
const (
	NotifyBuffer = 3
)
View Source 
const (
	// Denotes a host announcement in the Arbitrary Data section.
	PrefixHostAnnouncement = "HostAnnouncement"
)
View Source 
const (
	WalletDir = "wallet"
)

Variables

View Source 
var (
	BootstrapPeers = []NetAddress{
		"23.239.14.98:9981",
		"87.98.216.46:9981",
	}
)

TODO: Move this and it's functionality into the gateway package.

View Source 
var (
	ErrNonExtendingBlock = errors.New("block does not extend the longest fork.")
)
View Source 
var (
	// ErrTransactionPoolDuplicate is returned when a duplicate transaction is
	// submitted to the transaction pool.
	ErrTransactionPoolDuplicate = errors.New("transaction is a duplicate")
)
View Source 
var ExternalIP = func() string {
	if build.Release == "testing" {
		return "::1"
	}

	resp, err := http.Get("http://myexternalip.com/raw")
	if err != nil {
		return "::1"
	}
	defer resp.Body.Close()
	buf := make([]byte, 64)
	n, err := resp.Body.Read(buf)
	if err != nil && err != io.EOF {
		return "::1"
	}
	return string(buf[:n-1])
}()

ExternalIP is the external IP of the computer running this code. It is defined here to facilitate reuse, instead of requiring each module to make an HTTP call. During testing, the loopback address is returned.

View Source 
var (
	LowBalanceErr = errors.New("Insufficient Balance")
)
View Source 
var (
	RenterDir = "renter"
)
View Source 
var (
	SafeMutexDelay time.Duration
)

Functions

This section is empty.

Types

type ConsensusChange added in v0.3.3 

type ConsensusChange struct {
	// RevertedBlocks is the list of blocks that were reverted by the change.
	// The reverted blocks were always all reverted before the applied blocks
	// were applied. The revered blocks are presented in the order that they
	// were reverted.
	RevertedBlocks []types.Block

	// AppliedBlocks is the list of blocks that were applied by the change. The
	// applied blocks are always all applied after all the reverted blocks were
	// reverted. The applied blocks are presented in the order that they were
	// applied.
	AppliedBlocks []types.Block

	// SiacoinOutputDiffs contains the set of siacoin diffs that were applied
	// to the consensus set in the recent change. The direction for the set of
	// diffs is 'DiffApply'.
	SiacoinOutputDiffs []SiacoinOutputDiff

	// FileContractDiffs contains the set of file contract diffs that were
	// applied to the consensus set in the recent change. The direction for the
	// set of diffs is 'DiffApply'.
	FileContractDiffs []FileContractDiff

	// SiafundOutputDiffs contains the set of siafund diffs that were applied
	// to the consensus set in the recent change. The direction for the set of
	// diffs is 'DiffApply'.
	SiafundOutputDiffs []SiafundOutputDiff

	// SiafundPoolDiff is the siafund pool diff that was applied to the
	// consensus set in the recent change.
	SiafundPoolDiff SiafundPoolDiff
}

A ConsensusChange enumerates a set of changes that occured to the consensus set.

type ConsensusSet added in v0.3.2 

type ConsensusSet interface {
	// AcceptBlock adds a block to consensus. An error will be returned if the
	// block is invalid, has been seen before, is an orphan, or doesn't
	// contribute to the heaviest fork known to the consensus set. If the block
	// does not become the head of the heaviest known fork but is otherwise
	// valid, it will be remembered by the consensus set but an error will
	// still be returned.
	AcceptBlock(types.Block) error

	// ChildTarget returns the target required to extend the current heaviest
	// fork. This function is typically used by miners looking to extend the
	// heaviest fork.
	ChildTarget(types.BlockID) (types.Target, bool)

	// Close will shut down the consensus set, giving the module enough time to
	// run any required closing routines.
	Close() error

	// ConsensusSetSubscribe will subscribe another module to the consensus
	// set. Every time that there is a change to the consensus set, an update
	// will be sent to the module via the 'ReceiveConsensusSetUpdate' function.
	// This is a thread-safe way of managing updates.
	ConsensusSetSubscribe(ConsensusSetSubscriber)

	// CurrentBlock returns the most recent block on the heaviest fork known to
	// the consensus set.
	CurrentBlock() types.Block

	// EarliestChildTimestamp returns the earliest timestamp that is acceptable
	// on the current longest fork according to the consensus set. This is a
	// required piece of information for the miner, who could otherwise be at
	// risk of mining invalid blocks.
	EarliestChildTimestamp(types.BlockID) (types.Timestamp, bool)

	// GenesisBlock returns the genesis block.
	GenesisBlock() types.Block

	// InCurrentPath returns true if the block id presented is found in the
	// current path, false otherwise.
	InCurrentPath(types.BlockID) bool

	// Synchronize will try to synchronize to a specific peer. During general
	// use, this call should never be necessary.
	Synchronize(NetAddress) error

	// ValidStorageProofs checks that all the storage proofs in a transaction
	// are valid in the context of the current consensus set. An error is
	// returned if not.
	//
	// NOTE: For synchronization reasons, this call is not recommended and
	// should be deprecated.
	ValidStorageProofs(types.Transaction) error
}

A ConsensusSet accepts blocks and builds an understanding of network consensus.

type ConsensusSetSubscriber added in v0.3.2 

type ConsensusSetSubscriber interface {
	// ReceiveConsensusSetUpdate sends a consensus update to a module through a
	// function call. Updates will always be sent in the correct order.
	// Usually, the function receiving the updates will also process the
	// changes. If the function blocks indefinitely, the state will still
	// function.
	ReceiveConsensusSetUpdate(ConsensusChange)
}

A ConsensusSetSubscriber is an object that receives updates to the consensus set every time there is a change in consensus.

type ContractTerms 

type ContractTerms struct {
	FileSize           uint64                // How large the file is.
	Duration           types.BlockHeight     // How long the file is to be stored.
	DurationStart      types.BlockHeight     // The block height that the storing starts (typically required to start immediately, unless it's a chained contract).
	WindowSize         types.BlockHeight     // How long the host has to submit a proof of storage.
	Price              types.Currency        // Client contribution towards payout each window
	Collateral         types.Currency        // Host contribution towards payout each window
	ValidProofOutputs  []types.SiacoinOutput // Where money goes if the storage proof is successful.
	MissedProofOutputs []types.SiacoinOutput // Where the money goes if the storage proof fails.
}

ContractTerms are the parameters agreed upon by a client and a host when forming a FileContract.

type DelayedSiacoinOutputDiff added in v0.3.3 

type DelayedSiacoinOutputDiff struct {
	Direction      DiffDirection
	ID             types.SiacoinOutputID
	SiacoinOutput  types.SiacoinOutput
	MaturityHeight types.BlockHeight
}

type DiffDirection added in v0.3.1 

type DiffDirection bool

A DiffDirection indicates the "direction" of a diff, either applied or reverted. A bool is used to restrict the value to these two possibilities. 

const (
	ConsensusDir = "consensus"

	// DiffApply and DiffRevert are the names given to the variables
	// corresponding to applying and reverting diffs.
	DiffApply  DiffDirection = true
	DiffRevert DiffDirection = false
)

type DownloadInfo 

type DownloadInfo interface {
	// StartTime is when the download was initiated.
	StartTime() time.Time

	// Complete returns whether the file is ready to be used. Note that
	// Received == Filesize does not imply Complete, because the file may
	// require additional processing (e.g. decryption) after all of the raw
	// bytes have been downloaded.
	Complete() bool

	// Filesize is the size of the file being downloaded.
	Filesize() uint64

	// Received is the number of bytes downloaded so far.
	Received() uint64

	// Destination is the filepath that the file was downloaded into.
	Destination() string

	// Nickname is the identifier assigned to the file when it was uploaded.
	Nickname() string
}

DownloadInfo is an interface providing information about a file that has been requested for download.

type FileContractDiff added in v0.3.1 

type FileContractDiff struct {
	Direction    DiffDirection
	ID           types.FileContractID
	FileContract types.FileContract
}

A FileContractDiff indicates the addition or removal of a FileContract in the consensus set.

type FileInfo 

type FileInfo interface {
	// Available indicates whether the file is available for downloading or
	// not.
	Available() bool

	// UploadProgress is a percentage indicating the progress of the file as
	// it is being uploaded. This percentage is calculated internally (unlike
	// DownloadInfo) because redundancy schemes complicate the definition of
	// "progress." As a rule, Available == true IFF UploadProgress == 100.0.
	UploadProgress() float32

	// Nickname gives the nickname of the file.
	Nickname() string

	// Repairing indicates whether the file is actively being repaired. If
	// there are files being repaired, it is best to let them finish before
	// shutting down the program.
	Repairing() bool

	// TimeRemaining indicates how many blocks remain before the file expires.
	TimeRemaining() types.BlockHeight
}

FileInfo is an interface providing information about a file.

type FileUploadParams added in v0.3.1 

type FileUploadParams struct {
	Filename string
	Duration types.BlockHeight
	Nickname string
	Pieces   int
}

FileUploadParams contains the information used by the Renter to upload a file.

type Gateway 

type Gateway interface {
	// Connect establishes a persistent connection to a peer.
	Connect(NetAddress) error

	// Disconnect terminates a connection to a peer.
	Disconnect(NetAddress) error

	// Address returns the Gateway's address.
	Address() NetAddress

	// Peers returns the addresses that the Gateway is currently connected to.
	Peers() []NetAddress

	// RegisterRPC registers a function to handle incoming connections that
	// supply the given RPC ID.
	RegisterRPC(string, RPCFunc)

	// RegisterConnectCall registers an RPC name and function to be called
	// upon connecting to a peer.
	RegisterConnectCall(string, RPCFunc)

	// RPC calls an RPC on the given address. RPC cannot be called on an
	// address that the Gateway is not connected to.
	RPC(NetAddress, string, RPCFunc) error

	// Broadcast transmits obj, prefaced by the RPC name, to all of the
	// Gateway's connected peers in parallel.
	Broadcast(name string, obj interface{})

	// Close safely stops the Gateway's listener process.
	Close() error
}

A Gateway facilitates the interactions between the local node and remote nodes (peers). It relays incoming blocks and transactions to local modules, and broadcasts outgoing blocks and transactions to peers. In a broad sense, it is responsible for ensuring that the local consensus set is consistent with the "network" consensus set.

type Host 

type Host interface {
	// Address returns the host's network address
	Address() NetAddress

	// Announce announces the host on the blockchain.
	Announce() error

	// HostNotify will push a struct down the channel every time that an update
	// is received.
	HostNotify() <-chan struct{}

	// SetConfig sets the hosting parameters of the host.
	SetSettings(HostSettings)

	// Settings returns the host's settings.
	Settings() HostSettings

	// Info returns info about the host, including its hosting parameters, the
	// amount of storage remaining, and the number of active contracts.
	Info() HostInfo
}

type HostAnnouncement 

type HostAnnouncement struct {
	IPAddress NetAddress
}

HostAnnouncements are stored in the Arbitrary Data section of transactions on the blockchain. They announce the willingness of a node to host files. Renters can contact the host privately to obtain more detailed hosting parameters (see HostSettings). To mitigate Sybil attacks, HostAnnouncements are paired with a volume of 'frozen' coins. The FreezeIndex indicates which output in the transaction contains the frozen coins, and the SpendConditions indicate the number of blocks the coins are frozen for.

type HostDB 

type HostDB interface {
	// ActiveHosts returns the list of hosts that are actively being selected
	// from.
	ActiveHosts() []HostSettings

	// AllHosts returns the full list of hosts known to the hostdb.
	AllHosts() []HostSettings

	// HostDBNotify will push a struct down the returned channel every time the
	// hostdb receives an update from the consensus set.
	HostDBNotify() <-chan struct{}

	// InsertHost adds a host to the database.
	InsertHost(HostSettings) error

	// RandomHosts will pull up to 'num' random hosts from the hostdb. There
	// will be no repeats, but the length of the slice returned may be less
	// than 'num', and may even be 0. The hosts returned first have the higher
	// priority.
	RandomHosts(num int) []HostSettings

	// Remove deletes the host with the input address from the database.
	RemoveHost(NetAddress) error
}

A HostDB is a database of hosts that the renter can use for figuring out who to upload to, and download from.

type HostInfo 

type HostInfo struct {
	HostSettings

	StorageRemaining int64
	NumContracts     int
	Profit           types.Currency
	PotentialProfit  types.Currency
}

HostInfo contains HostSettings and details pertinent to the host's understanding of their offered services

type HostSettings 

type HostSettings struct {
	IPAddress    NetAddress
	TotalStorage int64 // Can go negative.
	MinFilesize  uint64
	MaxFilesize  uint64
	MinDuration  types.BlockHeight
	MaxDuration  types.BlockHeight
	WindowSize   types.BlockHeight
	Price        types.Currency
	Collateral   types.Currency
	UnlockHash   types.UnlockHash
}

HostSettings are the parameters advertised by the host. These are the values that the HostDB will request from the host in order to build its database.

type Miner added in v0.3.1 

type Miner interface {
	// BlockForWork returns a block that is ready for nonce grinding. All
	// blocks returned by BlockForWork have a unique merkle root, meaning that
	// each can safely start from nonce 0.
	BlockForWork() (types.Block, crypto.Hash, types.Target)

	// FindBlock will have the miner make 1 attempt to find a solved block that
	// builds on the current consensus set. It will give up after a few
	// seconds, returning a block, a bool indicating whether the block is
	// sovled, and an error. FindBlock will submit the block to the consensus
	// set.
	FindBlock() (types.Block, bool, error)

	// MinerInfo returns a MinerInfo struct, containing information about the
	// miner.
	MinerInfo() MinerInfo

	// MinerNotify is a channel to inform subscribers of when the miner has
	// updated. This is primarily used for synchronization during testing.
	MinerNotify() <-chan struct{}

	// SetThreads sets the number of threads in the miner.
	SetThreads(int) error

	// SolveBlock will have the miner make 1 attempt to solve the input block.
	// It will give up after a few seconds, returning the block, a bool
	// indicating whether it has been solved, and an error. SolveBlock is very
	// slow, and will not submit the block the the consensus set.
	SolveBlock(types.Block, types.Target) (types.Block, bool)

	// StartMining turns on the miner, which will endlessly work for new
	// blocks.
	StartMining() error

	// StopMining turns off the miner, but keeps the same number of threads.
	StopMining() error

	// SubmitBlock takes a block that has been worked on and has a valid
	// target. Typically used with external miners.
	SubmitBlock(types.Block) error
}

The Miner interface provides access to mining features.

type MinerInfo added in v0.3.1 

type MinerInfo struct {
	State          string
	Mining         bool
	Threads        int
	RunningThreads int
	HashRate       int64
	BlocksPerWeek  float64
	BlocksMined    int
	OrphansMined   int
	Address        types.UnlockHash
}

MinerStatus is the information that gets returned to the front end. Each item is returned in the format that it's meant to be displayed.

type NetAddress 

type NetAddress string

A NetAddress contains the information needed to contact a peer.

func (NetAddress) Host 

func (na NetAddress) Host() string

Host returns the NetAddress' IP.

func (NetAddress) Port 

func (na NetAddress) Port() string

Port returns the NetAddress' port number.

type PeerConn added in v0.3.1 

type PeerConn interface {
	net.Conn
}

A PeerConn is the connection type used when communicating with peers during an RPC. For now it is identical to a net.Conn.

type RPCFunc 

type RPCFunc func(PeerConn) error

RPCFunc is the type signature of functions that handle RPCs. It is used for both the caller and the callee. RPCFuncs may perform locking. RPCFuncs may close the connection early, and it is recommended that they do so to avoid keeping the connection open after all necessary I/O has been performed.

type RentInfo 

type RentInfo struct {
	Files []string
	Price types.Currency
}

RentInfo contains a list of all files by nickname. (deprecated)

type Renter 

type Renter interface {
	// DeleteFile deletes a file entry from the renter.
	DeleteFile(nickname string) error

	// Download downloads a file to the given filepath.
	Download(nickname, filepath string) error

	// DownloadQueue lists all the files that have been scheduled for download.
	DownloadQueue() []DownloadInfo

	// FileList returns information on all of the files stored by the renter.
	FileList() []FileInfo

	// Info returns the list of all files by nickname. (deprecated)
	Info() RentInfo

	// LoadSharedFile loads a '.sia' file into the renter, so that the user can
	// download files which have been shared with them.
	LoadSharedFile(filename string) ([]string, error)

	// LoadSharedFilesAscii loads a '.sia' file into the renter, except instead
	// of taking a filename it takes a base64 encoded string of the file.
	LoadSharedFilesAscii(asciiSia string) ([]string, error)

	// Rename changes the nickname of a file.
	RenameFile(currentName, newName string) error

	// RenterNotify will push a struct down the channel every time it receives
	// an update.
	RenterNotify() <-chan struct{}

	// ShareFiles creates a '.sia' file that can be shared with others, so that
	// they may download files which they have not uploaded.
	ShareFiles(nicknames []string, sharedest string) error

	// ShareFilesAscii creates a '.sia' file that can be shared with others,
	// except it returns the bytes of the file in base64.
	ShareFilesAscii(nicknames []string) (asciiSia string, err error)

	// Upload uploads a file using the input parameters.
	Upload(FileUploadParams) error
}

A Renter uploads, tracks, repairs, and downloads a set of files for the user.

type SiacoinOutputDiff added in v0.3.1 

type SiacoinOutputDiff struct {
	Direction     DiffDirection
	ID            types.SiacoinOutputID
	SiacoinOutput types.SiacoinOutput
}

A SiacoinOutputDiff indicates the addition or removal of a SiacoinOutput in the consensus set.

type SiafundOutputDiff added in v0.3.1 

type SiafundOutputDiff struct {
	Direction     DiffDirection
	ID            types.SiafundOutputID
	SiafundOutput types.SiafundOutput
}

A SiafundOutputDiff indicates the addition or removal of a SiafundOutput in the consensus set.

type SiafundPoolDiff added in v0.3.1 

type SiafundPoolDiff struct {
	Previous types.Currency
	Adjusted types.Currency
}

A SiafundPoolDiff contains the value of the siafundPool before the block was applied, and after the block was applied. When applying the diff, set siafundPool to 'Adjusted'. When reverting the diff, set siafundPool to 'Previous'.

type TransactionPool 

type TransactionPool interface {
	// AcceptTransaction takes a transaction, analyzes it, and either rejects
	// it or adds it to the transaction pool. Accepted transactions will be
	// relayed to connected peers.
	AcceptTransaction(types.Transaction) error

	// RelayTransaction is an RPC that accepts a block from a peer.
	RelayTransaction(PeerConn) error

	// IsStandardTransaction returns `err = nil` if the transaction is
	// standard, otherwise it returns an error explaining what is not standard.
	IsStandardTransaction(types.Transaction) error

	// PurgeTransactionPool is a termporary function available to the miner. In
	// the event that a miner mines an unacceptable block, the transaction pool
	// will be purged to clear out the transaction pool and get rid of the
	// illegal transaction. This should never happen, however there are bugs
	// that make this condition necessary.
	PurgeTransactionPool()

	// TransactionSet returns the set of unconfirmed transactions.
	TransactionSet() []types.Transaction

	// TransactionPoolNotify will push a struct down the channel any time that
	// the transaction pool updates. An update occurs any time there is a new
	// transaction or block introduced to the transaction pool.
	TransactionPoolNotify() <-chan struct{}

	// TransactionPoolSubscribe will subscribe the input object to the changes
	// in the transaction pool.
	TransactionPoolSubscribe(TransactionPoolSubscriber)
}

type TransactionPoolSubscriber added in v0.3.1 

type TransactionPoolSubscriber interface {
	// ReceiveTransactionPoolUpdate notifies subscribers of a change to the
	// consensus set and/or unconfirmed set.
	ReceiveTransactionPoolUpdate(cc ConsensusChange, unconfirmedTransactions []types.Transaction, unconfirmedSiacoinOutputDiffs []SiacoinOutputDiff)
}

A TransactionPoolSubscriber receives updates about the confirmed and unconfirmed set from the transaction pool. Generally, there is no need to subscribe to both the consensus set and the transaction pool.

type Wallet 

type Wallet interface {
	// Balance returns the total number of coins accessible to the wallet. If
	// full == true, the number of coins returned will also include coins that
	// have been spent in unconfirmed transactions.
	Balance(full bool) types.Currency

	// CoinAddress return an address into which coins can be paid. The bool
	// indicates whether the address should be visible to the user.
	CoinAddress(visible bool) (types.UnlockHash, types.UnlockConditions, error)

	// TimelockedCoinAddress returns an address that can only be spent after
	// block `unlockHeight`. The bool indicates whether the address should be
	// visible to the user.
	TimelockedCoinAddress(unlockHeight types.BlockHeight, visible bool) (types.UnlockHash, types.UnlockConditions, error)

	// RegisterTransaction creates a transaction out of an existing transaction
	// which can be modified by the wallet, returning an id that can be used to
	// reference the transaction.
	RegisterTransaction(types.Transaction) (id string, err error)

	// FundTransaction will add `amount` to a transaction's inputs. The funded
	// transaction is returned with an error.
	FundTransaction(id string, amount types.Currency) (types.Transaction, error)

	// AddSiacoinInput adds a siacoin input to the transaction. When
	// 'SignTransaction' gets called, this input will be left unsigned. The
	// updated transaction is returned along with the index of the new siacoin
	// input within the transaction.
	AddSiacoinInput(id string, input types.SiacoinInput) (types.Transaction, uint64, error)

	// AddMinerFee adds a single miner fee of value `fee`. The transaction is
	// returned, along with the index that the added fee ended up at.
	AddMinerFee(id string, fee types.Currency) (types.Transaction, uint64, error)

	// AddOutput adds an output to a transaction. It returns the transaction
	// with index of the output that got added.
	AddOutput(id string, output types.SiacoinOutput) (types.Transaction, uint64, error)

	// AddFileContract adds a file contract to a transaction, returning the
	// transaction and the index that the file contract was put at.
	AddFileContract(id string, fc types.FileContract) (types.Transaction, uint64, error)

	// AddStorageProof adds a storage proof to a transaction, returning the
	// transaction and the index that the storage proof was put at.
	AddStorageProof(id string, sp types.StorageProof) (types.Transaction, uint64, error)

	// AddArbitraryData adds a byte slice to the arbitrary data section of the
	// transaction, returning the transaction and the index of the new
	// arbitrary data.
	AddArbitraryData(id string, arb string) (types.Transaction, uint64, error)

	// AddSignature adds a signature to the transaction, the signature should
	// already be valid, and shouldn't sign any of the inputs that were added
	// by calling 'FundTransaction'. The updated transaction and the index of
	// the new signature are returned.
	AddSignature(id string, sig types.TransactionSignature) (types.Transaction, uint64, error)

	// Sign transaction will sign the transaction associated with the id and
	// then return the transaction. If wholeTransaction is set to true, then
	// the wholeTransaction flag will be set in CoveredFields for each
	// signature. After being signed, the transaction is deleted from the
	// wallet and must be reregistered if more changes are to be made.
	SignTransaction(id string, wholeTransaction bool) (types.Transaction, error)

	Info() WalletInfo

	SpendCoins(amount types.Currency, dest types.UnlockHash) (types.Transaction, error)

	// WalletNotify will push a struct down the channel any time that the
	// wallet updates.
	WalletNotify() <-chan struct{}

	// Close safely closes the wallet file.
	Close() error
}

Wallet in an interface that helps to build and sign transactions. The user can make a new transaction-in-progress by calling Register, and then can add outputs, fees, etc. This gives other modules full flexibility in creating dynamic transactions.

type WalletInfo 

type WalletInfo struct {
	Balance          types.Currency
	FullBalance      types.Currency
	VisibleAddresses []types.UnlockHash
	NumAddresses     int
}

WalletInfo contains basic information about the wallet.

Source Files

View all Source files

Directories

Path Synopsis
package hostdb provides a HostDB object that implements the modules.HostDB interface.
 package hostdb provides a HostDB object that implements the modules.HostDB interface.

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.