api

package
v0.0.0-...-9865f5a Latest Latest
Warning

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

 Go to latest Published: Jun 1, 2020 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Overview

Package consensus provides the implementation agnostic consensus backend.

Index

Constants

View Source 
const (

	// HeightLatest is the height that represents the most recent block height.
	HeightLatest int64 = 0
)

Variables

View Source 
var (
	// ErrNoCommittedBlocks is the error returned when there are no committed
	// blocks and as such no state can be queried.
	ErrNoCommittedBlocks = errors.New(moduleName, 1, "consensus: no committed blocks")

	// ErrOversizedTx is the error returned when the given transaction is too big to be processed.
	ErrOversizedTx = errors.New(moduleName, 2, "consensus: oversized transaction")

	// ErrVersionNotFound is the error returned when the given version (height) cannot be found,
	// possibly because it was pruned.
	ErrVersionNotFound = errors.New(moduleName, 3, "consensus: version not found")
)

Functions

func RegisterLightService 

func RegisterLightService(server *grpc.Server, service LightClientBackend)

RegisterLightService registers a new light client backend service with the given gRPC server.

func RegisterService 

func RegisterService(server *grpc.Server, service ClientBackend)

RegisterService registers a new client backend service with the given gRPC server.

func SignAndSubmitTx 

func SignAndSubmitTx(ctx context.Context, backend Backend, signer signature.Signer, tx *transaction.Transaction) error

SignAndSubmitTx is a helper function that signs and submits a transaction to the consensus backend.

If the nonce is set to zero, it will be automatically filled in based on the current consensus state.

If the fee is set to nil, it will be automatically filled in based on gas estimation and current gas price discovery.

Types

type Backend 

type Backend interface {
	ClientBackend

	// Synced returns a channel that is closed once synchronization is
	// complete.
	Synced() <-chan struct{}

	// ConsensusKey returns the consensus signing key.
	ConsensusKey() signature.PublicKey

	// GetAddresses returns the consensus backend addresses.
	GetAddresses() ([]node.ConsensusAddress, error)

	// RegisterHaltHook registers a function to be called when the
	// consensus Halt epoch height is reached.
	RegisterHaltHook(func(ctx context.Context, blockHeight int64, epoch epochtime.EpochTime))

	// SubmitEvidence submits evidence of misbehavior.
	SubmitEvidence(ctx context.Context, evidence Evidence) error

	// SubmissionManager returns the transaction submission manager.
	SubmissionManager() SubmissionManager

	// EpochTime returns the epochtime backend.
	EpochTime() epochtime.Backend

	// Beacon returns the beacon backend.
	Beacon() beacon.Backend

	// KeyManager returns the keymanager backend.
	KeyManager() keymanager.Backend

	// Registry returns the registry backend.
	Registry() registry.Backend

	// RootHash returns the roothash backend.
	RootHash() roothash.Backend

	// Staking returns the staking backend.
	Staking() staking.Backend

	// Scheduler returns the scheduler backend.
	Scheduler() scheduler.Backend
}

Backend is an interface that a consensus backend must provide.

type Block 

type Block struct {
	// Height contains the block height.
	Height int64 `json:"height"`
	// Hash contains the block header hash.
	Hash []byte `json:"hash"`
	// Time is the second-granular consensus time.
	Time time.Time `json:"time"`
	// Meta contains the consensus backend specific block metadata.
	Meta cbor.RawMessage `json:"meta"`
}

Block is a consensus block.

While some common fields are provided, most of the structure is dependent on the actual backend implementation.

type ClientBackend 

type ClientBackend interface {
	LightClientBackend
	TransactionAuthHandler

	// SubmitTx submits a signed consensus transaction.
	SubmitTx(ctx context.Context, tx *transaction.SignedTransaction) error

	// StateToGenesis returns the genesis state at the specified block height.
	StateToGenesis(ctx context.Context, height int64) (*genesis.Document, error)

	// EstimateGas calculates the amount of gas required to execute the given transaction.
	EstimateGas(ctx context.Context, req *EstimateGasRequest) (transaction.Gas, error)

	// WaitEpoch waits for consensus to reach an epoch.
	//
	// Note that an epoch is considered reached even if any epoch greater than
	// the one specified is reached (e.g., that the current epoch is already
	// in the future).
	WaitEpoch(ctx context.Context, epoch epochtime.EpochTime) error

	// GetEpoch returns the current epoch.
	GetEpoch(ctx context.Context, height int64) (epochtime.EpochTime, error)

	// GetBlock returns a consensus block at a specific height.
	GetBlock(ctx context.Context, height int64) (*Block, error)

	// GetTransactions returns a list of all transactions contained within a
	// consensus block at a specific height.
	//
	// NOTE: Any of these transactions could be invalid.
	GetTransactions(ctx context.Context, height int64) ([][]byte, error)

	// WatchBlocks returns a channel that produces a stream of consensus
	// blocks as they are being finalized.
	WatchBlocks(ctx context.Context) (<-chan *Block, pubsub.ClosableSubscription, error)

	// GetGenesisDocument returns the original genesis document.
	GetGenesisDocument(ctx context.Context) (*genesis.Document, error)

	// GetStatus returns the current status overview.
	GetStatus(ctx context.Context) (*Status, error)
}

ClientBackend is a limited consensus interface used by clients that connect to the local full node. This is separate from light clients which use the LightClientBackend interface.

func NewConsensusClient 

func NewConsensusClient(c *grpc.ClientConn) ClientBackend

NewConsensusClient creates a new gRPC consensus client service.

type ConsensusEvidence 

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

