whisper

Documentation

Overview

Package whisper implements the Whisper PoC-1.

(https://github.com/ethereum/wiki/wiki/Whisper-PoC-1-Protocol-Spec)

Whisper combines aspects of both DHTs and datagram messaging systems (e.g. UDP). As such it may be likened and compared to both, not dissimilar to the matter/energy duality (apologies to physicists for the blatant abuse of a fundamental and beautiful natural principle).

Whisper is a pure identity-based messaging system. Whisper provides a low-level (non-application-specific) but easily-accessible API without being based upon or prejudiced by the low-level hardware attributes and characteristics, particularly the notion of singular endpoints.

Index

• Constants
• func NewFilterTopics(data ...[][]byte) [][]Topic
• func NewFilterTopicsFlat(data ...[]byte) [][]Topic
• func NewFilterTopicsFromStrings(data ...[]string) [][]Topic
• func NewFilterTopicsFromStringsFlat(data ...string) [][]Topic
• type Envelope
  • func NewEnvelope(ttl time.Duration, topics []Topic, msg *Message) *Envelope
  • func (self *Envelope) DecodeRLP(s *rlp.Stream) error
  • func (self *Envelope) Hash() common.Hash
  • func (self *Envelope) Open(key *ecdsa.PrivateKey) (msg *Message, err error)
  • func (self *Envelope) Seal(pow time.Duration)
• type Filter
• type Message
  • func NewMessage(payload []byte) *Message
  • func (self *Message) Recover() *ecdsa.PublicKey
  • func (self *Message) Wrap(pow time.Duration, options Options) (*Envelope, error)
• type MessageEvent
• type Options
• type Topic
  • func NewTopic(data []byte) Topic
  • func NewTopicFromString(data string) Topic
  • func NewTopics(data ...[]byte) []Topic
  • func NewTopicsFromStrings(data ...string) []Topic
  • func (self *Topic) String() string
• type Whisper
  • func New() *Whisper
  • func (self *Whisper) GetIdentity(key *ecdsa.PublicKey) *ecdsa.PrivateKey
  • func (self *Whisper) HasIdentity(key *ecdsa.PublicKey) bool
  • func (self *Whisper) Messages(id int) []*Message
  • func (self *Whisper) NewIdentity() *ecdsa.PrivateKey
  • func (self *Whisper) Protocol() p2p.Protocol
  • func (self *Whisper) Send(envelope *Envelope) error
  • func (self *Whisper) Start()
  • func (self *Whisper) Stop()
  • func (self *Whisper) Unwatch(id int)
  • func (self *Whisper) Version() uint
  • func (self *Whisper) Watch(options Filter) int

Constants

const (
	DefaultTTL = 50 * time.Second
	DefaultPoW = 50 * time.Millisecond
)

Functions

func NewFilterTopics

func NewFilterTopics(data ...[][]byte) [][]Topic

NewFilterTopics creates a 2D topic array used by whisper.Filter from binary data elements.

func NewFilterTopicsFlat

func NewFilterTopicsFlat(data ...[]byte) [][]Topic

NewFilterTopicsFlat creates a 2D topic array used by whisper.Filter from flat binary data elements.

func NewFilterTopicsFromStrings

func NewFilterTopicsFromStrings(data ...[]string) [][]Topic

NewFilterTopicsFromStrings creates a 2D topic array used by whisper.Filter from textual data elements.

func NewFilterTopicsFromStringsFlat

func NewFilterTopicsFromStringsFlat(data ...string) [][]Topic

NewFilterTopicsFromStringsFlat creates a 2D topic array used by whisper.Filter from flat binary data elements.

Types

type Envelope

type Envelope struct {
	Expiry uint32 // Whisper protocol specifies int32, really should be int64
	TTL    uint32 // ^^^^^^
	Topics []Topic
	Data   []byte
	Nonce  uint32
	// contains filtered or unexported fields
}

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

func NewEnvelope

func NewEnvelope(ttl time.Duration, topics []Topic, msg *Message) *Envelope

NewEnvelope wraps a Whisper message with expiration and destination data included into an envelope for network forwarding.

func (*Envelope) DecodeRLP

func (self *Envelope) DecodeRLP(s *rlp.Stream) error

DecodeRLP decodes an Envelope from an RLP data stream.

func (*Envelope) Hash

func (self *Envelope) Hash() common.Hash

Hash returns the SHA3 hash of the envelope, calculating it if not yet done.

func (*Envelope) Open

func (self *Envelope) Open(key *ecdsa.PrivateKey) (msg *Message, err error)

Open extracts the message contained within a potentially encrypted envelope.

func (*Envelope) Seal

func (self *Envelope) Seal(pow time.Duration)

Seal closes the envelope by spending the requested amount of time as a proof of work on hashing the data.

type Filter

type Filter struct {
	To     *ecdsa.PublicKey   // Recipient of the message
	From   *ecdsa.PublicKey   // Sender of the message
	Topics [][]Topic          // Topics to filter messages with
	Fn     func(msg *Message) // Handler in case of a match
}

Filter is used to subscribe to specific types of whisper messages.

type Message

type Message struct {
	Flags     byte // First bit is signature presence, rest reserved and should be random
	Signature []byte
	Payload   []byte

	Sent time.Time     // Time when the message was posted into the network
	TTL  time.Duration // Maximum time to live allowed for the message

	To   *ecdsa.PublicKey // Message recipient (identity used to decode the message)
	Hash common.Hash      // Message envelope hash to act as a unique id
}

Message represents an end-user data packet to transmit through the Whisper protocol. These are wrapped into Envelopes that need not be understood by intermediate nodes, just forwarded.

func NewMessage

func NewMessage(payload []byte) *Message

NewMessage creates and initializes a non-signed, non-encrypted Whisper message.

func (*Message) Recover

func (self *Message) Recover() *ecdsa.PublicKey

Recover retrieves the public key of the message signer.

func (*Message) Wrap

func (self *Message) Wrap(pow time.Duration, options Options) (*Envelope, error)

Wrap bundles the message into an Envelope to transmit over the network.

pow (Proof Of Work) controls how much time to spend on hashing the message, inherently controlling its priority through the network (smaller hash, bigger priority).

The user can control the amount of identity, privacy and encryption through the options parameter as follows:

• options.From == nil && options.To == nil: anonymous broadcast
• options.From != nil && options.To == nil: signed broadcast (known sender)
• options.From == nil && options.To != nil: encrypted anonymous message
• options.From != nil && options.To != nil: encrypted signed message

type MessageEvent

type MessageEvent struct {
	To      *ecdsa.PrivateKey
	From    *ecdsa.PublicKey
	Message *Message
}

type Options

type Options struct {
	From   *ecdsa.PrivateKey
	To     *ecdsa.PublicKey
	TTL    time.Duration
	Topics []Topic
}

Options specifies the exact way a message should be wrapped into an Envelope.

type Topic

type Topic [4]byte

Topic 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 NewTopic

func NewTopic(data []byte) Topic

NewTopic creates a topic from the 4 byte prefix of the SHA3 hash of the data.

Note, empty topics are considered the wildcard, and cannot be used in messages.

func NewTopicFromString

func NewTopicFromString(data string) Topic

NewTopicFromString creates a topic using the binary data contents of the specified string.

func NewTopics

func NewTopics(data ...[]byte) []Topic

NewTopics creates a list of topics from a list of binary data elements, by iteratively calling NewTopic on each of them.

func NewTopicsFromStrings

func NewTopicsFromStrings(data ...string) []Topic

NewTopicsFromStrings creates a list of topics from a list of textual data elements, by iteratively calling NewTopicFromString on each of them.

func (*Topic) String

func (self *Topic) String() string

String converts a topic byte array to a string representation.

type Whisper

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

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

func New

func New() *Whisper

New creates a Whisper client ready to communicate through the Ethereum P2P network.

func (*Whisper) GetIdentity

func (self *Whisper) GetIdentity(key *ecdsa.PublicKey) *ecdsa.PrivateKey

GetIdentity retrieves the private key of the specified public identity.

func (*Whisper) HasIdentity

func (self *Whisper) HasIdentity(key *ecdsa.PublicKey) bool

HasIdentity checks if the the whisper node is configured with the private key of the specified public pair.

func (*Whisper) Messages

func (self *Whisper) Messages(id int) []*Message

Messages retrieves all the currently pooled messages matching a filter id.

func (*Whisper) NewIdentity

func (self *Whisper) NewIdentity() *ecdsa.PrivateKey

NewIdentity generates a new cryptographic identity for the client, and injects it into the known identities for message decryption.

func (*Whisper) Protocol

func (self *Whisper) Protocol() p2p.Protocol

Protocol returns the whisper sub-protocol handler for this particular client.

func (*Whisper) Send

func (self *Whisper) Send(envelope *Envelope) error

Send injects a message into the whisper send queue, to be distributed in the network in the coming cycles.

func (*Whisper) Start

func (self *Whisper) Start()

func (*Whisper) Stop

func (self *Whisper) Stop()

func (*Whisper) Unwatch

func (self *Whisper) Unwatch(id int)

Unwatch removes an installed message handler.

func (*Whisper) Version

func (self *Whisper) Version() uint

Version returns the whisper sub-protocols version number.

func (*Whisper) Watch

func (self *Whisper) Watch(options Filter) int

Watch installs a new message handler to run in case a matching packet arrives from the whisper network.