types

package
v1.0.0-beta.10 Latest Latest
Warning

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

 Go to latest Published: Nov 21, 2025 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source 
const DefaultSigningKeyType = "ed25519"

DefaultSigningKeyType is the key type used by the sequencer signing key

View Source 
const (
	// MaxClockDrift is the maximum allowed clock drift for timestamp validation.
	// This allows for slight time differences between nodes in a distributed system.
	MaxClockDrift = 1 * time.Minute
)

Variables

View Source 
var (
	// ErrNoProposerAddress is returned when the proposer address is not set.
	ErrNoProposerAddress = errors.New("no proposer address")

	// ErrProposerVerificationFailed is returned when the proposer verification fails.
	ErrProposerVerificationFailed = errors.New("proposer verification failed")

	// ErrInvalidTimestamp is returned when the timestamp is invalid.
	ErrInvalidTimestamp = errors.New("invalid timestamp")
)
View Source 
var (
	// ErrAggregatorSetHashMismatch is returned when the aggregator set hash
	// in the signed header doesn't match the hash of the validator set.
	ErrAggregatorSetHashMismatch = errors.New("aggregator set hash in signed header and hash of validator set do not match")

	// ErrSignatureVerificationFailed is returned when the signature
	// verification fails
	ErrSignatureVerificationFailed = errors.New("signature verification failed")

	// ErrProposerAddressMismatch is returned when the proposer address in the signed header does not match the proposer address in the validator set
	ErrProposerAddressMismatch = errors.New("proposer address in SignedHeader does not match the proposer address in the validator set")

	// ErrSignatureEmpty is returned when signature is empty
	ErrSignatureEmpty = errors.New("signature is empty")
)
View Source 
var (
	// ErrLastHeaderHashMismatch is returned when the last header hash doesn't match.
	ErrLastHeaderHashMismatch = errors.New("last header hash mismatch")
)
View Source 
var HeaderContextKey = headerContextKey{}

HeaderContextKey is used to store the header in the context. This is useful if the execution client needs to access the header during transaction execution.

View Source 
var InitStateVersion = Version{
	Block: 11,
	App:   0,
}

InitStateVersion sets the Consensus.Block and Software versions, but leaves the Consensus.App version blank. The Consensus.App version will be set during the Handshake, once we hear from the app what protocol version it is running.

Functions

func DefaultAggregatorNodeSignatureBytesProvider 

func DefaultAggregatorNodeSignatureBytesProvider(header *Header) ([]byte, error)

DefaultAggregatorNodeSignatureBytesProvider is the default implementation of AggregatorNodeSignatureBytesProvider.

func DefaultSyncNodeSignatureBytesProvider 

func DefaultSyncNodeSignatureBytesProvider(_ context.Context, header *Header, _ *Data) ([]byte, error)

DefaultSyncNodeSignatureBytesProvider is the default implementation of SyncNodeSignatureBytesProvider.

func GenerateRandomBlockCustom 

func GenerateRandomBlockCustom(config *BlockConfig, chainID string) (*SignedHeader, *Data, crypto.PrivKey)

GenerateRandomBlockCustom returns a block with random data and the given height, transactions, privateKey and proposer address.

func GenerateRandomBlockCustomWithAppHash 

func GenerateRandomBlockCustomWithAppHash(config *BlockConfig, chainID string, appHash []byte) (*SignedHeader, *Data, crypto.PrivKey)

GenerateRandomBlockCustomWithAppHash returns a block with random data and the given height, transactions, privateKey, proposer address, and custom appHash.

func GetGenesisWithPrivkey 

func GetGenesisWithPrivkey(chainID string) (genesis.Genesis, crypto.PrivKey, crypto.PubKey)

GetGenesisWithPrivkey returns a genesis state and a private key

func GetRandomBlock 

func GetRandomBlock(height uint64, nTxs int, chainID string) (*SignedHeader, *Data)

GetRandomBlock creates a block with a given height and number of transactions, intended for testing. It's tailored for simplicity, primarily used in test setups where additional outputs are not needed.

func GetRandomBytes 

func GetRandomBytes(n uint) []byte

GetRandomBytes returns a byte slice of random bytes of length n. It uses crypto/rand for cryptographically secure random number generation.

func KeyAddress 

func KeyAddress(pubKey crypto.PubKey) []byte

func RetrieveWithHelpers 

func RetrieveWithHelpers(
	ctx context.Context,
	da coreda.DA,
	logger zerolog.Logger,
	dataLayerHeight uint64,
	namespace []byte,
	requestTimeout time.Duration,
) coreda.ResultRetrieve

