shhext

README

Whisper API Extension

API

shhext_getNewFilterMessages

Accepts the same input as shh_getFilterMessages.

Returns

Returns a list of whisper messages matching the specified filter. Filters out the messages already confirmed received by shhext_confirmMessagesProcessed

Deduplication is made using the whisper envelope content and topic only, so the same content received in different whisper envelopes will be deduplicated.

shhext_confirmMessagesProcessed

Confirms whisper messages received and processed on the client side. These messages won't appear anymore when shhext_getNewFilterMessages is called.

Parameters

Gets a list of whisper envelopes.

shhext_post

Accepts same input as shh_post.

Returns

DATA, 32 Bytes - the envelope hash

shhext_requestMessages

Sends a request for historic messages to a mail server.

Parameters

1. Object - The message request object:

• mailServerPeer:URL - Mail servers' enode addess
• from:QUANTITY - (optional) Lower bound of time range as unix timestamp, default is 24 hours back from now
• to:QUANTITY- (optional) Upper bound of time range as unix timestamp, default is now
• topic:DATA, 4 Bytes - Regular whisper topic
• symKeyID:DATA- ID of a symmetric key to authenticate to mail server, derived form mail server password

Returns

Boolean - returns true if the request was send, otherwise false.

Signals

Sends sent signal once per envelope.

{
  "type": "envelope.sent",
  "event": {
    "hash": "0xea0b93079ed32588628f1cabbbb5ed9e4d50b7571064c2962c3853972db67790"
  }
}

Sends expired signal if envelope dropped from whisper local queue before it was sent to any peer on the network.

{
  "type": "envelope.expired",
  "event": {
    "hash": "0x754f4c12dccb14886f791abfeb77ffb86330d03d5a4ba6f37a8c21281988b69e"
  }
}

Documentation

Index

• Variables
• type EnvelopeEventsHandler
• type EnvelopeSignalHandler
  • func (h EnvelopeSignalHandler) EnvelopeExpired(hash common.Hash)
  • func (h EnvelopeSignalHandler) EnvelopeSent(hash common.Hash)
  • func (h EnvelopeSignalHandler) MailServerRequestCompleted(hash common.Hash)
  • func (h EnvelopeSignalHandler) MailServerRequestExpired(hash common.Hash)
• type EnvelopeState
• type MessagesRequest
• type PublicAPI
  • func NewPublicAPI(s *Service) *PublicAPI
  • func (api *PublicAPI) ConfirmMessagesProcessed(messages []*whisper.Message) error
  • func (api *PublicAPI) GetNewFilterMessages(filterID string) ([]*whisper.Message, error)
  • func (api *PublicAPI) Post(ctx context.Context, req whisper.NewMessage) (hash hexutil.Bytes, err error)
  • func (api *PublicAPI) RequestMessages(_ context.Context, r MessagesRequest) (hexutil.Bytes, error)
• type Service
  • func New(w *whisper.Whisper, handler EnvelopeEventsHandler, db *leveldb.DB) *Service
  • func (s *Service) APIs() []rpc.API
  • func (s *Service) Protocols() []p2p.Protocol
  • func (s *Service) Start(server *p2p.Server) error
  • func (s *Service) Stop() error

Variables

var (
	// ErrInvalidMailServerPeer is returned when it fails to parse enode from params.
	ErrInvalidMailServerPeer = errors.New("invalid mailServerPeer value")
	// ErrInvalidSymKeyID is returned when it fails to get a symmetric key.
	ErrInvalidSymKeyID = errors.New("invalid symKeyID value")
)

Types

type EnvelopeEventsHandler

type EnvelopeEventsHandler interface {
	EnvelopeSent(common.Hash)
	EnvelopeExpired(common.Hash)
	MailServerRequestCompleted(common.Hash)
	MailServerRequestExpired(common.Hash)
}

EnvelopeEventsHandler used for two different event types.

type EnvelopeSignalHandler

type EnvelopeSignalHandler struct{}

EnvelopeSignalHandler sends signals when envelope is sent or expired.

