protocol

package
v1.1.2 Latest Latest
Warning

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

Go to latest
Published: Dec 21, 2025 License: Apache-2.0 Imports: 18 Imported by: 3

Documentation

Overview

Package protocol provides context utilities for threshold signature protocols

Package protocol provides the ultimate optimized protocol handler with Lux integration

Package protocol provides unified interfaces for threshold signature protocols.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Group added in v1.1.0

func Group(ctx context.Context) curve.Curve

Group returns the curve group

func Parties added in v1.1.0

func Parties(ctx context.Context) []party.ID

Parties returns all party IDs

func Protocol added in v1.1.0

func Protocol(ctx context.Context) string

Protocol returns the protocol name

func Self added in v1.1.0

func Self(ctx context.Context) party.ID

Self returns the local party ID

func SessionID added in v1.1.0

func SessionID(ctx context.Context) []byte

SessionID returns the session identifier

func Threshold added in v1.1.0

func Threshold(ctx context.Context) int

Threshold returns the threshold value

func WithSession added in v1.1.0

func WithSession(ctx context.Context, info SessionInfo) context.Context

WithSession sets session info in context (call once at protocol start)

Types

type Config added in v1.0.1

type Config struct {
	// Worker pools
	Workers         int // CPU cores * 2 by default
	PriorityWorkers int // 4 by default

	// Channels
	BufferSize     int // 10000 by default
	PriorityBuffer int // 1000 by default

	// Timeouts
	MessageTimeout  time.Duration // 30s by default
	RoundTimeout    time.Duration // 60s by default
	ProtocolTimeout time.Duration // 5m by default

	// Performance
	EnableBatching       bool          // true by default
	BatchSize            int           // 100 by default
	BatchTimeout         time.Duration // 10ms by default
	EnableCompression    bool          // true for large messages
	CompressionThreshold int           // 1KB by default

	// Memory
	EnablePooling  bool // true by default
	MaxMessageSize int  // 10MB by default

	// Reliability
	RetryAttempts int           // 3 by default
	RetryBackoff  time.Duration // 1s by default
}

Config for handler - optimized for maximum performance

func DefaultConfig added in v1.0.1

func DefaultConfig() *Config

DefaultConfig returns the perfect configuration

type Context added in v1.1.0

type Context = context.Context

Context is just an alias for standard context.Context for cleaner call sites

type Error

type Error struct {
	// Culprit is empty if the identity of the misbehaving party cannot be known.
	Culprits []party.ID
	// Err is the underlying error.
	Err error
}

Error is a custom error for protocols which contains information about the responsible round in which it occurred, and the party responsible.

func (Error) Error

func (e Error) Error() string

Error implement error.

func (Error) Unwrap

func (e Error) Unwrap() error

Unwrap implement errors.Wrapper.

type Handler

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

Handler is the ONLY handler for threshold protocols - optimized for perfection

func NewHandler added in v1.0.1

func NewHandler(
	ctx context.Context,
	logger log.Logger,
	registry prometheus.Registerer,
	create StartFunc,
	sessionID []byte,
	config *Config,
) (*Handler, error)

NewHandler creates the perfect protocol handler

func NewMultiHandler

func NewMultiHandler(create StartFunc, sessionID []byte) (*Handler, error)

NewMultiHandler creates a handler with default config (temporary compatibility)

func (*Handler) Accept

func (h *Handler) Accept(msg *Message)

Accept accepts a message with non-blocking queue management

func (*Handler) CanAccept

func (h *Handler) CanAccept(msg *Message) bool

CanAccept checks if a message can be accepted

func (*Handler) Listen

func (h *Handler) Listen() <-chan *Message

Listen returns the output channel

func (*Handler) Result

func (h *Handler) Result() (interface{}, error)

Result returns the protocol result immediately if available

func (*Handler) Stop

func (h *Handler) Stop()

Stop gracefully shuts down the handler

func (*Handler) WaitForResult added in v1.0.1

func (h *Handler) WaitForResult() (interface{}, error)

WaitForResult blocks until the protocol completes or times out

type KeyID added in v1.0.1