RetrieveWithHelpers performs blob retrieval using the underlying DA layer, handling error mapping to produce a ResultRetrieve. It mimics the logic previously found in da.DAClient.Retrieve. requestTimeout defines the timeout for the each retrieval request.

func SubmitWithHelpers 

func SubmitWithHelpers(
	ctx context.Context,
	da coreda.DA,
	logger zerolog.Logger,
	data [][]byte,
	gasPrice float64,
	namespace []byte,
	options []byte,
) coreda.ResultSubmit

SubmitWithHelpers performs blob submission using the underlying DA layer, handling error mapping to produce a ResultSubmit. It assumes blob size filtering is handled within the DA implementation's Submit. It mimics the logic previously found in da.DAClient.Submit.

func Validate 

func Validate(header *SignedHeader, data *Data) error

Validate performs validation of data with respect to its header

Types

type AggregatorNodeSignatureBytesProvider 

type AggregatorNodeSignatureBytesProvider func(*Header) ([]byte, error)

AggregatorNodeSignatureBytesProvider defines the function type for providing a signature payload to sign.

type BaseHeader 

type BaseHeader struct {
	// Height represents the block height (aka block number) of a given header
	Height uint64
	// Time contains Unix nanotime of a block
	Time uint64
	// The Chain ID
	ChainID string
}

BaseHeader contains the most basic data of a header

type BlockConfig 

type BlockConfig struct {
	Height       uint64
	NTxs         int
	PrivKey      crypto.PrivKey // Input and Output option
	ProposerAddr []byte         // Input option
}

BlockConfig carries all necessary state for block generation

type Data 

type Data struct {
	*Metadata
	Txs Txs
}

Data defines Evolve block data.

func (*Data) ChainID 

func (d *Data) ChainID() string

ChainID returns chain ID of the block.

func (*Data) DACommitment 

func (d *Data) DACommitment() Hash

DACommitment returns the DA commitment of the Data excluding the Metadata

func (*Data) FromProto 

func (d *Data) FromProto(other *pb.Data) error

FromProto fills the Data with data from its protobuf representation

func (*Data) Hash 

func (d *Data) Hash() Hash

Hash returns hash of the Data

func (*Data) Height 

func (d *Data) Height() uint64

Height returns height of the block.

func (*Data) IsZero 

func (d *Data) IsZero() bool

IsZero returns true if the block is nil.

func (*Data) LastHeader 

func (d *Data) LastHeader() Hash

LastHeader returns last header hash of the block.

func (*Data) MarshalBinary 

func (d *Data) MarshalBinary() ([]byte, error)

MarshalBinary encodes Data into binary form and returns it.

func (*Data) New 

func (d *Data) New() *Data

New returns a new Block.

func (*Data) Size 

func (d *Data) Size() int

Size returns size of the block in bytes.

func (*Data) Time 

func (d *Data) Time() time.Time

Time returns time of the block.

func (*Data) ToProto 

func (d *Data) ToProto() *pb.Data

ToProto converts Data into protobuf representation and returns it.

func (*Data) UnmarshalBinary 

func (d *Data) UnmarshalBinary(data []byte) error

UnmarshalBinary decodes binary form of Data into object.

func (*Data) Validate 

func (d *Data) Validate() error

Validate performs basic validation of a block. this is used to implement the header interface for go header

func (*Data) Verify 

func (d *Data) Verify(untrustedData *Data) error

Verify Verifies a new, untrusted block against a trusted block.

type Hash 

type Hash = header.Hash

Hash is a 32-byte array which is used to represent a hash result.

func DefaultValidatorHasherProvider 

func DefaultValidatorHasherProvider(
	_ []byte,
	_ crypto.PubKey,
) (Hash, error)

DefaultValidatorHasherProvider is the default implementation of ValidatorHasherProvider. It returns an empty Hash, as ev-node does not use validator hashes itself. 

type Header struct {
	BaseHeader
	// Block and App version
	Version Version

	// prev block info
	LastHeaderHash Hash

	// hashes of block data
	DataHash Hash // Block.Data root aka Transactions
	AppHash  Hash // state after applying txs from the current block

	// compatibility with tendermint light client
	ValidatorHash Hash

	// Note that the address can be derived from the pubkey which can be derived
	// from the signature when using secp256k.
	// We keep this in case users choose another signature format where the
	// pubkey can't be recovered by the signature (e.g. ed25519).
	ProposerAddress []byte // original proposer of the block

	// Legacy holds fields that were removed from the canonical header JSON/Go
	// representation but may still be required for backwards compatible binary
	// serialization (e.g. legacy signing payloads).
	Legacy *LegacyHeaderFields
}

