shrexsub

Documentation

Overview

This package defines a protocol that is used to broadcast shares to peers over a pubsub network.

This protocol runs on a rudimentary floodsub network is primarily a pubsub protocol that broadcasts and listens for shares over a pubsub topic.

The pubsub topic used by this protocol is:

"{networkID}/eds-sub/v0.1.0"

where networkID is the network ID of the celestia-node that is running the protocol. (e.g. "arabica")

Usage

To use this protocol, you must first create a new `shrexsub.PubSub` instance by:

pubsub, err := shrexsub.NewPubSub(ctx, host, networkID)

where host is the libp2p host that is running the protocol, and networkID is the network ID of the celestia-node that is running the protocol.

After this, you can start the pubsub protocol by:

err := pubsub.Start(ctx)

Once you have started the `shrexsub.PubSub` instance, you can broadcast a share by:

err := pubsub.Broadcast(ctx, notification)

where `notification` is of type shrexsub.Notification.

and `DataHash` is the hash of the share that you want to broadcast, and `Height` is the height of the share.

You can also subscribe to the pubsub topic by:

sub, err := pubsub.Subscribe(ctx)

and then receive notifications by:

  for {
  	select {
  	case <-ctx.Done():
			sub.Cancel()
  		return
  	case notification, err := <-sub.Next():
  		// handle notification or err
  	}
  }

You can also manipulate the received pubsub messages by using the PubSub.AddValidator method:

pubsub.AddValidator(validator ValidatorFn)

where `validator` is of type shrexsub.ValidatorFn and `Notification` is the same as above.

You can also stop the pubsub protocol by:

err := pubsub.Stop(ctx)

Index

• type BroadcastFn
• type Notification
• type PubSub
  • func NewPubSub(ctx context.Context, h host.Host, networkID string) (*PubSub, error)
  • func (s *PubSub) AddValidator(v ValidatorFn) error
  • func (s *PubSub) Broadcast(ctx context.Context, notification Notification) error
  • func (s *PubSub) Start(context.Context) error
  • func (s *PubSub) Stop(context.Context) error
  • func (s *PubSub) Subscribe() (*Subscription, error)
• type Subscription
  • func (subs *Subscription) Cancel()
  • func (subs *Subscription) Next(ctx context.Context) (Notification, error)
• type ValidatorFn

Types

type BroadcastFn

type BroadcastFn func(context.Context, Notification) error

BroadcastFn aliases the function that broadcasts the DataHash.

type Notification

type Notification struct {
	DataHash share.DataHash
	Height   uint64
}

Notification is the format of message sent by Broadcaster

type PubSub

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

PubSub manages receiving and propagating the EDS from/to the network over "eds-sub" subscription.

func NewPubSub

func NewPubSub(ctx context.Context, h host.Host, networkID string) (*PubSub, error)

NewPubSub creates a libp2p.PubSub wrapper.

func (*PubSub) AddValidator

func (s *PubSub) AddValidator(v ValidatorFn) error

AddValidator registers given ValidatorFn for EDS notifications. Any amount of Validators can be registered.

func (*PubSub) Broadcast

func (s *PubSub) Broadcast(ctx context.Context, notification Notification) error

Broadcast sends the EDS notification (DataHash) to every connected peer.

func (*PubSub) Start

func (s *PubSub) Start(context.Context) error

Start creates an instances of FloodSub and joins specified topic.

func (*PubSub) Stop

func (s *PubSub) Stop(context.Context) error

Stop completely stops the PubSub: * Unregisters all the added Validators * Closes the `ShrEx/Sub` topic

func (*PubSub) Subscribe

func (s *PubSub) Subscribe() (*Subscription, error)

Subscribe provides a new Subscription for EDS notifications.

type Subscription

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

Subscription is a wrapper over pubsub.Subscription that handles receiving an EDS DataHash from other peers.

func (*Subscription) Cancel

func (subs *Subscription) Cancel()

Cancel stops the subscription.

func (*Subscription) Next

func (subs *Subscription) Next(ctx context.Context) (Notification, error)

Next blocks the caller until any new EDS DataHash notification arrives. Returns only notifications which successfully pass validation.

type ValidatorFn

type ValidatorFn func(context.Context, peer.ID, Notification) pubsub.ValidationResult

ValidatorFn is an injectable func and governs EDS notification msg validity. It receives the notification and sender peer and expects the validation result. ValidatorFn is allowed to be blocking for an indefinite time or until the context is canceled.