whispertypes

package
v0.5.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 22, 2019 License: MPL-2.0 Imports: 7 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// EnvelopeTimeNotSynced represents the code passed to notify of a clock skew situation
	EnvelopeTimeNotSynced uint = 1000
	// EnvelopeOtherError represents the code passed to notify of a generic error situation
	EnvelopeOtherError
)
View Source 
const (
	// TopicLength is the expected length of the topic, in bytes
	TopicLength = 4
	// BloomFilterSize is the expected length of a bloom filter byte array, in bytes
	BloomFilterSize = 64
)
View Source 
const (
	// PubKeyLength represents the length (in bytes) of an uncompressed public key
	PubKeyLength = 512 / 8
	// AesKeyLength represents the length (in bytes) of an private key
	AesKeyLength = 256 / 8
)
View Source 
const (
	// MaxLimitInMessagesRequest represents the maximum number of messages
	// that can be requested from the mailserver
	MaxLimitInMessagesRequest = 1000
)

Variables

This section is empty.

Functions

func BloomFilterMatch 

func BloomFilterMatch(filter, sample []byte) bool

BloomFilterMatch returns true if a sample matches a bloom filter

func MakeFullNodeBloom 

func MakeFullNodeBloom() []byte

MakeFullNodeBloom returns a bloom filter which matches all topics

func TopicToBloom 

func TopicToBloom(topic TopicType) []byte

TopicToBloom converts the topic (4 bytes) to the bloom filter (64 bytes)

Types

type Criteria 

type Criteria struct {
	SymKeyID     string      `json:"symKeyID"`
	PrivateKeyID string      `json:"privateKeyID"`
	Sig          []byte      `json:"sig"`
	MinPow       float64     `json:"minPow"`
	Topics       []TopicType `json:"topics"`
	AllowP2P     bool        `json:"allowP2P"`
}

Criteria holds various filter options for inbound messages.

type EnodeID 

type EnodeID [32]byte

EnodeID is a unique identifier for each node.

func (EnodeID) String 

func (n EnodeID) String() string

ID prints as a long hexadecimal number.

type Envelope 

type Envelope interface {
	Hash() protocol.Hash // Cached hash of the envelope to avoid rehashing every time.
	Bloom() []byte
}

Envelope represents a clear-text data packet to transmit through the Whisper network. Its contents may or may not be encrypted and signed.

type EnvelopeError 

type EnvelopeError struct {
	Hash        protocol.Hash
	Code        uint
	Description string
}

EnvelopeError code and optional description of the error.

type EnvelopeEvent 

type EnvelopeEvent struct {
	Event EventType
	Hash  protocol.Hash
	Batch protocol.Hash
	Peer  EnodeID
	Data  interface{}
}

EnvelopeEvent used for envelopes events.

type EventType 

type EventType string

EventType used to define known envelope events. 

const (
	// EventEnvelopeSent fires when envelope was sent to a peer.
	EventEnvelopeSent EventType = "envelope.sent"
	// EventEnvelopeExpired fires when envelop expired
	EventEnvelopeExpired EventType = "envelope.expired"
	// EventEnvelopeReceived is sent once envelope was received from a peer.
	// EventEnvelopeReceived must be sent to the feed even if envelope was previously in the cache.
	// And event, ideally, should contain information about peer that sent envelope to us.
	EventEnvelopeReceived EventType = "envelope.received"
	// EventBatchAcknowledged is sent when batch of envelopes was acknowleged by a peer.
	EventBatchAcknowledged EventType = "batch.acknowleged"
	// EventEnvelopeAvailable fires when envelop is available for filters
	EventEnvelopeAvailable EventType = "envelope.available"
	// EventMailServerRequestSent fires when such request is sent.
	EventMailServerRequestSent EventType = "mailserver.request.sent"
	// EventMailServerRequestCompleted fires after mailserver sends all the requested messages
	EventMailServerRequestCompleted EventType = "mailserver.request.completed"
	// EventMailServerRequestExpired fires after mailserver the request TTL ends.
	// This event is independent and concurrent to EventMailServerRequestCompleted.
	// Request should be considered as expired only if expiry event was received first.
	EventMailServerRequestExpired EventType = "mailserver.request.expired"
	// EventMailServerEnvelopeArchived fires after an envelope has been archived
	EventMailServerEnvelopeArchived EventType = "mailserver.envelope.archived"
	// EventMailServerSyncFinished fires when the sync of messages is finished.
	EventMailServerSyncFinished EventType = "mailserver.sync.finished"
)

NOTE: This list of event names is extracted from Geth. It must be kept in sync, or otherwise a mapping layer needs to be created

