dkg

README

DKG

Introduction

This is a spec implementation for a generalized DKG protocol for SSV.Network following SIP - DKG.

TODO

• [//] Generalized message processing flow
• spec tests
• specific dkg implementation

Documentation

Index

• func SignOutput(output *Output, privKey *ecdsa.PrivateKey) (types.Signature, error)
• type BlameOutput
• type Config
• type Init
  • func (msg *Init) Decode(data []byte) error
  • func (msg *Init) Encode() ([]byte, error)
  • func (msg *Init) Validate() error
• type KeyGenOutput
• type Message
  • func (msg *Message) Decode(data []byte) error
  • func (msg *Message) Encode() ([]byte, error)
  • func (msg *Message) GetRoot() ([]byte, error)
  • func (msg *Message) Validate() error
• type MsgType
• type Network
• type Node
  • func NewNode(operator *Operator, config *Config) *Node
  • func (n *Node) GetConfig() *Config
  • func (n *Node) ProcessMessage(msg *types.SSVMessage) error
• type Operator
• type Output
  • func (o *Output) GetRoot() ([]byte, error)
• type PartialDepositData
  • func (msg *PartialDepositData) Decode(data []byte) error
  • func (msg *PartialDepositData) Encode() ([]byte, error)
• type Protocol
• type ProtocolOutcome
  • func (o *ProtocolOutcome) IsFailedWithBlame() (bool, error)
• type RequestID
  • func NewRequestID(ethAddress common.Address, index uint32) RequestID
  • func (msg RequestID) GetETHAddress() common.Address
  • func (msg RequestID) GetRoleType() uint32
• type Reshare
  • func (msg *Reshare) Decode(data []byte) error
  • func (msg *Reshare) Encode() ([]byte, error)
  • func (msg *Reshare) Validate() error
• type Runner
• type Runners
  • func (runners Runners) AddRunner(id RequestID, runner Runner)
  • func (runners Runners) DeleteRunner(id RequestID)
  • func (runners Runners) RunnerForID(id RequestID) Runner
• type SignedMessage
  • func (signedMsg *SignedMessage) Decode(data []byte) error
  • func (signedMsg *SignedMessage) Encode() ([]byte, error)
  • func (signedMsg *SignedMessage) GetRoot() ([]byte, error)
  • func (signedMsg *SignedMessage) Validate() error
• type SignedOutput
  • func (msg *SignedOutput) Decode(data []byte) error
  • func (msg *SignedOutput) Encode() ([]byte, error)
• type Storage

Functions

func SignOutput

func SignOutput(output *Output, privKey *ecdsa.PrivateKey) (types.Signature, error)

Types

type BlameOutput

type BlameOutput struct {
	Valid        bool
	BlameMessage []byte
}

BlameOutput is the output of blame round

type Config

type Config struct {
	// Protocol the DKG protocol implementation
	KeygenProtocol      func(network Network, operatorID types.OperatorID, identifier RequestID, init *Init) Protocol
	ReshareProtocol     func(network Network, operatorID types.OperatorID, identifier RequestID, reshare *Reshare, output *KeyGenOutput) Protocol
	Network             Network
	Storage             Storage
	SignatureDomainType types.DomainType
	Signer              types.DKGSigner
}

type Init

type Init struct {
	// OperatorIDs are the operators selected for the DKG
	OperatorIDs []types.OperatorID
	// Threshold DKG threshold for signature reconstruction
	Threshold uint16
	// WithdrawalCredentials used when signing the deposit data
	WithdrawalCredentials []byte
	// Fork is eth2 fork version
	Fork phase0.Version
}

Init is the first message in a DKG which initiates a DKG

func (*Init) Decode

func (msg *Init) Decode(data []byte) error

Decode returns error if decoding failed

func (*Init) Encode

func (msg *Init) Encode() ([]byte, error)

Encode returns a msg encoded bytes or error

func (*Init) Validate

func (msg *Init) Validate() error

type KeyGenOutput

type KeyGenOutput struct {
	Share           *bls.SecretKey
	OperatorPubKeys map[types.OperatorID]*bls.PublicKey
	ValidatorPK     types.ValidatorPK
	Threshold       uint64
}

KeyGenOutput is the bare minimum output from the protocol

type Message

type Message struct {
	MsgType    MsgType
	Identifier RequestID
	Data       []byte
}

func (*Message) Decode

func (msg *Message) Decode(data []byte) error

Decode returns error if decoding failed

func (*Message) Encode

func (msg *Message) Encode() ([]byte, error)

Encode returns a msg encoded bytes or error

func (*Message) GetRoot

func (msg *Message) GetRoot() ([]byte, error)

func (*Message) Validate

func (msg *Message) Validate() error

type MsgType

type MsgType int

const (
	// InitMsgType sent when DKG instance is started by requester
	InitMsgType MsgType = iota
	// ProtocolMsgType is the DKG itself
	ProtocolMsgType
	// DepositDataMsgType post DKG deposit data signatures
	DepositDataMsgType
	// OutputMsgType final output msg used by requester to make deposits and register validator with SSV
	OutputMsgType
	// ReshareMsgType sent when Resharing is requested
	ReshareMsgType
)

type Network

type Network interface {
	// StreamDKGBlame will stream to any subscriber the blame result of the DKG
	StreamDKGBlame(blame *BlameOutput) error
	// StreamDKGOutput will stream to any subscriber the result of the DKG
	StreamDKGOutput(output map[types.OperatorID]*SignedOutput) error
	// BroadcastDKGMessage will broadcast a msg to the dkg network
	BroadcastDKGMessage(msg *SignedMessage) error
}

Network is a collection of funcs for DKG

type Node

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

Node is responsible for receiving and managing DKG session and messages

func NewNode

func NewNode(operator *Operator, config *Config) *Node

func (*Node) GetConfig

func (n *Node) GetConfig() *Config

func (*Node) ProcessMessage

func (n *Node) ProcessMessage(msg *types.SSVMessage) error

ProcessMessage processes network Messages of all types

type Operator

type Operator struct {
	// OperatorID the node's Operator ID
	OperatorID types.OperatorID
	// ETHAddress the operator's eth address used to sign and verify messages against
	ETHAddress common.Address
	// EncryptionPubKey encryption pubkey for shares
	EncryptionPubKey *rsa.PublicKey
}

Operator holds all info regarding a DKG Operator on the network

type Output

type Output struct {
	// RequestID for the DKG instance (not used for signing)
	RequestID RequestID
	// EncryptedShare standard SSV encrypted shares
	EncryptedShare []byte
	// SharePubKey is the share's BLS pubkey
	SharePubKey []byte
	// ValidatorPubKey the resulting public key corresponding to the shared private key
	ValidatorPubKey types.ValidatorPK
	// DepositDataSignature reconstructed signature of DepositMessage according to eth2 spec
	DepositDataSignature types.Signature
}

Output is the last message in every DKG which marks a specific node's end of process

func (*Output) GetRoot

func (o *Output) GetRoot() ([]byte, error)

type PartialDepositData

type PartialDepositData struct {
	Signer    types.OperatorID
	Root      []byte
	Signature types.Signature
}

PartialDepositData contains a partial deposit data signature

func (*PartialDepositData) Decode

func (msg *PartialDepositData) Decode(data []byte) error

Decode returns error if decoding failed

func (*PartialDepositData) Encode

func (msg *PartialDepositData) Encode() ([]byte, error)

Encode returns a msg encoded bytes or error

type Protocol

type Protocol interface {
	Start() error
	// ProcessMsg returns true and a bls share if finished
	ProcessMsg(msg *SignedMessage) (bool, *ProtocolOutcome, error)
}

Protocol is an interface for all DKG protocol to support a variety of protocols for future upgrades

type ProtocolOutcome

type ProtocolOutcome struct {
	ProtocolOutput *KeyGenOutput
	BlameOutput    *BlameOutput
}

func (*ProtocolOutcome) IsFailedWithBlame

func (o *ProtocolOutcome) IsFailedWithBlame() (bool, error)

type RequestID

type RequestID [24]byte

func NewRequestID

func NewRequestID(ethAddress common.Address, index uint32) RequestID

func (RequestID) GetETHAddress

func (msg RequestID) GetETHAddress() common.Address

func (RequestID) GetRoleType

func (msg RequestID) GetRoleType() uint32

type Reshare

type Reshare struct {
	// ValidatorPK is the the public key to be reshared
	ValidatorPK types.ValidatorPK
	// OperatorIDs are the operators in the new set
	OperatorIDs []types.OperatorID
	// Threshold is the threshold of the new set
	Threshold uint16
}

Reshare triggers the resharing protocol

func (*Reshare) Decode

func (msg *Reshare) Decode(data []byte) error

Decode returns error if decoding failed

func (*Reshare) Encode

func (msg *Reshare) Encode() ([]byte, error)

Encode returns a msg encoded bytes or error

func (*Reshare) Validate

func (msg *Reshare) Validate() error

type Runner

type Runner interface {
	ProcessMsg(msg *SignedMessage) (bool, error)
}

type Runners

type Runners map[string]Runner

Runners is a map of dkg runners mapped by dkg ID.

func (Runners) AddRunner

func (runners Runners) AddRunner(id RequestID, runner Runner)

func (Runners) DeleteRunner

func (runners Runners) DeleteRunner(id RequestID)

func (Runners) RunnerForID

func (runners Runners) RunnerForID(id RequestID) Runner

RunnerForID returns a Runner from the provided msg ID, or nil if not found

type SignedMessage

type SignedMessage struct {
	Message   *Message
	Signer    types.OperatorID
	Signature types.Signature
}

func (*SignedMessage) Decode

func (signedMsg *SignedMessage) Decode(data []byte) error

Decode returns error if decoding failed

func (*SignedMessage) Encode

func (signedMsg *SignedMessage) Encode() ([]byte, error)

Encode returns a msg encoded bytes or error

func (*SignedMessage) GetRoot

func (signedMsg *SignedMessage) GetRoot() ([]byte, error)

func (*SignedMessage) Validate

func (signedMsg *SignedMessage) Validate() error

type SignedOutput

type SignedOutput struct {
	// Data signed
	Data *Output
	// Signer Operator ID which signed
	Signer types.OperatorID
	// Signature over Data.GetRoot()
	Signature types.Signature
}

func (*SignedOutput) Decode

func (msg *SignedOutput) Decode(data []byte) error

Decode returns error if decoding failed

func (*SignedOutput) Encode

func (msg *SignedOutput) Encode() ([]byte, error)

Encode returns a msg encoded bytes or error

type Storage

type Storage interface {
	// GetDKGOperator returns true and operator object if found by operator ID
	GetDKGOperator(operatorID types.OperatorID) (bool, *Operator, error)
	SaveKeyGenOutput(output *KeyGenOutput) error
	GetKeyGenOutput(pk types.ValidatorPK) (*KeyGenOutput, error)
}