components

Documentation

Index

• Constants
• Variables
• type Host
• type HostAnnouncement
• type HostDB
• type HostEntry
• type HostInfo
• type HostUpdate
• type Miner
• type MinerInfo
• type MinerUpdate
• type RentFileParameters
• type RentInfo
• type RentSmallFileParameters
• type Renter
• type Wallet
• type WalletInfo

Constants

const (
	AcceptContractResponse = "accept"
)

const (
	HostAnnouncementPrefix = 1
)

Variables

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

Types

type Host

type Host interface {
	// Announce puts an annoucement out so that clients can find the host.
	AnnounceHost(freezeVolume consensus.Currency, freezeUnlockHeight consensus.BlockHeight) (consensus.Transaction, error)

	HostInfo() (HostInfo, error)

	// NegotiateContract is a strict function that enables a client to
	// communicate with the host to propose a contract.
	//
	// TODO: enhance this documentataion. For now, see the host package for a
	// reference implementation.
	NegotiateContract(conn net.Conn) error

	// RetrieveFile is a strict function that enables a client to download a
	// file from a host.
	RetrieveFile(conn net.Conn) error

	// Returns the number of contracts being managed by the host.
	//
	// TODO: Switch all of this to a status struct.
	NumContracts() int

	// UpdateHost changes the settings used by the host.
	UpdateHost(HostUpdate) error
}

type HostAnnouncement

type HostAnnouncement struct {
	IPAddress          network.Address
	TotalStorage       int64 // Can go negative.
	MinFilesize        uint64
	MaxFilesize        uint64
	MinDuration        consensus.BlockHeight
	MaxDuration        consensus.BlockHeight
	MinChallengeWindow consensus.BlockHeight
	MaxChallengeWindow consensus.BlockHeight
	MinTolerance       uint64
	Price              consensus.Currency
	Burn               consensus.Currency
	CoinAddress        consensus.CoinAddress // Host may want to give different addresses to each client.

	SpendConditions consensus.SpendConditions
	FreezeIndex     uint64 // The index of the output that froze coins.
}

A HostAnnouncement is a struct that can appear in the arbitrary data field. It is preceded by 8 bytes that decode to the integer 1.

type HostDB

type HostDB interface {
	// FlagHost alerts the HostDB that a host is not behaving as expected. The
	// HostDB may decide to remove the host, or just reduce the weight, or it
	// may decide to ignore the flagging. If the flagging is ignored, an error
	// will be returned explaining why.
	FlagHost(id string) error

	// Info returns an arbitrary byte slice presumably with information about
	// the status of the hostdb. Info is not relevant to the sia package, but
	// instead toa frontend.
	Info() ([]byte, error)

	// Insert puts a host entry into the host database.
	Insert(HostEntry) error

	// Remove pulls a host entry from the host database.
	Remove(id string) error

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

	// Size returns the number of active hosts in the hostdb.
	Size() int

	// Update gives the hostdb a set of blocks that have been applied and
	// reversed.
	Update(initialStateHeight consensus.BlockHeight, rewoundBlocks []consensus.Block, appliedBlocks []consensus.Block) error
}

type HostEntry

type HostEntry struct {
	ID          string
	IPAddress   network.Address
	MinFilesize uint64
	MaxFilesize uint64
	MinDuration consensus.BlockHeight
	MaxDuration consensus.BlockHeight
	Window      consensus.BlockHeight
	Tolerance   uint64
	Price       consensus.Currency
	Burn        consensus.Currency
	Freeze      consensus.Currency
	CoinAddress consensus.CoinAddress
}

the Host struct is kept in the client package because it's what the client uses to weigh hosts and pick them out when storing files.

type HostInfo

type HostInfo struct {
	Announcement HostAnnouncement

	StorageRemaining int
	ContractCount    int
}

type HostUpdate

type HostUpdate struct {
	Announcement    HostAnnouncement
	Height          consensus.BlockHeight
	HostDir         string
	TransactionChan chan consensus.Transaction

	Network network.TCPServer
	Wallet  Wallet

	InitialStateHeight consensus.BlockHeight
	RewoundBlocks      []consensus.Block
	AppliedBlocks      []consensus.Block
}

type Miner

type Miner interface {
	// Info returns an arbitrary byte slice presumably with information about
	// the status of the miner. Info is not relevant to the sia package, but
	// instead to the front end.
	Info() (MinerInfo, error)

	// Threads returns the number of threads being used by the miner.
	Threads() int

	// SubsidyAddress returns the address that is currently being used by the
	// miner while looking for a block.
	SubsidyAddress() consensus.CoinAddress

	// Update allows the state to change the block channel, the number of
	// threads, and the block mining information.
	//
	// If MinerUpdate.Threads == 0, the number of threads is kept the same.
	// There should be a cleaner way of doing this.
	UpdateMiner(MinerUpdate) error

	// StartMining will turn on the miner and begin consuming computational
	// cycles.
	StartMining() error

	// StopMining will turn of the miner and stop consuming computational
	// cycles.
	StopMining() error

	// SolveBlock will attempt to solve a block, returning the most recent
	// attempt and indicating whether the solve was successful or not.
	SolveBlock() (block consensus.Block, solved bool, err error)
}

