contracts

package
v1.1.2 Latest Latest
Warning

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

Go to latest
Published: Jul 11, 2024 License: MIT Imports: 21 Imported by: 1

Documentation

Index

Constants

View Source
const (
	ActionBroadcastFormation     = "formation"
	ActionReject                 = "reject"
	ActionBroadcastFinalRevision = "revision"
	ActionBroadcastResolution    = "resolve"
	ActionExpire                 = "expire"
)

An action determines what lifecycle event should be performed on a contract.

View Source
const (
	// RebroadcastBuffer is the number of blocks after the negotiation height to
	// attempt to rebroadcast the contract.
	RebroadcastBuffer = 36 // 6 hours
	// RevisionSubmissionBuffer number of blocks before the proof window to
	// submit a revision and prevent modification of the contract.
	RevisionSubmissionBuffer = 144 // 24 hours
)
View Source
const (
	ContractSortStatus            = "status"
	ContractSortNegotiationHeight = "negotiationHeight"
	ContractSortExpirationHeight  = "expirationHeight"
)

fields that the contracts can be sorted by.

Variables

View Source
var (
	// ErrNotFound is returned by the contract store when a contract is not
	// found.
	ErrNotFound = errors.New("contract not found")
	// ErrContractExists is returned by the contract store during formation when
	// the contract already exists.
	ErrContractExists = errors.New("contract already exists")
)

Functions

This section is empty.

Types

type Alerts

type Alerts interface {
	Register(alerts.Alert)
	Dismiss(...types.Hash256)
}

Alerts registers and dismisses global alerts.

type ChainManager

type ChainManager interface {
	TipState() consensus.State
	IndexAtHeight(height uint64) (types.ChainIndex, error)
	Subscribe(s modules.ConsensusSetSubscriber, ccID modules.ConsensusChangeID, cancel <-chan struct{}) error
}

ChainManager defines the interface required by the contract manager to interact with the consensus set.

type Contract

type Contract struct {
	SignedRevision

	Status           ContractStatus `json:"status"`
	LockedCollateral types.Currency `json:"lockedCollateral"`
	Usage            Usage          `json:"usage"`

	// NegotiationHeight is the height the contract was negotiated at.
	NegotiationHeight uint64 `json:"negotiationHeight"`
	// FormationConfirmed is true if the contract formation transaction
	// has been confirmed on the blockchain.
	FormationConfirmed bool `json:"formationConfirmed"`
	// RevisionConfirmed is true if the contract revision transaction has
	// been confirmed on the blockchain.
	RevisionConfirmed bool `json:"revisionConfirmed"`
	// ResolutionHeight is the height the storage proof was confirmed
	// at. If the contract has not been resolved, the field is the zero
	// value.
	ResolutionHeight uint64 `json:"resolutionHeight"`
	// RenewedTo is the ID of the contract that renewed this contract. If
	// this contract was not renewed, this field is the zero value.
	RenewedTo types.FileContractID `json:"renewedTo"`
	// RenewedFrom is the ID of the contract that this contract renewed. If
	// this contract is not a renewal, the field is the zero value.
	RenewedFrom types.FileContractID `json:"renewedFrom"`
}

A Contract contains metadata on the current state of a file contract.

type ContractFilter

type ContractFilter struct {
	// filters
	Statuses    []ContractStatus       `json:"statuses"`
	ContractIDs []types.FileContractID `json:"contractIDs"`
	RenewedFrom []types.FileContractID `json:"renewedFrom"`
	RenewedTo   []types.FileContractID `json:"renewedTo"`
	RenterKey   []types.PublicKey      `json:"renterKey"`

	MinNegotiationHeight uint64 `json:"minNegotiationHeight"`
	MaxNegotiationHeight uint64 `json:"maxNegotiationHeight"`

	MinExpirationHeight uint64 `json:"minExpirationHeight"`
	MaxExpirationHeight uint64 `json:"maxExpirationHeight"`

	// pagination
	Limit  int `json:"limit"`
	Offset int `json:"offset"`

	// sorting
	SortField string `json:"sortField"`
	SortDesc  bool   `json:"sortDesc"`
}