func (EnvelopeSignalHandler) EnvelopeExpired

func (h EnvelopeSignalHandler) EnvelopeExpired(hash common.Hash)

EnvelopeExpired triggered when envelope is expired but wasn't delivered to any peer.

func (EnvelopeSignalHandler) EnvelopeSent

func (h EnvelopeSignalHandler) EnvelopeSent(hash common.Hash)

EnvelopeSent triggered when envelope delivered atleast to 1 peer.

func (EnvelopeSignalHandler) MailServerRequestCompleted

func (h EnvelopeSignalHandler) MailServerRequestCompleted(hash common.Hash)

MailServerRequestCompleted triggered when mailserver send a ack with a requesID sent previously

func (EnvelopeSignalHandler) MailServerRequestExpired

func (h EnvelopeSignalHandler) MailServerRequestExpired(hash common.Hash)

MailServerRequestExpired triggered when mail server request expires

type EnvelopeState

type EnvelopeState int

EnvelopeState in local tracker

const (
	// EnvelopePosted is set when envelope was added to a local whisper queue.
	EnvelopePosted EnvelopeState = iota
	// EnvelopeSent is set when envelope is sent to atleast one peer.
	EnvelopeSent
	// MailServerRequestSent is set when p2p request is sent to the mailserver
	MailServerRequestSent
)

type MessagesRequest

type MessagesRequest struct {
	// MailServerPeer is MailServer's enode address.
	MailServerPeer string `json:"mailServerPeer"`

	// From is a lower bound of time range (optional).
	// Default is 24 hours back from now.
	From uint32 `json:"from"`

	// To is a upper bound of time range (optional).
	// Default is now.
	To uint32 `json:"to"`

	// Topic is a regular Whisper topic.
	Topic whisper.TopicType `json:"topic"`

	// SymKeyID is an ID of a symmetric key to authenticate to MailServer.
	// It's derived from MailServer password.
	SymKeyID string `json:"symKeyID"`

	// Timeout is the time to live of the request specified in seconds.
	// Default is 10 seconds
	Timeout time.Duration `json:"timeout"`
}

MessagesRequest is a payload send to a MailServer to get messages.

type PublicAPI

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

PublicAPI extends whisper public API.

func NewPublicAPI

func NewPublicAPI(s *Service) *PublicAPI

NewPublicAPI returns instance of the public API.

func (*PublicAPI) ConfirmMessagesProcessed

func (api *PublicAPI) ConfirmMessagesProcessed(messages []*whisper.Message) error

ConfirmMessagesProcessed is a method to confirm that messages was consumed by the client side.

func (*PublicAPI) GetNewFilterMessages

func (api *PublicAPI) GetNewFilterMessages(filterID string) ([]*whisper.Message, error)

GetNewFilterMessages is a prototype method with deduplication

func (*PublicAPI) Post

func (api *PublicAPI) Post(ctx context.Context, req whisper.NewMessage) (hash hexutil.Bytes, err error)

Post shamelessly copied from whisper codebase with slight modifications.

func (*PublicAPI) RequestMessages

func (api *PublicAPI) RequestMessages(_ context.Context, r MessagesRequest) (hexutil.Bytes, error)

RequestMessages sends a request for historic messages to a MailServer.

type Service

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

Service is a service that provides some additional Whisper API.

func New

func New(w *whisper.Whisper, handler EnvelopeEventsHandler, db *leveldb.DB) *Service

New returns a new Service.

func (*Service) APIs

func (s *Service) APIs() []rpc.API

APIs returns a list of new APIs.

func (*Service) Protocols

func (s *Service) Protocols() []p2p.Protocol

Protocols returns a new protocols list. In this case, there are none.

func (*Service) Start

func (s *Service) Start(server *p2p.Server) error

Start is run when a service is started. It does nothing in this case but is required by `node.Service` interface.

func (*Service) Stop

func (s *Service) Stop() error

Stop is run when a service is stopped. It does nothing in this case but is required by `node.Service` interface.