ConsensusEvidence is consensus backend-specific evidence.

func NewConsensusEvidence 

func NewConsensusEvidence(inner interface{}) ConsensusEvidence

NewConsensusEvidence creates new consensus backend-specific evidence.

func (ConsensusEvidence) Kind 

func (ce ConsensusEvidence) Kind() EvidenceKind

Kind returns the evidence kind.

func (ConsensusEvidence) Unwrap 

func (ce ConsensusEvidence) Unwrap() interface{}

Unwrap returns the unwrapped evidence (if any).

type EstimateGasRequest 

type EstimateGasRequest struct {
	Caller      signature.PublicKey      `json:"caller"`
	Transaction *transaction.Transaction `json:"transaction"`
}

EstimateGasRequest is a EstimateGas request.

type Evidence 

type Evidence interface {
	// Kind returns the evidence kind.
	Kind() EvidenceKind
	// Unwrap returns the unwrapped evidence (if any).
	Unwrap() interface{}
}

Evidence is evidence of a node misbehaving.

type EvidenceKind 

type EvidenceKind int

EvidenceKind is kind of evindence of a node misbehaving. 

const (
	// EvidenceKindConsensus is consensus-layer specific evidence.
	EvidenceKindConsensus EvidenceKind = 0

	EvidenceKindMax = EvidenceKindConsensus
)

func (EvidenceKind) String 

func (k EvidenceKind) String() string

String returns a string representation of an EvidenceKind.

type GetSignerNonceRequest 

type GetSignerNonceRequest struct {
	ID     signature.PublicKey `json:"id"`
	Height int64               `json:"height"`
}

GetSignerNonceRequest is a GetSignerNonce request.

type LightClientBackend 

type LightClientBackend interface {
	// GetSignedHeader returns the signed header for a specific height.
	GetSignedHeader(ctx context.Context, height int64) (*SignedHeader, error)

	// GetValidatorSet returns the validator set for a specific height.
	GetValidatorSet(ctx context.Context, height int64) (*ValidatorSet, error)

	// GetParameters returns the consensus parameters for a specific height.
	GetParameters(ctx context.Context, height int64) (*Parameters, error)
}

LightClientBackend is the limited consensus interface used by light clients.

func NewConsensusLightClient 

func NewConsensusLightClient(c *grpc.ClientConn) LightClientBackend

NewConsensusLightClient creates a new gRPC consensus light client service.

type Parameters 

type Parameters struct {
	// Height contains the block height these consensus parameters are for.
	Height int64 `json:"height"`
	// Meta contains the consensus backend specific consensus parameters.
	Meta []byte `json:"meta"`
}

Parameters are the consensus backend parameters.

type PriceDiscovery 

type PriceDiscovery interface {
	// GasPrice returns the current consensus gas price.
	GasPrice(ctx context.Context) (*quantity.Quantity, error)
}

PriceDiscovery is the consensus fee price discovery interface.

func NewStaticPriceDiscovery 

func NewStaticPriceDiscovery(price uint64) (PriceDiscovery, error)

NewStaticPriceDiscovery creates a price discovery mechanism which always returns the same static price specified at construction time.

type SignedHeader 

type SignedHeader struct {
	// Height contains the block height this header is for.
	Height int64 `json:"height"`
	// Meta contains the consensus backend specific signed header.
	Meta []byte `json:"meta"`
}

SignedHeader is a signed consensus block header.

type Status 

type Status struct {
	// ConsensusVersion is the version of the consensus protocol that the node is using.
	ConsensusVersion string `json:"consensus_version"`
	// Backend is the consensus backend identifier.
	Backend string `json:"backend"`

	// NodePeers is a list of node's peers.
	NodePeers []string `json:"node_peers"`

	// LatestHeight is the height of the latest block.
	LatestHeight int64 `json:"latest_height"`
	// LatestHash is the hash of the latest block.
	LatestHash []byte `json:"latest_hash"`
	// LatestTime is the timestamp of the latest block.
	LatestTime time.Time `json:"latest_time"`

	// GenesisHeight is the height of the genesis block.
	GenesisHeight int64 `json:"genesis_height"`
	// GenesisHash is the hash of the genesis block.
	GenesisHash []byte `json:"genesis_hash"`
}

Status is the current status overview.

type SubmissionManager 

type SubmissionManager interface {
	// SignAndSubmitTx populates the nonce and fee fields in the transaction, signs the transaction
	// with the passed signer and submits it to consensus backend.
	//
	// It also automatically handles retries in case the nonce was incorrectly estimated.
	SignAndSubmitTx(ctx context.Context, signer signature.Signer, tx *transaction.Transaction) error
}

SubmissionManager is a transaction submission manager interface.

func NewSubmissionManager 

func NewSubmissionManager(backend Backend, priceDiscovery PriceDiscovery, maxFee uint64) SubmissionManager

NewSubmissionManager creates a new transaction submission manager.

type TransactionAuthHandler 

type TransactionAuthHandler interface {
	// GetSignerNonce returns the nonce that should be used by the given
	// signer for transmitting the next transaction.
	GetSignerNonce(ctx context.Context, req *GetSignerNonceRequest) (uint64, error)
}

TransactionAuthHandler is the interface for handling transaction authentication (checking nonces and fees).

type ValidatorSet 

type ValidatorSet struct {
	// Height contains the block height this validator set is for.
	Height int64 `json:"height"`
	// Meta contains the consensus backend specific validator set.
	Meta []byte `json:"meta"`
}

ValidatorSet contains the validator set information.

Source Files

View all Source files

Directories

Path Synopsis

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.