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 ¶
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 ¶
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 ¶
func (*NewFilterArgs) UnmarshalJSON ¶
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 PostArgs ¶
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 ¶
type PublicWhisperAPI ¶
type PublicWhisperAPI struct {
// contains filtered or unexported fields
}
PublicWhisperAPI provides the whisper RPC service.
func NewPublicWhisperAPI ¶
func NewPublicWhisperAPI(w *Whisper) *PublicWhisperAPI
NewPublicWhisperAPI create a new RPC whisper service.
func (*PublicWhisperAPI) GetFilterChanges ¶
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 ¶
func (s *PublicWhisperAPI) GetMessages(filterId rpc.HexNumber) []WhisperMessage
GetMessages retrieves all the known messages that match a specific filter.
func (*PublicWhisperAPI) HasIdentity ¶
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 ¶
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 ¶
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 ¶
func (s *PublicWhisperAPI) Post(args PostArgs) (bool, error)
Post injects a message into the whisper network for distribution.
func (*PublicWhisperAPI) UninstallFilter ¶
func (s *PublicWhisperAPI) UninstallFilter(filterId rpc.HexNumber) bool
UninstallFilter disables and removes an existing filter.
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 ¶
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) GetIdentity ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
func NewWhisperMessage(message *Message) WhisperMessage
NewWhisperMessage converts an internal message into an API version.