api

Documentation

Overview

Package api provides the implementation agnostic consensus API.

Index

• Constants
• type Block
• type EstimateGasRequest
• type Evidence
• type FeatureMask
  • func (m FeatureMask) String() string
• type GetSignerNonceRequest
• type HaltHook
• type LightBlock
• type Mode
  • func (m Mode) MarshalText() ([]byte, error)
  • func (m Mode) String() string
  • func (m *Mode) UnmarshalText(text []byte) error
• type NextBlockState
• type NoOpSubmissionManager
• 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 TransactionsWithResults
• type Vote
• type Votes

Constants

const (

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

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

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 Mode

type Mode string

Mode is the consensus node mode.

const (
	// ModeFull is the name of the full node consensus mode.
	ModeFull Mode = "full"
	// ModeSeed is the name of the seed-only node consensus mode.
	ModeSeed Mode = "seed"
	// ModeArchive is the name of the archive node consensus mode.
	ModeArchive Mode = "archive"
)

func (Mode) MarshalText

func (m Mode) MarshalText() ([]byte, error)

MarshalText encodes a Mode into text form.

func (Mode) String

func (m Mode) String() string

String returns a string representation of the mode.

func (*Mode) UnmarshalText

func (m *Mode) UnmarshalText(text []byte) error

UnmarshalText decodes a text marshaled consensus mode.

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 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"`
	// Mode is the consensus mode identifier.
	Mode Mode `json:"mode"`
	// Features are the indicated consensus backend features.
	Features FeatureMask `json:"features"`

	// 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 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"`
}

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 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.