consensus

package
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Mar 17, 2015 License: MIT Imports: 12 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	DEBUG = true // This is a temporary setting, will stay during beta.

	BlockSizeLimit        = 1e6         // Blocks cannot be more than 1MB.
	BlockFrequency        = 600         // In seconds.
	TargetWindow          = 1e3         // Number of blocks to use when calculating the target.
	MedianTimestampWindow = 11          // Number of blocks that get considered when determining if a timestamp is valid - should be an odd number.
	FutureThreshold       = 3 * 60 * 60 // Seconds into the future block timestamps are valid.
	SiafundCount          = 10e3        // The total (static) number of siafunds.
	MaturityDelay         = 50          // The number of blocks that need to be waited before certain types of outputs come to maturity.
	SiafundPortion        = 0.039       // Percent of all contract payouts that go to the siafund pool.

	InitialCoinbase = 300e3
	MinimumCoinbase = 30e3

	RenterZeroConfDelay = 60e9 // 1 minute
)

Variables

View Source 
var (
	ErrBadBlock        = errors.New("block is known to be invalid")
	ErrBlockKnown      = errors.New("block exists in block map")
	ErrEarlyTimestamp  = errors.New("block timestamp is too early")
	ErrFutureTimestamp = errors.New("block timestamp too far in future")
	ErrOrphan          = errors.New("block has no known parent")
	ErrLargeBlock      = errors.New("block is too large to be accepted")
	ErrMinerPayout     = errors.New("miner payout sum does not equal block subsidy")
	ErrMissedTarget    = errors.New("block does not meet target")
)
View Source 
var (
	RootTarget = Target{0, 0, 0, 64}
	RootDepth  = Target{255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255}

	MaxAdjustmentUp   = big.NewRat(1001, 1000)
	MaxAdjustmentDown = big.NewRat(999, 1000)

	CoinbaseAugment = new(big.Int).Exp(big.NewInt(10), big.NewInt(24), nil)

	GenesisTimestamp         = Timestamp(1426537000) // Approx. 4:16pm EST Mar. 16th, 2015
	GenesisSiafundUnlockHash = ZeroUnlockHash
	GenesisClaimUnlockHash   = ZeroUnlockHash
)
View Source 
var (
	ZeroUnlockHash = UnlockHash{0}
	ZeroCurrency   = NewCurrency64(0)
)

The ZeroUnlockHash and ZeroCurrency are convenience variables.

View Source 
var (
	SpecifierSiacoinOutput                 = Specifier{'s', 'i', 'a', 'c', 'o', 'i', 'n', ' ', 'o', 'u', 't', 'p', 'u', 't'}
	SpecifierFileContract                  = Specifier{'f', 'i', 'l', 'e', ' ', 'c', 'o', 'n', 't', 'r', 'a', 'c', 't'}
	SpecifierFileContractTerminationPayout = Specifier{'f', 'i', 'l', 'e', ' ', 'c', 'o', 'n', 't', 'r', 'a', 'c', 't', ' ', 't'}
	SpecifierStorageProofOutput            = Specifier{'s', 't', 'o', 'r', 'a', 'g', 'e', ' ', 'p', 'r', 'o', 'o', 'f'}
	SpecifierSiafundOutput                 = Specifier{'s', 'i', 'a', 'f', 'u', 'n', 'd', ' ', 'o', 'u', 't', 'p', 'u', 't'}
)

These Specifiers are used internally when calculating a type's ID. See Specifier for more details.

View Source 
var (
	SignatureEntropy = Specifier{'e', 'n', 't', 'r', 'o', 'p', 'y'}
	SignatureEd25519 = Specifier{'e', 'd', '2', '5', '5', '1', '9'}
)

These Specifiers enumerate the types of signatures that are recognized by this implementation. If a signature's type is unrecognized, the signature is treated as valid. Signatures using the special "entropy" type are always treated as invalid; see Consensus.md for more details.

View Source 
var (
	ErrMissingSiacoinOutput = errors.New("transaction spends a nonexisting siacoin output")
	ErrMissingFileContract  = errors.New("transaction terminates a nonexisting file contract")
	ErrMissingSiafundOutput = errors.New("transaction spends a nonexisting siafund output")
)
View Source 
var (
	ErrMissingSignatures = errors.New("transaction has inputs with missing signatures")
)
View Source 
var SurpassThreshold = big.NewRat(20, 100)

