Documentation ¶
Index ¶
- Constants
- Variables
- type Block
- func (b Block) CalculateSubsidy(height BlockHeight) Currency
- func (b Block) Header() BlockHeader
- func (b Block) ID() BlockID
- func (b Block) MarshalSia(w io.Writer) error
- func (b Block) MerkleRoot() crypto.Hash
- func (b Block) MinerPayoutID(i uint64) SiacoinOutputID
- func (b *Block) UnmarshalSia(r io.Reader) error
- type BlockHeader
- type BlockHeight
- type BlockID
- type BlockNonce
- type Clock
- type CoveredFields
- type Currency
- func CalculateCoinbase(height BlockHeight) Currency
- func CalculateNumSiacoins(height BlockHeight) Currency
- func NewCurrency(b *big.Int) (c Currency)
- func NewCurrency64(x uint64) (c Currency)
- func PostTax(height BlockHeight, payout Currency) Currency
- func Tax(height BlockHeight, payout Currency) Currency
- func (x Currency) Add(y Currency) (c Currency)
- func (c Currency) Big() *big.Int
- func (x Currency) Cmp(y Currency) int
- func (x Currency) Cmp64(y uint64) int
- func (x Currency) Div(y Currency) (c Currency)
- func (x Currency) Div64(y uint64) (c Currency)
- func (x Currency) Equals(y Currency) bool
- func (x Currency) Equals64(y uint64) bool
- func (c Currency) HumanString() string
- func (c Currency) IsZero() bool
- func (c Currency) MarshalJSON() ([]byte, error)
- func (c Currency) MarshalSia(w io.Writer) error
- func (c Currency) MarshalSiaSize() int
- func (x Currency) Mul(y Currency) (c Currency)
- func (x Currency) Mul64(y uint64) (c Currency)
- func (x Currency) MulFloat(y float64) (c Currency)
- func (x Currency) MulRat(y *big.Rat) (c Currency)
- func (x Currency) MulTax() (c Currency)
- func (x Currency) RoundDown(y Currency) (c Currency)
- func (c *Currency) Scan(s fmt.ScanState, ch rune) error
- func (x Currency) Sqrt() (c Currency)
- func (c Currency) String() string
- func (x Currency) Sub(y Currency) (c Currency)
- func (c Currency) Uint64() (u uint64, err error)
- func (c *Currency) UnmarshalJSON(b []byte) error
- func (c *Currency) UnmarshalSia(r io.Reader) error
- type FileContract
- type FileContractID
- type FileContractRevision
- type OutputID
- type ProofStatus
- type SiaPublicKey
- type SiacoinInput
- type SiacoinOutput
- type SiacoinOutputID
- type SiafundInput
- type SiafundOutput
- type SiafundOutputID
- type Specifier
- type StdClock
- type StorageProof
- type Target
- func (x Target) AddDifficulties(y Target) (t Target)
- func (x Target) Cmp(y Target) int
- func (t Target) Difficulty() Currency
- func (t Target) Int() *big.Int
- func (t Target) Inverse() *big.Rat
- func (x Target) MulDifficulty(y *big.Rat) (t Target)
- func (t Target) Rat() *big.Rat
- func (x Target) SubtractDifficulties(y Target) (t Target)
- type Timestamp
- type TimestampSlice
- type Transaction
- func (t Transaction) FileContractID(i uint64) FileContractID
- func (t Transaction) ID() TransactionID
- func (t Transaction) MarshalSia(w io.Writer) error
- func (t Transaction) MarshalSiaSize() (size int)
- func (t Transaction) SiacoinOutputID(i uint64) SiacoinOutputID
- func (t Transaction) SiacoinOutputSum() (sum Currency)
- func (t Transaction) SiafundOutputID(i uint64) SiafundOutputID
- func (t Transaction) SigHash(i int) (hash crypto.Hash)
- func (t Transaction) StandaloneValid(currentHeight BlockHeight) (err error)
- type TransactionID
- type TransactionSignature
- type UnlockConditions
- type UnlockHash
Constants ¶
const ( SpecifierLen = 16 // UnlockHashChecksumSize is the size of the checksum used to verify // human-readable addresses. It is not a crypytographically secure // checksum, it's merely intended to prevent typos. 6 is chosen because it // brings the total size of the address to 38 bytes, leaving 2 bytes for // potential version additions in the future. UnlockHashChecksumSize = 6 )
const ( // BlockHeaderSize is the size, in bytes, of a block header. // 32 (ParentID) + 8 (Nonce) + 8 (Timestamp) + 32 (MerkleRoot) BlockHeaderSize = 80 )
Variables ¶
var ( BlockSizeLimit = uint64(2e6) 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} BlockFrequency BlockHeight MaturityDelay BlockHeight GenesisTimestamp Timestamp RootTarget Target MedianTimestampWindow = uint64(11) TargetWindow BlockHeight MaxAdjustmentUp *big.Rat MaxAdjustmentDown *big.Rat FutureThreshold Timestamp ExtremeFutureThreshold Timestamp SiafundCount = NewCurrency64(10000) SiafundPortion = big.NewRat(39, 1000) SiacoinPrecision = NewCurrency(new(big.Int).Exp(big.NewInt(10), big.NewInt(24), nil)) InitialCoinbase = uint64(300e3) MinimumCoinbase uint64 GenesisSiafundAllocation []SiafundOutput GenesisBlock Block // The GenesisID is used in many places. Calculating it once saves lots of // redundant computation. GenesisID BlockID // Oak hardfork constants. Oak is the name of the difficulty algorithm for // Sia following a hardfork at block 135e3. OakHardforkBlock BlockHeight OakDecayNum int64 OakDecayDenom int64 OakMaxRise *big.Rat OakMaxDrop *big.Rat OakHardforkTxnSizeLimit = uint64(64e3) // 64 KB )
var ( // ZeroCurrency defines a currency of value zero. ZeroCurrency = NewCurrency64(0) // ErrNegativeCurrency is the error that is returned if performing an // operation results in a negative currency. ErrNegativeCurrency = errors.New("negative currency not allowed") // ErrUint64Overflow is the error that is returned if converting to a // unit64 would cause an overflow. ErrUint64Overflow = errors.New("cannot return the uint64 of this currency - result is an overflow") )
var ( // 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. SignatureEntropy = Specifier{'e', 'n', 't', 'r', 'o', 'p', 'y'} SignatureEd25519 = Specifier{'e', 'd', '2', '5', '5', '1', '9'} ErrEntropyKey = errors.New("transaction tries to sign an entproy public key") ErrFrivolousSignature = errors.New("transaction contains a frivolous signature") ErrInvalidPubKeyIndex = errors.New("transaction contains a signature that points to a nonexistent public key") ErrInvalidUnlockHashChecksum = errors.New("provided unlock hash has an invalid checksum") ErrMissingSignatures = errors.New("transaction has inputs with missing signatures") ErrPrematureSignature = errors.New("timelock on signature has not expired") ErrPublicKeyOveruse = errors.New("public key was used multiple times while signing transaction") ErrSortedUniqueViolation = errors.New("sorted unique violation") ErrUnlockHashWrongLen = errors.New("marshalled unlock hash is the wrong length") ErrWholeTransactionViolation = errors.New("covered fields violation") // FullCoveredFields is a covered fileds object where the // 'WholeTransaction' field has been set to true. The primary purpose of // this variable is syntactic sugar. FullCoveredFields = CoveredFields{WholeTransaction: true} )
var ( SpecifierMinerPayout = Specifier{'m', 'i', 'n', 'e', 'r', ' ', 'p', 'a', 'y', 'o', 'u', 't'} SpecifierSiacoinInput = Specifier{'s', 'i', 'a', 'c', 'o', 'i', 'n', ' ', 'i', 'n', 'p', 'u', 't'} 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'} SpecifierFileContractRevision = Specifier{'f', 'i', 'l', 'e', ' ', 'c', 'o', 'n', 't', 'r', 'a', 'c', 't', ' ', 'r', 'e'} SpecifierStorageProof = Specifier{'s', 't', 'o', 'r', 'a', 'g', 'e', ' ', 'p', 'r', 'o', 'o', 'f'} SpecifierStorageProofOutput = Specifier{'s', 't', 'o', 'r', 'a', 'g', 'e', ' ', 'p', 'r', 'o', 'o', 'f'} SpecifierSiafundInput = Specifier{'s', 'i', 'a', 'f', 'u', 'n', 'd', ' ', 'i', 'n', 'p', 'u', 't'} SpecifierSiafundOutput = Specifier{'s', 'i', 'a', 'f', 'u', 'n', 'd', ' ', 'o', 'u', 't', 'p', 'u', 't'} SpecifierClaimOutput = Specifier{'c', 'l', 'a', 'i', 'm', ' ', 'o', 'u', 't', 'p', 'u', 't'} SpecifierMinerFee = Specifier{'m', 'i', 'n', 'e', 'r', ' ', 'f', 'e', 'e'} ErrTransactionIDWrongLen = errors.New("input has wrong length to be an encoded transaction id") )
These Specifiers are used internally when calculating a type's ID. See Specifier for more details.
var ( ErrDoubleSpend = errors.New("transaction uses a parent object twice") ErrFileContractWindowEndViolation = errors.New("file contract window must end at least one block after it starts") ErrFileContractWindowStartViolation = errors.New("file contract window must start in the future") ErrFileContractOutputSumViolation = errors.New("file contract has invalid output sums") ErrNonZeroClaimStart = errors.New("transaction has a siafund output with a non-zero siafund claim") ErrNonZeroRevision = errors.New("new file contract has a nonzero revision number") ErrStorageProofWithOutputs = errors.New("transaction has both a storage proof and other outputs") ErrTimelockNotSatisfied = errors.New("timelock has not been met") ErrTransactionTooLarge = errors.New("transaction is too large to fit in a block") ErrZeroMinerFee = errors.New("transaction has a zero value miner fee") ErrZeroOutput = errors.New("transaction cannot have an output or payout that has zero value") ErrZeroRevision = errors.New("transaction has a file contract revision with RevisionNumber=0") )
var (
ErrNegativeTarget = errors.New("negative value used when converting to target")
)
Functions ¶
This section is empty.
Types ¶
type Block ¶
type Block struct { ParentID BlockID `json:"parentid"` Nonce BlockNonce `json:"nonce"` Timestamp Timestamp `json:"timestamp"` MinerPayouts []SiacoinOutput `json:"minerpayouts"` Transactions []Transaction `json:"transactions"` }
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 (Block) CalculateSubsidy ¶ added in v0.3.3
func (b Block) CalculateSubsidy(height BlockHeight) Currency
CalculateSubsidy takes a block and a height and determines the block subsidy.
func (Block) Header ¶ added in v0.3.3
func (b Block) Header() BlockHeader
Header returns the header of a block.
func (Block) ID ¶
ID returns the ID of a Block, which is calculated by hashing the concatenation of the block's parent's ID, nonce, and the result of the b.MerkleRoot(). It is equivalent to calling block.Header().ID()
func (Block) MarshalSia ¶ added in v1.0.0
MarshalSia implements the encoding.SiaMarshaler interface.
func (Block) MerkleRoot ¶
MerkleRoot calculates the Merkle root of a Block. The leaves of the Merkle tree are composed of the miner outputs (one leaf per payout), and the transactions (one leaf per transaction).
func (Block) MinerPayoutID ¶
func (b Block) MinerPayoutID(i uint64) 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 BlockHeader ¶ added in v0.3.3
type BlockHeader struct { ParentID BlockID `json:"parentid"` Nonce BlockNonce `json:"nonce"` Timestamp Timestamp `json:"timestamp"` MerkleRoot crypto.Hash `json:"merkleroot"` }
A BlockHeader, when encoded, is an 80-byte constant size field containing enough information to do headers-first block downloading. Hashing the header results in the block ID.
func (BlockHeader) ID ¶ added in v1.0.0
func (h BlockHeader) ID() BlockID
ID returns the ID of a Block, which is calculated by hashing the header.
type BlockHeight ¶
type BlockHeight uint64
type BlockID ¶
func (BlockID) MarshalJSON ¶ added in v1.0.0
MarshalJSON marshales a block id as a hex string.
func (*BlockID) UnmarshalJSON ¶ added in v1.0.0
UnmarshalJSON decodes the json hex string of the block id.
type BlockNonce ¶ added in v0.3.3
type BlockNonce [8]byte
type Clock ¶ added in v1.0.0
type Clock interface {
Now() Timestamp
}
Clock allows clients to retrieve the current time.
type CoveredFields ¶
type CoveredFields struct { WholeTransaction bool `json:"wholetransaction"` SiacoinInputs []uint64 `json:"siacoininputs"` SiacoinOutputs []uint64 `json:"siacoinoutputs"` FileContracts []uint64 `json:"filecontracts"` FileContractRevisions []uint64 `json:"filecontractrevisions"` StorageProofs []uint64 `json:"storageproofs"` SiafundInputs []uint64 `json:"siafundinputs"` SiafundOutputs []uint64 `json:"siafundoutputs"` MinerFees []uint64 `json:"minerfees"` ArbitraryData []uint64 `json:"arbitrarydata"` TransactionSignatures []uint64 `json:"transactionsignatures"` }
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).
func (CoveredFields) MarshalSia ¶ added in v1.2.0
func (cf CoveredFields) MarshalSia(w io.Writer) error
MarshalSia implements the encoding.SiaMarshaler interface.
func (CoveredFields) MarshalSiaSize ¶ added in v1.3.0
func (cf CoveredFields) MarshalSiaSize() (size int)
MarshalSiaSize returns the encoded size of cf.
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. Currency cannot be negative.
func CalculateCoinbase ¶
func CalculateCoinbase(height BlockHeight) Currency
CalculateCoinbase calculates the coinbase for a given height. The coinbase equation is:
coinbase := max(InitialCoinbase - height, MinimumCoinbase) * SiacoinPrecision
func CalculateNumSiacoins ¶ added in v1.0.0
func CalculateNumSiacoins(height BlockHeight) Currency
CalculateNumSiacoins calculates the number of siacoins in circulation at a given height.
func NewCurrency ¶
NewCurrency creates a Currency value from a big.Int. Undefined behavior occurs if a negative input is used.
func NewCurrency64 ¶
NewCurrency64 creates a Currency value from a uint64.
func PostTax ¶ added in v1.0.0
func PostTax(height BlockHeight, payout Currency) Currency
PostTax returns the amount of currency remaining in a file contract payout after tax.
func Tax ¶ added in v1.0.0
func Tax(height BlockHeight, payout Currency) Currency
Tax returns the amount of Currency that will be taxed from fc.
func (Currency) Big ¶
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.
func (Currency) Cmp ¶
Cmp compares two Currency values. The return value follows the convention of math/big.
func (Currency) Cmp64 ¶ added in v1.0.4
Cmp64 compares x to a uint64. The return value follows the convention of math/big.
func (Currency) HumanString ¶ added in v1.3.0
HumanString prints the Currency using human readable units. The unit used will be the largest unit that results in a value greater than 1. The value is rounded to 4 significant digits.
func (Currency) MarshalJSON ¶
MarshalJSON implements the json.Marshaler interface.
func (Currency) MarshalSia ¶
MarshalSia implements the encoding.SiaMarshaler interface. It writes the byte-slice representation of the Currency's internal big.Int to w. 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) MarshalSiaSize ¶ added in v1.3.0
MarshalSiaSize returns the encoded size of c.
func (Currency) MulFloat ¶
COMPATv0.4.0 - until the first 10e3 blocks have been archived, MulFloat is needed while verifying the first set of blocks.
MulFloat returns a new Currency value y = c * x, where x is a float64. Behavior is undefined when x is negative.
func (Currency) MulRat ¶ added in v1.0.0
MulRat returns a new Currency value c = x * y, where y is a big.Rat.
func (Currency) MulTax ¶ added in v1.0.0
MulTax returns a new Currency value c = x * 0.039, where 0.039 is a big.Rat.
func (*Currency) Scan ¶
Scan implements the fmt.Scanner interface, allowing Currency values to be scanned from text.
func (Currency) Sqrt ¶
Sqrt returns a new Currency value y = sqrt(c). Result is rounded down to the nearest integer.
func (Currency) Uint64 ¶ added in v1.0.0
Uint64 converts a Currency to a uint64. An error is returned because this function is sometimes called on values that can be determined by users - rather than have all user-facing points do input checking, the input checking should happen at the base type. This minimizes the chances of a rogue user causing a build.Critical to be triggered.
func (*Currency) UnmarshalJSON ¶
UnmarshalJSON implements the json.Unmarshaler interface. An error is returned if a negative number is provided.
type FileContract ¶
type FileContract struct { FileSize uint64 `json:"filesize"` FileMerkleRoot crypto.Hash `json:"filemerkleroot"` WindowStart BlockHeight `json:"windowstart"` WindowEnd BlockHeight `json:"windowend"` Payout Currency `json:"payout"` ValidProofOutputs []SiacoinOutput `json:"validproofoutputs"` MissedProofOutputs []SiacoinOutput `json:"missedproofoutputs"` UnlockHash UnlockHash `json:"unlockhash"` RevisionNumber uint64 `json:"revisionnumber"` }
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 'WindowStart' and 'WindowEnd'. Upon submitting the proof, the outputs for 'ValidProofOutputs' are created. If the party does not submit a storage proof by 'WindowEnd', 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) MarshalSia ¶ added in v1.3.0
func (fc FileContract) MarshalSia(w io.Writer) error
MarshalSia implements the encoding.SiaMarshaler interface.
func (FileContract) MarshalSiaSize ¶ added in v1.3.0
func (fc FileContract) MarshalSiaSize() (size int)
MarshalSiaSize returns the encoded size of fc.
type FileContractID ¶
func (FileContractID) MarshalJSON ¶ added in v1.0.0
func (fcid FileContractID) MarshalJSON() ([]byte, error)
MarshalJSON marshals an id as a hex string.
func (FileContractID) StorageProofOutputID ¶
func (fcid FileContractID) StorageProofOutputID(proofStatus ProofStatus, i uint64) 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.
func (FileContractID) String ¶ added in v1.0.0
func (fcid FileContractID) String() string
String prints the id in hex.
func (*FileContractID) UnmarshalJSON ¶ added in v1.0.0
func (fcid *FileContractID) UnmarshalJSON(b []byte) error
UnmarshalJSON decodes the json hex string of the id.
type FileContractRevision ¶
type FileContractRevision struct { ParentID FileContractID `json:"parentid"` UnlockConditions UnlockConditions `json:"unlockconditions"` NewRevisionNumber uint64 `json:"newrevisionnumber"` NewFileSize uint64 `json:"newfilesize"` NewFileMerkleRoot crypto.Hash `json:"newfilemerkleroot"` NewWindowStart BlockHeight `json:"newwindowstart"` NewWindowEnd BlockHeight `json:"newwindowend"` NewValidProofOutputs []SiacoinOutput `json:"newvalidproofoutputs"` NewMissedProofOutputs []SiacoinOutput `json:"newmissedproofoutputs"` NewUnlockHash UnlockHash `json:"newunlockhash"` }
A FileContractRevision revises an existing file contract. The ParentID points to the file contract that is being revised. The UnlockConditions are the conditions under which the revision is valid, and must match the UnlockHash of the parent file contract. The Payout of the file contract cannot be changed, but all other fields are allowed to be changed. The sum of the outputs must match the original payout (taking into account the fee for the proof payouts.) A revision number is included. When getting accepted, the revision number of the revision must be higher than any previously seen revision number for that file contract.
FileContractRevisions enable trust-free modifications to existing file contracts.
func (FileContractRevision) MarshalSia ¶ added in v1.3.0
func (fcr FileContractRevision) MarshalSia(w io.Writer) error
MarshalSia implements the encoding.SiaMarshaler interface.
func (FileContractRevision) MarshalSiaSize ¶ added in v1.3.0
func (fcr FileContractRevision) MarshalSiaSize() (size int)
MarshalSiaSize returns the encoded size of fcr.
type OutputID ¶ added in v1.0.0
func (OutputID) MarshalJSON ¶ added in v1.0.0
MarshalJSON marshals an id as a hex string.
func (*OutputID) UnmarshalJSON ¶ added in v1.0.0
UnmarshalJSON decodes the json hex string of the id.
type ProofStatus ¶ added in v0.3.3
type ProofStatus bool
var ( ProofValid ProofStatus = true ProofMissed ProofStatus = false )
type SiaPublicKey ¶
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.
func Ed25519PublicKey ¶ added in v1.2.0
func Ed25519PublicKey(pk crypto.PublicKey) SiaPublicKey
Ed25519PublicKey returns pk as a SiaPublicKey, denoting its algorithm as Ed25519.
func (*SiaPublicKey) LoadString ¶ added in v1.1.1
func (spk *SiaPublicKey) LoadString(s string)
LoadString is the inverse of SiaPublicKey.String().
func (SiaPublicKey) MarshalSia ¶ added in v1.2.0
func (spk SiaPublicKey) MarshalSia(w io.Writer) error
MarshalSia implements the encoding.SiaMarshaler interface.
func (*SiaPublicKey) String ¶ added in v1.0.3
func (spk *SiaPublicKey) String() string
String defines how to print a SiaPublicKey - hex is used to keep things compact during logging. The key type prefix and lack of a checksum help to separate it from a sia address.
type SiacoinInput ¶
type SiacoinInput struct { ParentID SiacoinOutputID `json:"parentid"` UnlockConditions UnlockConditions `json:"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.
func (SiacoinInput) MarshalSia ¶ added in v1.2.0
func (sci SiacoinInput) MarshalSia(w io.Writer) error
MarshalSia implements the encoding.SiaMarshaler interface.
type SiacoinOutput ¶
type SiacoinOutput struct { Value Currency `json:"value"` UnlockHash UnlockHash `json:"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.
func (SiacoinOutput) MarshalSia ¶ added in v1.2.0
func (sco SiacoinOutput) MarshalSia(w io.Writer) error
MarshalSia implements the encoding.SiaMarshaler interface.
type SiacoinOutputID ¶
func (SiacoinOutputID) MarshalJSON ¶ added in v1.0.0
func (scoid SiacoinOutputID) MarshalJSON() ([]byte, error)
MarshalJSON marshals an id as a hex string.
func (SiacoinOutputID) String ¶ added in v1.0.0
func (scoid SiacoinOutputID) String() string
String prints the id in hex.
func (*SiacoinOutputID) UnmarshalJSON ¶ added in v1.0.0
func (scoid *SiacoinOutputID) UnmarshalJSON(b []byte) error
UnmarshalJSON decodes the json hex string of the id.
type SiafundInput ¶
type SiafundInput struct { ParentID SiafundOutputID `json:"parentid"` UnlockConditions UnlockConditions `json:"unlockconditions"` ClaimUnlockHash UnlockHash `json:"claimunlockhash"` }
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.
func (SiafundInput) MarshalSia ¶ added in v1.2.0
func (sfi SiafundInput) MarshalSia(w io.Writer) error
MarshalSia implements the encoding.SiaMarshaler interface.
type SiafundOutput ¶
type SiafundOutput struct { Value Currency `json:"value"` UnlockHash UnlockHash `json:"unlockhash"` ClaimStart Currency `json:"claimstart"` }
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.
func (SiafundOutput) MarshalSia ¶ added in v1.2.0
func (sfo SiafundOutput) MarshalSia(w io.Writer) error
MarshalSia implements the encoding.SiaMarshaler interface.
type SiafundOutputID ¶
func (SiafundOutputID) MarshalJSON ¶ added in v1.0.0
func (sfoid SiafundOutputID) MarshalJSON() ([]byte, error)
MarshalJSON marshals an id as a hex string.
func (SiafundOutputID) SiaClaimOutputID ¶
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.
func (SiafundOutputID) String ¶ added in v1.0.0
func (sfoid SiafundOutputID) String() string
String prints the id in hex.
func (*SiafundOutputID) UnmarshalJSON ¶ added in v1.0.0
func (sfoid *SiafundOutputID) UnmarshalJSON(b []byte) error
UnmarshalJSON decodes the json hex string of the id.
type Specifier ¶
type Specifier [SpecifierLen]byte
A Specifier is a fixed-length byte-array 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.
func (Specifier) MarshalJSON ¶ added in v1.0.0
MarshalJSON marshals a specifier as a string.
func (Specifier) String ¶ added in v1.0.0
String returns the specifier as a string, trimming any trailing zeros.
func (*Specifier) UnmarshalJSON ¶ added in v1.0.0
UnmarshalJSON decodes the json string of the specifier.
type StdClock ¶ added in v1.0.0
type StdClock struct{}
StdClock is an implementation of Clock that retrieves the current time using the system time.
type StorageProof ¶
type StorageProof struct { ParentID FileContractID `json:"parentid"` Segment [crypto.SegmentSize]byte `json:"segment"` HashSet []crypto.Hash `json:"hashset"` }
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 'WindowStart' - 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.
func (*StorageProof) MarshalSia ¶ added in v1.3.0
func (sp *StorageProof) MarshalSia(w io.Writer) error
MarshalSia implements the encoding.SiaMarshaler interface.
type Target ¶
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 ¶
IntToTarget converts a big.Int to a Target. Negative inputs trigger a panic.
func RatToTarget ¶
RatToTarget converts a big.Rat to a Target.
func (Target) AddDifficulties ¶ added in v0.3.3
AddDifficulties returns the resulting target with the difficulty of 'x' and 'y' are added together. Note that the difficulty is the inverse of the target. The sum is defined by:
sum(x, y) = 1/(1/x + 1/y)
func (Target) Cmp ¶
Cmp compares the difficulties of two targets. Note that the difficulty is the inverse of the target. The results are as follows:
-1 if x < y 0 if x == y +1 if x > y
func (Target) Difficulty ¶ added in v1.0.0
Difficulty returns the difficulty associated with a given target.
func (Target) MulDifficulty ¶ added in v0.3.3
Mul multiplies the difficulty of a target by y. The product is defined by:
y / x
func (Target) SubtractDifficulties ¶ added in v1.0.0
SubtractDifficulties returns the resulting target with the difficulty of 'x' is subtracted from the target with difficulty 'y'. Note that the difficulty is the inverse of the target. The difference is defined by:
sum(x, y) = 1/(1/x - 1/y)
type Timestamp ¶
type Timestamp uint64
func CurrentTimestamp ¶
func CurrentTimestamp() Timestamp
CurrentTimestamp returns the current time as a Timestamp.
type TimestampSlice ¶
type TimestampSlice []Timestamp
func (TimestampSlice) Less ¶
func (ts TimestampSlice) Less(i, j int) bool
Less is part of sort.Interface
type Transaction ¶
type Transaction struct { SiacoinInputs []SiacoinInput `json:"siacoininputs"` SiacoinOutputs []SiacoinOutput `json:"siacoinoutputs"` FileContracts []FileContract `json:"filecontracts"` FileContractRevisions []FileContractRevision `json:"filecontractrevisions"` StorageProofs []StorageProof `json:"storageproofs"` SiafundInputs []SiafundInput `json:"siafundinputs"` SiafundOutputs []SiafundOutput `json:"siafundoutputs"` MinerFees []Currency `json:"minerfees"` ArbitraryData [][]byte `json:"arbitrarydata"` TransactionSignatures []TransactionSignature `json:"transactionsignatures"` }
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 uint64) 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) ID ¶
func (t Transaction) ID() TransactionID
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) MarshalSia ¶ added in v1.2.0
func (t Transaction) MarshalSia(w io.Writer) error
MarshalSia implements the encoding.SiaMarshaler interface.
func (Transaction) MarshalSiaSize ¶ added in v1.3.0
func (t Transaction) MarshalSiaSize() (size int)
MarshalSiaSize returns the encoded size of t.
func (Transaction) SiacoinOutputID ¶
func (t Transaction) SiacoinOutputID(i uint64) 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 ¶
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 ¶
func (t Transaction) SiafundOutputID(i uint64) 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) (hash crypto.Hash)
SigHash returns the hash of the fields in a transaction covered by a given signature. See CoveredFields for more details.
func (Transaction) StandaloneValid ¶
func (t Transaction) StandaloneValid(currentHeight BlockHeight) (err error)
StandaloneValid returns an error if a transaction is not valid in any context, for example if the same output is spent twice in the same transaction. StandaloneValid will not check that all outputs being spent are legal outputs, as it has no confirmed or unconfirmed set to look at.
type TransactionID ¶ added in v1.0.0
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.
func (TransactionID) MarshalJSON ¶ added in v1.0.0
func (tid TransactionID) MarshalJSON() ([]byte, error)
MarshalJSON marshals an id as a hex string.
func (TransactionID) String ¶ added in v1.0.0
func (tid TransactionID) String() string
String prints the id in hex.
func (*TransactionID) UnmarshalJSON ¶ added in v1.0.0
func (tid *TransactionID) UnmarshalJSON(b []byte) error
UnmarshalJSON decodes the json hex string of the id.
type TransactionSignature ¶
type TransactionSignature struct { ParentID crypto.Hash `json:"parentid"` PublicKeyIndex uint64 `json:"publickeyindex"` Timelock BlockHeight `json:"timelock"` CoveredFields CoveredFields `json:"coveredfields"` Signature []byte `json:"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.
func (TransactionSignature) MarshalSia ¶ added in v1.2.0
func (ts TransactionSignature) MarshalSia(w io.Writer) error
MarshalSia implements the encoding.SiaMarshaler interface.
type UnlockConditions ¶
type UnlockConditions struct { Timelock BlockHeight `json:"timelock"` PublicKeys []SiaPublicKey `json:"publickeys"` SignaturesRequired uint64 `json:"signaturesrequired"` }
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 'SignaturesRequired' unique keys must sign the transaction. The keys that do not need to use the same cryptographic algorithm.
If 'SignaturesRequired' == 0, the UnlockConditions are effectively "anyone can unlock." If 'SignaturesRequired' > len('PublicKeys'), then the UnlockConditions cannot be fulfilled under any circumstances.
func (UnlockConditions) MarshalSia ¶ added in v1.2.0
func (uc UnlockConditions) MarshalSia(w io.Writer) error
MarshalSia implements the encoding.SiaMarshaler interface.
func (UnlockConditions) MarshalSiaSize ¶ added in v1.3.0
func (uc UnlockConditions) MarshalSiaSize() (size int)
MarshalSiaSize returns the encoded size of uc.
func (UnlockConditions) UnlockHash ¶
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 SignaturesRequired are both low entropy fields; they can be protected by having random public keys next to them.
type UnlockHash ¶
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 UnlockConditions.UnlockHash for details on how the UnlockHash is constructed.
func (*UnlockHash) LoadString ¶ added in v1.0.0
func (uh *UnlockHash) LoadString(strUH string) error
LoadString loads a hex representation (including checksum) of an unlock hash into an unlock hash object. An error is returned if the string is invalid or fails the checksum.
func (UnlockHash) MarshalJSON ¶ added in v0.3.2
func (uh UnlockHash) MarshalJSON() ([]byte, error)
MarshalJSON is implemented on the unlock hash to always produce a hex string upon marshalling.
func (UnlockHash) String ¶ added in v1.0.0
func (uh UnlockHash) String() string
String returns the hex representation of the unlock hash as a string - this includes a checksum.
func (*UnlockHash) UnmarshalJSON ¶ added in v0.3.2
func (uh *UnlockHash) UnmarshalJSON(b []byte) error
UnmarshalJSON is implemented on the unlock hash to recover an unlock hash that has been encoded to a hex string.