mirrors/core-lightning
1
0
Fork 0
mirror of https://github.com/ElementsProject/lightning.git synced 2024-11-19 09:54:16 +01:00
Code Issues Projects Releases Wiki Activity

docs: Document the custom plugin notifications

Browse Source
This commit is contained in:
Christian Decker 2021-04-29 11:02:47 +02:00 committed by Rusty Russell
parent ef7f9a8022
commit c58b15de19
1 changed files with 66 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
doc/PLUGINS.md
View File

@ -102,6 +102,11 @@ example:
"init": "0E000000",
"invoice": "00AD0000"
},
"notifications": [
{
"method": "mycustomnotification"
}
],
"dynamic": true
}
```
@ -147,6 +152,13 @@ position bits for experiments. If you'd like to standardize your extension
please reach out to the [specification repository][spec] to get a featurebit
assigned.
The `notifications` array allows plugins to announce which custom
notifications they intend to send to `lightningd`. These custom
notifications can then be subscribed to by other plugins, allowing
them to communicate with each other via the existing publish-subscribe
mechanism and react to events that happen in other plugins, or collect
information based on the notification topics.
Plugins are free to register any `name` for their `rpcmethod` as long
as the name was not previously registered. This includes both built-in
methods, such as `help` and `getinfo`, as well as methods registered
@ -206,6 +218,60 @@ Here's an example option set, as sent in response to `getmanifest`
],
```
#### Custom notifications
The plugins may emit custom notifications for topics they have
announced during startup. The list of notification topics declared
during startup must include all topics that may be emitted, in order
to verify that all topics plugins subscribe to are also emitted by
some other plugin, and warn if a plugin subscribes to a non-existent
topic. In case a plugin emits notifications it has not announced the
notification will be ignored and not forwarded to subscribers.
When forwarding a custom notification `lightningd` will wrap the
payload of the notification in an object that contains metadata about
the notification. The following is an example of this
transformation. The first listing is the original notification emitted
by the `sender` plugin, while the second is the the notification as
received by the `receiver` plugin (both listings show the full
[JSON-RPC][jsonrpc-spec] notification to illustrate the wrapping).
```json
{
"jsonrpc": "2.0",
"method": "mycustomnotification",
"params": {
"key": "value",
"message": "Hello fellow plugin!"
}
}
```
is delivered as
```json
{
"jsonrpc": "2.0",
"method": "mycustomnotification",
"params": {
"origin": "sender",
"payload": {
"key": "value",
"message": "Hello fellow plugin!"
}
}
}
```
The notification topic (`method` in the JSON-RPC message) must not
match one of the internal events in order to prevent breaking
subscribers that expect the existing notification format. Multiple
plugins are allowed to emit notifications for the same topics,
allowing things like metric aggregators where the aggregator
subscribes to a common topic and other plugins publish metrics as
notifications.
### The `init` method
The `init` method is required so that `lightningd` can pass back the