SurpassThreshold is a percentage that dictates how much heavier a competing chain has to be before the node will switch to mining on that chain. This is not a consensus rule. This percentage is only applied to the most recent block, not the entire chain; see blockNode.heavierThan.

If no threshold were in place, it would be possible to manipulate a block's timestamp to produce a sufficiently heavier block.

Functions

This section is empty.

Types

type Block 

type Block struct {
	ParentID     BlockID
	Nonce        uint64
	Timestamp    Timestamp
	MinerPayouts []SiacoinOutput
	Transactions []Transaction
}

A Block is a summary of changes to the state that have occurred since the previous block. Blocks reference the ID of the previous block (their "parent"), creating the linked-list commonly known as the blockchain. Their primary function is to bundle together transactions on the network. Blocks are created by "miners," who collect transactions from other nodes, and then try to pick a Nonce that results in a block whose BlockID is below a given Target.

func MineTestingBlock added in v0.3.0 

func MineTestingBlock(parent BlockID, timestamp Timestamp, minerPayouts []SiacoinOutput, txns []Transaction, target Target) (b Block)

MineTestingBlock accepts a bunch of parameters for a block and then grinds blocks until a block with the appropriate target is found.

func (Block) CheckTarget 

func (b Block) CheckTarget(target Target) bool

CheckTarget returns true if the block's ID meets the given target.

func (Block) ID 

func (b Block) ID() BlockID

ID returns the ID of a Block, which is calculated by hashing the concatenation of the block's parent ID, nonce, and Merkle root.

func (Block) MerkleRoot 

func (b Block) MerkleRoot() crypto.Hash

MerkleRoot calculates the Merkle root of a Block. The leaves of the Merkle tree are composed of the Timestamp, the miner outputs (one leaf per payout), and the transactions (one leaf per transaction).

func (Block) MinerPayoutID added in v0.3.0 

func (b Block) MinerPayoutID(i int) SiacoinOutputID

MinerPayoutID returns the ID of the miner payout at the given index, which is calculated by hashing the concatenation of the BlockID and the payout index.

type BlockHeight 

type BlockHeight uint64

type BlockID 

type BlockID crypto.Hash

IDs are used to refer to a type without revealing its contents. They are constructed by hashing specific fields of the type, along with a Specifier. While all of these types are hashes, defining type aliases gives us type safety and makes the code more readable.

type ConsensusTester added in v0.3.0 

type ConsensusTester struct {
	*State
	*testing.T

	UnlockConditions UnlockConditions
	UnlockHash       UnlockHash
	SecretKey        crypto.SecretKey
	// contains filtered or unexported fields
}

A ConsensusTester holds a state and a testing object as well as some minimal and simplistic features for performing actions such as mining and building transactions.

func NewConsensusTester added in v0.3.0 

func NewConsensusTester(t *testing.T, s *State) (ct *ConsensusTester)

NewConsensusTester returns an assistant that's ready to help with testing.

func NewTestingEnvironment added in v0.3.0 

func NewTestingEnvironment(t *testing.T) (ct *ConsensusTester)

NewTestingEnvironment creates a state and an assistant that wraps around the state, then mines enough blocks that the assistant has outputs ready to spend.

func (*ConsensusTester) AddSiacoinInputToTransaction added in v0.3.0 

func (ct *ConsensusTester) AddSiacoinInputToTransaction(inputT Transaction, sci SiacoinInput) (t Transaction)

AddSiacoinInputToTransaction takes a transaction and adds an input that the assistant knows how to spend, returning the transaction and the value of the input that got added.

func (*ConsensusTester) ConsistencyChecks added in v0.3.0 

func (ct *ConsensusTester) ConsistencyChecks()

consistencyChecks calls all of the consistency functions on each of the states.

func (*ConsensusTester) CurrencyCheck added in v0.3.0 

func (ct *ConsensusTester) CurrencyCheck()

currencyCheck uses the height to determine the total amount of currency that should be in the system, and then tallys up the outputs to see if that is the case.

func (*ConsensusTester) CurrentPathCheck added in v0.3.0 

func (ct *ConsensusTester) CurrentPathCheck()

CurrentPathCheck looks at every block listed in currentPath and verifies that every block from current to genesis matches the block listed in currentPath.

func (*ConsensusTester) FileContractTransaction added in v0.3.0 

func (ct *ConsensusTester) FileContractTransaction(start BlockHeight, expiration BlockHeight) (txn Transaction, file []byte)

FileContractTransaction creates and funds a transaction that has a file contract, and returns that transaction.

func (*ConsensusTester) FindSpendableSiacoinInput added in v0.3.0 

