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](https://github.com/ethereum/go-ethereum/wiki/Whisper-v6-RPC-API).
## Wire Protocol
### Transport
Nodes SHOULD expose a [JSON RPC](https://www.jsonrpc.org/specification) API that can be accessed. The JSON RPC version SHOULD be `2.0`. Below is an example request:
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](/spec/7) along with all of its metadata and other extra information such as the hash.
| `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](https://www.jsonrpc.org/specification#error_object) 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](https://www.jsonrpc.org/specification#error_object) 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](https://www.jsonrpc.org/specification#error_object) on failure.
#### `waku_newKeyPair`
Generates a keypair used for message encryption and decryption.
##### Parameters
none
##### Response
- **string** - Key ID on success or an [error](https://www.jsonrpc.org/specification#error_object) 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](https://www.jsonrpc.org/specification#error_object) 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](https://www.jsonrpc.org/specification#error_object) 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](https://www.jsonrpc.org/specification#error_object) 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](https://www.jsonrpc.org/specification#error_object) 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](https://www.jsonrpc.org/specification#error_object) 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](https://www.jsonrpc.org/specification#error_object) 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](https://www.jsonrpc.org/specification#error_object) 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](https://www.jsonrpc.org/specification#error_object) 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](https://www.jsonrpc.org/specification#error_object) 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](https://www.jsonrpc.org/specification#error_object) 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](https://www.jsonrpc.org/specification#error_object) 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:
1.**string** - The ID of the function call, in case of Waku this must contain the value "messages".
2.**object** - The [message filter](#filter).
##### Response
- **string** - ID of the subscription or an [error](https://www.jsonrpc.org/specification#error_object) on failure.
###### Notifications
Notifications received by the client contain a [message](#message) matching the filter. Below is an example notification:
