beacon

Documentation

Index

• Constants
• Variables
• func CurrentRound(now int64, period time.Duration, genesis int64) uint64
• func Message(currRound uint64, prevSig []byte) []byte
• func NextRound(now int64, period time.Duration, genesis int64) (uint64, int64)
• func RandomnessFromSignature(sig []byte) []byte
• func TimeOfRound(period time.Duration, genesis int64, round uint64) int64
• func Verify(pubkey kyber.Point, prevSig, signature []byte, round uint64) error
• func VerifyBeacon(pubkey kyber.Point, b *Beacon) error
• type Beacon
  • func (b *Beacon) Equal(b2 *Beacon) bool
  • func (b *Beacon) GetRound() uint64
  • func (b *Beacon) Marshal() ([]byte, error)
  • func (b *Beacon) Randomness() []byte
  • func (b *Beacon) String() string
  • func (b *Beacon) Unmarshal(buff []byte) error
• type CallbackStore
  • func NewCallbackStore(s Store) *CallbackStore
  • func (c *CallbackStore) AddCallback(fn func(*Beacon))
  • func (c *CallbackStore) Put(b *Beacon) error
• type Config
• type Cursor
• type Handler
  • func NewHandler(c net.ProtocolClient, s Store, conf *Config, l log.Logger) (*Handler, error)
  • func (h *Handler) AddCallback(fn func(*Beacon))
  • func (h *Handler) Catchup()
  • func (h *Handler) ProcessPartialBeacon(c context.Context, p *proto.PartialBeaconPacket) (*proto.Empty, error)
  • func (h *Handler) Start() error
  • func (h *Handler) Stop()
  • func (h *Handler) StopAt(stopTime int64) error
  • func (h *Handler) Store() Store
  • func (h *Handler) SyncChain(req *proto.SyncRequest, p proto.Protocol_SyncChainServer) error
  • func (h *Handler) Transition(prevGroup *key.Group) error
  • func (h *Handler) TransitionNewGroup(newShare *key.Share, newGroup *key.Group)
• type Store
  • func NewBoltStore(folder string, opts *bolt.Options) (Store, error)

Constants

const BoltFileName = "drand.db"

BoltFileName is the name of the file boltdb writes to

Variables

var ErrNoBeaconSaved = errors.New("beacon not found in database")

ErrNoBeaconSaved is the error returned when no beacon have been saved in the database yet.

var MaxSyncWaitTime = 2 * time.Second

Once a connection is made, we should not wait too much to receive new beacons from one peer

Functions

func CurrentRound

func CurrentRound(now int64, period time.Duration, genesis int64) uint64

func Message

func Message(currRound uint64, prevSig []byte) []byte

Message returns a slice of bytes as the message to sign or to verify alongside a beacon signature. H ( prevSig || currRound)

func NextRound

func NextRound(now int64, period time.Duration, genesis int64) (uint64, int64)

NextRound returns the next upcoming round and its UNIX time given the genesis time and the period. round at time genesis = round 1. Round 0 is fixed.

func RandomnessFromSignature

func RandomnessFromSignature(sig []byte) []byte

func TimeOfRound

func TimeOfRound(period time.Duration, genesis int64, round uint64) int64

TimeOfRound is returning the time the current round should happen

func Verify

func Verify(pubkey kyber.Point, prevSig, signature []byte, round uint64) error

Verify is similar to verify beacon but doesn't require to get the full beacon structure.

func VerifyBeacon

func VerifyBeacon(pubkey kyber.Point, b *Beacon) error

VerifyBeacon returns an error if the given beacon does not verify given the public key. The public key "point" can be obtained from the `key.DistPublic.Key()` method. The distributed public is the one written in the configuration file of the network.

Types

type Beacon

type Beacon struct {
	// PreviousSig is the previous signature generated
	PreviousSig []byte
	// Round is the round number this beacon is tied to
	Round uint64
	// Signature is the BLS deterministic signature over Round || PreviousRand
	Signature []byte
}

Beacon holds the randomness as well as the info to verify it.

func (*Beacon) Equal

func (b *Beacon) Equal(b2 *Beacon) bool

func (*Beacon) GetRound

func (b *Beacon) GetRound() uint64

func (*Beacon) Marshal

func (b *Beacon) Marshal() ([]byte, error)

func (*Beacon) Randomness

func (b *Beacon) Randomness() []byte

Randomness returns the hashed signature. It is an example that uses sha256, but it could use blake2b for example.

func (*Beacon) String

func (b *Beacon) String() string

func (*Beacon) Unmarshal

func (b *Beacon) Unmarshal(buff []byte) error

