README
¶
waku
Table of contents
What is Waku?
Waku is a communication protocol for sending messages between Dapps. Waku is a fork of the Ethereum Whisper subprotocol, although not directly compatible with Whisper, both Waku and Whisper subprotocols can communicate via bridging.
Waku was created to solve scaling issues with Whisper and currently diverges from Whisper in the following ways:
- RLPx subprotocol is changed from
shh/6
towaku/1
. - Light node capability is added.*
- Optional rate limiting is added.
- Status packet has following additional parameters: light-node, confirmations-enabled and rate-limits
- Mail Server and Mail Client functionality is now part of the specification.
- P2P Message packet contains a list of envelopes instead of a single envelope.
*As per vacp2p/specs#117 Waku de jure introduced light nodes as far as updates to the written Whisper specifications. Though the de facto case is that the go-ethereum
Whisper implementation had already implemented light nodes and weren't a new feature in code.
Although status-go
's Waku light node functionality is a direct fork of go-ethereum
's Whisper light node functionality, technically, as far as specifications are concerned, light nodes are considered a new feature introduced in Waku.
Waku versioning
This package follows a versioning pattern that makes clean separation between breaking versions. As detailed in the PR that introduced this strategy to the package.
... the way we will move across versions is to maintain completely separate codebases and eventually remove those that are not supported anymore.
This has the drawback of some code duplication, but the advantage is that is more explicit what each version requires, and changes in one version will not impact the other, so we won't pile up backward compatible code. This is the same strategy used by whisper in go ethereum and is influenced by https://www.youtube.com/watch?v=oyLBGkS5ICk.
Familiarise yourself with the Spec-ulation Keynote by Rich Hickey, if you wish to more deeply understand the rationale for this versioning implementation.
This means that breaking changes will necessitate a new protocol version and a new version sub-package. The packages follow the naming convention of v*
where *
represents the major / breaking version number of the protocol.
Currently the package has the following version sub-packages:
What does this package do?
The basic function of this package is to implement the waku specifications, and provide the status-go
binary with the ability to send and receive messages via Waku.
Waku package files
Root
waku.go
waku.go
serves as the main entry point for the package and where the main Waku{}
struct lives.
api.go
api.go
is home to the PublicWakuAPI{}
struct which provides the waku RPC service that can be used publicly without security implications.
PublicWakuAPI{}
wraps the main Waku{}
, making the Waku{}
functionality suitable for external consumption.
Consumption
PublicWakuAPI{}
is wrapped by eth-node\bridge\geth.gethPublicWakuAPIWrapper{}
, which is initialised via eth-node\bridge\geth.NewGethPublicWakuAPIWrapper()
and exposed via gethWakuWrapper.PublicWakuAPI()
and is finally consumed by wider parts of the application.
Notes
It is worth noting that each function of PublicWakuAPI{}
received an unused context.Context
parameter. This is originally passed in way higher up the food-chain and without significant refactoring is not a simple thing to remove / change. Mobile bindings depend on the ability to pass in a context.
config.go
config.go
is home to the Config{}
struct and the declaration of DefaultConfig
.
Config{}
is used to initialise the settings of an instantiated Waku{}
. waku.New()
creates a new instance of a Waku{}
and takes a Config{}
as a parameter, if nil is passed instead of an instance of Config{}
, DefaultConfig
is used.
Configuration values
Name | Type | Description |
---|---|---|
MaxMessageSize |
uint32 |
Sets the maximum size of a waku message in bytes |
MinimumAcceptedPoW |
float64 |
Sets the minimum amount of work a message needs to have to be accepted by the waku node |
BloomFilterMode |
bool |
When true, the waku node only matches against bloom filter |
LightClient |
bool |
When true, the waku node does not forward messages |
FullNode |
bool |
When true, the waku node forwards all messages |
RestrictLightClientsConn |
bool |
When true, the waku node does not accept light clients as peers if it is a light client itself |
EnableConfirmations |
bool |
When true, sends message confirmations |
Default
The default configuration for a status-go
Waku node is:
MaxMessageSize : 1Mb
MinimumAcceptedPoW : 0.2
RestrictLightClientsConn : true
mailserver.go
mailserver.go
is home to MailServer
interface, which is implemented by mailserver.WakuMailServer{}
found in the package file mailserver/mailserver.go
. MailServer
represents a mail server, capable of receiving and archiving messages for subsequent delivery to the peers.
Additionally this package is home to MailServerResponse{}
which represents the response payload sent by the mail-server. MailServerResponse{}
is ultimately initialised by CreateMailServerEvent()
, which is tied to the main Waku{}
via the Waku.OnP2PRequestCompleted()
function. This is ultimately accessed via the Peer.Run()
function and is made available outside of the package with the waku.HandlePeer()
function via Waku.protocol.Run := waku.HandlePeer
.
Common
bloomfilter.go
bloomfilter.go
holds a few bloomfilter specific functions.
const.go
const.go
, originally a hangover from the go-ethereum
whisperv6/doc.go
package file later refactored, is home to the common Waku constants.
Notes
Versions also have version specific const.go
files.
envelope.go
envelope.go
is home to the Evelope{}
and EnvelopeError{}
structs. Envelope{}
is used as the data packet in which message data is sent through the Waku network.
Envelope{}
is accessed via the initialisation function NewEnvelope()
, which is exclusively consumed by Message.Wrap()
that prepares a message to be sent via Waku.
errors.go
errors.go
holds generic package errors.
events.go
events.go
handles data related to Waku events. This file contains string type const
s that identify known Waku events.
Additionally, the file contains EnvelopeEvent{}
, which serves as a representation of events created by envelopes. EnvelopeEvent{}
s are initialised exclusively within the waku
package.
filter.go
filter.go
is home to Filter{}
which represents a waku filter.
Usage
A status-go
node will install / register filters through RPC calls from a client (eg status-react
). The basic implementation of a filter requires at least 2 things:
- An encryption key, example "
superSafeEncryptionKey
" - A 4 byte topic (
TopicType
), example "0x1234
"
The node will install the filter [0x1234][{"superSafeEncryptionKey"}]
on an instance of Filters{}
and will notify its peers of this event
When a node receives an envelope it will attempt to match the topics against the installed filters, and then try to decrypt the envelope if the topic matches.
For example, if a node receives an envelope with topic 0x1234
, the node will try to use the installed filter key superSafeEncryptionKey
to decrypt the message. On success the node passes the decrypted message to the client.
In addition to the basic example above Filter{}
allows for richer filtering:
Field Name | Type | Description |
---|---|---|
Src |
*ecdsa.PublicKey |
Sender of the message. Currently not used |
KeyAsym |
*ecdsa.PrivateKey |
Private Key of recipient |
KeySym |
[]byte |
Key associated with the Topic |
Topics |
[][]byte |
Topics to filter messages with |
PoW |
float64 |
Proof of work as described in the Waku specs . Note: In status-react each client listens to the topic hash(pk), if a client wants to send a message to hash(pk1) they will also need to listen the hash(pk1) topic. However if the client doesn't want to receive envelopes for topic hash(pk1), the client may set the PoW to 1 so that all envelopes for topic hash(pk1) are discarded. |
AllowP2P |
bool |
Indicates whether this filter is interested in direct peer-to-peer messages. Note: Typically set to true, we always want to receive P2P envelopes on a filter from trusted peers |
SymKeyHash |
common.Hash |
The Keccak256Hash of the symmetric key, needed for optimization |
Waku / Whisper divergence
Whisper, will process all the installed filters that the node has, and build a BloomFilter
from all the topics of each installed filter (i.e. func ToBloomFilter(topics []TopicType) []byte { ... }
). When a peer receives this BloomFilter, it will match the topic on each envelope that they receive against the BloomFilter, if it matches, it will forward this to the peer.
Waku, by default, does not send a BloomFilter, instead sends the topic in a clear array of []TopicType
. This is an improvement on Whisper's usage as a BloomFilter may include false positives, which increase bandwidth usage. In contrast, clear topics are matched exactly and therefore don't create redundant bandwidth usage.
helpers.go
helpers.go
holds the package's generic functions.
message.go
message.go
is home to all message related functionality and contains a number of structs:
Name | Description |
---|---|
MessageParams{} |
Specifies the exact way a message should be wrapped into an Envelope |
sentMessage{} |
Represents an end-user data packet to transmit through the Waku protocol. These are wrapped into Envelopes that need not be understood by intermediate nodes, just forwarded. |
ReceivedMessage{} |
Represents a data packet to be received through the Waku protocol and successfully decrypted. |
MessagesRequest{} |
Contains details of a request for historic messages. |
MessagesResponse{} |
Represents a request response sent after processing batch of envelopes. |
MessageStore interface |
Implemented by MemoryMessageStore{} |
MemoryMessageStore{} |
Represents messages stored in a memory hash table. |
metrics.go
metrics.go
is home to Prometheus metric hooks, for counting a range of Waku related metrics.
protocol.go
protocol.go
houses the Peer
and WakuHost
interfaces.
Peer
represents a remote Waku client with which the local host waku instance exchanges data / messages.
WakuHost
is the local instance of waku, which both interacts with remote clients (peers) and local clients (like status-react
, via a RPC API).
rate_limiter.go
rate_limiter.go
was introduced as an improvement to Whisper allowing Waku nodes to limit the rate at which data is transferred. These limits are defined by the RateLimits{}
which allows nodes to limit the following:
Limit Type | Description |
---|---|
IPLimits |
Messages per second from a single IP (default 0, no limits) |
PeerIDLimits |
Messages per second from a single peer ID (default 0, no limits) |
TopicLimits |
Messages per second from a single topic (default 0, no limits) |
In addition to the RateLimits{}
this file also contains the following interfaces and structs.
Name | Description |
---|---|
RateLimiterPeer interface |
Represents a Peer{} that is capable of being rate limited |
RateLimiterHandler interface |
Represents handler functionality for a Rate Limiter in the cases of exceeding a peer limit and exceeding an IP limit |
MetricsRateLimiterHandler{} |
Implements RateLimiterHandler , represents a handler for reporting rate limit Exceed data to the metrics collection service (currently prometheus) |
DropPeerRateLimiterHandler{} |
Implements RateLimiterHandler , represents a handler that introduces Tolerance to the number of Peer connections before Limit Exceeded errors are returned. |
RateLimits{} |
Represents rate limit settings exchanged using rateLimitingCode packet or in the handshake. |
PeerRateLimiterConfig{} |
Represents configurations for initialising a PeerRateLimiter |
PeerRateLimiter{} |
Represents a rate limiter that limits communication between Peers |
The default PeerRateLimiterConfig is:
LimitPerSecIP: 10,
LimitPerSecPeerID: 5,
WhitelistedIPs: nil,
WhitelistedPeerIDs: nil,
topic.go
topic.go
houses the TopicType
type.
TopicType
represents a cryptographically secure, probabilistic partial classification of a message, determined as the first (leftmost) 4 bytes of the SHA3 hash of some arbitrary data given by the original author of a message.
Topics are used to filter incoming messages that the host's user has registered interest in. For further details on filtering see filter.go.
Versioned
For details about the divergence between versions please consult the README
s of each version package.
Version const.go
const.go
is home to the version sub-package's const
s. These constants are version dependant and, as expected, may change from version to version.
Version init.go
init.go
is home to the version sub-package's initialisation, and is used to initialise struct based variables at runtime.
Version message.go
message.go
is home to the MultiVersionResponse{}
and Version1MessageResponse{}
structs, both of which are exclusively consumed by the version subpackage's Peer{}
.
Both of these structs are used for handling Waku message responses, also known as message confirmations.
Version1MessageResponse{}
is used for sending message responses. MultiVersionResponse{}
is used for handling incoming message responses.
Usage
Message confirmations are used to inform a user, via the UI, that a message has been sent. Initially the message is marked as "Pending" and eventually as "Sent".
In order to trigger the message state transition from "pending" to "sent",
Waku uses MessageResponse{}
. Each peer on receiving a message will send back a MessageResponse
,
see the NewMessagesResponse()
function.
The Waku host checks that the peer is a mailserver and if this mailserver was selected by the user, if so the message will be marked as "Sent" in the UI.
For further details read the Waku specification section on the subject.
Notes
Versioning at the MessageResponse
level (see the struct Version field) should be phased out and defer to the subpackage's version number. Consider removal once we decide to move to a new major Waku version (i.e. waku/2
).
Version peer.go
peer.go
holds the version's sub-package Peer{}
implementation of the common.Peer
interface.
Version status_options.go
status_options.go
holds the version's sub-package StatusOptions{}
which implements the ethereum/go-ethereum/rlp
Decoder
and Encoder
interfaces.
StatusOptions
defines additional information shared between peers during the handshake. There might be more options provided than fields in StatusOptions
, and as per the specs, should be ignored during deserialisation to stay forward compatible. In the case of RLP, options should be serialised to an array of tuples where the first item is a field name and the second is a RLP-serialised value.
For further details on RLP see:
Documentation
¶
Index ¶
- Variables
- func CreateMailServerEvent(nodeID enode.ID, payload []byte) (*common.EnvelopeEvent, error)
- func CreateMailServerRequestCompletedPayload(requestID, lastEnvelopeHash gethcommon.Hash, cursor []byte) []byte
- func CreateMailServerRequestFailedPayload(requestID gethcommon.Hash, err error) []byte
- type Bridge
- type Config
- type Criteria
- type Info
- type MailServer
- type MailServerResponse
- type Message
- type NewMessage
- type PublicWakuAPI
- func (api *PublicWakuAPI) AddPrivateKey(ctx context.Context, privateKey hexutil.Bytes) (string, error)
- func (api *PublicWakuAPI) AddSymKey(ctx context.Context, key hexutil.Bytes) (string, error)
- func (api *PublicWakuAPI) CancelLightClient(ctx context.Context) bool
- func (api *PublicWakuAPI) DeleteKeyPair(ctx context.Context, key string) (bool, error)
- func (api *PublicWakuAPI) DeleteMessageFilter(id string) (bool, error)
- func (api *PublicWakuAPI) DeleteSymKey(ctx context.Context, id string) bool
- func (api *PublicWakuAPI) GenerateSymKeyFromPassword(ctx context.Context, passwd string) (string, error)
- func (api *PublicWakuAPI) GetFilterMessages(id string) ([]*Message, error)
- func (api *PublicWakuAPI) GetPrivateKey(ctx context.Context, id string) (hexutil.Bytes, error)
- func (api *PublicWakuAPI) GetPublicKey(ctx context.Context, id string) (hexutil.Bytes, error)
- func (api *PublicWakuAPI) GetSymKey(ctx context.Context, id string) (hexutil.Bytes, error)
- func (api *PublicWakuAPI) HasKeyPair(ctx context.Context, id string) bool
- func (api *PublicWakuAPI) HasSymKey(ctx context.Context, id string) bool
- func (api *PublicWakuAPI) Info(ctx context.Context) Info
- func (api *PublicWakuAPI) MakeLightClient(ctx context.Context) bool
- func (api *PublicWakuAPI) MarkTrustedPeer(ctx context.Context, url string) (bool, error)
- func (api *PublicWakuAPI) Messages(ctx context.Context, crit Criteria) (*rpc.Subscription, error)
- func (api *PublicWakuAPI) NewKeyPair(ctx context.Context) (string, error)
- func (api *PublicWakuAPI) NewMessageFilter(req Criteria) (string, error)
- func (api *PublicWakuAPI) NewSymKey(ctx context.Context) (string, error)
- func (api *PublicWakuAPI) Post(ctx context.Context, req NewMessage) (hexutil.Bytes, error)
- func (api *PublicWakuAPI) SetBloomFilter(ctx context.Context, bloom hexutil.Bytes) (bool, error)
- func (api *PublicWakuAPI) SetMaxMessageSize(ctx context.Context, size uint32) (bool, error)
- func (api *PublicWakuAPI) SetMinPoW(ctx context.Context, pow float64) (bool, error)
- func (api *PublicWakuAPI) UninstallFilter(id string)
- func (api *PublicWakuAPI) Unsubscribe(id string)
- type Waku
- func (w *Waku) APIs() []rpc.API
- func (w *Waku) AddKeyPair(key *ecdsa.PrivateKey) (string, error)
- func (w *Waku) AddSymKey(id string, key []byte) (string, error)
- func (w *Waku) AddSymKeyDirect(key []byte) (string, error)
- func (w *Waku) AddSymKeyFromPassword(password string) (string, error)
- func (w *Waku) AllowP2PMessagesFromPeer(peerID []byte) error
- func (w *Waku) BloomFilter() []byte
- func (w *Waku) BloomFilterMode() bool
- func (w *Waku) BloomFilterTolerance() []byte
- func (w *Waku) BytesRateLimits() common.RateLimits
- func (w *Waku) ConfirmationsEnabled() bool
- func (w *Waku) CurrentTime() time.Time
- func (w *Waku) DeleteKeyPair(key string) bool
- func (w *Waku) DeleteKeyPairs() error
- func (w *Waku) DeleteSymKey(id string) bool
- func (w *Waku) Envelopes() []*common.Envelope
- func (w *Waku) FullNode() bool
- func (w *Waku) GenerateSymKey() (string, error)
- func (w *Waku) GetEnvelope(hash gethcommon.Hash) *common.Envelope
- func (w *Waku) GetFilter(id string) *common.Filter
- func (w *Waku) GetPrivateKey(id string) (*ecdsa.PrivateKey, error)
- func (w *Waku) GetStats() types.StatsSummary
- func (w *Waku) GetSymKey(id string) ([]byte, error)
- func (w *Waku) HandlePeer(peer common.Peer, rw p2p.MsgReadWriter) error
- func (w *Waku) HasKeyPair(id string) bool
- func (w *Waku) HasSymKey(id string) bool
- func (w *Waku) IsEnvelopeCached(hash gethcommon.Hash) bool
- func (w *Waku) LightClientMode() bool
- func (w *Waku) LightClientModeConnectionRestricted() bool
- func (w *Waku) Mailserver() bool
- func (w *Waku) MaxMessageSize() uint32
- func (w *Waku) MinPow() float64
- func (w *Waku) MinPowTolerance() float64
- func (w *Waku) NewKeyPair() (string, error)
- func (w *Waku) OnBatchAcknowledged(batchHash gethcommon.Hash, p common.Peer) error
- func (w *Waku) OnDeprecatedMessagesRequest(request *common.Envelope, p common.Peer) error
- func (w *Waku) OnMessagesRequest(request common.MessagesRequest, p common.Peer) error
- func (w *Waku) OnMessagesResponse(response common.MessagesResponse, p common.Peer) error
- func (w *Waku) OnNewEnvelopes(envelopes []*common.Envelope, peer common.Peer) ([]common.EnvelopeError, error)
- func (w *Waku) OnNewP2PEnvelopes(envelopes []*common.Envelope) error
- func (w *Waku) OnP2PRequestCompleted(payload []byte, p common.Peer) error
- func (w *Waku) PacketRateLimits() common.RateLimits
- func (w *Waku) Protocols() []p2p.Protocol
- func (w *Waku) RegisterBridge(b Bridge)
- func (w *Waku) RegisterMailServer(server MailServer)
- func (w *Waku) RegisterRateLimiter(r *common.PeerRateLimiter)
- func (w *Waku) RequestHistoricMessages(peerID []byte, envelope *common.Envelope) error
- func (w *Waku) RequestHistoricMessagesWithTimeout(peerID []byte, envelope *common.Envelope, timeout time.Duration) error
- func (w *Waku) SelectKeyPair(key *ecdsa.PrivateKey) error
- func (w *Waku) Send(envelope *common.Envelope) error
- func (w *Waku) SendEnvelopeEvent(event common.EnvelopeEvent) int
- func (w *Waku) SendHistoricMessageResponse(peerID []byte, payload []byte) error
- func (w *Waku) SendMessagesRequest(peerID []byte, request common.MessagesRequest) error
- func (w *Waku) SendP2PMessages(peerID []byte, envelopes ...*common.Envelope) error
- func (w *Waku) SendRawP2PDirect(peerID []byte, envelopes ...rlp.RawValue) error
- func (w *Waku) SetBloomFilter(bloom []byte) error
- func (w *Waku) SetBloomFilterMode(mode bool)
- func (w *Waku) SetFullNode(set bool)
- func (w *Waku) SetLightClientMode(v bool)
- func (w *Waku) SetMaxMessageSize(size uint32) error
- func (w *Waku) SetMinimumPoW(val float64, tolerate bool) error
- func (w *Waku) SetTimeSource(timesource func() time.Time)
- func (w *Waku) SetTopicInterest(topicInterest []common.TopicType) error
- func (w *Waku) Start() error
- func (w *Waku) Stop() error
- func (w *Waku) Subscribe(f *common.Filter) (string, error)
- func (w *Waku) SubscribeEnvelopeEvents(events chan<- common.EnvelopeEvent) event.Subscription
- func (w *Waku) TopicInterest() []common.TopicType
- func (w *Waku) Unsubscribe(id string) error
- func (w *Waku) UnsubscribeMany(ids []string) error
- func (w *Waku) Version() uint
Constants ¶
This section is empty.
Variables ¶
var ( ErrSymAsym = errors.New("specify either a symmetric or an asymmetric key") ErrInvalidSymmetricKey = errors.New("invalid symmetric key") ErrInvalidPublicKey = errors.New("invalid public key") ErrInvalidSigningPubKey = errors.New("invalid signing public key") ErrTooLowPoW = errors.New("message rejected, PoW too low") ErrNoTopics = errors.New("missing topic(s)") )
List of errors
var DefaultConfig = Config{ MaxMessageSize: common.DefaultMaxMessageSize, MinimumAcceptedPoW: common.DefaultMinimumPoW, RestrictLightClientsConn: true, }
Functions ¶
func CreateMailServerEvent ¶
CreateMailServerEvent returns EnvelopeEvent with correct data if payload corresponds to any of the know mailserver events: * request completed successfully * request failed If the payload is unknown/unparseable, it returns `nil`
func CreateMailServerRequestCompletedPayload ¶
func CreateMailServerRequestCompletedPayload(requestID, lastEnvelopeHash gethcommon.Hash, cursor []byte) []byte
CreateMailServerRequestCompletedPayload creates a payload representing a successful request to mailserver
func CreateMailServerRequestFailedPayload ¶
func CreateMailServerRequestFailedPayload(requestID gethcommon.Hash, err error) []byte
CreateMailServerRequestFailedPayload creates a payload representing a failed request to a mailserver
Types ¶
type Config ¶
type Config struct { MaxMessageSize uint32 `toml:",omitempty"` MinimumAcceptedPoW float64 `toml:",omitempty"` BloomFilterMode bool `toml:",omitempty"` // when true, we only match against bloom filter LightClient bool `toml:",omitempty"` // when true, it does not forward messages FullNode bool `toml:",omitempty"` // when true, it forwards all messages RestrictLightClientsConn bool `toml:",omitempty"` // when true, do not accept light client as peers if it is a light client itself EnableConfirmations bool `toml:",omitempty"` // when true, sends message confirmations SoftBlacklistedPeerIDs []string `toml:",omitempty"` }
Config represents the configuration state of a waku node.
type Criteria ¶
type Criteria struct { SymKeyID string `json:"symKeyID"` PrivateKeyID string `json:"privateKeyID"` Sig []byte `json:"sig"` MinPow float64 `json:"minPow"` Topics []common.TopicType `json:"topics"` AllowP2P bool `json:"allowP2P"` }
Criteria holds various filter options for inbound messages.
type Info ¶
type Info struct { Messages int `json:"messages"` // Number of floating messages. MinPow float64 `json:"minPow"` // Minimal accepted PoW MaxMessageSize uint32 `json:"maxMessageSize"` // Maximum accepted message size }
Info contains diagnostic information.
type MailServer ¶
type MailServer interface { Archive(env *common.Envelope) DeliverMail(peerID []byte, request *common.Envelope) // DEPRECATED; use Deliver() Deliver(peerID []byte, request common.MessagesRequest) }
MailServer represents a mail server, capable of archiving the old messages for subsequent delivery to the peers. Any implementation must ensure that both functions are thread-safe. Also, they must return ASAP. DeliverMail should use p2pMessageCode for delivery, in order to bypass the expiry checks.
type MailServerResponse ¶
type MailServerResponse struct { LastEnvelopeHash gethcommon.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 common.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 waku message.
func ToWakuMessage ¶
func ToWakuMessage(message *common.ReceivedMessage) *Message
ToWakuMessage converts an internal message into an API version.
type NewMessage ¶
type NewMessage struct { SymKeyID string `json:"symKeyID"` PublicKey []byte `json:"pubKey"` Sig string `json:"sig"` TTL uint32 `json:"ttl"` Topic common.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 waku message that is posted through the RPC.
type PublicWakuAPI ¶
type PublicWakuAPI struct {
// contains filtered or unexported fields
}
PublicWakuAPI provides the waku RPC service that can be use publicly without security implications.
func NewPublicWakuAPI ¶
func NewPublicWakuAPI(w *Waku) *PublicWakuAPI
NewPublicWakuAPI create a new RPC waku service.
func (*PublicWakuAPI) AddPrivateKey ¶
func (api *PublicWakuAPI) AddPrivateKey(ctx context.Context, privateKey hexutil.Bytes) (string, error)
AddPrivateKey imports the given private key.
func (*PublicWakuAPI) AddSymKey ¶
AddSymKey import a symmetric key. It returns an ID that can be used to refer to the key. Can be used encrypting and decrypting messages where the key is known to both parties.
func (*PublicWakuAPI) CancelLightClient ¶
func (api *PublicWakuAPI) CancelLightClient(ctx context.Context) bool
CancelLightClient cancels light client mode.
func (*PublicWakuAPI) DeleteKeyPair ¶
DeleteKeyPair removes the key with the given key if it exists.
func (*PublicWakuAPI) DeleteMessageFilter ¶
func (api *PublicWakuAPI) DeleteMessageFilter(id string) (bool, error)
DeleteMessageFilter deletes a filter.
func (*PublicWakuAPI) DeleteSymKey ¶
func (api *PublicWakuAPI) DeleteSymKey(ctx context.Context, id string) bool
DeleteSymKey deletes the symmetric key that is associated with the given id.
func (*PublicWakuAPI) GenerateSymKeyFromPassword ¶
func (api *PublicWakuAPI) GenerateSymKeyFromPassword(ctx context.Context, passwd string) (string, error)
GenerateSymKeyFromPassword derive a key from the given password, stores it, and returns its ID.
func (*PublicWakuAPI) GetFilterMessages ¶
func (api *PublicWakuAPI) GetFilterMessages(id string) ([]*Message, error)
GetFilterMessages returns the messages that match the filter criteria and are received between the last poll and now.
func (*PublicWakuAPI) GetPrivateKey ¶
GetPrivateKey returns the private key associated with the given key. The key is the hex encoded representation of a key in the form specified in section 4.3.6 of ANSI X9.62.
func (*PublicWakuAPI) GetPublicKey ¶
GetPublicKey returns the public key associated with the given key. The key is the hex encoded representation of a key in the form specified in section 4.3.6 of ANSI X9.62.
func (*PublicWakuAPI) HasKeyPair ¶
func (api *PublicWakuAPI) HasKeyPair(ctx context.Context, id string) bool
HasKeyPair returns an indication if the node has a key pair that is associated with the given id.
func (*PublicWakuAPI) HasSymKey ¶
func (api *PublicWakuAPI) HasSymKey(ctx context.Context, id string) bool
HasSymKey returns an indication if the node has a symmetric key associated with the given key.
func (*PublicWakuAPI) Info ¶
func (api *PublicWakuAPI) Info(ctx context.Context) Info
Info returns diagnostic information about the waku node.
func (*PublicWakuAPI) MakeLightClient ¶
func (api *PublicWakuAPI) MakeLightClient(ctx context.Context) bool
MakeLightClient turns the node into light client, which does not forward any incoming messages, and sends only messages originated in this node.
func (*PublicWakuAPI) MarkTrustedPeer ¶
MarkTrustedPeer marks a peer trusted, which will allow it to send historic (expired) messages. Note: This function is not adding new nodes, the node needs to exists as a peer.
func (*PublicWakuAPI) Messages ¶
func (api *PublicWakuAPI) Messages(ctx context.Context, crit Criteria) (*rpc.Subscription, error)
Messages set up a subscription that fires events when messages arrive that match the given set of criteria.
func (*PublicWakuAPI) NewKeyPair ¶
func (api *PublicWakuAPI) NewKeyPair(ctx context.Context) (string, error)
NewKeyPair generates a new public and private key pair for message decryption and encryption. It returns an ID that can be used to refer to the keypair.
func (*PublicWakuAPI) NewMessageFilter ¶
func (api *PublicWakuAPI) NewMessageFilter(req Criteria) (string, error)
NewMessageFilter creates a new filter that can be used to poll for (new) messages that satisfy the given criteria.
func (*PublicWakuAPI) NewSymKey ¶
func (api *PublicWakuAPI) NewSymKey(ctx context.Context) (string, error)
NewSymKey generate a random symmetric key. It returns an ID that can be used to refer to the key. Can be used encrypting and decrypting messages where the key is known to both parties.
func (*PublicWakuAPI) Post ¶
func (api *PublicWakuAPI) Post(ctx context.Context, req NewMessage) (hexutil.Bytes, error)
Post posts a message on the Waku network. returns the hash of the message in case of success.
func (*PublicWakuAPI) SetBloomFilter ¶
SetBloomFilter sets the new value of bloom filter, and notifies the peers.
func (*PublicWakuAPI) SetMaxMessageSize ¶
SetMaxMessageSize sets the maximum message size that is accepted. Upper limit is defined by MaxMessageSize.
func (*PublicWakuAPI) UninstallFilter ¶
func (api *PublicWakuAPI) UninstallFilter(id string)
UninstallFilter is alias for Unsubscribe
func (*PublicWakuAPI) Unsubscribe ¶
func (api *PublicWakuAPI) Unsubscribe(id string)
Unsubscribe disables and removes an existing filter.
type Waku ¶
type Waku struct {
// contains filtered or unexported fields
}
Waku represents a dark communication interface through the Ethereum network, using its very own P2P communication layer.
func (*Waku) AddKeyPair ¶
func (w *Waku) AddKeyPair(key *ecdsa.PrivateKey) (string, error)
AddKeyPair imports a asymmetric private key and returns it identifier.
func (*Waku) AddSymKeyDirect ¶
AddSymKeyDirect stores the key, and returns its id.
func (*Waku) AddSymKeyFromPassword ¶
AddSymKeyFromPassword generates the key from password, stores it, and returns its id.
func (*Waku) AllowP2PMessagesFromPeer ¶
AllowP2PMessagesFromPeer marks specific peer trusted, which will allow it to send historic (expired) messages.
func (*Waku) BloomFilter ¶
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.
func (*Waku) BloomFilterMode ¶
BloomFilterMode returns whether the node is running in bloom filter mode
func (*Waku) BloomFilterTolerance ¶
BloomFilterTolerance returns the bloom filter which is tolerated for a limited time after new bloom was advertised to the peers. If sufficient time have elapsed or no change of bloom filter have ever occurred, the return value will be the same as return value of BloomFilter().
func (*Waku) BytesRateLimits ¶ added in v0.55.1
func (w *Waku) BytesRateLimits() common.RateLimits
BytesRateLimiting returns RateLimits information for bytes
func (*Waku) ConfirmationsEnabled ¶
ConfirmationsEnabled returns true if message confirmations are enabled.
func (*Waku) DeleteKeyPair ¶
DeleteKeyPair deletes the specified key if it exists.
func (*Waku) DeleteKeyPairs ¶
DeleteKeyPairs removes all cryptographic identities known to the node
func (*Waku) DeleteSymKey ¶
DeleteSymKey deletes the key associated with the name string if it exists.
func (*Waku) GenerateSymKey ¶
GenerateSymKey generates a random symmetric key and stores it under id, which is then returned. Will be used in the future for session key exchange.
func (*Waku) GetEnvelope ¶
func (w *Waku) GetEnvelope(hash gethcommon.Hash) *common.Envelope
GetEnvelope retrieves an envelope from the message queue by its hash. It returns nil if the envelope can not be found.
func (*Waku) GetPrivateKey ¶
func (w *Waku) GetPrivateKey(id string) (*ecdsa.PrivateKey, error)
GetPrivateKey retrieves the private key of the specified identity.
func (*Waku) GetStats ¶ added in v0.83.8
func (w *Waku) GetStats() types.StatsSummary
func (*Waku) HandlePeer ¶
HandlePeer is called by the underlying P2P layer when the waku sub-protocol connection is negotiated.
func (*Waku) HasKeyPair ¶
HasKeyPair checks if the waku node is configured with the private key of the specified public pair.
func (*Waku) HasSymKey ¶
HasSymKey returns true if there is a key associated with the given id. Otherwise returns false.
func (*Waku) IsEnvelopeCached ¶ added in v0.53.0
func (w *Waku) IsEnvelopeCached(hash gethcommon.Hash) bool
isEnvelopeCached checks if envelope with specific hash has already been received and cached.
func (*Waku) LightClientMode ¶
LightClientMode indicates is this node is light client (does not forward any messages)
func (*Waku) LightClientModeConnectionRestricted ¶
LightClientModeConnectionRestricted indicates that connection to light client in light client mode not allowed
func (*Waku) Mailserver ¶ added in v0.53.0
func (*Waku) MaxMessageSize ¶
MaxMessageSize returns the maximum accepted message size.
func (*Waku) MinPowTolerance ¶
MinPowTolerance returns the value of minimum PoW which is tolerated for a limited time after PoW was changed. If sufficient time have elapsed or no change of PoW have ever occurred, the return value will be the same as return value of MinPow().
func (*Waku) NewKeyPair ¶
NewKeyPair generates a new cryptographic identity for the client, and injects it into the known identities for message decryption. Returns ID of the new key pair.
func (*Waku) OnBatchAcknowledged ¶ added in v0.53.0
func (*Waku) OnDeprecatedMessagesRequest ¶ added in v0.53.2
func (*Waku) OnMessagesRequest ¶ added in v0.53.0
func (*Waku) OnMessagesResponse ¶ added in v0.53.0
func (*Waku) OnNewEnvelopes ¶ added in v0.53.0
func (*Waku) OnNewP2PEnvelopes ¶ added in v0.53.0
func (*Waku) OnP2PRequestCompleted ¶ added in v0.53.0
func (*Waku) PacketRateLimits ¶ added in v0.55.1
func (w *Waku) PacketRateLimits() common.RateLimits
PacketRateLimiting returns RateLimits information for packets
func (*Waku) RegisterBridge ¶
RegisterBridge registers a new Bridge that moves envelopes between different subprotocols. It's important that a bridge is registered before the service is started, otherwise, it won't read and propagate envelopes.
func (*Waku) RegisterMailServer ¶
func (w *Waku) RegisterMailServer(server MailServer)
RegisterMailServer registers MailServer interface. MailServer will process all the incoming messages with p2pRequestCode.
func (*Waku) RegisterRateLimiter ¶
func (w *Waku) RegisterRateLimiter(r *common.PeerRateLimiter)
SetRateLimiter registers a rate limiter.
func (*Waku) RequestHistoricMessages ¶
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 waku protocol is agnostic of the format and contents of envelope.
func (*Waku) RequestHistoricMessagesWithTimeout ¶
func (w *Waku) RequestHistoricMessagesWithTimeout(peerID []byte, envelope *common.Envelope, timeout time.Duration) error
RequestHistoricMessagesWithTimeout acts as RequestHistoricMessages but requires to pass a timeout. It sends an event EventMailServerRequestExpired after the timeout.
func (*Waku) SelectKeyPair ¶
func (w *Waku) SelectKeyPair(key *ecdsa.PrivateKey) error
SelectKeyPair adds cryptographic identity, and makes sure that it is the only private key known to the node.
func (*Waku) Send ¶
Send injects a message into the waku send queue, to be distributed in the network in the coming cycles.
func (*Waku) SendEnvelopeEvent ¶ added in v0.53.0
func (w *Waku) SendEnvelopeEvent(event common.EnvelopeEvent) int
func (*Waku) SendHistoricMessageResponse ¶
func (*Waku) SendMessagesRequest ¶
func (w *Waku) SendMessagesRequest(peerID []byte, request common.MessagesRequest) error
func (*Waku) SendP2PMessages ¶
SendP2PMessage sends a peer-to-peer message to a specific peer. It sends one or more envelopes in a single batch.
func (*Waku) SendRawP2PDirect ¶
SendRawP2PDirect sends a peer-to-peer message to a specific peer. It sends one or more envelopes in a single batch.
func (*Waku) SetBloomFilter ¶
SetBloomFilter sets the new bloom filter
func (*Waku) SetBloomFilterMode ¶
func (*Waku) SetFullNode ¶ added in v0.59.0
func (*Waku) SetLightClientMode ¶
SetLightClientMode makes node light client (does not forward any messages)
func (*Waku) SetMaxMessageSize ¶
SetMaxMessageSize sets the maximal message size allowed by this node
func (*Waku) SetMinimumPoW ¶
SetMinimumPoW sets the minimal PoW required by this node
func (*Waku) SetTimeSource ¶
SetTimeSource assigns a particular source of time to a waku object.
func (*Waku) SetTopicInterest ¶
SetTopicInterest sets the new topicInterest
func (*Waku) Start ¶
Start implements node.Service, starting the background data propagation thread of the Waku protocol.
func (*Waku) Stop ¶
Stop implements node.Service, stopping the background data propagation thread of the Waku protocol.
func (*Waku) Subscribe ¶
Subscribe installs a new message handler used for filtering, decrypting and subsequent storing of incoming messages.
func (*Waku) SubscribeEnvelopeEvents ¶
func (w *Waku) SubscribeEnvelopeEvents(events chan<- common.EnvelopeEvent) event.Subscription
SubscribeEnvelopeEvents subscribes to envelopes feed. In order to prevent blocking waku producers events must be amply buffered.
func (*Waku) TopicInterest ¶
TopicInterest returns the all the topics of interest. The nodes are required to send only messages that match the advertised topics. If a message does not match the topic-interest, it will tantamount to spam, and the peer will be disconnected.
func (*Waku) Unsubscribe ¶
Unsubscribe removes an installed message handler. TODO: This does not seem to update the bloom filter, but does update the topic interest map
func (*Waku) UnsubscribeMany ¶ added in v0.69.0
Unsubscribe removes an installed message handler. TODO: This does not seem to update the bloom filter, but does update the topic interest map