contracts

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Sep 26, 2023 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 

func (cm *ContractManager) Lock(ctx context.Context, id types.FileContractID) (SignedRevision, error)

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

func (cm *ContractManager) SectorRoots(id types.FileContractID, limit, offset int) ([]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, usage Usage, oldSectors uint64, 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 UpdateContractTransaction 

type UpdateContractTransaction interface {
	// AppendSector appends a sector root to the end of the contract
	AppendSector(root types.Hash256) error
	// SwapSectors swaps the sector roots at the given indices.
	SwapSectors(i, j uint64) error
	// TrimSectors removes the last n sector roots from the contract.
	TrimSectors(n int) error
	// UpdateSector updates the sector root at the given index.
	UpdateSector(index uint64, newRoot types.Hash256) error

	// AddUsage adds the additional usage costs to the contract.
	AddUsage(Usage) error
	// ReviseContract updates the current revision associated with a contract.
	ReviseContract(SignedRevision) error
}

UpdateContractTransaction atomically updates a single contract and its associated sector roots.

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

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.