blockchain

Documentation

Index

• Variables
• func PickAction(gasLimit uint64, actionIterator actioniterator.ActionIterator) ([]action.SealedEnvelope, error)
• type ActPoolManager
• type BlockCreationSubscriber
• type Blockchain
  • func NewBlockchain(cfg config.Config, opts ...Option) Blockchain
• type Option
  • func BoltDBDaoOption() Option
  • func ClockOption(clk clock.Clock) Option
  • func DefaultStateFactoryOption() Option
  • func InMemDaoOption() Option
  • func InMemStateFactoryOption() Option
  • func PrecreatedDaoOption(dao blockdao.BlockDAO) Option
  • func PrecreatedStateFactoryOption(sf factory.Factory) Option
  • func RegistryOption(registry *protocol.Registry) Option
• type Validator

Variables

var (
	// ErrInvalidTipHeight is the error returned when the block height is not valid
	ErrInvalidTipHeight = errors.New("invalid tip height")
	// ErrInvalidBlock is the error returned when the block is not valid
	ErrInvalidBlock = errors.New("failed to validate the block")
	// ErrActionNonce is the error when the nonce of the action is wrong
	ErrActionNonce = errors.New("invalid action nonce")
	// ErrInsufficientGas indicates the error of insufficient gas value for data storage
	ErrInsufficientGas = errors.New("insufficient intrinsic gas value")
	// ErrBalance indicates the error of balance
	ErrBalance = errors.New("invalid balance")
)

Functions

func PickAction

func PickAction(gasLimit uint64, actionIterator actioniterator.ActionIterator) ([]action.SealedEnvelope, error)

PickAction returns picked action list

Types

type ActPoolManager

type ActPoolManager interface {
	// GetActionByHash returns the pending action in pool given action's hash
	GetActionByHash(hash hash.Hash256) (action.SealedEnvelope, error)
}

ActPoolManager defines the actpool interface

type BlockCreationSubscriber

type BlockCreationSubscriber interface {
	HandleBlock(*block.Block) error
}

BlockCreationSubscriber is an interface which will get notified when a block is created

type Blockchain