func (ct *ConsensusTester) FindSpendableSiacoinInput() (sci SiacoinInput, value Currency)

FindSpendableSiacoinInput returns a SiacoinInput that the ConsensusTester is able to spend, as well as the value of the input. There is no guarantee on the value, it could be anything.

func (*ConsensusTester) MineAndApplyValidBlock added in v0.3.0 

func (ct *ConsensusTester) MineAndApplyValidBlock() (block Block)

MineAndApplyValidBlock mines a block and sets a handful of payouts to addresses that the assistant can spend, which will give the assistant a good volume of outputs to draw on for testing.

func (*ConsensusTester) MineAndSubmitCurrentBlock added in v0.3.0 

func (ct *ConsensusTester) MineAndSubmitCurrentBlock(txns []Transaction)

MineAndSubmitCurrentBlock is a shortcut function that calls MineCurrentBlock and then submits it to the state.

func (*ConsensusTester) MineCurrentBlock added in v0.3.0 

func (ct *ConsensusTester) MineCurrentBlock(txns []Transaction) (b Block)

MineCurrentBlock is a shortcut function that calls MineTestingBlock using variables that satisfy the current state.

func (*ConsensusTester) Payouts added in v0.3.0 

func (ct *ConsensusTester) Payouts(height BlockHeight, txns []Transaction) (payouts []SiacoinOutput)

Payouts returns a block with 12 payouts worth 1e6 and a final payout that makes the total payout amount add up correctly. This produces a large set of outputs that can be used for testing.

func (*ConsensusTester) RewindABlock added in v0.3.0 

func (ct *ConsensusTester) RewindABlock()

RewindABlock removes the most recent block from the consensus set.

func (*ConsensusTester) RewindApplyCheck added in v0.3.0 

func (ct *ConsensusTester) RewindApplyCheck()

rewindApplyCheck grabs the state hash and then rewinds to the genesis block. Then the state moves forwards to the initial starting place and verifies that the state hash is the same.

func (*ConsensusTester) SiacoinOutputTransaction added in v0.3.0 

func (ct *ConsensusTester) SiacoinOutputTransaction() (txn Transaction)

SiacoinOutputTransaction creates and funds a transaction that has a siacoin output, and returns that transaction.

type CoveredFields 

type CoveredFields struct {
	WholeTransaction         bool
	SiacoinInputs            []uint64
	SiacoinOutputs           []uint64
	FileContracts            []uint64
	FileContractTerminations []uint64
	StorageProofs            []uint64
	SiafundInputs            []uint64
	SiafundOutputs           []uint64
	MinerFees                []uint64
	ArbitraryData            []uint64
	Signatures               []uint64
}

CoveredFields indicates which fields in a transaction have been covered by the signature. (Note that the signature does not sign the fields themselves, but rather their combined hash; see SigHash.) Each slice corresponds to a slice in the Transaction type, indicating which indices of the slice have been signed. The indices must be valid, i.e. within the bounds of the slice. In addition, they must be sorted and unique.

As a convenience, a signature of the entire transaction can be indicated by the 'WholeTransaction' field. If 'WholeTransaction' == true, all other fields must be empty (except for the Signatures field, since a signature cannot sign itself).

type Currency 

type Currency struct {
	// contains filtered or unexported fields
}

A Currency represents a number of siacoins or siafunds. Internally, a Currency value is unbounded; however, Currency values sent over the wire protocol are subject to a maximum size of 255 bytes (approximately 10^614). Unlike the math/big library, whose methods modify their receiver, all arithmetic Currency methods return a new value. This is necessary to preserve the immutability of types containing Currency fields.

func CalculateCoinbase 

func CalculateCoinbase(height BlockHeight) (c Currency)

CalculateCoinbase calculates the coinbase for a given height. The coinbase equation is: 

coinbase := max(InitialCoinbase - height, MinimumCoinbase) * CoinbaseAugment

func NewCurrency added in v0.3.0 

func NewCurrency(b *big.Int) (c Currency)

NewCurrency creates a Currency value from a big.Int.

func NewCurrency64 added in v0.3.0 

func NewCurrency64(x uint64) (c Currency)

NewCurrency64 creates a Currency value from a uint64.

func (Currency) Add added in v0.3.0 

func (c Currency) Add(x Currency) (y Currency)

Add returns a new Currency value y = c + x.

func (Currency) Big added in v0.3.0 

func (c Currency) Big() *big.Int