type CallbackStore

type CallbackStore struct {
	Store

	sync.Mutex
	// contains filtered or unexported fields
}

func NewCallbackStore

func NewCallbackStore(s Store) *CallbackStore

NewCallbackStore returns a Store that calls the given callback in a goroutine each time a new Beacon is saved into the given store. It does not call the callback if there has been any errors while saving the beacon.

func (*CallbackStore) AddCallback

func (c *CallbackStore) AddCallback(fn func(*Beacon))

func (*CallbackStore) Put

func (c *CallbackStore) Put(b *Beacon) error

type Config

type Config struct {
	// Public key of this node
	Public *key.Node
	// Share of this node in the network
	Share *key.Share
	// Group listing all nodes and public key of the network
	Group *key.Group
	// Clock to use - useful to testing
	Clock clock.Clock
	// Callback to use when a new beacon is created - can be nil and new
	// callbacks can be added afterwards to the beacon
	Callback func(*Beacon)
}

Config holds the different cryptographc informations necessary to run the randomness beacon.

type Cursor

type Cursor interface {
	First() *Beacon
	Next() *Beacon
	Seek(round uint64) *Beacon
	Last() *Beacon
}

Iterate over items in sorted key order. This starts from the first key/value pair and updates the k/v variables to the next key/value on each iteration.

The loop finishes at the end of the cursor when a nil key is returned.

for k, v := c.First(); k != nil; k, v = c.Next() {
    fmt.Printf("A %s is %s.\n", k, v)
}

type Handler

type Handler struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Handler holds the logic to initiate, and react to the TBLS protocol. Each time a full signature can be recosntructed, it saves it to the given Store.

func NewHandler

func NewHandler(c net.ProtocolClient, s Store, conf *Config, l log.Logger) (*Handler, error)

NewHandler returns a fresh handler ready to serve and create randomness beacon

func (*Handler) AddCallback

func (h *Handler) AddCallback(fn func(*Beacon))

func (*Handler) Catchup

func (h *Handler) Catchup()

Catchup waits the next round's time to participate. This method is called when a node stops its daemon (maintenance or else) and get backs in the already running network . If the node does not have the previous randomness, it sync its local chain with other nodes to be able to participate in the next upcoming round.

func (*Handler) ProcessPartialBeacon

func (h *Handler) ProcessPartialBeacon(c context.Context, p *proto.PartialBeaconPacket) (*proto.Empty, error)

ProcessPartialBeacon receives a request for a beacon partial signature. It forwards it to the round manager if it is a valid beacon.

func (*Handler) Start

func (h *Handler) Start() error

Start runs the beacon protocol (threshold BLS signature). The first round will sign the message returned by the config.FirstRound() function. If the genesis time specified in the group is already passed, Start returns an error. In that case, if the group is already running, you should call SyncAndRun(). Round 0 = genesis seed - fixed Round 1 starts at genesis time, and is signing over the genesis seed

func (*Handler) Stop

func (h *Handler) Stop()

Stop the beacon loop from aggregating further randomness, but it finishes the one it is aggregating currently.

func (*Handler) StopAt

func (h *Handler) StopAt(stopTime int64) error

StopAt will stop the handler at the given time. It is useful when transitionining for a resharing.

func (*Handler) Store

func (h *Handler) Store() Store

Store returns the store associated with this beacon handler

func (*Handler) SyncChain

func (h *Handler) SyncChain(req *proto.SyncRequest, p proto.Protocol_SyncChainServer) error

SyncChain is the server side call that reply with the beacon in order to the client requesting the syncing.

func (*Handler) Transition

func (h *Handler) Transition(prevGroup *key.Group) error

Transition makes this beacon continuously sync until the time written in the "TransitionTime" in the handler's group file, where he will start generating randomness. To sync, he contact the nodes listed in the previous group file given. TODO: it should be better to use the public streaming API but since it is likely to change, right now we use the sync API. Later on when API is well defined, best to use streaming.

func (*Handler) TransitionNewGroup

func (h *Handler) TransitionNewGroup(newShare *key.Share, newGroup *key.Group)

type Store

type Store interface {
	Len() int
	Put(*Beacon) error
	Last() (*Beacon, error)
	Get(round uint64) (*Beacon, error)
	Cursor(func(Cursor))
	Close()
	Del(round uint64) error
}

Store is an interface to store Beacons packets where they can also be retrieved to be delivered to end clients.

func NewBoltStore

func NewBoltStore(folder string, opts *bolt.Options) (Store, error)

NewBoltStore returns a Store implementation using the boltdb storage engine.