type Filter 

type Filter interface {
	ID() string
}

Filter represents a Whisper message filter

type MailServerResponse 

type MailServerResponse struct {
	LastEnvelopeHash protocol.Hash
	Cursor           []byte
	Error            error
}

MailServerResponse is the response payload sent by the mailserver.

type Message 

type Message struct {
	Sig       []byte    `json:"sig,omitempty"`
	TTL       uint32    `json:"ttl"`
	Timestamp uint32    `json:"timestamp"`
	Topic     TopicType `json:"topic"`
	Payload   []byte    `json:"payload"`
	Padding   []byte    `json:"padding"`
	PoW       float64   `json:"pow"`
	Hash      []byte    `json:"hash"`
	Dst       []byte    `json:"recipientPublicKey,omitempty"`
	P2P       bool      `json:"bool,omitempty"`
}

Message is the RPC representation of a whisper message.

func (Message) MarshalJSON 

func (m Message) MarshalJSON() ([]byte, error)

MarshalJSON marshals type Message to a json string

func (*Message) UnmarshalJSON 

func (m *Message) UnmarshalJSON(input []byte) error

UnmarshalJSON unmarshals type Message to a json string

type MessagesRequest 

type MessagesRequest struct {
	// ID of the request. The current implementation requires ID to be 32-byte array,
	// however, it's not enforced for future implementation.
	ID []byte `json:"id"`
	// From is a lower bound of time range.
	From uint32 `json:"from"`
	// To is a upper bound of time range.
	To uint32 `json:"to"`
	// Limit determines the number of messages sent by the mail server
	// for the current paginated request.
	Limit uint32 `json:"limit"`
	// Cursor is used as starting point for paginated requests.
	Cursor []byte `json:"cursor"`
	// Bloom is a filter to match requested messages.
	Bloom []byte `json:"bloom"`
}

MessagesRequest contains details of a request of historic messages.

func (*MessagesRequest) SetDefaults 

func (r *MessagesRequest) SetDefaults(now time.Time)

SetDefaults sets the From and To defaults

type NegotiatedSecret 

type NegotiatedSecret struct {
	PublicKey *ecdsa.PublicKey
	Key       []byte
}

NegotiatedSecret represents a negotiated secret (both public and private keys)

type NewMessage 

type NewMessage struct {
	SymKeyID   string    `json:"symKeyID"`
	PublicKey  []byte    `json:"pubKey"`
	SigID      string    `json:"sig"`
	TTL        uint32    `json:"ttl"`
	Topic      TopicType `json:"topic"`
	Payload    []byte    `json:"payload"`
	Padding    []byte    `json:"padding"`
	PowTime    uint32    `json:"powTime"`
	PowTarget  float64   `json:"powTarget"`
	TargetPeer string    `json:"targetPeer"`
}

NewMessage represents a new whisper message that is posted through the RPC.

type PublicWhisperAPI 

type PublicWhisperAPI interface {
	// AddPrivateKey imports the given private key.
	AddPrivateKey(ctx context.Context, privateKey protocol.HexBytes) (string, error)
	// GenerateSymKeyFromPassword derives a key from the given password, stores it, and returns its ID.
	GenerateSymKeyFromPassword(ctx context.Context, passwd string) (string, error)
	// DeleteKeyPair removes the key with the given key if it exists.
	DeleteKeyPair(ctx context.Context, key string) (bool, error)

	// Post posts a message on the Whisper network.
	// returns the hash of the message in case of success.
	Post(ctx context.Context, req NewMessage) ([]byte, error)

	// NewMessageFilter creates a new filter that can be used to poll for
	// (new) messages that satisfy the given criteria.
	NewMessageFilter(req Criteria) (string, error)
	// GetFilterMessages returns the messages that match the filter criteria and
	// are received between the last poll and now.
	GetFilterMessages(id string) ([]*Message, error)
}

PublicWhisperAPI provides the whisper RPC service that can be use publicly without security implications.

type Subscription 

type Subscription interface {
	Err() <-chan error // returns the error channel
	Unsubscribe()      // cancels sending of events, closing the error channel
}

Subscription represents a stream of events. The carrier of the events is typically a channel, but isn't part of the interface.

Subscriptions can fail while established. Failures are reported through an error channel. It receives a value if there is an issue with the subscription (e.g. the network connection delivering the events has been closed). Only one value will ever be sent.

The error channel is closed when the subscription ends successfully (i.e. when the source of events is closed). It is also closed when Unsubscribe is called.