Header defines the structure of Evolve block header.

func GetRandomHeader 

func GetRandomHeader(chainID string, appHash []byte) Header

GetRandomHeader returns a header with random fields and current time

func GetRandomNextHeader 

func GetRandomNextHeader(header Header, chainID string) Header

GetRandomNextHeader returns a header with random data and height of +1 from the provided Header

func HeaderFromContext 

func HeaderFromContext(ctx context.Context) (Header, bool)

func (*Header) ApplyLegacyDefaults 

func (h *Header) ApplyLegacyDefaults()

ApplyLegacyDefaults ensures the Header has a Legacy block initialised with the expected defaults so that legacy serialization works without callers needing to populate every field explicitly.

func (*Header) ChainID 

func (h *Header) ChainID() string

ChainID returns chain ID of the header.

func (Header) Clone 

func (h Header) Clone() Header

Clone creates a deep copy of the header, ensuring all mutable slices are duplicated to avoid unintended sharing between variants.

func (*Header) FromProto 

func (h *Header) FromProto(other *pb.Header) error

FromProto fills Header with data from its protobuf representation.

func (*Header) Hash 

func (h *Header) Hash() Hash

Hash returns hash of the header

func (*Header) HashLegacy 

func (h *Header) HashLegacy() (Hash, error)

HashLegacy returns the SHA256 hash of the header using the legacy binary encoding that includes the deprecated fields.

func (*Header) HashSlim 

func (h *Header) HashSlim() (Hash, error)

HashSlim returns the SHA256 hash of the header using the slim (current) binary encoding.

func (*Header) Height 

func (h *Header) Height() uint64

Height returns height of the header.

func (*Header) IsZero 

func (h *Header) IsZero() bool

IsZero returns true if the header is nil.

func (*Header) LastHeader 

func (h *Header) LastHeader() Hash

LastHeader returns last header hash of the header.

func (*Header) MarshalBinary 

func (h *Header) MarshalBinary() ([]byte, error)

MarshalBinary encodes Header into binary form and returns it.

func (*Header) MarshalBinaryLegacy 

func (h *Header) MarshalBinaryLegacy() ([]byte, error)

MarshalBinaryLegacy returns the legacy header encoding that includes the deprecated fields.

func (*Header) New 

func (h *Header) New() *Header

New creates a new Header.

func (*Header) Time 

func (h *Header) Time() time.Time

Time returns timestamp as unix time with nanosecond precision

func (*Header) ToProto 

func (h *Header) ToProto() *pb.Header

ToProto converts Header into protobuf representation and returns it.

func (*Header) UnmarshalBinary 

func (h *Header) UnmarshalBinary(data []byte) error

UnmarshalBinary decodes binary form of Header into object.

func (*Header) Validate 

func (h *Header) Validate() error

Validate performs basic validation of a header.

func (*Header) ValidateBasic 

func (h *Header) ValidateBasic() error

ValidateBasic performs basic validation of a header.

func (*Header) Verify 

func (h *Header) Verify(untrstH *Header) error

Verify verifies the header.

type HeaderConfig 

type HeaderConfig struct {
	Height   uint64
	DataHash header.Hash
	AppHash  header.Hash
	Signer   signer.Signer
}

HeaderConfig carries all necessary state for header generation

type LegacyHeaderFields 

type LegacyHeaderFields struct {
	LastCommitHash  Hash
	ConsensusHash   Hash
	LastResultsHash Hash
}

LegacyHeaderFields captures the deprecated header fields that existed prior to the header minimisation change. When populated, these values are re-used while constructing the protobuf payload so that legacy nodes can continue to verify signatures and hashes.

Migration Guide

This compatibility layer enables networks to sync from genesis after the header minimization changes. The system automatically handles both legacy and slim header formats through a multi-format verification fallback mechanism.

## Format Detection

Headers are decoded and verified using the following strategy:

  1. Try custom signature provider (if configured)
  2. Try slim header format (new format without legacy fields)
  3. Try legacy header format (includes LastCommitHash, ConsensusHash, LastResultsHash)

The Legacy field is automatically populated during deserialization when legacy fields are detected in the protobuf unknown fields (field numbers 5, 7, 9).

## For Block Producers

New blocks should use the slim header format by default (Legacy == nil). The legacy encoding is only required when:

  • Syncing historical blocks from genesis
  • Interoperating with legacy nodes
  • Verifying signatures on historical blocks

## For Node Operators

Nodes will automatically:

  • Decode legacy headers when syncing from genesis
  • Verify signatures using the appropriate format
  • Handle mixed networks with both old and new nodes

No configuration changes are required for the migration.

## Legacy Field Defaults

When encoding legacy headers, ConsensusHash defaults to a 32-byte zero hash if not explicitly set, matching the historical behavior. Other legacy fields remain nil if unset.

func (*LegacyHeaderFields) Clone 

func (l *LegacyHeaderFields) Clone() *LegacyHeaderFields

Clone returns a deep copy of the legacy fields.

func (*LegacyHeaderFields) EnsureDefaults 

func (l *LegacyHeaderFields) EnsureDefaults()

EnsureDefaults initialises missing legacy fields with their historical default values so that the legacy protobuf payload matches the pre-change encoding.

func (*LegacyHeaderFields) IsZero 

func (l *LegacyHeaderFields) IsZero() bool

IsZero reports whether all legacy fields are unset.

type Metadata 

type Metadata struct {
	ChainID      string
	Height       uint64
	Time         uint64
	LastDataHash Hash
}

Metadata defines metadata for Data struct to help with p2p gossiping.

func (*Metadata) FromProto 

func (m *Metadata) FromProto(other *pb.Metadata) error

FromProto fills Metadata with data from its protobuf representation.

func (*Metadata) MarshalBinary 

func (m *Metadata) MarshalBinary() ([]byte, error)

MarshalBinary encodes Metadata into binary form and returns it.

func (*Metadata) ToProto 

func (m *Metadata) ToProto() *pb.Metadata

ToProto converts Metadata into protobuf representation and returns it.

func (*Metadata) UnmarshalBinary 

func (m *Metadata) UnmarshalBinary(metadata []byte) error

UnmarshalBinary decodes binary form of Metadata into object.

type Signature 

type Signature []byte

Signature represents signature of block creator.

func GetSignature 

func GetSignature(header Header, signer signer.Signer) (Signature, error)

GetSignature returns a signature from the given private key over the given header

func (*Signature) ValidateBasic 

func (signature *Signature) ValidateBasic() error

ValidateBasic performs basic validation of a signature.

type SignedData 

type SignedData struct {
	Data
	Signature Signature
	Signer    Signer
}

SignedData combines Data and its signature.

func (*SignedData) FromProto 

func (sd *SignedData) FromProto(other *pb.SignedData) error

FromProto fills SignedData with data from protobuf representation.

func (*SignedData) MarshalBinary 

func (sd *SignedData) MarshalBinary() ([]byte, error)

MarshalBinary encodes SignedData into binary form and returns it.

func (*SignedData) ToProto 

func (sd *SignedData) ToProto() (*pb.SignedData, error)

ToProto converts SignedData into protobuf representation and returns it.

func (*SignedData) UnmarshalBinary 

func (sd *SignedData) UnmarshalBinary(data []byte) error

UnmarshalBinary decodes binary form of SignedData into object.

type SignedHeader 

type SignedHeader struct {
	Header
	// Note: This is backwards compatible as ABCI exported types are not affected.
	Signature Signature
	Signer    Signer
	// contains filtered or unexported fields
}

SignedHeader combines Header and its signature.

Used mostly for gossiping.

func GetFirstSignedHeader 

func GetFirstSignedHeader(signer signer.Signer, chainID string) (*SignedHeader, error)

GetFirstSignedHeader creates a 1st signed header for a chain, given a valset and signing key.

func GetRandomNextSignedHeader 

func GetRandomNextSignedHeader(signedHeader *SignedHeader, signer signer.Signer, chainID string) (*SignedHeader, error)

GetRandomNextSignedHeader returns a signed header with random data and height of +1 from the provided signed header

func GetRandomSignedHeader 

func GetRandomSignedHeader(chainID string) (*SignedHeader, crypto.PrivKey, error)

GetRandomSignedHeader generates a signed header with random data and returns it.

func GetRandomSignedHeaderCustom 

func GetRandomSignedHeaderCustom(config *HeaderConfig, chainID string) (*SignedHeader, error)

GetRandomSignedHeaderCustom creates a signed header based on the provided HeaderConfig.

func (*SignedHeader) FromProto 

func (sh *SignedHeader) FromProto(other *pb.SignedHeader) error

FromProto fills SignedHeader with data from protobuf representation. The contained Signer can only be used to verify signatures, not to sign messages.

func (*SignedHeader) IsZero 

func (sh *SignedHeader) IsZero() bool

IsZero returns true if the SignedHeader is nil

func (*SignedHeader) MarshalBinary 

func (sh *SignedHeader) MarshalBinary() ([]byte, error)

MarshalBinary encodes SignedHeader into binary form and returns it.

func (*SignedHeader) New 

func (sh *SignedHeader) New() *SignedHeader

New creates a new SignedHeader.

func (*SignedHeader) SetCustomVerifierForAggregator 

func (sh *SignedHeader) SetCustomVerifierForAggregator(provider AggregatorNodeSignatureBytesProvider)

SetCustomVerifierForAggregator sets a custom signature provider for the SignedHeader. If set, ValidateBasic will use this function to verify the signature.

func (*SignedHeader) SetCustomVerifierForSyncNode 

func (sh *SignedHeader) SetCustomVerifierForSyncNode(provider SyncNodeSignatureBytesProvider)

SetCustomVerifierForSyncNode sets a custom signature provider for the SignedHeader. If set, ValidateBasic will use this function to verify the signature.

func (*SignedHeader) ToProto 

func (sh *SignedHeader) ToProto() (*pb.SignedHeader, error)

ToProto converts SignedHeader into protobuf representation and returns it.

func (*SignedHeader) UnmarshalBinary 

func (sh *SignedHeader) UnmarshalBinary(data []byte) error

UnmarshalBinary decodes binary form of SignedHeader into object.

func (*SignedHeader) ValidateBasic 

func (sh *SignedHeader) ValidateBasic() error

Validate performs basic validation of a signed header for the aggregator node.

func (*SignedHeader) ValidateBasicWithData 

func (sh *SignedHeader) ValidateBasicWithData(data *Data) error

ValidateBasicWithData performs basic validator of a signed header, granted data for syncing node.

func (*SignedHeader) Verify 

func (sh *SignedHeader) Verify(untrstH *SignedHeader) error

Verify verifies the signed header.

type Signer 

type Signer struct {
	PubKey  crypto.PubKey
	Address []byte
}

Signer is a type that can verify messages.

func NewSigner 

func NewSigner(pubKey crypto.PubKey) (Signer, error)

NewSigner creates a new signer from a public key.

func (*Signer) Verify 

func (s *Signer) Verify(vote []byte, signature []byte) (bool, error)

Verify verifies a vote with a signature.

type State 

type State struct {
	Version Version

	// immutable
	ChainID       string
	InitialHeight uint64

	// LastBlockHeight=0 at genesis (ie. block(H=0) does not exist)
	LastBlockHeight uint64
	LastBlockTime   time.Time

	// LastHeaderHash is the hash of the header of the last block
	LastHeaderHash Hash

	// DAHeight identifies DA block containing the latest applied Evolve block.
	DAHeight uint64

	// the latest AppHash we've received from calling abci.Commit()
	AppHash []byte
}

State contains information about current state of the blockchain.

func (State) AssertValidForNextState 

func (s State) AssertValidForNextState(header *SignedHeader, data *Data) error

AssertValidForNextState performs common validation of a header and data against the current state. It assumes any context-specific basic header checks and verifier setup have already been performed

func (*State) FromProto 

func (s *State) FromProto(other *pb.State) error

FromProto fills State with data from its protobuf representation.

func (*State) NextState 

func (s *State) NextState(header Header, stateRoot []byte) (State, error)

func (*State) ToProto 

func (s *State) ToProto() (*pb.State, error)

ToProto converts State into protobuf representation and returns it.

type SyncNodeSignatureBytesProvider 

type SyncNodeSignatureBytesProvider func(context.Context, *Header, *Data) ([]byte, error)

SyncNodeSignatureBytesProvider defines the function type for providing a signature payload to be verified by syncing nodes.

type Tx 

type Tx []byte

Tx represents transaction.

func GetRandomTx 

func GetRandomTx() Tx

GetRandomTx returns a tx with random data

type Txs 

type Txs []Tx

Txs represents a slice of transactions.

type ValidatorHasherProvider 

type ValidatorHasherProvider func(
	proposerAddress []byte,
	pubKey crypto.PubKey,
) (Hash, error)

ValidatorHasherProvider defines the function type for hashing a validator's public key and address.

type Version 

type Version struct {
	Block uint64
	App   uint64
}

Version captures the consensus rules for processing a block in the blockchain, including all blockchain data structures and the rules of the application's state transition machine. This is equivalent to the tmversion.Consensus type in Tendermint.

Source Files

View all Source files

Directories

Path Synopsis
pb
evnode/v1
evnode/v1/v1connect

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.