From 5bf59a1cc70c6b120e63b6ad88b1be67a24218e1 Mon Sep 17 00:00:00 2001 From: Neil Booth Date: Mon, 2 Jan 2017 19:29:19 +0900 Subject: [PATCH] Add documentation of the RPC interface --- docs/RPC-INTERFACE.rst | 143 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 docs/RPC-INTERFACE.rst diff --git a/docs/RPC-INTERFACE.rst b/docs/RPC-INTERFACE.rst new file mode 100644 index 0000000..db33ba5 --- /dev/null +++ b/docs/RPC-INTERFACE.rst @@ -0,0 +1,143 @@ +The ElectrumX RPC Interface +=========================== + +You can query the status of a running server, and affect its behaviour +using the RPC interface. + +The general form of invocation is: + + ``electrumx_rpc.py [arg1 [arg2...]`` + +The following commands are available: + +* **getinfo** + + Returns a summary of server state. This command takes no arguments. + A typical result is as follows (with annotated comments): + + .. code:: + + $ electrumx_rpc.py getinfo + { + "closing": 1, # The number of sessions being closed down + "daemon_height": 446231, # The daemon's height when last queried + "db_height": 446231, # The height to which the DB is processed + "errors": 1, # Errors across current sessions + "groups": 2, # The number of session groups + "logged": 0, # The number of sessions being logged + "paused": 0, # The number of paused sessions. + "peers": 62, # Number of peer servers (from IRC) + "pid": 126275, # The server's process ID + "requests": 0, # Number of unprocessed requests + "sessions": 85, # Number of current sessions (connections) + "subs": 6235, # Number of current address subscriptions + "txs_sent": 2 # Total transactions sent by ElectrumX + } + + Clients that are slow to consume data sent to them are *paused* + until their socket buffer drains sufficiently, at which point + processing of requests resumes. + + Each ill-formed request, or one that does not follow the Electrum + protocol, increments the error count of the session that sent it. + If the error count reaches a certain level (currently 10) that + client is disconnected. + + Apart from very short intervals, typically after a new block or when + a client has just connected, the number of unprocessed requests + should normally be zero. + + Sessions are put into groups, primarily as an anti-DoS measure. + Initially all connections made within a period of time are put in + the same group. High bandwidth usage by a member of a group + deprioritizes itself, and all members of its group to a lesser + extent. Low-priority sessions have their requests served after + higher priority sessions. ElectrumX will start delaying responses + to a sessions if it becomes sufficiently deprioritized. + +* **sessions** + + Returns a list of all current sessions. Takes no arguments. + + .. code:: + + $ electrumx_rpc.py sessions + + ID Flags Client Reqs Txs Subs Recv Recv KB Sent Sent KB Time Peer + 0 S1 2.7.12 0 0 293 352 34 355 35 0:49:27 192.168.0.1:4093 + 1 T1 2.5.2 0 0 87 141 12 144 13 0:49:25 xxx.xx.xx.x:39272 + 2 T1 all_seeing_eye 0 0 0 10 0 13 2 0:49:25 xxx.xx.xxx.xx:57862 + 3 S1 all_seeing_eye 0 0 0 10 0 13 2 0:49:25 xxx.xx.xxx.xx:41315 + 4 S1 2.6.4 0 0 2,048 2,104 215 2,108 122 0:49:25 xxx.xx.xxx.xx:35287 + ... + 435 R0 RPC 0 0 0 1 0 0 0 0:00:00 [::1]:1484 + + + The columns show the session ID, flags (see below), how the client + identifies itself - typically the Electrum client version, the + number of unprocessed requests, the number of transactions sent, the + number of address subscriptions, the number of requests received and + the bandwidth used, the number of messages sent and the bandwidth + used, how long the client has been connected, and the client's IP + address. + + The flags are: + + * S an SSL connection + * T a TCP connection + * R a local RPC connection + * L a logged session + * C a connection that is being closed + * the non-negative number is the connection priority, with lower + numbers having higher priority. RPC connections have priority + 0, normal connections have priority at least 1. + +* **groups** + + Returns a list of all current groups. Takes no arguments. + + The output is quite similar to the **sessions** command. + +* **disconnect** + + Disconnects the given session IDs. Session IDs can be seen in the + logs or with the **sessions** RPC command. + + .. code:: + + $ ./electrumx_rpc.py disconnect 2 3 + [ + "disconnected 2", + "disconnected 3" + ] + + ElectrumX initiates the socket close process for the passed + sessions. Whilst most connections close quickly, it can take + several minutes for Python to close some SSL connections down. + +* **log** + + Toggles logging of the given session IDs. Session IDs can be seen + in the logs or with the **sessions** RPC command. + + .. code:: + + $ electrumx_rpc.py log 0 1 2 3 4 5 + [ + "log 0: False", + "log 1: False", + "log 2: False", + "log 3: True", + "log 4: True", + "unknown session: 5" + ] + + The return value shows this command turned off logging for sesssions + 0, 1 and 2. It was turned on for sessions 3 and 4, and there was no + session 5. + +* **peers** + + Returns a list of peer electrum servers. This command takes no arguments. + + Currently this is data gleaned from an IRC session.