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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BroadcastFn ¶
type BroadcastFn func(context.Context, Notification) error
BroadcastFn aliases the function that broadcasts the DataHash.
type Notification ¶
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 (*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) Stop ¶
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) 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.