type KeyID struct {
	// ProtocolID identifies the protocol (e.g., "cmp/keygen", "frost/keygen")
	ProtocolID string
	// Group is the elliptic curve group being used
	Group curve.Curve
	// PublicKey is the shared public key (if available)
	PublicKey curve.Point
	// PartyIDs is the canonical ordered list of all parties
	PartyIDs []party.ID
	// Threshold is the threshold parameter
	Threshold int
	// Generation is an optional generation counter for key refresh
	Generation uint32
}

KeyID represents a stable, phase-independent identifier for a key generation context. This is used for cross-phase cryptographic commitments and verification.

Unlike sessionID which changes per phase for anti-replay, KeyID remains constant across all phases (keygen, presign, sign) to ensure cryptographic bindings remain valid.

func NewKeyID added in v1.0.1

func NewKeyID(protocolID string, group curve.Curve, publicKey curve.Point, partyIDs []party.ID, threshold int, generation uint32) *KeyID

NewKeyID creates a new KeyID for a key generation context. The partyIDs will be canonically sorted to ensure consistency.

func (*KeyID) Bytes added in v1.0.1

func (k *KeyID) Bytes() []byte

Bytes returns the hash sum of the KeyID as a byte slice.

func (*KeyID) Hash added in v1.0.1

func (k *KeyID) Hash() *hash.Hash

Hash returns a cryptographic hash of the KeyID that can be used for commitments and verification across phases.

func (*KeyID) HashForParty added in v1.0.1

func (k *KeyID) HashForParty(id party.ID) *hash.Hash

HashForParty returns a hash initialized with the KeyID and a specific party ID. This is useful for party-specific commitments that need to be stable across phases.

type Message

type Message struct {
	// SSID is a byte string which uniquely identifies the session this message belongs to.
	SSID []byte
	// From is the party.ID of the sender
	From party.ID
	// To is the intended recipient for this message. If To == "", then the message should be sent to all.
	To party.ID
	// Protocol identifies the protocol this message belongs to
	Protocol string
	// RoundNumber is the index of the round this message belongs to
	RoundNumber round.Number
	// Data is the actual content consumed by the round.
	Data []byte
	// Broadcast indicates whether this message should be reliably broadcast to all participants.
	Broadcast bool
	// BroadcastVerification is the hash of all messages broadcast by the parties,
	// and is included in all messages in the round following a broadcast round.
	BroadcastVerification []byte
	// Compressed indicates whether the Data field is compressed
	Compressed bool
}

func (*Message) Hash

func (m *Message) Hash() []byte

Hash returns a 64 byte hash of the message content, including the headers. Can be used to produce a signature for the message.

func (Message) IsFor

func (m Message) IsFor(id party.ID) bool

IsFor returns true if the message is intended for the designated party.

func (*Message) MarshalBinary

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

func (Message) String

func (m Message) String() string

String implements fmt.Stringer.

func (*Message) UnmarshalBinary

func (m *Message) UnmarshalBinary(data []byte) error

type MessageStore added in v1.0.1

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

MessageStore provides zero-contention sharded message storage

func (*MessageStore) Load added in v1.0.1

func (ms *MessageStore) Load(roundNum round.Number, from party.ID) (*Message, bool)

func (*MessageStore) LoadAll added in v1.0.1

func (ms *MessageStore) LoadAll(roundNum round.Number) map[party.ID]*Message

func (*MessageStore) Store added in v1.0.1

func (ms *MessageStore) Store(roundNum round.Number, from party.ID, msg *Message)

type Metrics added in v1.0.1

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

Metrics for Prometheus monitoring

type MultiHandler

type MultiHandler = Handler

MultiHandler is an alias for Handler for temporary compatibility

type ProtocolAdapter added in v1.0.1

type ProtocolAdapter[C ThresholdConfig] struct {
	// contains filtered or unexported fields
}

ProtocolAdapter wraps a specific protocol implementation to provide a unified interface

func NewProtocolAdapter added in v1.0.1

func NewProtocolAdapter[C ThresholdConfig](protocol ThresholdProtocol, config C) *ProtocolAdapter[C]

NewProtocolAdapter creates a new adapter for a specific protocol

func (*ProtocolAdapter[C]) Execute added in v1.0.1