Big returns the value of c as a *big.Int. Importantly, it does not provide access to the c's internal big.Int object, only a copy. This is in accordance with the immutability constraint described above.

func (Currency) Cmp added in v0.3.0 

func (c Currency) Cmp(y Currency) int

Cmp compares two Currency values. The return value follows the convention of the math/big package.

func (Currency) Div added in v0.3.0 

func (c Currency) Div(x Currency) (y Currency)

Div returns a new Currency value y = c / x.

func (Currency) MarshalJSON added in v0.3.0 

func (c Currency) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (Currency) MarshalSia added in v0.3.0 

func (c Currency) MarshalSia() []byte

MarshalSia implements the encoding.SiaMarshaler interface. It returns the byte-slice representation of the Currency's internal big.Int, prepended with a single byte indicating the length of the slice. This implies a maximum encodable value of 2^(255 * 8), or approximately 10^614.

Note that as the bytes of the big.Int correspond to the absolute value of the integer, there is no way to marshal a negative Currency.

func (Currency) Mul added in v0.3.0 

func (c Currency) Mul(x Currency) (y Currency)

Mul returns a new Currency value y = c * x.

func (Currency) MulFloat added in v0.3.0 

func (c Currency) MulFloat(x float64) (y Currency)

MulFloat returns a new Currency value y = c * x, where x is a float64.

func (Currency) RoundDown added in v0.3.0 

func (c Currency) RoundDown(n uint64) (y Currency)

RoundDown returns the largest multiple of n <= c.

func (*Currency) Scan added in v0.3.0 

func (c *Currency) Scan(s fmt.ScanState, ch rune) error

Scan implements the fmt.Scanner interface, allowing Currency values to be scanned from text.

func (Currency) Sign added in v0.3.0 

func (c Currency) Sign() int

Sign returns the sign of a Currency. The return value follows of the convention of the math/big package.

func (Currency) Sqrt added in v0.3.0 

func (c Currency) Sqrt() (y Currency)

Sqrt returns a new Currency value y = sqrt(c)

func (Currency) String added in v0.3.0 

func (c Currency) String() string

String implements the fmt.Stringer interface.

func (Currency) Sub added in v0.3.0 

func (c Currency) Sub(x Currency) (y Currency)

Sub returns a new Currency value y = c - x.

func (*Currency) UnmarshalJSON added in v0.3.0 

func (c *Currency) UnmarshalJSON(b []byte) error

UnmarshalJSON implements the json.Unmarshaler interface.

func (*Currency) UnmarshalSia added in v0.3.0 

func (c *Currency) UnmarshalSia(b []byte) int

UnmarshalSia implements the encoding.SiaUnmarshaler interface. See MarshalSia for a description of how Currency values are marshalled.

type DiffDirection added in v0.3.0 

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 FileContract 

type FileContract struct {
	FileSize           uint64
	FileMerkleRoot     crypto.Hash
	Start              BlockHeight
	Expiration         BlockHeight
	Payout             Currency
	ValidProofOutputs  []SiacoinOutput
	MissedProofOutputs []SiacoinOutput
	TerminationHash    UnlockHash
}

A FileContract is a public record of a storage agreement between a "host" and a "renter." It mandates that a host must submit a storage proof to the network, proving that they still possess the file they have agreed to store.

The party must submit the storage proof in a block that is between 'Start' and 'Expiration'. Upon submitting the proof, the outputs for 'ValidProofOutputs' are created. If the party does not submit a storage proof by 'Expiration', then the outputs for 'MissedProofOutputs' are created instead. The sum of 'MissedProofOutputs' must equal 'Payout', and the sum of 'ValidProofOutputs' must equal 'Payout' plus the siafund fee. This fee is sent to the siafund pool, which is a set of siacoins only spendable by siafund owners.

Under normal circumstances, the payout will be funded by both the host and the renter, which gives the host incentive not to lose the file. The 'ValidProofUnlockHash' will typically be spendable by host, and the 'MissedProofUnlockHash' will either by spendable by the renter or by nobody (the ZeroUnlockHash).

A contract can be terminated early by submitting a FileContractTermination whose UnlockConditions hash to 'TerminationHash'.

func (FileContract) Tax added in v0.3.0 

func (fc FileContract) Tax() Currency

Tax returns the amount of Currency that will be taxed from fc.

type FileContractDiff added in v0.3.0 

type FileContractDiff struct {
	Direction    DiffDirection
	ID           FileContractID
	FileContract FileContract
}

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

type FileContractID added in v0.3.0 

