modules

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
}

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
}

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

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

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

type DiffDirection bool

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
}

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

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
}

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

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
}

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 struct {
	IPAddress NetAddress
}

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
}

type HostInfo struct {
	HostSettings

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

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
}

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
}

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

type NetAddress string

type PeerConn interface {
	net.Conn
}

type RPCFunc func(PeerConn) error

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

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
}

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

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

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

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 interface {
	// ReceiveTransactionPoolUpdate notifies subscribers of a change to the
	// consensus set and/or unconfirmed set.
	ReceiveTransactionPoolUpdate(cc ConsensusChange, unconfirmedTransactions []types.Transaction, unconfirmedSiacoinOutputDiffs []SiacoinOutputDiff)
}

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
}

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