lp2p

Documentation

Overview

Package lp2p 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 client. You can Wrap multiple client together.

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 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.

Index

• Variables
• func NewPubsub(ctx context.Context, listenAddr string, relayAddrs []string) (*pubsub.PubSub, host.Host, error)
• func PubSubTopic(h string) string
• func WithPubsub(ps *pubsub.PubSub) client.Option
• type Client
  • func NewWithPubsub(l log.Logger, 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 drandi.Result
• type UnsubFunc

Examples

• NewPubsub

Variables

var WatchBufferSize = 100

WatchBufferSize controls how many incoming messages can be in-flight until they start to be dropped by the library when using Client.Watch

Functions

func NewPubsub

func NewPubsub(ctx context.Context, listenAddr string, relayAddrs []string) (*pubsub.PubSub, host.Host, error)

NewPubsub constructs a basic libp2p pubsub module for use with the drand client. The local libp2p host is returned as well to allow to properly close it once done.

Example

package main

import (
	"bytes"
	"context"
	"fmt"
	"time"

	"github.com/drand/drand/v2/common"
	"github.com/drand/drand/v2/common/chain"
	"github.com/drand/drand/v2/common/log"
	gclient "github.com/drand/go-clients/client/lp2p"
)

const (
	// relayP2PAddr is the p2p multiaddr of the drand gossipsub relay node to connect to.
	relayP2PAddr  = "/dnsaddr/api.drand.sh"
	relayP2PAddr2 = "/dnsaddr/api2.drand.sh"
	relayP2PAddr3 = "/dnsaddr/api3.drand.sh"

	// jsonQuicknetInfo, can be hardcoded since these don't change over time
	jsonQuicknetInfo = `{
  "genesis_time": 1692803367,
  "groupHash": "f477d5c89f21a17c863a7f937c6a6d15859414d2be09cd448d4279af331c5d3e",
  "hash": "52db9ba70e0cc0f6eaf7803dd07447a1f5477735fd3f661792ba94600c84e971",
  "metadata": {
    "beaconID": "quicknet"
  },
  "period": 3,
  "public_key": "83cf0f2896adee7eb8b5f01fcad3912212c437e0073e911fb90022d3e760183c8c4b450b6a0a6c3ac6a5776a2d1064510d1fec758c921cc22b0e17e63aaf4bcb5ed66304de9cf809bd274ca73bab4af5a6e9c76a4bc09e76eae8991ef5ece45a",
  "schemeID": "bls-unchained-g1-rfc9380"
}
`
)

func main() {
	ctx := context.Background()

	// /0 to use a random free port
	ps, h, err := gclient.NewPubsub(ctx, "/ip4/0.0.0.0/tcp/0", []string{relayP2PAddr, relayP2PAddr2, relayP2PAddr3})
	if err != nil {
		panic(err)
	}
	defer h.Close()

	info, err := chain.InfoFromJSON(bytes.NewReader([]byte(jsonQuicknetInfo)))
	if err != nil {
		panic(err)
	}

	// NewWithPubSub will automatically register the topic for the chainhash you're interested in
	c, err := gclient.NewWithPubsub(log.DefaultLogger(), ps, info, nil)
	if err != nil {
		panic(err)
	}

	// This can be slow to "start"
	for res := range c.Watch(context.Background()) {
		expected := common.CurrentRound(time.Now().Unix(), info.Period, info.GenesisTime)
		fmt.Println("correct round:", expected == res.GetRound(), "with", len(res.GetRandomness()), "random bytes")
		// we just waited on the first one as an example
		break
	}

}

Output:

correct round: true with 32 random bytes

func PubSubTopic

func PubSubTopic(h string) string

PubSubTopic generates a drand pubsub topic from a chain hash.

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(l log.Logger, ps *pubsub.PubSub, info *chain.Info, cache client.Cache) (*Client, error)

NewWithPubsub creates a gossip randomness client. If the logger l is nil, it will default to a default Logger,

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 drandi.Result

Watch implements the client.Watcher interface

type UnsubFunc

type UnsubFunc func()

UnsubFunc is a cancel function for pubsub subscription