9/WAKU-RPC

Status: stable
Editor: Andrea Maria Piana <andreap@status.im>
Contributors:
- Dean Eigenmann <dean@status.im>
- Oskar Thorén <oskarth@titanproxy.com>

This specification describes the RPC API that Waku nodes MAY adhere to. The unified API allows clients to easily be able to connect to any node implementation. The API described is privileged as a node stores the keys of clients.

Introduction

This API is based off the Whisper V6 RPC API.

Wire Protocol

Transport

Nodes SHOULD expose a JSON RPC API that can be accessed. The JSON RPC version SHOULD be 2.0. Below is an example request:

{
  "jsonrpc":"2.0",
  "method":"waku_version",
  "params":[],
  "id":1
}

Fields

Field	Description
`jsonrpc`	Contains the used JSON RPC version (`Default: 2.0`)
`method`	Contains the JSON RPC method that is being called
`params`	An array of parameters for the request
`id`	The request ID

Objects

In this section you will find objects used throughout the JSON RPC API.

Message

The message object represents a Waku message. Below you will find the description of the attributes contained in the message object. A message is the decrypted payload and padding of an envelope along with all of its metadata and other extra information such as the hash.

Field	Type	Description
`sig`	string	Public Key that signed this message
`recipientPublicKey`	string	The recipients public key
`ttl`	number	Time-to-live in seconds
`timestamp`	number	Unix timestamp of the message generation
`topic`	string	4 bytes, the message topic
`payload`	string	Decrypted payload
`padding`	string	Optional padding, byte array of arbitrary length
`pow`	number	The proof of work value
`hash`	string	Hash of the enveloped message

Filter

The filter object represents filters that can be applied to retrieve messages. Below you will find the description of the attributes contained in the filter object.

Field	Type	Description
`symKeyID`	string	ID of the symmetric key for message decryption
`privateKeyID`	string	ID of private (asymmetric) key for message decryption
`sig`	string	Public key of the signature
`minPow`	number	Minimal PoW requirement for incoming messages
`topics`	array	Array of possible topics, this can also contain partial topics
`allowP2P`	boolean	Indicates if this filter allows processing of direct peer-to-peer messages

All fields are optional, however symKeyID or privateKeyID must be present, it cannot be both. Additionally, the topics field is only optional when an asymmetric key is used.

Methods

`waku_version`

The waku_version method returns the current version number.

Parameters

none

Response

string - The version number.

`waku_info`

The waku_info method returns information about a Waku node.

Parameters

none

Response

The response is an Object containing the following fields:

minPow [number] - The current PoW requirement.
maxEnvelopeSize [float] - The current maximum envelope size in bytes.
memory [number] - The memory size of the floating messages in bytes.
envelopes [number] - The number of floating envelopes.

`waku_setMaxEnvelopeSize`

Sets the maximum envelope size allowed by this node. Any envelopes larger than this size both incoming and outgoing will be rejected. The envelope size can never exceed the underlying envelope size of 10mb.

Parameters

number - The message size in bytes.

Response

bool - true on success or an error on failure.

`waku_setMinPoW`

Sets the minimal PoW required by this node.

Parameters

number - The new PoW requirement.

Response

bool - true on success or an error on failure.

`waku_markTrustedPeer`

Marks a specific peer as trusted allowing it to send expired messages.

Parameters

string - enode of the peer.

Response

bool - true on success or an error on failure.

`waku_newKeyPair`

Generates a keypair used for message encryption and decryption.

Parameters

none

Response

string - Key ID on success or an error on failure.

`waku_addPrivateKey`

Stores a key and returns its ID.

Parameters

string - Private key as hex bytes.

Response

string - Key ID on success or an error on failure.

`waku_deleteKeyPair`

Deletes a specific key if it exists.

Parameters

string - ID of the Key pair.

Response

bool - true on success or an error on failure.

`waku_hasKeyPair`

Checks if the node has a private key of a key pair matching the given ID.

Parameters

string - ID of the Key pair.

Response

bool - true or false or an error on failure.

`waku_getPublicKey`

Returns the public key for an ID.

Parameters

string - ID of the Key.

Response

string - The public key or an error on failure.

`waku_getPrivateKey`

Returns the private key for an ID.

Parameters

string - ID of the Key.

Response

string - The private key or an error on failure.

`waku_newSymKey`

Generates a random symmetric key and stores it under an ID. This key can be used to encrypt and decrypt messages where the key is known to both parties.

Parameters

none

Response

string - The key ID or an error on failure.

`waku_addSymKey`

Stores the key and returns its ID.

Parameters

string - The raw key for symmetric encryption hex encoded.

Response

string - The key ID or an error on failure.

`waku_generateSymKeyFromPassword`

Generates the key from a password and stores it.

Parameters

string - The password.

Response

string - The key ID or an error on failure.

`waku_hasSymKey`

Returns whether there is a key associated with the ID.

Parameters

string - ID of the Key.

Response

bool - true or false or an error on failure.

`waku_getSymKey`

Returns the symmetric key associated with an ID.

Parameters

string - ID of the Key.

Response

string - Raw key on success or an error of failure.

`waku_deleteSymKey`

Deletes the key associated with an ID.

Parameters