ContractFilter defines the filter criteria for a contract query.

type ContractManager

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

A ContractManager manages contracts' lifecycle

func NewManager

func NewManager(store ContractStore, alerts Alerts, storage StorageManager, c ChainManager, tpool TransactionPool, wallet Wallet, log *zap.Logger) (*ContractManager, error)

NewManager creates a new contract manager.

func (*ContractManager) AddContract

func (cm *ContractManager) AddContract(revision SignedRevision, formationSet []types.Transaction, lockedCollateral types.Currency, initialUsage Usage) error

AddContract stores the provided contract, should error if the contract already exists.

func (*ContractManager) CheckIntegrity

func (cm *ContractManager) CheckIntegrity(ctx context.Context, contractID types.FileContractID) (<-chan IntegrityResult, uint64, error)

CheckIntegrity checks the integrity of a contract's sector roots on disk. The result of every checked sector is sent on the returned channel. The channel is closed when all checks are complete.

func (*ContractManager) Close

func (cm *ContractManager) Close() error

Close closes the contract manager.

func (*ContractManager) Contract

func (cm *ContractManager) Contract(id types.FileContractID) (Contract, error)

Contract returns the contract with the given id.

func (*ContractManager) Contracts

func (cm *ContractManager) Contracts(filter ContractFilter) ([]Contract, int, error)

Contracts returns a paginated list of contracts matching the filter and the total number of contracts matching the filter.

func (*ContractManager) Lock

Lock locks a contract for modification.

func (*ContractManager) ProcessConsensusChange

func (cm *ContractManager) ProcessConsensusChange(cc modules.ConsensusChange)

ProcessConsensusChange applies a block update to the contract manager.

func (*ContractManager) RenewContract

func (cm *ContractManager) RenewContract(renewal SignedRevision, existing SignedRevision, formationSet []types.Transaction, lockedCollateral types.Currency, clearingUsage, initialUsage Usage) error

RenewContract renews a contract. It is expected that the existing contract will be cleared.

func (*ContractManager) ReviseContract

func (cm *ContractManager) ReviseContract(contractID types.FileContractID) (*ContractUpdater, error)

ReviseContract initializes a new contract updater for the given contract.

func (*ContractManager) ScanHeight added in v1.0.0

func (cm *ContractManager) ScanHeight() uint64

ScanHeight returns the height of the last block processed by the contract

func (*ContractManager) SectorRoots

func (cm *ContractManager) SectorRoots(id types.FileContractID) ([]types.Hash256, error)

SectorRoots returns the roots of all sectors stored by the contract.

func (*ContractManager) Unlock

func (cm *ContractManager) Unlock(id types.FileContractID)

Unlock unlocks a locked contract.

type ContractStatus

type ContractStatus uint8

ContractStatus is an enum that indicates the current status of a contract.

const (
	// ContractStatusPending indicates that the contract has been formed but
	// has not yet been confirmed on the blockchain. The contract is still
	// usable, but there is a risk that the contract will never be confirmed.
	ContractStatusPending ContractStatus = iota
	// ContractStatusRejected indicates that the contract formation transaction
	// was never confirmed on the blockchain
	ContractStatusRejected
	// ContractStatusActive indicates that the contract has been confirmed on
	// the blockchain and is currently active.
	ContractStatusActive
	// ContractStatusSuccessful indicates that a storage proof has been
	// confirmed or the contract expired without requiring the host to burn
	// Siacoin (e.g. renewal, unused contracts).
	ContractStatusSuccessful
	// ContractStatusFailed indicates that the contract ended without a storage proof
	// and the host was required to burn Siacoin.
	ContractStatusFailed
)

ContractStatus is an enum that indicates the current status of a contract.

func (ContractStatus) MarshalJSON

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

MarshalJSON implements the json.Marshaler interface.

func (ContractStatus) String

func (c ContractStatus) String() string