func (a *ProtocolAdapter[C]) Execute(operation func(ThresholdConfig) (StartFunc, error)) (StartFunc, error)

Execute runs a protocol operation with the wrapped configuration

type ReshareableProtocol added in v1.0.1

type ReshareableProtocol interface {
	ThresholdProtocol

	// Reshare changes the participant set
	Reshare(config ThresholdConfig, newParticipants []party.ID, newThreshold int) (StartFunc, error)

	// AddParties adds new participants
	AddParties(config ThresholdConfig, newParties []party.ID) (StartFunc, error)

	// RemoveParties removes participants
	RemoveParties(config ThresholdConfig, partiesToRemove []party.ID) (StartFunc, error)
}

ReshareableProtocol extends ThresholdProtocol with resharing capabilities

type SessionInfo added in v1.1.0

type SessionInfo struct {
	SessionID []byte
	SelfID    party.ID
	PartyIDs  []party.ID
	Threshold int
	Group     curve.Curve
	Protocol  string // "cmp", "frost", "lss", etc.
}

SessionInfo holds immutable protocol session information

func MustSession added in v1.1.0

func MustSession(ctx context.Context) SessionInfo

MustSession panics if session info is missing (fail-fast pattern)

type SignatureScheme added in v1.0.1

type SignatureScheme int

SignatureScheme represents the type of signature that can be produced

const (
	ECDSA SignatureScheme = iota
	Schnorr
	EdDSA
)

type StartFunc

type StartFunc func(sessionID []byte) (round.Session, error)

StartFunc creates the first round of a protocol

type ThresholdConfig added in v1.0.1

type ThresholdConfig interface {
	// Core identity and parameters
	GetID() party.ID
	GetThreshold() int
	GetGroup() curve.Curve

	// Key material
	GetPrivateShare() curve.Scalar
	GetPublicKey() (curve.Point, error)
	GetPublicShare(id party.ID) (curve.Point, error)

	// Protocol-specific data
	GetChainKey() []byte
	GetRID() []byte

	// Validation
	Validate() error
	IsCompatible(other ThresholdConfig) bool
}

ThresholdConfig is a unified interface for all threshold protocol configurations. This allows LSS to work with any underlying protocol (CMP, FROST, etc.)

type ThresholdProtocol added in v1.0.1

type ThresholdProtocol interface {
	// Keygen creates a new distributed key
	Keygen(group curve.Curve, selfID party.ID, participants []party.ID, threshold int) (StartFunc, error)

	// Sign creates a signature with the given signers
	Sign(config ThresholdConfig, signers []party.ID, message []byte) (StartFunc, error)

	// Refresh updates shares without changing the key
	Refresh(config ThresholdConfig) (StartFunc, error)

	// GetScheme returns the signature scheme this protocol implements
	GetScheme() SignatureScheme

	// SupportsResharing indicates if the protocol supports dynamic resharing
	SupportsResharing() bool
}

ThresholdProtocol defines operations that any threshold protocol must support

type ThresholdSigner added in v1.0.1

type ThresholdSigner[S any] interface {
	// Sign produces a signature of type S
	Sign(config ThresholdConfig, signers []party.ID, message []byte) (S, error)

	// Verify checks if a signature is valid
	Verify(signature S, publicKey curve.Point, message []byte) bool
}

ThresholdSigner is a generic interface for signature generation

type TwoPartyHandler

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

TwoPartyHandler represents a restriction of the Handler for 2 party protocols.

func NewTwoPartyHandler

func NewTwoPartyHandler(create StartFunc, sessionID []byte, leader bool) (*TwoPartyHandler, error)

func (*TwoPartyHandler) Accept

func (h *TwoPartyHandler) Accept(msg *Message)

func (*TwoPartyHandler) CanAccept

func (h *TwoPartyHandler) CanAccept(msg *Message) bool

func (*TwoPartyHandler) Listen

func (h *TwoPartyHandler) Listen() <-chan *Message

func (*TwoPartyHandler) Result

func (h *TwoPartyHandler) Result() (interface{}, error)

func (*TwoPartyHandler) Stop

func (h *TwoPartyHandler) Stop()

func (*TwoPartyHandler) String

func (h *TwoPartyHandler) String() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL