plugin: Document JSON-RPC passthrough and notifications

Signed-off-by: Christian Decker <decker.christian@gmail.com>

Author: cdecker

doc/plugins.md

@@ -78,6 +78,10 @@ this example:
 			"description": "Returns the current time in {timezone}",
 			"long_description": "Returns the current time in the timezone that is given as the only parameter.\nThis description may be quite long and is allowed to span multiple lines."
 		}
+	],
+	"subscriptions": [
+		"connect",
+		"disconnect"
 	]
 }
 ```
@@ -109,8 +113,12 @@ simple JSON object containing the options:
 
 ```json
 {
-	"objects": {
+	"options": {
 		"greeting": "World"
+	},
+	"configuration": {
+		 "lightning-dir": "/home/user/.lightning",
+		 "rpc-file": "lightning-rpc"
 	}
 }
 ```
@@ -120,10 +128,98 @@ arbitrary and will currently be discarded by `lightningd`. JSON-RPC
 commands were chosen over notifications in order not to force plugins
 to implement notifications which are not that well supported.
 
-## Event stream subscriptions
+## JSON-RPC passthrough
 
-*TBD*
+Plugins may register their own JSON-RPC methods that are exposed
+through the JSON-RPC provided by `lightningd`. This provides users
+with a single interface to interact with, while allowing the addition
+of custom methods without having to modify the daemon itself.
+
+JSON-RPC methods are registered as part of the `getmanifest`
+result. Each registered method must provide a `name` and a
+`description`. An optional `long_description` may also be
+provided. This information is then added to the internal dispatch
+table, and used to return the help text when using `lightning-cli
+help`, and the methods can be called using the `name`.
+
+For example the above `getmanifest` result will register two methods,
+called `hello` and `gettime`:
+
+```json
+    ...
+	"rpcmethods": [
+		{
+			"name": "hello",
+			"description": "Returns a personalized greeting for {greeting} (set via options)."
+		},
+		{
+			"name": "gettime",
+			"description": "Returns the current time in {timezone}",
+			"long_description": "Returns the current time in the timezone that is given as the only parameter.\nThis description may be quite long and is allowed to span multiple lines."
+		}
+	],
+	...
+```
+
+The RPC call will be passed through unmodified, with the exception of
+the JSON-RPC call `id`, which is internally remapped to a unique
+integer instead, in order to avoid collisions. When passing the result
+back the `id` field is restored to its original value.
+
+## Event notifications
 
+Event notifications allow a plugin to subscribe to events in
+`lightningd`. `lightningd` will then send a push notification if an
+event matching the subscription occurred. A notification is defined in
+the JSON-RPC [specification][jsonrpc-spec] as an RPC call that does
+not include an `id` parameter:
+
+> A Notification is a Request object without an "id" member. A Request
+> object that is a Notification signifies the Client's lack of
+> interest in the corresponding Response object, and as such no
+> Response object needs to be returned to the client. The Server MUST
+> NOT reply to a Notification, including those that are within a batch
+> request.
+>
+> Notifications are not confirmable by definition, since they do not
+> have a Response object to be returned. As such, the Client would not
+> be aware of any errors (like e.g. "Invalid params","Internal
+> error").
+
+Plugins subscribe by returning an array of subscriptions as part of
+the `getmanifest` response. The result for the `getmanifest` call
+above for example subscribes to the two topics `connect` and
+`disconnect`. The topics that are currently defined and the
+corresponding payloads are listed below.
+
+### Notification Types
+
+#### `connect`
+
+A notification for topic `connect` is sent every time a new connection
+to a peer is established.
+
+```json
+{
+	"id": "02f6725f9c1c40333b67faea92fd211c183050f28df32cac3f9d69685fe9665432",
+	"address": "1.2.3.4"
+}
+```
+
+#### `disconnect`
+
+A notification for topic `disconnect` is sent every time a connection
+to a peer was lost.
+
+```json
+{
+	"id": "02f6725f9c1c40333b67faea92fd211c183050f28df32cac3f9d69685fe9665432"
+}
+```
 ## Hooks
 
 *TBD*
+
+
+[jsonrpc-spec]: https://www.jsonrpc.org/specification
+[jsonrpc-notification-spec]: https://www.jsonrpc.org/specification#notification