client

Documentation

Overview

Package client provides a drand client implementation that retrieves randomness by subscribing to a libp2p pubsub topic.

WARNING: this client can only be used to "Watch" for new randomness rounds and "Get" randomness rounds it has previously seen that are still in the cache.

If you need to "Get" arbitrary rounds from the chain then you must combine this client with the http or grpc clients.

The agnostic client builder must receive "WithChainInfo()" in order for it to validate randomness rounds it receives, or "WithChainHash()" and be combined with the HTTP or gRPC client implementations so that chain information can be fetched from them.

It is particularly important that rounds are verified since they can be delivered by any peer in the network.

Example using "WithChainInfo()":

package main

import (
	"github.com/drand/drand/chain"
	"github.com/drand/drand/client"
	gclient "github.com/drand/drand/lp2p/client"
	pubsub "github.com/libp2p/go-libp2p-pubsub"
)

func main() {
	ps := newPubSub()
	info := readChainInfo()

	c, err := client.New(
		gclient.WithPubsub(ps),
		client.WithChainInfo(info),
	)
}

func newPubSub() *pubsub.Pubsub {
	// ...
}

func readChainInfo() *chain.Info {
	// ...
}

Example using "WithChainHash()" and combining it with a different client:

package main

import (
	"encoding/hex"

	"github.com/drand/drand/client"
	"github.com/drand/drand/client/http"
	gclient "github.com/drand/drand/lp2p/client"
	pubsub "github.com/libp2p/go-libp2p-pubsub"
)

var urls = []string{
	"https://api.drand.sh",
	"https://drand.cloudflare.com",
	// ...
}

var chainHash, _ = hex.DecodeString("8990e7a9aaed2ffed73dbd7092123d6f289930540d7651336225dc172e51b2ce")

func main() {
	ps := newPubSub()

	c, err := client.New(
		gclient.WithPubsub(ps),
		client.WithChainHash(chainHash),
		client.From(http.ForURLs(urls, chainHash)...),
	)
}

func newPubSub() *pubsub.Pubsub {
	// ...
}

Index

• func WithPubsub(ps *pubsub.PubSub) client.Option
• type Client
  • func NewWithPubsub(ps *pubsub.PubSub, info *chain.Info, cache client.Cache) (*Client, error)
  • func (c *Client) Close() error
  • func (c *Client) SetLog(l log.Logger)
  • func (c *Client) Sub(ch chan drand.PublicRandResponse) UnsubFunc
  • func (c *Client) Watch(ctx context.Context) <-chan client.Result
• type UnsubFunc

Functions

func WithPubsub

func WithPubsub(ps *pubsub.PubSub) client.Option

WithPubsub provides an option for integrating pubsub notification into a drand client.

Types

type Client

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

Client is a concrete pubsub client implementation

func NewWithPubsub

func NewWithPubsub(ps *pubsub.PubSub, info *chain.Info, cache client.Cache) (*Client, error)

NewWithPubsub creates a gossip randomness client.

func (*Client) Close

func (c *Client) Close() error

Close stops Client, cancels PubSub subscription and closes the topic.

func (*Client) SetLog

func (c *Client) SetLog(l log.Logger)

SetLog configures the client log output

func (*Client) Sub

func (c *Client) Sub(ch chan drand.PublicRandResponse) UnsubFunc

Sub subscribes to notifications about new randomness. Client instance owns the channel after it is passed to Sub function, thus the channel should not be closed by library user

It is recommended to use a buffered channel. If the channel is full, notification about randomness will be dropped.

Notification channels will be closed when the client is Closed

func (*Client) Watch

func (c *Client) Watch(ctx context.Context) <-chan client.Result

Watch implements the client.Watcher interface

type UnsubFunc

type UnsubFunc func()

UnsubFunc is a cancel function for pubsub subscription