Merge pull request #5833 from paritytech/pubsub-docs

Docs for Pub-Sub, optional parameter for parity_subscribe

js/src/api/api.spec.js

@@ -36,12 +36,19 @@ describe('api/Api', () => {
 
   describe('interface', () => {
     const api = new Api(new Api.Transport.Http(TEST_HTTP_URL, -1));
+    const ignored = [
+      'eth_subscribe', 'eth_unsubscribe',
+      'parity_subscribe', 'parity_unsubscribe',
+      'signer_subscribePending', 'signer_unsubscribePending'
+    ];
 
     Object.keys(ethereumRpc).sort().forEach((endpoint) => {
       describe(endpoint, () => {
-        Object.keys(ethereumRpc[endpoint]).sort().forEach((method) => {
-          endpointTest(api, endpoint, method);
-        });
+        Object.keys(ethereumRpc[endpoint]).sort()
+          .filter(method => ignored.indexOf(method) !== -1)
+          .forEach((method) => {
+            endpointTest(api, endpoint, method);
+          });
       });
     });
   });

js/src/jsonrpc/interfaces/eth.js

@@ -17,6 +17,8 @@
 import { Address, BlockNumber, Data, Hash, Quantity, CallRequest, TransactionRequest } from '../types';
 import { withPreamble, fromDecimal, withComment, Dummy } from '../helpers';
 
+const SUBDOC_PUBSUB = 'pubsub';
+
 export default withPreamble(`
 
 ## The default block parameter
@@ -1192,5 +1194,60 @@ The following options are possible for the \`defaultBlock\` parameter:
       type: Boolean,
       desc: 'whether the call was successful'
     }
+  },
+
+  // Pub-Sub
+  subscribe: {
+    subdoc: SUBDOC_PUBSUB,
+    desc: `
+Starts a subscription (on WebSockets / IPC / TCP transports) to a particular event. For every event that
+matches the subscription a JSON-RPC notification with event details and subscription ID will be sent to a client.
+
+An example notification received by subscribing to \`newHeads\` event:
+\`\`\`
+{"jsonrpc":"2.0","method":"eth_subscription","params":{"subscription":"0x416d77337e24399d","result":{"difficulty":"0xd9263f42a87",<...>,
+"uncles":[]}}}
+\`\`\`
+
+You can unsubscribe using \`eth_unsubscribe\` RPC method. Subscriptions are also tied to a transport
+connection, disconnecting causes all subscriptions to be canceled.
+    `,
+    params: [
+      {
+        type: String,
+        desc: 'Subscription type: one of `newHeads`, `logs`',
+        example: 'newHeads'
+      },
+      {
+        type: Object,
+        desc: `
+Subscription type-specific parameters. It must be left empty for
+\`newHeads\` and must contain filter object for \`logs\`.
+        `,
+        example: {
+          fromBlock: 'latest',
+          toBlock: 'latest'
+        }
+      }
+    ],
+    returns: {
+      type: String,
+      desc: 'Assigned subscription ID',
+      example: '0x416d77337e24399d'
+    }
+  },
+  unsubscribe: {
+    subdoc: SUBDOC_PUBSUB,
+    desc: 'Unsubscribes from a subscription.',
+    params: [{
+      type: String,
+      desc: 'Subscription ID',
+      example: '0x416d77337e24399d'
+    }],
+    returns: {
+      type: Boolean,
+      desc: 'whether the call was successful',
+      example: true
+    }
   }
 });

js/src/jsonrpc/interfaces/parity.js

@@ -26,6 +26,7 @@ const SECTION_VAULT = 'Account Vaults';
 
 const SUBDOC_SET = 'set';
 const SUBDOC_ACCOUNTS = 'accounts';
+const SUBDOC_PUBSUB = 'pubsub';
 
 export default {
   accountsInfo: {
@@ -2005,6 +2006,54 @@ export default {
       desc: 'Base58 encoded CID',
       example: 'QmSbFjqjd6nFwNHqsBCC7SK8GShGcayLUEtysJjNGhZAnC'
     }
+  },
+
+  // Pub-Sub
+  subscribe: {
+    subdoc: SUBDOC_PUBSUB,
+    desc: `
+Starts a subscription (on WebSockets / IPC / TCP transports) to results of calling some other RPC method.
+For every change in returned value of that RPC call a JSON-RPC notification with result and subscription ID will be sent to a client.
+
+An example notification received by subscribing to \`eth_accounts\` RPC method:
+\`\`\`
+{"jsonrpc":"2.0","method":"parity_subscription","params":{"subscription":"0x416d77337e24399d","result":["0xcd2a3d9f938e13cd947ec05abc7fe734df8dd826"]}}
+\`\`\`
+
+You can unsubscribe using \`parity_unsubscribe\` RPC method. Subscriptions are also tied to a transport
+connection, disconnecting causes all subscriptions to be canceled.
+    `,
+    params: [
+      {
+        type: String,
+        desc: 'RPC method name',
+        example: 'eth_getBalance'
+      },
+      {
+        type: Array,
+        desc: 'Parameters passed to RPC method. (Optional, defaults to no parameters)',
+        example: ['0xcd2a3d9f938e13cd947ec05abc7fe734df8dd826', 'latest']
+      }
+    ],
+    returns: {
+      type: String,
+      desc: 'Assigned subscription ID',
+      example: '0x416d77337e24399d'
+    }
+  },
+  unsubscribe: {
+    subdoc: SUBDOC_PUBSUB,
+    desc: 'Unsubscribes from a subscription.',
+    params: [{
+      type: String,
+      desc: 'Subscription ID',
+      example: '0x416d77337e24399d'
+    }],
+    returns: {
+      type: Boolean,
+      desc: 'whether the call was successful',
+      example: true
+    }
   }
 
 };

js/src/jsonrpc/interfaces/signer.js

@@ -198,5 +198,40 @@ export default {
       desc: '`true` when enabled, `false` when disabled.',
       example: true
     }
+  },
+
+  // Pub-Sub
+  subscribePending: {
+    desc: `
+Starts a subscription for transactions in the confirmation queue.
+Each event contains all transactions currently in the queue.
+
+An example notification received by subscribing to this event:
+\`\`\`
+{"jsonrpc":"2.0","method":"signer_pending","params":{"subscription":"0x416d77337e24399d","result":[]}}
+\`\`\`
+
+You can unsubscribe using \`signer_unsubscribePending\` RPC method. Subscriptions are also tied to a transport
+connection, disconnecting causes all subscriptions to be canceled.
+    `,
+    params: [],
+    returns: {
+      type: String,
+      desc: 'Assigned subscription ID',
+      example: '0x416d77337e24399d'
+    }
+  },
+  unsubscribePending: {
+    desc: 'Unsubscribes from pending transactions subscription.',
+    params: [{
+      type: String,
+      desc: 'Subscription ID',
+      example: '0x416d77337e24399d'
+    }],
+    returns: {
+      type: Boolean,
+      desc: 'whether the call was successful',
+      example: true
+    }
   }
 };