string - ID of the Key.

Response

bool - true or false or an error on failure.

`waku_subscribe`

Creates and registers a new subscription to receive notifications for inbound Waku messages.

Parameters

The parameters for this request is an array containing the following fields:

string - The ID of the function call, in case of Waku this must contain the value "messages".
object - The message filter.

Response

string - ID of the subscription or an error on failure.

Notifications

Notifications received by the client contain a message matching the filter. Below is an example notification:

{
  "jsonrpc": "2.0",
  "method": "waku_subscription",
  "params": {
    "subscription": "02c1f5c953804acee3b68eda6c0afe3f1b4e0bec73c7445e10d45da333616412",
    "result": {
      "sig": "0x0498ac1951b9078a0549c93c3f6088ec7c790032b17580dc3c0c9e900899a48d89eaa27471e3071d2de6a1f48716ecad8b88ee022f4321a7c29b6ffcbee65624ff",
      "recipientPublicKey": null,
      "ttl": 10,
      "timestamp": 1498577270,
      "topic": "0xffaadd11",
      "payload": "0xffffffdddddd1122",
      "padding": "0x35d017b66b124dd4c67623ed0e3f23ba68e3428aa500f77aceb0dbf4b63f69ccfc7ae11e39671d7c94f1ed170193aa3e327158dffdd7abb888b3a3cc48f718773dc0a9dcf1a3680d00fe17ecd4e8d5db31eb9a3c8e6e329d181ecb6ab29eb7a2d9889b49201d9923e6fd99f03807b730780a58924870f541a8a97c87533b1362646e5f573dc48382ef1e70fa19788613c9d2334df3b613f6e024cd7aadc67f681fda6b7a84efdea40cb907371cd3735f9326d02854",
      "pow": 0.6714754098360656,
      "hash": "0x17f8066f0540210cf67ef400a8a55bcb32a494a47f91a0d26611c5c1d66f8c57"
    }
  }
}

`waku_unsubscribe`

Cancels and removes an existing subscription. The node MUST stop sending the client notifications.

Parameters

string - The subscription ID.

Response

bool - true or false

`waku_newMessageFilter`

Creates a new message filter within the node. This filter can be used to poll for new messages that match the criteria.

Parameters

The request must contain a message filter as its parameter.

Response

string - The ID of the filter.

`waku_deleteMessageFilter`

Removes a message filter from the node.

Parameters

string - ID of the filter created with waku_newMessageFilter.

Response

bool - true on success or an error on failure.

`waku_getFilterMessages`

Retrieves messages that match a filter criteria and were received after the last time this function was called.

Parameters

string - ID of the filter created with waku_newMessageFilter.

Response

The response contains an array of messages or an error on failure.

`waku_post`

The waku_post method creates a waku envelope and propagates it to the network.

Parameters

The parameters is an Object containing the following fields:

symKeyID [string] optional - The ID of the symmetric key used for encryption
pubKey [string] optional - The public key for message encryption.
sig [string] optional - The ID of the signing key.
ttl [number] - The time-to-live in seconds.
topic [string] - 4 bytes message topic.
payload [string] - The payload to be encrypted.
padding [string] optional - The padding, a byte array of arbitrary length.
powTime [number] - Maximum time in seconds to be spent on the proof of work.
powTarget [number] - Minimal PoW target required for this message.
targetPeer [string] optional - The optional peer ID for peer-to-peer messages.

Either the symKeyID or the pubKey need to be present. It can not be both.

Response

bool - true on success or an error on failure.

Changelog

Version	Comment
1.0.0	Initial release.

Introduction​

Wire Protocol​

Transport​

Fields​

Objects​

Message​

Filter​

Methods​

waku_version​

Parameters​

Response​

waku_info​

waku_setMaxEnvelopeSize​

waku_setMinPoW​

waku_markTrustedPeer​

waku_newKeyPair​

waku_addPrivateKey​

waku_deleteKeyPair​

waku_hasKeyPair​

waku_getPublicKey​

waku_getPrivateKey​

waku_newSymKey​

waku_addSymKey​

waku_generateSymKeyFromPassword​

waku_hasSymKey​

waku_getSymKey​

waku_deleteSymKey​

waku_subscribe​

waku_unsubscribe​

waku_newMessageFilter​

waku_deleteMessageFilter​

waku_getFilterMessages​

waku_post​

Changelog​

Copyright​

Introduction

Wire Protocol

Transport

Fields

Objects

Message

Filter

Methods

`waku_version`

Parameters

Response

`waku_info`

`waku_setMaxEnvelopeSize`

`waku_setMinPoW`

`waku_markTrustedPeer`

`waku_newKeyPair`

`waku_addPrivateKey`

`waku_deleteKeyPair`

`waku_hasKeyPair`

`waku_getPublicKey`

`waku_getPrivateKey`

`waku_newSymKey`

`waku_addSymKey`

`waku_generateSymKeyFromPassword`

`waku_hasSymKey`

`waku_getSymKey`

`waku_deleteSymKey`

`waku_subscribe`

`waku_unsubscribe`

`waku_newMessageFilter`

`waku_deleteMessageFilter`

`waku_getFilterMessages`

`waku_post`

Changelog

Copyright