The miner is used by the Core to facilitate the mining of blocks.

type MinerInfo

type MinerInfo struct {
	State          string
	Threads        int
	RunningThreads int
	Address        consensus.CoinAddress
}

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 MinerUpdate

type MinerUpdate struct {
	Parent            consensus.BlockID
	Transactions      []consensus.Transaction
	Target            consensus.Target
	Address           consensus.CoinAddress
	EarliestTimestamp consensus.Timestamp

	BlockChan chan consensus.Block
	Threads   int
}

MinerUpdate condenses the set of inputs to the Update() function into a single struct.

type RentFileParameters

type RentFileParameters struct {
	Filepath       string
	Nickname       string
	TotalPieces    int
	RequiredPieces int
	OptimalPieces  int
}

type RentInfo

type RentInfo struct {
	Files []string
}

type RentSmallFileParameters

type RentSmallFileParameters struct {
	FullFile       []byte
	Nickname       string
	TotalPieces    int
	RequiredPieces int
	OptimalPieces  int
}

type Renter

type Renter interface {
	Download(nickname, filepath string) error
	RentInfo() (RentInfo, error)
	RenameFile(currentName, newName string) error
	RentFile(RentFileParameters) error

	RentSmallFile(RentSmallFileParameters) error
}

type Wallet

type Wallet interface {
	// Info takes zero arguments and returns an arbitrary set of information
	// about the wallet in the form of json. The frontend will have to know how
	// to parse it, but Core and Daemon don't need to understand what's in the
	// json.
	WalletInfo() (WalletInfo, error)

	// Update takes two sets of blocks. The first is the set of blocks that
	// have been rewound since the previous call to update, and the second set
	// is the blocks that were applied after rewinding.
	Update([]consensus.OutputDiff) error

	// Reset will clear the list of spent transactions, which is nice if you've
	// accidentally made transactions that aren't spreading on the network for
	// whatever reason (for example, 0 fee transaction, or if there are bugs in
	// the software). Reset will also destroy all in-progress transactions.
	Reset() error

	// 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) consensus.Currency

	// CoinAddress return an address into which coins can be paid.
	CoinAddress() (consensus.CoinAddress, consensus.SpendConditions, error)

	// TimelockedCoinAddress returns an address that can only be spent after block `unlockHeight`.
	TimelockedCoinAddress(unlockHeight consensus.BlockHeight) (consensus.CoinAddress, consensus.SpendConditions, 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(consensus.Transaction) (id string, err error)

	// FundTransaction will add `amount` to a transaction's inputs.
	FundTransaction(id string, amount consensus.Currency) error

	// AddMinerFee adds a single miner fee of value `fee`.
	AddMinerFee(id string, fee consensus.Currency) error

	// AddOutput adds an output to a transaction.
	AddOutput(id string, output consensus.Output) error

	// AddTimelockedRefund will create an output with coins that are locked
	// until block `release`. The spend conditions are returned so that they
	// can be shown as proof that coins have been timelocked.
	//
	// It's a refund and not an output because currently the only way for a
	// wallet to know that it can spend a timelocked address is if the wallet
	// made the address itself.
	//
	// TODO: Eventually, there should be an extension that allows requests of
	// timelocked coin addresses.
	AddTimelockedRefund(id string, amount consensus.Currency, release consensus.BlockHeight) (sc consensus.SpendConditions, refundIndex uint64, err error)

	// AddFileContract adds a file contract to a transaction.
	AddFileContract(id string, fc consensus.FileContract) error

	// AddStorageProof adds a storage proof to a transaction.
	AddStorageProof(id string, sp consensus.StorageProof) error

	// AddArbitraryData adds a byte slice to the arbitrary data section of the
	// transaction.
	AddArbitraryData(id string, arb string) 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.
	//
	// Upon being signed and returned, the transaction-in-progress is deleted
	// from the wallet.
	SignTransaction(id string, wholeTransaction bool) (consensus.Transaction, 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.

TODO: CoinAddress returns spend conditions, add a TimelockedCoinAddress(). This will obsolete the AddTimelockedRefund() function.

type WalletInfo

type WalletInfo struct {
	Balance      consensus.Currency
	FullBalance  consensus.Currency
	NumAddresses int
}