blockchain

Documentation

Index

• Variables
• func PickAction(gasLimit uint64, actionIterator actioniterator.ActionIterator) ([]action.SealedEnvelope, error)
• type BlockCreationSubscriber
• type Blockchain
  • func NewBlockchain(cfg config.Config, opts ...Option) Blockchain
• type IndexBuilder
  • func NewIndexBuilder(chain Blockchain, reindex bool) (*IndexBuilder, error)
  • func (ib *IndexBuilder) HandleBlock(blk *block.Block) error
  • func (ib *IndexBuilder) Start(_ context.Context) error
  • func (ib *IndexBuilder) Stop(_ context.Context) error
• type Option
  • func BoltDBDaoOption() Option
  • func ClockOption(clk clock.Clock) Option
  • func DefaultStateFactoryOption() Option
  • func InMemDaoOption() Option
  • func InMemStateFactoryOption() Option
  • func PrecreatedDaoOption(dao *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")
)

var (

	// ErrNotOpened indicates db is not opened
	ErrNotOpened = errors.New("DB is not opened")
)

Functions

func PickAction

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

PickAction returns picked action list

Types

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
	// 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 IndexBuilder

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

IndexBuilder defines the index builder

func NewIndexBuilder

func NewIndexBuilder(chain Blockchain, reindex bool) (*IndexBuilder, error)

NewIndexBuilder instantiates an index builder

func (*IndexBuilder) HandleBlock

func (ib *IndexBuilder) HandleBlock(blk *block.Block) error

HandleBlock handles the block and create the indices for the actions and receipts in it

func (*IndexBuilder) Start

func (ib *IndexBuilder) Start(_ context.Context) error

Start starts the index builder

func (*IndexBuilder) Stop

func (ib *IndexBuilder) Stop(_ context.Context) error

Stop stops the index builder

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

Validator is the interface of validator