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
- type Envelope
- type Filter
- type Message
- type MessageEvent
- type NewFilterArgs
- type Options
- type PostArgs
- type PublicWhisperAPI
- func (s *PublicWhisperAPI) GetFilterChanges(filterId rpc.HexNumber) []WhisperMessage
- func (s *PublicWhisperAPI) GetMessages(filterId rpc.HexNumber) []WhisperMessage
- func (s *PublicWhisperAPI) HasIdentity(identity string) (bool, error)
- func (s *PublicWhisperAPI) NewFilter(args NewFilterArgs) (*rpc.HexNumber, error)
- func (s *PublicWhisperAPI) NewIdentity() (string, error)
- func (s *PublicWhisperAPI) Post(args PostArgs) (bool, error)
- func (s *PublicWhisperAPI) UninstallFilter(filterId rpc.HexNumber) bool
- func (s *PublicWhisperAPI) Version() (*rpc.HexNumber, error)
- type Topic
- type Whisper
- func (s *Whisper) APIs() []rpc.API
- 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) Protocols() []p2p.Protocol
- func (self *Whisper) Send(envelope *Envelope) error
- func (self *Whisper) Start(*p2p.Server) error
- func (self *Whisper) Stop() error
- func (self *Whisper) Unwatch(id int)
- func (self *Whisper) Version() uint
- func (self *Whisper) Watch(options Filter) int
- type WhisperMessage
Constants ¶
const ( DefaultTTL = 50 * time.Second DefaultPoW = 50 * time.Millisecond )
Variables ¶
This section is empty.
Functions ¶
func NewFilterTopics ¶ added in v0.9.17
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 ¶
NewEnvelope wraps a Whisper message with expiration and destination data included into an envelope for network forwarding.
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 ¶
NewMessage creates and initializes a non-signed, non-encrypted Whisper message.
func (*Message) Wrap ¶ added in v0.9.17
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
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 ¶ added in v0.9.17
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
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.
type Topic ¶ added in v0.9.17
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 ¶ added in v0.9.17
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.
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
APIs returns the RPC descriptors the Whisper implementation offers
func (*Whisper) GetIdentity ¶ added in v0.8.4
func (self *Whisper) GetIdentity(key *ecdsa.PublicKey) *ecdsa.PrivateKey
GetIdentity retrieves the private key of the specified public identity.
func (*Whisper) HasIdentity ¶
HasIdentity checks if the the whisper node is configured with the private key of the specified public pair.
func (*Whisper) Messages ¶ added in v0.8.4
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
Protocols returns the whisper sub-protocols ran by this particular client.
func (*Whisper) Send ¶
Send injects a message into the whisper send queue, to be distributed in the network in the coming cycles.
func (*Whisper) Start ¶ added in v0.8.4
Start implements node.Service, starting the background data propagation thread of the Whisper protocol.
func (*Whisper) Stop ¶
Stop implements node.Service, stopping the background data propagation thread of the Whisper protocol.
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.