The Unsubscribe method cancels the sending of events. You must call Unsubscribe in all cases to ensure that resources related to the subscription are released. It can be called any number of times.

type SubscriptionOptions 

type SubscriptionOptions struct {
	PrivateKeyID string
	SymKeyID     string
	PoW          float64
	Topics       [][]byte
}

SubscriptionOptions represents the parameters passed to Whisper.Subscribe to customize the subscription behavior

type SyncEventResponse 

type SyncEventResponse struct {
	Cursor []byte
	Error  string
}

SyncEventResponse is a response from the Mail Server form which the peer received envelopes.

type SyncMailRequest 

type SyncMailRequest struct {
	// Lower is a lower bound of time range for which messages are requested.
	Lower uint32
	// Upper is a lower bound of time range for which messages are requested.
	Upper uint32
	// Bloom is a bloom filter to filter envelopes.
	Bloom []byte
	// Limit is the max number of envelopes to return.
	Limit uint32
	// Cursor is used for pagination of the results.
	Cursor []byte
}

SyncMailRequest contains details which envelopes should be synced between Mail Servers.

type TopicType 

type TopicType [TopicLength]byte

TopicType represents a cryptographically secure, probabilistic partial classifications of a message, determined as the first (left) 4 bytes of the SHA3 hash of some arbitrary data given by the original author of the message.

func BytesToTopic 

func BytesToTopic(b []byte) (t TopicType)

BytesToTopic converts from the byte array representation of a topic into the TopicType type.

func (TopicType) MarshalText 

func (t TopicType) MarshalText() ([]byte, error)

MarshalText returns the hex representation of t.

func (*TopicType) String 

func (t *TopicType) String() string

String converts a topic byte array to a string representation.

func (*TopicType) UnmarshalText 

func (t *TopicType) UnmarshalText(input []byte) error

UnmarshalText parses a hex representation to a topic.

type Whisper 

type Whisper interface {
	PublicWhisperAPI() PublicWhisperAPI

	// Poll must be run periodically on the main thread by the host application
	Poll()

	// MinPow returns the PoW value required by this node.
	MinPow() float64
	// BloomFilter returns the aggregated bloom filter for all the topics of interest.
	// The nodes are required to send only messages that match the advertised bloom filter.
	// If a message does not match the bloom, it will tantamount to spam, and the peer will
	// be disconnected.
	BloomFilter() []byte
	// SetTimeSource assigns a particular source of time to a whisper object.
	SetTimeSource(timesource func() time.Time)
	// GetCurrentTime returns current time.
	GetCurrentTime() time.Time

	// SelectedKeyPairID returns the id of currently selected key pair.
	// It helps distinguish between different users w/o exposing the user identity itself.
	SelectedKeyPairID() string
	// GetPrivateKey retrieves the private key of the specified identity.
	GetPrivateKey(id string) (*ecdsa.PrivateKey, error)

	SubscribeEnvelopeEvents(events chan<- EnvelopeEvent) Subscription

	// AddKeyPair imports a asymmetric private key and returns a deterministic identifier.
	AddKeyPair(key *ecdsa.PrivateKey) (string, error)
	// DeleteKeyPair deletes the specified key if it exists.
	DeleteKeyPair(key string) bool
	// SelectKeyPair adds cryptographic identity, and makes sure
	// that it is the only private key known to the node.
	SelectKeyPair(key *ecdsa.PrivateKey) error
	AddSymKeyDirect(key []byte) (string, error)
	AddSymKeyFromPassword(password string) (string, error)
	DeleteSymKey(id string) bool
	GetSymKey(id string) ([]byte, error)

	Subscribe(opts *SubscriptionOptions) (string, error)
	GetFilter(id string) Filter
	Unsubscribe(id string) error

	// RequestHistoricMessages sends a message with p2pRequestCode to a specific peer,
	// which is known to implement MailServer interface, and is supposed to process this
	// request and respond with a number of peer-to-peer messages (possibly expired),
	// which are not supposed to be forwarded any further.
	// The whisper protocol is agnostic of the format and contents of envelope.
	// A timeout of 0 never expires.
	RequestHistoricMessagesWithTimeout(peerID []byte, envelope Envelope, timeout time.Duration) error
	// SendMessagesRequest sends a MessagesRequest. This is an equivalent to RequestHistoricMessages
	// in terms of the functionality.
	SendMessagesRequest(peerID []byte, request MessagesRequest) error
	// SyncMessages can be sent between two Mail Servers and syncs envelopes between them.
	SyncMessages(peerID []byte, req SyncMailRequest) error
}

Whisper represents a dark communication interface through the Ethereum network, using its very own P2P communication layer.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.