type FileContractID crypto.Hash

func (FileContractID) FileContractTerminationPayoutID added in v0.3.0 

func (fcid FileContractID) FileContractTerminationPayoutID(i int) SiacoinOutputID

FileContractTerminationPayoutID returns the ID of a file contract termination payout, given the index of the payout in the termination. The ID is calculated by hashing the concatenation of the FileContractTerminationPayout Specifier, the ID of the file contract being terminated, and the payout index.

func (FileContractID) StorageProofOutputID added in v0.3.0 

func (fcid FileContractID) StorageProofOutputID(proofValid bool, i int) SiacoinOutputID

StorageProofOutputID returns the ID of an output created by a file contract, given the status of the storage proof. The ID is calculating by hashing the concatenation of the StorageProofOutput Specifier, the ID of the file contract that the proof is for, a boolean indicating whether the proof was valid (true) or missed (false), and the index of the output within the file contract.

type FileContractTermination added in v0.3.0 

type FileContractTermination struct {
	ParentID              FileContractID
	TerminationConditions UnlockConditions
	Payouts               []SiacoinOutput
}

A FileContractTermination terminates a file contract. The ParentID specifies the contract being terminated, and the TerminationConditions are the conditions under which termination will be treated as valid. The hash of the TerminationConditions must match the TerminationHash in the contract. 'Payouts' is a set of SiacoinOutputs describing how the payout of the contract is redistributed. It follows that the sum of these outputs must equal the original payout. The outputs can have any Value and UnlockHash, and do not need to match the ValidProofUnlockHash or MissedProofUnlockHash of the original FileContract.

type SiaPublicKey added in v0.3.0 

type SiaPublicKey struct {
	Algorithm Specifier
	Key       string
}

A SiaPublicKey is a public key prefixed by a Specifier. The Specifier indicates the algorithm used for signing and verification. Unrecognized algorithms will always verify, which allows new algorithms to be added to the protocol via a soft-fork.

type SiacoinInput added in v0.3.0 

type SiacoinInput struct {
	ParentID         SiacoinOutputID
	UnlockConditions UnlockConditions
}

A SiacoinInput consumes a SiacoinOutput and adds the siacoins to the set of siacoins that can be spent in the transaction. The ParentID points to the output that is getting consumed, and the UnlockConditions contain the rules for spending the output. The UnlockConditions must match the UnlockHash of the output.

type SiacoinOutput added in v0.3.0 

type SiacoinOutput struct {
	Value      Currency
	UnlockHash UnlockHash
}

A SiacoinOutput holds a volume of siacoins. Outputs must be spent atomically; that is, they must all be spent in the same transaction. The UnlockHash is the hash of the UnlockConditions that must be fulfilled in order to spend the output.

type SiacoinOutputDiff added in v0.3.0 

type SiacoinOutputDiff struct {
	Direction     DiffDirection
	ID            SiacoinOutputID
	SiacoinOutput SiacoinOutput
}

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

type SiacoinOutputID added in v0.3.0 

type SiacoinOutputID crypto.Hash

type Siafund added in v0.3.0 

type Siafund Currency // arbitrary-precision unsigned integer

type SiafundInput added in v0.3.0 

type SiafundInput struct {
	ParentID         SiafundOutputID
	UnlockConditions UnlockConditions
}

A SiafundInput consumes a SiafundOutput and adds the siafunds to the set of siafunds that can be spent in the transaction. The ParentID points to the output that is getting consumed, and the UnlockConditions contain the rules for spending the output. The UnlockConditions must match the UnlockHash of the output.

type SiafundOutput added in v0.3.0 

type SiafundOutput struct {
	Value           Currency
	UnlockHash      UnlockHash
	ClaimUnlockHash UnlockHash
	ClaimStart      Currency
}

A SiafundOutput holds a volume of siafunds. Outputs must be spent atomically; that is, they must all be spent in the same transaction. The UnlockHash is the hash of a set of UnlockConditions that must be fulfilled in order to spend the output.

When the SiafundOutput is spent, a SiacoinOutput is created, where: 

SiacoinOutput.Value := (SiafundPool - ClaimStart) / 10,000
SiacoinOutput.UnlockHash := SiafundOutput.ClaimUnlockHash

When a SiafundOutput is put into a transaction, the ClaimStart must always equal zero. While the transaction is being processed, the ClaimStart is set to the value of the SiafundPool.

type SiafundOutputDiff added in v0.3.0 

