modules

Documentation

Index

• Constants
• Variables
• type ConsensusSet
• type ConsensusSetSubscriber
• type ContractTerms
• type DiffDirection
• type DownloadInfo
• type FileContractDiff
• type FileInfo
• type FileUploadParams
• type Gateway
• type Host
• type HostAnnouncement
• type HostDB
• type HostInfo
• type HostSettings
• type Miner
• type MinerInfo
• type NetAddress
  • func (na NetAddress) Host() string
  • func (na NetAddress) Port() string
• type PeerConn
• type RPCFunc
• type RentInfo
• type Renter
• type SiacoinOutputDiff
• type SiafundOutputDiff
• type SiafundPoolDiff
• type TransactionPool
• type TransactionPoolSubscriber
• type Wallet
• type WalletInfo

Constants

const (
	AcceptTermsResponse = "accept"
	HostDir             = "host"
)

const (
	ConsensusDir = "consensus"
)

const (
	GatewayDir = "gateway"
)

const (
	NotifyBuffer = 3
)

const (
	// Denotes a host announcement in the Arbitrary Data section.
	PrefixHostAnnouncement = "HostAnnouncement"
)

const (
	WalletDir = "wallet"
)

Variables

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

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

var (
	// ErrTransactionPoolDuplicate is returned when a duplicate transaction is
	// submitted to the transaction pool.
	ErrTransactionPoolDuplicate = errors.New("transaction is a duplicate")
)

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.

var (
	LowBalanceErr = errors.New("Insufficient Balance")
)

var (
	RenterDir = "renter"
)

var (
	SafeMutexDelay time.Duration
)

Types

type ConsensusSet

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)

	// 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
}

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

type ConsensusSetSubscriber

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(revertedBlocks []types.Block, appliedBlocks []types.Block)
}

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 DiffDirection

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 (
	DiffApply  DiffDirection = true
	DiffRevert DiffDirection = false
)

type DownloadInfo

type DownloadInfo interface {
	// 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

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

	// 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

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

	// RandomHost pulls a host entry at random from the database, weighted
	// according to whatever score is assigned the hosts.
	RandomHost() (HostSettings, error)

	// 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
}

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

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() (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(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

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

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
}

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

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

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

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

type TransactionPoolSubscriber interface {
	// ReceiveTransactionPoolUpdate notifies subscribers of a change to the
	// consensus set and/or unconfirmed set.
	ReceiveTransactionPoolUpdate(revertedBlocks, appliedBlocks []types.Block, 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.