String returns the string representation of a ContractStatus.

func (*ContractStatus) UnmarshalJSON

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

UnmarshalJSON implements the json.Unmarshaler interface.

type ContractStore

type ContractStore interface {
	LastContractChange() (id modules.ConsensusChangeID, err error)
	// Contracts returns a paginated list of contracts sorted by expiration
	// asc.
	Contracts(ContractFilter) ([]Contract, int, error)
	// Contract returns the contract with the given ID.
	Contract(types.FileContractID) (Contract, error)
	// ContractFormationSet returns the formation transaction set for the
	// contract with the given ID.
	ContractFormationSet(types.FileContractID) ([]types.Transaction, error)
	// ExpireContract is used to mark a contract as complete. It should only
	// be used on active or pending contracts.
	ExpireContract(types.FileContractID, ContractStatus) error
	// Add stores the provided contract, should error if the contract
	// already exists in the store.
	AddContract(revision SignedRevision, formationSet []types.Transaction, lockedCollateral types.Currency, initialUsage Usage, negotationHeight uint64) error
	// RenewContract renews a contract. It is expected that the existing
	// contract will be cleared.
	RenewContract(renewal SignedRevision, existing SignedRevision, formationSet []types.Transaction, lockedCollateral types.Currency, clearingUsage, initialUsage Usage, negotationHeight uint64) error
	// SectorRoots returns the sector roots for a contract. If limit is 0, all roots
	// are returned.
	SectorRoots(id types.FileContractID) ([]types.Hash256, error)
	// ContractAction calls contractFn on every contract in the store that
	// needs a lifecycle action performed.
	ContractAction(height uint64, contractFn func(types.FileContractID, uint64, string)) error
	// ReviseContract atomically updates a contract and its associated
	// sector roots.
	ReviseContract(revision SignedRevision, oldRoots []types.Hash256, usage Usage, sectorChanges []SectorChange) error
	// UpdateContractState atomically updates the contract manager's state.
	UpdateContractState(modules.ConsensusChangeID, uint64, func(UpdateStateTransaction) error) error
	// ExpireContractSectors removes sector roots for any contracts that are
	// past their proof window.
	ExpireContractSectors(height uint64) error
}

A ContractStore stores contracts for the host. It also updates stored contracts and determines which contracts need lifecycle actions.

type ContractUpdater

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

A ContractUpdater is used to atomically update a contract's sectors and metadata.

func (*ContractUpdater) AppendSector

func (cu *ContractUpdater) AppendSector(root types.Hash256)

AppendSector appends a sector to the contract.

func (*ContractUpdater) Close

func (cu *ContractUpdater) Close() error

Close must be called when the contract updater is no longer needed.

func (*ContractUpdater) Commit

func (cu *ContractUpdater) Commit(revision SignedRevision, usage Usage) error

Commit atomically applies all changes to the contract store.

func (*ContractUpdater) MerkleRoot

func (cu *ContractUpdater) MerkleRoot() types.Hash256

MerkleRoot returns the merkle root of the contract's sector roots.

func (*ContractUpdater) SectorCount

func (cu *ContractUpdater) SectorCount() uint64

SectorCount returns the number of sectors in the contract.

func (*ContractUpdater) SectorRoot

func (cu *ContractUpdater) SectorRoot(i uint64) (types.Hash256, error)

SectorRoot returns the Merkle root of the sector at the given index.

func (*ContractUpdater) SectorRoots

func (cu *ContractUpdater) SectorRoots() []types.Hash256

SectorRoots returns a copy of the current state of the contract's sector roots.

func (*ContractUpdater) SwapSectors

func (cu *ContractUpdater) SwapSectors(a, b uint64) error

SwapSectors swaps the sectors at the given indices.

func (*ContractUpdater) TrimSectors

func (cu *ContractUpdater) TrimSectors(n uint64) error

TrimSectors removes the last n sectors from the contract.

func (*ContractUpdater) UpdateSector

func (cu *ContractUpdater) UpdateSector(root types.Hash256, i uint64) error