type SiafundOutputDiff struct {
	Direction     DiffDirection
	ID            SiafundOutputID
	SiafundOutput SiafundOutput
}

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

type SiafundOutputID added in v0.3.0 

type SiafundOutputID crypto.Hash

func (SiafundOutputID) SiaClaimOutputID added in v0.3.0 

func (id SiafundOutputID) SiaClaimOutputID() SiacoinOutputID

SiaClaimOutputID returns the ID of the SiacoinOutput that is created when the siafund output is spent. The ID is the hash the SiafundOutputID.

type SiafundPoolDiff added in v0.3.0 

type SiafundPoolDiff struct {
	Previous Currency
	Adjusted 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 Signature added in v0.3.0 

type Signature string

The Signature type is arbitrary-length to enable a variety of signature algorithms.

type Specifier added in v0.3.0 

type Specifier [16]byte

A Specifier is a fixed-length string that serves two purposes. In the wire protocol, they are used to identify a particular encoding algorithm, signature algorithm, etc. This allows nodes to communicate on their own terms; for example, to reduce bandwidth costs, a node might only accept compressed messages.

Internally, Specifiers are used to guarantee unique IDs. Various consensus types have an associated ID, calculated by hashing the data contained in the type. By prepending the data with Specifier, we can guarantee that distinct types will never produce the same hash.

type State 

type State struct {
	// contains filtered or unexported fields
}

The State is the object responsible for tracking the current status of the blockchain. Broadly speaking, it is responsible for maintaining consensus. It accepts blocks and constructs a blockchain, forking when necessary.

func CreateGenesisState 

func CreateGenesisState() (s *State)

CreateGenesisState returns a State containing only the genesis block.

func (*State) AcceptBlock 

func (s *State) AcceptBlock(b Block) (err error)

AcceptBlock will add blocks to the state, forking the blockchain if they are on a fork that is heavier than the current fork.

func (*State) Block added in v0.3.0 

func (s *State) Block(id BlockID) (b Block, exists bool)

Block returns the block associated with the given id.

func (*State) BlockAtHeight 

func (s *State) BlockAtHeight(height BlockHeight) (b Block, exists bool)

BlockAtHeight returns the block on the current path with the given height.

func (*State) BlockOutputDiffs added in v0.3.0 

func (s *State) BlockOutputDiffs(id BlockID) (scods []SiacoinOutputDiff, err error)

BlockOutputDiffs returns the SiacoinOutputDiffs for a given block.

func (*State) BlockRange added in v0.3.0 

func (s *State) BlockRange(start, stop BlockHeight) ([]Block, error)

BlockRange returns a slice of the blocks that fall within the given range [start, stop].

func (*State) BlocksSince added in v0.3.0 

func (s *State) BlocksSince(id BlockID) (removedBlocks, addedBlocks []BlockID, err error)

BlocksSince returns a set of output diffs representing how the state has changed since block 'id'. OutputDiffsSince will flip the `new` value for diffs that got reversed.

func (*State) CurrentBlock 

func (s *State) CurrentBlock() Block

CurrentBlock returns the highest block on the tallest fork.

func (*State) CurrentTarget 

func (s *State) CurrentTarget() Target

CurrentTarget returns the target of the next block that needs to be submitted to the state.

func (*State) EarliestTimestamp added in v0.3.0 

func (s *State) EarliestTimestamp() Timestamp

EarliestTimestamp returns the earliest timestamp that the next block can have in order for it to be considered valid.

func (*State) FileContract added in v0.3.0 

func (s *State) FileContract(id FileContractID) (fc FileContract, exists bool)

FileContract returns the file contract associated with the 'id'. If the contract does not exist, exists will be false.

func (*State) Height 

func (s *State) Height() BlockHeight

Height returns the height of the current blockchain (the longest fork).

func (*State) HeightOfBlock 

func (s *State) HeightOfBlock(bid BlockID) (height BlockHeight, exists bool)

HeightOfBlock returns the height of the block with the given ID.

func (*State) RLock added in v0.3.0 

func (s *State) RLock() int

RLock will readlock the state.

func (*State) RUnlock added in v0.3.0 

func (s *State) RUnlock(counter int)

RUnlock will readunlock the state.

func (*State) SiacoinOutput added in v0.3.0 

func (s *State) SiacoinOutput(id SiacoinOutputID) (output SiacoinOutput, exists bool)

SiacoinOutput returns the siacoin output associated with the given ID.

func (*State) SiafundOutput added in v0.3.0 

func (s *State) SiafundOutput(id SiafundOutputID) (output SiafundOutput, exists bool)

SiafundOutput returns the siafund output associated with the given ID.

func (*State) SortedUtxoSet 

func (s *State) SortedUtxoSet() []SiacoinOutput

SortedUtxoSet returns all of the unspent transaction outputs sorted according to the numerical value of their id.

func (*State) StateHash 

func (s *State) StateHash() crypto.Hash

StateHash returns the markle root of the current state of consensus.

func (*State) StorageProofSegment added in v0.3.0 

func (s *State) StorageProofSegment(fcid FileContractID) (index uint64, err error)

StorageProofSegment returns the segment to be used in the storage proof for a given file contract.

func (*State) SubscribeToConsensusChanges added in v0.3.0 

func (s *State) SubscribeToConsensusChanges() <-chan struct{}

SubscribeToConsensusChanges returns a channel that will be sent an empty struct every time the consensus set changes.

func (*State) ValidTransaction 

func (s *State) ValidTransaction(t Transaction) (err error)

ValidTransaction checks that a transaction is valid within the context of the current consensus set.

func (*State) ValidTransactionComponents added in v0.3.0 

func (s *State) ValidTransactionComponents(t Transaction) (err error)

ValidTransactionComponents checks that a transaction follows basic rules, such as the storage proof rules, and it checks that all of the signatures are valid, but it does not check that all of the inputs, storage proofs, and terminations act on existing outputs and contracts. This function is primarily for the transaction pool, which has access to unconfirmed transactions. ValidTransactionComponents will not return an error simply because there are missing inputs. ValidTransactionComponents will return an error if the state height is not sufficient to fulfill all of the requirements of the transaction.

func (*State) ValidUnlockConditions added in v0.3.0 

func (s *State) ValidUnlockConditions(uc UnlockConditions, uh UnlockHash) (err error)

ValidUnlockConditions checks that the conditions of uc have been met.

type StateInfo added in v0.3.0 

type StateInfo struct {
	CurrentBlock BlockID
	Height       BlockHeight
	Target       Target
}

StateInfo contains basic information about the State.

type StorageProof 

type StorageProof struct {
	ParentID FileContractID
	Segment  [crypto.SegmentSize]byte
	HashSet  []crypto.Hash
}

A StorageProof fulfills a FileContract. The proof contains a specific segment of the file, along with a set of hashes from the file's Merkle tree. In combination, these can be used to prove that the segment came from the file. To prevent abuse, the segment must be chosen randomly, so the ID of block 'Start' - 1 is used as a seed value; see StorageProofSegment for the exact implementation.

A transaction with a StorageProof cannot have any SiacoinOutputs, SiafundOutputs, or FileContracts. This is because a mundane reorg can invalidate the proof, and with it the rest of the transaction.

type Target 

type Target crypto.Hash

A Target is a hash that a block's ID must be "less than" in order for the block to be considered valid. Miners vary the block's 'Nonce' field in order to brute-force such an ID. The inverse of a Target is called the "difficulty," because it is proportional to the amount of time required to brute-force the Target.

func IntToTarget 

func IntToTarget(i *big.Int) (t Target)

IntToTarget converts a big.Int to a Target.

func RatToTarget 

func RatToTarget(r *big.Rat) Target

RatToTarget converts a big.Rat to a Target.

func (Target) Int 

func (t Target) Int() *big.Int

Int converts a Target to a big.Int.

func (Target) Inverse 

func (t Target) Inverse() *big.Rat

Inverse returns the inverse of a Target as a big.Rat

func (Target) Rat 

func (t Target) Rat() *big.Rat

Rat converts a Target to a big.Rat.

type Timestamp 

type Timestamp uint64

func CurrentTimestamp added in v0.3.0 

func CurrentTimestamp() Timestamp

CurrentTimestamp returns the current time as a Timestamp.

type Transaction 

type Transaction struct {
	SiacoinInputs            []SiacoinInput
	SiacoinOutputs           []SiacoinOutput
	FileContracts            []FileContract
	FileContractTerminations []FileContractTermination
	StorageProofs            []StorageProof
	SiafundInputs            []SiafundInput
	SiafundOutputs           []SiafundOutput
	MinerFees                []Currency
	ArbitraryData            []string
	Signatures               []TransactionSignature
}

A Transaction is an atomic component of a block. Transactions can contain inputs and outputs, file contracts, storage proofs, and even arbitrary data. They can also contain signatures to prove that a given party has approved the transaction, or at least a particular subset of it.

Transactions can depend on other previous transactions in the same block, but transactions cannot spend outputs that they create or otherwise be self-dependent.

func (Transaction) FileContractID 

func (t Transaction) FileContractID(i int) FileContractID

FileContractID returns the ID of a file contract at the given index, which is calculated by hashing the concatenation of the FileContract Specifier, all of the fields in the transaction (except the signatures), and the contract index.

func (Transaction) FollowsStorageProofRules added in v0.3.0 

func (t Transaction) FollowsStorageProofRules() error

FollowsStorageProofRules checks that a transaction follows the limitations placed on transactions that have storage proofs.

func (Transaction) ID added in v0.3.0 

func (t Transaction) ID() crypto.Hash

ID returns the id of a transaction, which is taken by marshalling all of the fields except for the signatures and taking the hash of the result.

func (Transaction) SiacoinOutputID added in v0.3.0 

func (t Transaction) SiacoinOutputID(i int) SiacoinOutputID

SiacoinOutputID returns the ID of a siacoin output at the given index, which is calculated by hashing the concatenation of the SiacoinOutput Specifier, all of the fields in the transaction (except the signatures), and output index.

func (Transaction) SiacoinOutputSum added in v0.3.0 

func (t Transaction) SiacoinOutputSum() (sum Currency)

SiacoinOutputSum returns the sum of all the siacoin outputs in the transaction, which must match the sum of all the siacoin inputs. Siacoin outputs created by storage proofs and siafund outputs are not considered, as they were considered when the contract responsible for funding them was created.

func (Transaction) SiafundOutputID added in v0.3.0 

func (t Transaction) SiafundOutputID(i int) SiafundOutputID

SiafundOutputID returns the ID of a SiafundOutput at the given index, which is calculated by hashing the concatenation of the SiafundOutput Specifier, all of the fields in the transaction (except the signatures), and output index.

func (Transaction) SigHash 

func (t Transaction) SigHash(i int) crypto.Hash

SigHash returns the hash of the fields in a transaction covered by a given signature. See CoveredFields for more details.

type TransactionSignature 

type TransactionSignature struct {
	ParentID       crypto.Hash
	PublicKeyIndex uint64
	Timelock       BlockHeight
	CoveredFields  CoveredFields
	Signature      Signature
}

A TransactionSignature is a signature that is included in the transaction. The signature should correspond to a public key in one of the UnlockConditions of the transaction. This key is specified first by 'ParentID', which specifies the UnlockConditions, and then 'PublicKeyIndex', which indicates the key in the UnlockConditions. There are three types that use UnlockConditions: SiacoinInputs, SiafundInputs, and FileContractTerminations. Each of these types also references a ParentID, and this is the hash that 'ParentID' must match. The 'Timelock' prevents the signature from being used until a certain height. 'CoveredFields' indicates which parts of the transaction are being signed; see CoveredFields.

type UnlockConditions added in v0.3.0 

type UnlockConditions struct {
	Timelock      BlockHeight
	PublicKeys    []SiaPublicKey
	NumSignatures uint64
}

UnlockConditions are a set of conditions which must be met to execute certain actions, such as spending a SiacoinOutput or terminating a FileContract.

The simplest requirement is that the block containing the UnlockConditions must have a height >= 'Timelock'.

'PublicKeys' specifies the set of keys that can be used to satisfy the UnlockConditions; of these, at least 'NumSignatures' unique keys must sign the transaction. The keys that do not need to use the same cryptographic algorithm.

If 'NumSignatures' == 0, the UnlockConditions are effectively "anyone can unlock." If 'NumSignatures' > len('PublicKeys'), then the UnlockConditions cannot be fulfilled under any circumstances.

func (UnlockConditions) UnlockHash added in v0.3.0 

func (uc UnlockConditions) UnlockHash() UnlockHash

UnlockHash calculates the root hash of a Merkle tree of the UnlockConditions object. The leaves of this tree are formed by taking the hash of the timelock, the hash of the public keys (one leaf each), and the hash of the number of signatures. The keys are put in the middle because Timelock and NumSignatures are both low entropy fields; they can be protected by having random public keys next to them.

type UnlockHash added in v0.3.0 

type UnlockHash crypto.Hash

An UnlockHash is a specially constructed hash of the UnlockConditions type. "Locked" values can be unlocked by providing the UnlockConditions that hash to a given UnlockHash. See SpendConditions.UnlockHash for details on how the UnlockHash is constructed.

Source Files

View all Source files

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.