whisper

package
v5.2.0+incompatible Latest Latest
Warning

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

 Go to latest Published: Apr 13, 2018 License: GPL-3.0 Imports: 18 Imported by: 0

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

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

Variables

This section is empty.

Functions

func NewFilterTopics 

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

NewFilterTopics creates a 2D topic array used by whisper.Filter from 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 NewFilterArgs added in v1.4.0 

type NewFilterArgs struct {
	To     string
	From   string
	Topics [][][]byte
}

func (*NewFilterArgs) UnmarshalJSON added in v1.4.0 

func (args *NewFilterArgs) UnmarshalJSON(b []byte) (err error)

UnmarshalJSON implements the json.Unmarshaler interface, invoked to convert a JSON message blob into a WhisperFilterArgs structure.

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 PostArgs added in v1.4.0 

type PostArgs struct {
	From     string   `json:"from"`
	To       string   `json:"to"`
	Topics   [][]byte `json:"topics"`
	Payload  string   `json:"payload"`
	Priority int64    `json:"priority"`
	TTL      int64    `json:"ttl"`
}

func (*PostArgs) UnmarshalJSON added in v1.4.0 

func (args *PostArgs) UnmarshalJSON(data []byte) (err error)

type PublicWhisperAPI added in v1.4.0 

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

PublicWhisperAPI provides the whisper RPC service.

func NewPublicWhisperAPI added in v1.4.0 

func NewPublicWhisperAPI(w *Whisper) *PublicWhisperAPI

NewPublicWhisperAPI create a new RPC whisper service.

func (*PublicWhisperAPI) GetFilterChanges added in v1.4.0 

func (s *PublicWhisperAPI) GetFilterChanges(filterId rpc.HexNumber) []WhisperMessage

GetFilterChanges retrieves all the new messages matched by a filter since the last retrieval.

func (*PublicWhisperAPI) GetMessages added in v1.4.0 

func (s *PublicWhisperAPI) GetMessages(filterId rpc.HexNumber) []WhisperMessage

GetMessages retrieves all the known messages that match a specific filter.

func (*PublicWhisperAPI) HasIdentity added in v1.4.0 

func (s *PublicWhisperAPI) HasIdentity(identity string) (bool, error)

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

func (*PublicWhisperAPI) NewFilter added in v1.4.0 

func (s *PublicWhisperAPI) NewFilter(args NewFilterArgs) (*rpc.HexNumber, error)

NewWhisperFilter creates and registers a new message filter to watch for inbound whisper messages.

func (*PublicWhisperAPI) NewIdentity added in v1.4.0 

func (s *PublicWhisperAPI) NewIdentity() (string, error)

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

func (*PublicWhisperAPI) Post added in v1.4.0 

func (s *PublicWhisperAPI) Post(args PostArgs) (bool, error)

Post injects a message into the whisper network for distribution.

func (*PublicWhisperAPI) UninstallFilter added in v1.4.0 

func (s *PublicWhisperAPI) UninstallFilter(filterId rpc.HexNumber) bool

UninstallFilter disables and removes an existing filter.

func (*PublicWhisperAPI) Version added in v1.4.0 

func (s *PublicWhisperAPI) Version() (*rpc.HexNumber, error)

Version returns the Whisper version this node offers.

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 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 (*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) APIs added in v1.4.0 

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

APIs returns the RPC descriptors the Whisper implementation offers

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) Protocols added in v1.4.0 

func (self *Whisper) Protocols() []p2p.Protocol

Protocols returns the whisper sub-protocols ran by 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(*p2p.Server) error

Start implements node.Service, starting the background data propagation thread of the Whisper protocol.

func (*Whisper) Stop 

func (self *Whisper) Stop() error

Stop implements node.Service, stopping the background data propagation thread of the Whisper protocol.

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.

type WhisperMessage added in v1.4.0 

type WhisperMessage struct {
	Payload string `json:"payload"`
	To      string `json:"to"`
	From    string `json:"from"`
	Sent    int64  `json:"sent"`
	TTL     int64  `json:"ttl"`
	Hash    string `json:"hash"`
	// contains filtered or unexported fields
}

WhisperMessage is the RPC representation of a whisper message.

func NewWhisperMessage added in v1.4.0 

func NewWhisperMessage(message *Message) WhisperMessage

NewWhisperMessage converts an internal message into an API version.

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.