block

Documentation

Overview

Copyright (C) 2019-2021, Dijets, Inc. All rights reserved. See the file LICENSE for licensing terms.

Index

• Variables
• func BatchedParseBlock(vm Parser, blks [][]byte) ([]snowman.Block, error)
• func GetAncestors(vm Getter, blkID ids.ID, maxBlocksNum int, maxBlocksSize int, ...) ([][]byte, error)
• type BatchedChainVM
• type ChainVM
• type Getter
• type HeightIndexedChainVM
• type Parser
• type TestBatchedVM
  • func (vm *TestBatchedVM) BatchedParseBlock(blks [][]byte) ([]snowman.Block, error)
  • func (vm *TestBatchedVM) Default(cant bool)
  • func (vm *TestBatchedVM) GetAncestors(blkID ids.ID, maxBlocksNum int, maxBlocksSize int, ...) ([][]byte, error)
• type TestHeightIndexedVM
  • func (vm *TestHeightIndexedVM) GetBlockIDAtHeight(height uint64) (ids.ID, error)
  • func (vm *TestHeightIndexedVM) VerifyHeightIndex() error
• type TestVM
  • func (vm *TestVM) BuildBlock() (snowman.Block, error)
  • func (vm *TestVM) Default(cant bool)
  • func (vm *TestVM) GetBlock(id ids.ID) (snowman.Block, error)
  • func (vm *TestVM) LastAccepted() (ids.ID, error)
  • func (vm *TestVM) ParseBlock(b []byte) (snowman.Block, error)
  • func (vm *TestVM) SetPreference(id ids.ID) error

Variables

var (
	ErrHeightIndexedVMNotImplemented = errors.New("vm does not implement HeightIndexedChainVM interface")
	ErrIndexIncomplete               = errors.New("query failed because height index is incomplete")
)

var ErrRemoteVMNotImplemented = errors.New("vm does not implement RemoteVM interface")

Functions

func BatchedParseBlock

func BatchedParseBlock(vm Parser, blks [][]byte) ([]snowman.Block, error)

func GetAncestors

func GetAncestors(
	vm Getter,
	blkID ids.ID,
	maxBlocksNum int,
	maxBlocksSize int,
	maxBlocksRetrivalTime time.Duration,
) ([][]byte, error)

Types

type BatchedChainVM

type BatchedChainVM interface {
	GetAncestors(
		blkID ids.ID,
		maxBlocksNum int,
		maxBlocksSize int,
		maxBlocksRetrivalTime time.Duration,
	) ([][]byte, error)

	BatchedParseBlock(blks [][]byte) ([]snowman.Block, error)
}

BatchedChainVM extends the minimal functionalities exposed by ChainVM for VMs communicating over network (gRPC in our case). This allows more efficient operations since calls over network can be duly batched

type ChainVM

type ChainVM interface {
	common.VM

	Getter
	Parser

	// Attempt to create a new block from data contained in the VM.
	//
	// If the VM doesn't want to issue a new block, an error should be
	// returned.
	BuildBlock() (snowman.Block, error)

	// Notify the VM of the currently preferred block.
	//
	// This should always be a block that has no children known to consensus.
	SetPreference(ids.ID) error

	// LastAccepted returns the ID of the last accepted block.
	//
	// If no blocks have been accepted by consensus yet, it is assumed there is
	// a definitionally accepted block, the Genesis block, that will be
	// returned.
	LastAccepted() (ids.ID, error)
}

ChainVM defines the required functionality of a Snowman VM.

A Snowman VM is responsible for defining the representation of state, the representation of operations on that state, the application of operations on that state, and the creation of the operations. Consensus will decide on if the operation is executed and the order operations are executed in.

For example, suppose we have a VM that tracks an increasing number that is agreed upon by the network. The state is a single number. The operation is setting the number to a new, larger value. Applying the operation will save to the database the new value. The VM can attempt to issue a new number, of larger value, at any time. Consensus will ensure the network agrees on the number at every block height.

type Getter