UpdateSector updates the Merkle root of the sector at the given index.

type IntegrityResult

type IntegrityResult struct {
	ExpectedRoot types.Hash256 `json:"expectedRoot"`
	ActualRoot   types.Hash256 `json:"actualRoot"`
	Error        error         `json:"error"`
}

An IntegrityResult contains the result of an integrity check for a contract sector.

func (IntegrityResult) MarshalJSON

func (i IntegrityResult) MarshalJSON() ([]byte, error)

MarshalJSON implements a custom json.Marshaler to handle the error interface.

func (*IntegrityResult) UnmarshalJSON

func (i *IntegrityResult) UnmarshalJSON(b []byte) error

UnmarshalJSON implements a custom json.Unmarshaler to handle the error interface.

type SectorAction

type SectorAction string

A SectorAction denotes the type of action to be performed on a contract sector.

const (
	SectorActionAppend SectorAction = "append"
	SectorActionUpdate SectorAction = "update"
	SectorActionSwap   SectorAction = "swap"
	SectorActionTrim   SectorAction = "trim"
)

A SectorAction denotes the type of action to be performed on a contract sector.

type SectorChange

type SectorChange struct {
	Action SectorAction
	Root   types.Hash256
	A, B   uint64
}

A SectorChange defines an action to be performed on a contract's sectors.

type SignedRevision

type SignedRevision struct {
	Revision types.FileContractRevision `json:"revision"`

	HostSignature   types.Signature `json:"hostSignature"`
	RenterSignature types.Signature `json:"renterSignature"`
}

A SignedRevision pairs a contract revision with the signatures of the host and renter needed to broadcast the revision.

func (SignedRevision) RenterKey

func (sr SignedRevision) RenterKey() types.PublicKey

RenterKey returns the renter's public key.

func (SignedRevision) Signatures

func (sr SignedRevision) Signatures() []types.TransactionSignature

Signatures returns the host and renter transaction signatures for the contract revision.

type StorageManager

type StorageManager interface {
	// Read reads a sector from the store
	Read(root types.Hash256) (*[rhp2.SectorSize]byte, error)
}

A StorageManager stores and retrieves sectors.

type TransactionPool

type TransactionPool interface {
	AcceptTransactionSet([]types.Transaction) error
	RecommendedFee() types.Currency
}

A TransactionPool broadcasts transactions to the network.

type UpdateStateTransaction

type UpdateStateTransaction interface {
	ContractRelevant(types.FileContractID) (bool, error)

	ConfirmFormation(types.FileContractID) error
	ConfirmRevision(types.FileContractRevision) error
	ConfirmResolution(id types.FileContractID, height uint64) error

	RevertFormation(types.FileContractID) error
	RevertRevision(types.FileContractID) error
	RevertResolution(types.FileContractID) error
}

UpdateStateTransaction atomically updates the contract manager's state.

type Usage

type Usage struct {
	RPCRevenue       types.Currency `json:"rpc"`
	StorageRevenue   types.Currency `json:"storage"`
	EgressRevenue    types.Currency `json:"egress"`
	IngressRevenue   types.Currency `json:"ingress"`
	RegistryRead     types.Currency `json:"registryRead"`
	RegistryWrite    types.Currency `json:"registryWrite"`
	AccountFunding   types.Currency `json:"accountFunding"`
	RiskedCollateral types.Currency `json:"riskedCollateral"`
}

Usage tracks the usage of a contract's funds.

func (Usage) Add

func (u Usage) Add(b Usage) (c Usage)

Add returns the sum of two usages.

type Wallet

type Wallet interface {
	Address() types.Address
	UnlockConditions() types.UnlockConditions
	FundTransaction(txn *types.Transaction, amount types.Currency) (toSign []types.Hash256, release func(), err error)
	SignTransaction(cs consensus.State, txn *types.Transaction, toSign []types.Hash256, cf types.CoveredFields) error
}

A Wallet manages Siacoins and funds transactions

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL