common

package
v0.188.0 Latest Latest
Warning

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

 Go to latest Published: Jul 14, 2026 License: Apache-2.0 Imports: 12 Imported by: 30

Documentation

Overview

The common package contains types used by multiple mini-protocols

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ApplyDefaultKESVerifier added in v0.146.0 

func ApplyDefaultKESVerifier(auth *MessageAuthenticator)

ApplyDefaultKESVerifier applies the package-level default KES verifier to the provided authenticator if a default has been set.

func ComputeDmqMessageID added in v0.170.0 

func ComputeDmqMessageID(payload DmqMessagePayload) ([]byte, error)

ComputeDmqMessageID returns Blake2b-256(cbor(messagePayload)).

func MarshalDmqMessageLegacyCBOR added in v0.170.0 

func MarshalDmqMessageLegacyCBOR(msg DmqMessage) ([]byte, error)

MarshalDmqMessageLegacyCBOR encodes the legacy V1 wire shape used before CIP-0137 moved messageId from messagePayload to message.

func SetDefaultKESVerifier added in v0.146.0 

func SetDefaultKESVerifier(
	v func([]byte, []byte, []byte, uint64, uint64, uint64) (bool, error),
)

SetDefaultKESVerifier sets a package-level default KES verifier. Callers (e.g. main) can set this once at startup to avoid per-constructor imports of ledger.

Types

type AlreadyReceivedReason added in v0.146.0 

type AlreadyReceivedReason struct{}

AlreadyReceivedReason indicates the message was already received and processed.

func (AlreadyReceivedReason) RejectReasonType added in v0.146.0 

func (r AlreadyReceivedReason) RejectReasonType() uint8

RejectReasonType returns 1 for already received reason

type DmqMessage added in v0.146.0 

type DmqMessage struct {
	cbor.StructAsArray
	// MessageID is the Blake2b-256 hash of the CBOR-encoded payload.
	MessageID []byte
	// Payload is the unsigned message payload
	Payload DmqMessagePayload
	// KESSignature is the 448-byte KES signature over the payload
	KESSignature []byte
	// OperationalCertificate contains the KES certificate and cold signature
	OperationalCertificate OperationalCertificate
	// ColdVerificationKey is the 32-byte SPO cold public key
	ColdVerificationKey []byte
}

DmqMessage represents a complete authenticated DMQ message with cryptographic proofs.

func (DmqMessage) ID added in v0.170.0 

func (m DmqMessage) ID() []byte

ID returns the message id, accepting Payload.MessageID as a legacy alias.

func (*DmqMessage) IsValid added in v0.146.0 

func (m *DmqMessage) IsValid() bool

IsValid checks if a message has not yet expired by comparing its expiration time against the current Unix timestamp.

func (*DmqMessage) IsValidAt added in v0.146.0 

func (m *DmqMessage) IsValidAt(t time.Time) bool

IsValidAt checks if a message has not yet expired when evaluated at the provided time. This variant is provided for testability so callers can validate expiration behavior deterministically by passing a specific timestamp.

func (DmqMessage) MarshalCBOR added in v0.170.0 

func (m DmqMessage) MarshalCBOR() ([]byte, error)

MarshalCBOR encodes the message using the current CIP-0137 shape: [messageId, messagePayload, kesSignature, operationalCertificate, coldVerificationKey].

func (*DmqMessage) SetComputedMessageID added in v0.170.0 

func (m *DmqMessage) SetComputedMessageID() error

SetComputedMessageID computes and stores the CIP-0137 message id.

func (*DmqMessage) SetMessageID added in v0.170.0 

func (m *DmqMessage) SetMessageID(messageID []byte)

SetMessageID updates both the current field and the legacy payload alias.

func (*DmqMessage) UnmarshalCBOR added in v0.170.0 

func (m *DmqMessage) UnmarshalCBOR(data []byte) error

UnmarshalCBOR decodes both the current CIP-0137 message shape and the legacy V1 implementation shape, which encoded [payload, signature, opcert, coldKey] and kept messageId inside payload.

type DmqMessagePayload added in v0.146.0 

type DmqMessagePayload struct {
	cbor.StructAsArray
	// MessageID is a legacy alias kept for source compatibility. It is not
	// part of the current CIP-0137 messagePayload CBOR encoding.
	MessageID []byte `cbor:"-"`
	// MessageBody contains the actual message data
	MessageBody []byte
	// KESPeriod is the KES key evolution step period
	KESPeriod uint64
	// ExpiresAt is the Unix timestamp when the message expires
	ExpiresAt uint32
}

DmqMessagePayload represents the unsigned message payload for DMQ messages.

func (DmqMessagePayload) MarshalCBOR added in v0.170.0 

func (p DmqMessagePayload) MarshalCBOR() ([]byte, error)

MarshalCBOR encodes the payload using the current CIP-0137 shape: [messageBody, kesPeriod, expiresAt].

func (*DmqMessagePayload) UnmarshalCBOR added in v0.170.0 

func (p *DmqMessagePayload) UnmarshalCBOR(data []byte) error

UnmarshalCBOR decodes both the current payload shape and the legacy V1 implementation shape, which included messageId inside messagePayload.

type ExpiredReason added in v0.146.0 

type ExpiredReason struct{}

ExpiredReason indicates the message's TTL has passed.

func (ExpiredReason) RejectReasonType added in v0.146.0 

func (r ExpiredReason) RejectReasonType() uint8

RejectReasonType returns 2 for expired reason

type InvalidReason added in v0.146.0 

type InvalidReason struct {
	// Message describes the validation error
	Message string
}

InvalidReason indicates the message failed validation checks.

func (InvalidReason) RejectReasonType added in v0.146.0 

func (r InvalidReason) RejectReasonType() uint8

RejectReasonType returns 0 for invalid reason

type MessageAuthenticator added in v0.146.0 

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

MessageAuthenticator handles DMQ message authentication verification per CIP-0137. It verifies message signatures, operational certificates, SPO pool registration, and KES period rotation to prevent replay attacks and unauthorized messages.

func NewMessageAuthenticator added in v0.146.0 

func NewMessageAuthenticator(logger *slog.Logger) *MessageAuthenticator

NewMessageAuthenticator creates a new message authenticator.

func NewNoOpAuthenticator added in v0.146.0 

func NewNoOpAuthenticator(logger *slog.Logger) *MessageAuthenticator

NewNoOpAuthenticator returns an authenticator that performs no validation. Suitable for testing or trusted environments where authentication is intentionally disabled.

func (*MessageAuthenticator) IsSPOPoolRegistered added in v0.146.0 

func (m *MessageAuthenticator) IsSPOPoolRegistered(poolID string) bool

IsSPOPoolRegistered returns whether a poolID is known and registered. This provides a stable public API for tests and callers instead of accessing internal maps directly.

func (*MessageAuthenticator) RegisterSPOPool added in v0.146.0 

func (m *MessageAuthenticator) RegisterSPOPool(poolID string)

RegisterSPOPool adds an SPO pool ID to the known active pools.

func (*MessageAuthenticator) RemoveKESOpCertCacheEntry added in v0.146.0 

func (m *MessageAuthenticator) RemoveKESOpCertCacheEntry(poolID string)

RemoveKESOpCertCacheEntry removes a pool entry from the KES opcert cache. The cache does not evict automatically, so long-running nodes should call this (or wrap the authenticator with their own TTL/LRU policy) when pools are unregistered or otherwise inactive to avoid unbounded growth.

func (*MessageAuthenticator) SetAllowInsecureKES added in v0.158.0 

func (m *MessageAuthenticator) SetAllowInsecureKES(allow bool)

SetAllowInsecureKES enables or disables insecure KES verification bypass. WARNING: Setting this to true disables cryptographic verification of block producer identity. Only use for testing or when KES verification is handled externally.

func (*MessageAuthenticator) SetKESVerifier added in v0.146.0 

func (m *MessageAuthenticator) SetKESVerifier(
	v func([]byte, []byte, []byte, uint64, uint64, uint64) (bool, error),
)

SetKESVerifier sets a custom KES verifier function used by VerifyMessage. This avoids hard dependency on the ledger package in the protocol/common package and lets callers inject the ledger verifier when available. Thread-safe; uses atomic.Value for concurrent access.

func (*MessageAuthenticator) UnregisterSPOPool added in v0.146.0 

func (m *MessageAuthenticator) UnregisterSPOPool(poolID string)

UnregisterSPOPool removes an SPO pool ID from known pools.

func (*MessageAuthenticator) VerifyMessage added in v0.146.0 

func (m *MessageAuthenticator) VerifyMessage(msg *DmqMessage) error

VerifyMessage performs complete message authentication as per CIP-0137. It verifies: operational certificate, KES signature, SPO pool registration, message ID, and KES period rotation. Returns error if verification fails (which is a protocol violation and should result in peer disconnection). VerifyMessage verifies a message using no explicit slot (slot==0). Use VerifyMessageWithSlot when the caller has an explicit slot value to supply.

func (*MessageAuthenticator) VerifyMessageWithSlot added in v0.146.0 

func (m *MessageAuthenticator) VerifyMessageWithSlot(
	msg *DmqMessage,
	slot uint64,
) error

VerifyMessageWithSlot verifies a message using an explicit slot value. When available, callers should supply the slot (e.g., from the block header) so KES period/current period checks are accurate.

type MessageIDAndSize added in v0.146.0 

type MessageIDAndSize struct {
	cbor.StructAsArray
	// MessageID is the unique message identifier
	MessageID []byte
	// SizeInBytes is the total size of the serialized message
	SizeInBytes uint32
}

MessageIDAndSize represents a message identifier with its serialized size in bytes.

type OperationalCertificate added in v0.146.0 

type OperationalCertificate struct {
	cbor.StructAsArray
	// KESVerificationKey is the 32-byte KES public key
	KESVerificationKey []byte
	// IssueNumber is the certificate issue number (for rotation tracking)
	IssueNumber uint64
	// KESPeriod is the KES period at certificate creation
	KESPeriod uint64
	// ColdSignature is the 64-byte signature by the cold key
	ColdSignature []byte
}

OperationalCertificate represents an SPO's operational certificate used for message authentication.

type OtherReason added in v0.146.0 

type OtherReason struct {
	// Message describes the other rejection reason
	Message string
}

OtherReason indicates some other rejection cause not covered by the standard reasons.

func (OtherReason) RejectReasonType added in v0.146.0 

func (r OtherReason) RejectReasonType() uint8

RejectReasonType returns 3 for other reason

type Point 

type Point struct {
	cbor.StructAsArray
	Slot uint64
	Hash []byte
}

The Point type represents a point on the blockchain. It consists of a slot number and block hash

func NewPoint 

func NewPoint(slot uint64, blockHash []byte) Point

NewPoint returns a Point object with the specified slot number and block hash

func NewPointOrigin 

func NewPointOrigin() Point

NewPointOrigin returns an "empty" Point object which represents the origin of the blockchain

func (*Point) MarshalCBOR 

func (p *Point) MarshalCBOR() ([]byte, error)

MarshalCBOR is a helper function for encoding a Point object to CBOR. The object content can vary, so we need to do some special handling when encoding. It is not intended to be called directly.

func (*Point) UnmarshalCBOR 

func (p *Point) UnmarshalCBOR(data []byte) error

UnmarshalCBOR is a helper function for decoding a Point object from CBOR. The object content can vary, so we need to do some special handling when decoding. It is not intended to be called directly.

type RejectReason added in v0.146.0 

type RejectReason interface {
	// RejectReasonType returns the reason code (0-3)
	RejectReasonType() uint8
}

RejectReason provides information about why a submitted message was rejected. Implementations must support the following reason types via RejectReasonType().

func FromRejectReasonData added in v0.146.0 

func FromRejectReasonData(data RejectReasonData) RejectReason

FromRejectReasonData converts RejectReasonData back to a concrete public API type. This is used during decoding to reconstruct the public RejectReason interface type.

type RejectReasonData added in v0.146.0 

type RejectReasonData struct {
	cbor.StructAsArray
	Type    uint8
	Message string
}

RejectReasonData is a concrete, CBOR-marshalable representation of a reject reason. It encodes as an array [type, message?] where type is 0..3 and message is optional.

func ToRejectReasonData added in v0.146.0 

func ToRejectReasonData(rr RejectReason) RejectReasonData

ToRejectReasonData converts any RejectReason implementation into a concrete RejectReasonData.

func (RejectReasonData) MarshalCBOR added in v0.146.0 

func (r RejectReasonData) MarshalCBOR() ([]byte, error)

MarshalCBOR encodes RejectReasonData as an array [type, message?] for deterministic wire format.

func (RejectReasonData) RejectReasonType added in v0.146.0 

func (r RejectReasonData) RejectReasonType() uint8

RejectReasonType implements the RejectReason interface.

func (*RejectReasonData) UnmarshalCBOR added in v0.146.0 

func (r *RejectReasonData) UnmarshalCBOR(data []byte) error

UnmarshalCBOR decodes a CBOR array [type, message?] back into RejectReasonData.

type TTLValidator added in v0.146.0 

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

TTLValidator enforces message time-to-live (TTL) constraints per CIP-0137. It validates that messages have not expired and rejects messages with expiration timestamps too far in the future.

func NewNoOpTTLValidator added in v0.146.0 

func NewNoOpTTLValidator(logger *slog.Logger) *TTLValidator

NewNoOpTTLValidator returns a validator that performs no TTL checks. Intended for trusted/testing environments where TTL enforcement is explicitly disabled.

func NewTTLValidator added in v0.146.0 

func NewTTLValidator(
	maxAllowedTTL time.Duration,
	logger *slog.Logger,
) *TTLValidator

NewTTLValidator creates a new TTL validator with configurable max TTL. If maxAllowedTTL is 0, defaults to 30 minutes per CIP-0137. Negative values are clamped to 0.

func (*TTLValidator) GetTimeUntilExpiration added in v0.146.0 

func (v *TTLValidator) GetTimeUntilExpiration(msg *DmqMessage) time.Duration

GetTimeUntilExpiration returns the time remaining before message expires, or 0 if already expired.

func (*TTLValidator) ValidateMessageTTL added in v0.146.0 

func (v *TTLValidator) ValidateMessageTTL(msg *DmqMessage) error

ValidateMessageTTL checks if a message's expiration is valid (not expired and not too far in future). It evaluates the message against the current wall-clock time. For deterministic evaluation against a caller-supplied time, use TTLValidator.ValidateMessageTTLAt.

func (*TTLValidator) ValidateMessageTTLAt added in v0.171.0 

func (v *TTLValidator) ValidateMessageTTLAt(
	msg *DmqMessage,
	now time.Time,
) error

ValidateMessageTTLAt checks if a message's expiration is valid (not expired and not too far in future) when evaluated at the provided point in time. This variant lets callers pin the evaluation moment explicitly, which is useful for tests, deterministic replay, or evaluating messages against a clock that is not the local wall clock.

A disabled (no-op) validator returns nil regardless of the message or now value. A nil message returns an error. Otherwise the same max-TTL and expired/too-far-future rules used by TTLValidator.ValidateMessageTTL apply.

type Tip added in v0.109.0 

type Tip struct {
	cbor.StructAsArray
	Point       Point
	BlockNumber uint64
}

Tip represents a Point combined with a block number

Source Files

View all Source files

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.