type Getter interface {
	// Attempt to load a block.
	//
	// If the block does not exist, an error should be returned.
	//
	// TODO: Update the invariant to report database.ErrNotFound if the
	//       operation is missing.
	GetBlock(ids.ID) (snowman.Block, error)
}

Getter defines the functionality for fetching a block by its ID.

type HeightIndexedChainVM

type HeightIndexedChainVM interface {
	// VerifyHeightIndex should return:
	// - nil if the height index is available.
	// - ErrHeightIndexedVMNotImplemented if the height index is not supported.
	// - ErrIndexIncomplete if the height index is not currently available.
	// - Any other non-standard error that may have occurred when verifying the
	//   index.
	VerifyHeightIndex() error

	// GetBlockIDAtHeight returns the ID of the block that was accepted with
	// [height].
	GetBlockIDAtHeight(height uint64) (ids.ID, error)
}

HeightIndexedChainVM extends ChainVM to allow querying block IDs by height.

type Parser

type Parser interface {
	// Attempt to create a block from a stream of bytes.
	//
	// The block should be represented by the full byte array, without extra
	// bytes.
	ParseBlock([]byte) (snowman.Block, error)
}

Parser defines the functionality for fetching a block by its bytes.

type TestBatchedVM

type TestBatchedVM struct {
	T *testing.T

	CantGetAncestors    bool
	CantBatchParseBlock bool

	GetAncestorsF func(
		blkID ids.ID,
		maxBlocksNum int,
		maxBlocksSize int,
		maxBlocksRetrivalTime time.Duration,
	) ([][]byte, error)

	BatchedParseBlockF func(blks [][]byte) ([]snowman.Block, error)
}

TestBatchedVM is a BatchedVM that is useful for testing.

func (*TestBatchedVM) BatchedParseBlock

func (vm *TestBatchedVM) BatchedParseBlock(blks [][]byte) ([]snowman.Block, error)

func (*TestBatchedVM) Default

func (vm *TestBatchedVM) Default(cant bool)

func (*TestBatchedVM) GetAncestors

func (vm *TestBatchedVM) GetAncestors(
	blkID ids.ID,
	maxBlocksNum int,
	maxBlocksSize int,
	maxBlocksRetrivalTime time.Duration,
) ([][]byte, error)

type TestHeightIndexedVM

type TestHeightIndexedVM struct {
	T *testing.T

	CantVerifyHeightIndex  bool
	CantGetBlockIDAtHeight bool

	VerifyHeightIndexF  func() error
	GetBlockIDAtHeightF func(height uint64) (ids.ID, error)
}

TestBatchedVM is a BatchedVM that is useful for testing.

func (*TestHeightIndexedVM) GetBlockIDAtHeight

func (vm *TestHeightIndexedVM) GetBlockIDAtHeight(height uint64) (ids.ID, error)

func (*TestHeightIndexedVM) VerifyHeightIndex

func (vm *TestHeightIndexedVM) VerifyHeightIndex() error

type TestVM

type TestVM struct {
	common.TestVM

	CantBuildBlock,
	CantParseBlock,
	CantGetBlock,
	CantSetPreference,
	CantLastAccepted bool

	BuildBlockF    func() (snowman.Block, error)
	ParseBlockF    func([]byte) (snowman.Block, error)
	GetBlockF      func(ids.ID) (snowman.Block, error)
	SetPreferenceF func(ids.ID) error
	LastAcceptedF  func() (ids.ID, error)
}

TestVM is a ChainVM that is useful for testing.

func (*TestVM) BuildBlock

func (vm *TestVM) BuildBlock() (snowman.Block, error)

func (*TestVM) Default

func (vm *TestVM) Default(cant bool)

func (*TestVM) GetBlock

func (vm *TestVM) GetBlock(id ids.ID) (snowman.Block, error)

func (*TestVM) LastAccepted

func (vm *TestVM) LastAccepted() (ids.ID, error)

func (*TestVM) ParseBlock

func (vm *TestVM) ParseBlock(b []byte) (snowman.Block, error)

func (*TestVM) SetPreference

func (vm *TestVM) SetPreference(id ids.ID) error