api

Documentation

Overview

Package api provides the implementation agnostic consensus API.

Index

• Constants
• type Block
• type BlockMetadata
• type EstimateGasRequest
• type Evidence
• type FeatureMask
  • func (m FeatureMask) String() string
• type GetSignerNonceRequest
• type HaltHook
• type LightBlock
• type LightClientStatus
• type NextBlockState
• type NoOpSubmissionManager
• type P2PStatus
• type Parameters
• type Status
• type StatusState
  • func (s StatusState) MarshalText() ([]byte, error)
  • func (s StatusState) String() string
  • func (s *StatusState) UnmarshalText(text []byte) error
• type TransactionsWithProofs
• type TransactionsWithResults
• type Vote
• type Votes

Constants

const (
	// ModuleName is the module name used for error definitions.
	ModuleName = "consensus"

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

const BlockMetadataMaxSize = 16_384

BlockMetadataMaxSize is the maximum size of a fully populated and signed block metadata transaction.

This should be less than any reasonably configured MaxTxSize.

Types

type Block

type Block struct {
	// Height contains the block height.
	Height int64 `json:"height"`
	// Hash contains the block header hash.
	Hash hash.Hash `json:"hash"`
	// Time is the second-granular consensus time.
	Time time.Time `json:"time"`
	// StateRoot is the Merkle root of the consensus state tree.
	StateRoot mkvsNode.Root `json:"state_root"`
	// 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 BlockMetadata

type BlockMetadata struct {
	// StateRoot is the state root after executing all logic in the block.
	StateRoot hash.Hash `json:"state_root"`
	// EventsRoot is the provable events root.
	EventsRoot []byte `json:"events_root"`
}

BlockMetadata contains additional metadata related to the executing block.

The metadata is included in the form of a special transaction where this structure is the transaction body.

type EstimateGasRequest

type EstimateGasRequest struct {
	Signer      signature.PublicKey      `json:"signer"`
	Transaction *transaction.Transaction `json:"transaction"`
}

EstimateGasRequest is a EstimateGas request.

type Evidence

type Evidence struct {
	// Meta contains the consensus backend specific evidence.
	Meta []byte `json:"meta"`
}

Evidence is evidence of a node's Byzantine behavior.

type FeatureMask

type FeatureMask uint8

FeatureMask is the consensus backend feature bitmask.

const (
	// FeatureServices indicates support for communicating with consensus services.
	FeatureServices FeatureMask = 1 << 0

	// FeatureFullNode indicates that the consensus backend is independently fully verifying all
	// consensus-layer blocks.
	FeatureFullNode FeatureMask = 1 << 1

	// FeatureArchiveNode indicates that the node is an archive node.
	FeatureArchiveNode FeatureMask = 1 << 2
)

func (FeatureMask) String

func (m FeatureMask) String() string

String returns a string representation of the consensus backend feature bitmask.

type GetSignerNonceRequest

type GetSignerNonceRequest struct {
	AccountAddress staking.Address `json:"account_address"`
	Height         int64           `json:"height"`
}

GetSignerNonceRequest is a GetSignerNonce request.

type HaltHook

type HaltHook func(ctx context.Context, blockHeight int64, epoch beacon.EpochTime, err error)

HaltHook is a function that gets called when consensus needs to halt for some reason.

type LightBlock

type LightBlock struct {
	// Height contains the block height.
	Height int64 `json:"height"`
	// Meta contains the consensus backend specific light block.
	Meta []byte `json:"meta"`
}

LightBlock is a light consensus block suitable for syncing light clients.

type LightClientStatus

type LightClientStatus struct {
	// LatestHeight is the height of the latest block.
	LatestHeight int64 `json:"latest_height"`
	// LatestHash is the hash of the latest block.
	LatestHash hash.Hash `json:"latest_hash"`
	// LatestTime is the timestamp of the latest block.
	LatestTime time.Time `json:"latest_time"`

	// OldestHeight is the height of the oldest block.
	OldestHeight int64 `json:"oldest_height"`
	// LatestHash is the hash of the oldest block.
	OldestHash hash.Hash `json:"oldest_hash"`
	// OldestTime is the timestamp of the oldest block.
	OldestTime time.Time `json:"oldest_time"`

	// PeersIDs are the light client provider peer identifiers.
	PeerIDs []string `json:"peer_ids"`
}

LightClientStatus is the current light client status overview.

type NextBlockState

type NextBlockState struct {
	Height int64 `json:"height"`

	NumValidators uint64 `json:"num_validators"`
	VotingPower   uint64 `json:"voting_power"`

	Prevotes   Votes `json:"prevotes"`
	Precommits Votes `json:"precommits"`
}

NextBlockState has the state of the next block being voted on by validators.

type NoOpSubmissionManager

type NoOpSubmissionManager struct{}

NoOpSubmissionManager implements a submission manager that doesn't support submitting transactions.

type P2PStatus

type P2PStatus struct {
	// PubKey is the public key used for consensus P2P communication.
	PubKey signature.PublicKey `json:"pub_key"`

	// PeerID is the peer ID derived by hashing peer's public key.
	PeerID string `json:"peer_id"`

	// Addresses is a list of configured P2P addresses used when registering the node.
	Addresses []node.ConsensusAddress `json:"addresses"`

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

P2PStatus is the P2P status of a node.

type Parameters

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

Parameters are the consensus backend parameters.

type Status

type Status struct {
	// Status is an concise status of the consensus backend.
	Status StatusState `json:"status"`

	// Version is the version of the consensus protocol that the node is using.
	Version version.Version `json:"version"`
	// Backend is the consensus backend identifier.
	Backend string `json:"backend"`
	// Features are the indicated consensus backend features.
	Features FeatureMask `json:"features"`

	// LatestHeight is the height of the latest block.
	LatestHeight int64 `json:"latest_height"`
	// LatestHash is the hash of the latest block.
	LatestHash hash.Hash `json:"latest_hash"`
	// LatestTime is the timestamp of the latest block.
	LatestTime time.Time `json:"latest_time"`
	// LatestEpoch is the epoch of the latest block.
	LatestEpoch beacon.EpochTime `json:"latest_epoch"`
	// LatestStateRoot is the Merkle root of the consensus state tree.
	LatestStateRoot mkvsNode.Root `json:"latest_state_root"`

	// GenesisHeight is the height of the genesis block.
	GenesisHeight int64 `json:"genesis_height"`
	// GenesisHash is the hash of the genesis block.
	GenesisHash hash.Hash `json:"genesis_hash"`

	// LastRetainedHeight is the height of the oldest retained block.
	LastRetainedHeight int64 `json:"last_retained_height"`
	// LastRetainedHash is the hash of the oldest retained block.
	LastRetainedHash hash.Hash `json:"last_retained_hash"`

	// ChainContext is the chain domain separation context.
	ChainContext string `json:"chain_context"`

	// IsValidator returns whether the current node is part of the validator set.
	IsValidator bool `json:"is_validator"`

	// P2P is the P2P status of the node.
	P2P *P2PStatus `json:"p2p,omitempty"`
}

Status is the current status overview.

type StatusState

type StatusState uint8

StatusState is the concise status state of the consensus backend.

var (
	// StatusStateReady is the ready status state.
	StatusStateReady StatusState
	// StatusStateSyncing is the syncing status state.
	StatusStateSyncing StatusState = 1
)

func (StatusState) MarshalText

func (s StatusState) MarshalText() ([]byte, error)

MarshalText encodes a StatusState into text form.

func (StatusState) String

func (s StatusState) String() string

String returns a string representation of a status state.

func (*StatusState) UnmarshalText

func (s *StatusState) UnmarshalText(text []byte) error

UnmarshalText decodes a text slice into a StatusState.

type TransactionsWithProofs

type TransactionsWithProofs struct {
	Transactions [][]byte `json:"transactions"`
	Proofs       [][]byte `json:"proofs"`
}

TransactionsWithProofs is GetTransactionsWithProofs response.

Proofs[i] is a proof of block inclusion for Transactions[i].

type TransactionsWithResults

type TransactionsWithResults struct {
	Transactions [][]byte          `json:"transactions"`
	Results      []*results.Result `json:"results"`
}

TransactionsWithResults is GetTransactionsWithResults response.

Results[i] are the results of executing Transactions[i].

type Vote

type Vote struct {
	NodeID        signature.PublicKey `json:"node_id"`
	EntityID      signature.PublicKey `json:"entity_id"`
	EntityAddress staking.Address     `json:"entity_address"`
	VotingPower   uint64              `json:"voting_power"`
}

Vote contains metadata about a vote for the next block.

type Votes

type Votes struct {
	VotingPower uint64  `json:"voting_power"`
	Ratio       float64 `json:"ratio"`
	Votes       []Vote  `json:"votes"`
}

Votes are the votes for the next block.