type Blockchain interface {
	lifecycle.StartStopper

	// Balance returns balance of an account
	Balance(addr string) (*big.Int, error)
	// Nonce returns the nonce if the account exists
	Nonce(addr string) (uint64, error)
	// CreateState adds a new account with initial balance to the factory
	CreateState(addr string, init *big.Int) (*state.Account, error)
	// CandidatesByHeight returns the candidate list by a given height
	CandidatesByHeight(height uint64) ([]*state.Candidate, error)
	// ProductivityByEpoch returns the number of produced blocks per delegate in an epoch
	ProductivityByEpoch(epochNum uint64) (uint64, map[string]uint64, error)
	// For exposing blockchain states
	// GetHeightByHash returns Block's height by hash
	GetHeightByHash(h hash.Hash256) (uint64, error)
	// GetHashByHeight returns Block's hash by height
	GetHashByHeight(height uint64) (hash.Hash256, error)
	// GetBlockByHeight returns Block by height
	GetBlockByHeight(height uint64) (*block.Block, error)
	// GetBlockByHash returns Block by hash
	GetBlockByHash(h hash.Hash256) (*block.Block, error)
	// BlockHeaderByHeight return block header by height
	BlockHeaderByHeight(height uint64) (*block.Header, error)
	// BlockHeaderByHash return block header by hash
	BlockHeaderByHash(h hash.Hash256) (*block.Header, error)
	// BlockFooterByHeight return block footer by height
	BlockFooterByHeight(height uint64) (*block.Footer, error)
	// BlockFooterByHash return block footer by hash
	BlockFooterByHash(h hash.Hash256) (*block.Footer, error)
	// GetTotalActions returns the total number of actions
	GetTotalActions() (uint64, error)
	// GetNumActions returns the number of actions in certain block
	GetNumActions(height uint64) (uint64, error)
	// GetTranferAmount returns the transfer amount
	GetTranferAmount(height uint64) (*big.Int, error)
	// GetReceiptByActionHash returns the receipt by action hash
	GetReceiptByActionHash(h hash.Hash256) (*action.Receipt, error)
	// GetActionsFromIndex returns action hash from index
	GetActionsFromIndex(uint64, uint64) ([][]byte, error)
	// GetActionsByAddress returns actions by address
	GetActionsByAddress(string, uint64, uint64) ([][]byte, error)
	// GetActionCountByAddress returns action count by address
	GetActionCountByAddress(address string) (uint64, error)
	// GetActionByActionHash returns action by action hash
	GetActionByActionHash(h hash.Hash256) (action.SealedEnvelope, error)
	// GetBlockHashByActionHash returns Block hash by action hash
	GetBlockHashByActionHash(h hash.Hash256) (hash.Hash256, error)
	// GetReceiptsByHeight returns action receipts by block height
	GetReceiptsByHeight(height uint64) ([]*action.Receipt, error)
	// GetFactory returns the state factory
	GetFactory() factory.Factory
	// GetBlockDAO returns the block DAO
	GetBlockDAO() blockdao.BlockDAO
	// ChainID returns the chain ID
	ChainID() uint32
	// ChainAddress returns chain address on parent chain, the root chain return empty.
	ChainAddress() string
	// TipHash returns tip block's hash
	TipHash() hash.Hash256
	// TipHeight returns tip block's height
	TipHeight() uint64
	// StateByAddr returns account of a given address
	StateByAddr(address string) (*state.Account, error)
	// RecoverChainAndState recovers the chain to target height and refresh state db if necessary
	RecoverChainAndState(targetHeight uint64) error
	// GenesisTimestamp returns the timestamp of genesis
	GenesisTimestamp() int64

	// For block operations
	// MintNewBlock creates a new block with given actions
	// Note: the coinbase transfer will be added to the given transfers when minting a new block
	MintNewBlock(
		actionMap map[string][]action.SealedEnvelope,
		timestamp time.Time,
	) (*block.Block, error)
	// CommitBlock validates and appends a block to the chain
	CommitBlock(blk *block.Block) error
	// ValidateBlock validates a new block before adding it to the blockchain
	ValidateBlock(blk *block.Block) error

	// For action operations
	// Validator returns the current validator object
	Validator() Validator
	// SetValidator sets the current validator object
	SetValidator(val Validator)

	// For smart contract operations
	// ExecuteContractRead runs a read-only smart contract operation, this is done off the network since it does not
	// cause any state change
	ExecuteContractRead(caller address.Address, ex *action.Execution) ([]byte, *action.Receipt, error)

	// AddSubscriber make you listen to every single produced block
	AddSubscriber(BlockCreationSubscriber) error

	// RemoveSubscriber make you listen to every single produced block
	RemoveSubscriber(BlockCreationSubscriber) error
}

Blockchain represents the blockchain data structure and hosts the APIs to access it

func NewBlockchain

func NewBlockchain(cfg config.Config, opts ...Option) Blockchain

NewBlockchain creates a new blockchain and DB instance

type Option

type Option func(*blockchain, config.Config) error

Option sets blockchain construction parameter

func BoltDBDaoOption

func BoltDBDaoOption() Option

BoltDBDaoOption sets blockchain's dao with BoltDB from config.Chain.ChainDBPath

func ClockOption

func ClockOption(clk clock.Clock) Option

ClockOption overrides the default clock

func DefaultStateFactoryOption

func DefaultStateFactoryOption() Option

DefaultStateFactoryOption sets blockchain's sf from config

func InMemDaoOption

func InMemDaoOption() Option

InMemDaoOption sets blockchain's dao with MemKVStore

func InMemStateFactoryOption

func InMemStateFactoryOption() Option

InMemStateFactoryOption sets blockchain's factory.Factory as in memory sf

func PrecreatedDaoOption

func PrecreatedDaoOption(dao blockdao.BlockDAO) Option

PrecreatedDaoOption sets blockchain's dao

func PrecreatedStateFactoryOption

func PrecreatedStateFactoryOption(sf factory.Factory) Option

PrecreatedStateFactoryOption sets blockchain's state.Factory to sf

func RegistryOption

func RegistryOption(registry *protocol.Registry) Option

RegistryOption sets the blockchain with the protocol registry

type Validator

type Validator interface {
	// Validate validates the given block's content
	Validate(block *block.Block, tipHeight uint64, tipHash hash.Hash256) error
	// AddActionValidators add validators
	AddActionValidators(...protocol.ActionValidator)
	AddActionEnvelopeValidators(...protocol.ActionEnvelopeValidator)

	// SetActPool set ActPoolManager
	SetActPool(actPool ActPoolManager)
}

Validator is the interface of validator