JSON-RPC interfaces with documentation (#4276)

* Extended Markdown generator

* Synced and extended all JSON-RPC interfaces

* Fix linter errors

* Format `parity_listAccounts` output in API

* typo

js/src/api/rpc/parity/parity.js

@@ -14,7 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with Parity.  If not, see <http://www.gnu.org/licenses/>.
 
-import { inAddress, inAddresses, inData, inHex, inNumber16, inOptions } from '../../format/input';
+import { inAddress, inAddresses, inData, inHex, inNumber16, inOptions, inBlockNumber } from '../../format/input';
 import { outAccountInfo, outAddress, outAddresses, outChainStatus, outHistogram, outNumber, outPeers, outTransaction } from '../../format/output';
 
 export default class Parity {
@@ -101,6 +101,11 @@ export default class Parity {
       .execute('parity_enode');
   }
 
+  encryptMessage (pubkey, data) {
+    return this._transport
+      .execute('parity_encryptMessage', inHex(pubkey), inHex(data));
+  }
+
   executeUpgrade () {
     return this._transport
       .execute('parity_executeUpgrade');
@@ -111,6 +116,17 @@ export default class Parity {
       .execute('parity_extraData');
   }
 
+  futureTransactions () {
+    return this._transport
+      .execute('parity_futureTransactions');
+  }
+
+  gasCeilTarget () {
+    return this._transport
+      .execute('parity_gasCeilTarget')
+      .then(outNumber);
+  }
+
   gasFloorTarget () {
     return this._transport
       .execute('parity_gasFloorTarget')
@@ -156,11 +172,22 @@ export default class Parity {
       .execute('parity_killAccount', inAddress(account), password);
   }
 
+  listAccounts (count, offset = null, blockNumber = 'latest') {
+    return this._transport
+      .execute('parity_listAccounts', count, inAddress(offset), inBlockNumber(blockNumber))
+      .then((accounts) => (accounts || []).map(outAddress));
+  }
+
   listRecentDapps () {
     return this._transport
       .execute('parity_listRecentDapps');
   }
 
+  listStorageKeys (address, count, hash = null, blockNumber = 'latest') {
+    return this._transport
+      .execute('parity_listStorageKeys', inAddress(address), count, inHex(hash), inBlockNumber(blockNumber));
+  }
+
   removeAddress (address) {
     return this._transport
       .execute('parity_removeAddress', inAddress(address));
@@ -311,16 +338,31 @@ export default class Parity {
       .execute('parity_setDappsAddresses', dappId, inAddresses(addresses));
   }
 
+  setEngineSigner (address, password) {
+    return this._transport
+      .execute('parity_setEngineSigner', inAddress(address), password);
+  }
+
   setExtraData (data) {
     return this._transport
       .execute('parity_setExtraData', inData(data));
   }
 
+  setGasCeilTarget (quantity) {
+    return this._transport
+      .execute('parity_setGasCeilTarget', inNumber16(quantity));
+  }
+
   setGasFloorTarget (quantity) {
     return this._transport
       .execute('parity_setGasFloorTarget', inNumber16(quantity));
   }
 
+  setMaxTransactionGas (quantity) {
+    return this._transport
+      .execute('parity_setMaxTransactionGas', inNumber16(quantity));
+  }
+
   setMinGasPrice (quantity) {
     return this._transport
       .execute('parity_setMinGasPrice', inNumber16(quantity));

js/src/jsonrpc/.gitignore

@@ -0,0 +1 @@
+docs

js/src/jsonrpc/interfaces/net.js

@@ -15,6 +15,7 @@
 // along with Parity.  If not, see <http://www.gnu.org/licenses/>.
 
 import { Quantity } from '../types';
+import { fromDecimal } from '../helpers';
 
 export default {
   listening: {
@@ -22,7 +23,8 @@ export default {
     params: [],
     returns: {
       type: Boolean,
-      desc: '`true` when listening, otherwise `false`.'
+      desc: '`true` when listening, otherwise `false`.',
+      example: true
     }
   },
 
@@ -32,7 +34,8 @@ export default {
     returns: {
       type: Quantity,
       desc: 'Integer of the number of connected peers',
-      format: 'utils.toDecimal'
+      format: 'utils.toDecimal',
+      example: fromDecimal(2)
     }
   },
 
@@ -41,7 +44,8 @@ export default {
     params: [],
     returns: {
       type: String,
-      desc: 'The current network protocol version'
+      desc: 'The current network protocol version',
+      example: '8995'
     }
   }
 };

js/src/jsonrpc/interfaces/personal.js

@@ -18,30 +18,36 @@ import { Address, Data, Quantity } from '../types';
 
 export default {
   listAccounts: {
-    desc: 'Returns a list of addresses owned by client.',
+    desc: 'Lists all stored accounts.',
     params: [],
     returns: {
       type: Array,
-      desc: '20 Bytes addresses owned by the client.'
+      desc: 'A list of 20 byte account identifiers.',
+      example: [
+        '0x7bf87721a96849d168de02fd6ea5986a3a147383',
+        '0xca807a90fd64deed760fb98bf0869b475c469348'
+      ]
     }
   },
 
   newAccount: {
-    desc: 'Creates new account',
+    desc: 'Creates new account.\n\n**Note:** it becomes the new current unlocked account. There can only be one unlocked account at a time.',
     params: [
       {
         type: String,
-        desc: 'Password'
+        desc: 'Password for the new account.',
+        example: 'hunter2'
       }
     ],
     returns: {
       type: Address,
-      desc: 'The created address'
+      desc: '20 Bytes - The identifier of the new account.',
+      example: '0x8f0227d45853a50eefd48dd4fec25d5b3fd2295e'
     }
   },
 
   signAndSendTransaction: {
-    desc: 'Sends and signs a transaction given account passphrase. Does not require the account to be unlocked nor unlocks the account for future transactions. ',
+    desc: 'Sends transaction and signs it in a single call. The account does not need to be unlocked to make this call, and will not be left unlocked after.',
     params: [
       {
         type: Object,
@@ -49,59 +55,83 @@ export default {
         details: {
           from: {
             type: Address,
-            desc: '20 Bytes - The address the transaction is send from'
+            desc: '20 Bytes - The address of the account to unlock and send the transaction from.'
           },
           to: {
             type: Address,
-            desc: '20 Bytes - (optional when creating new contract) The address the transaction is directed to'
+            desc: '20 Bytes - (optional when creating new contract) The address the transaction is directed to.'
           },
           gas: {
             type: Quantity,
-            desc: 'Integer of the gas provided for the transaction execution. It will return unused gas',
+            desc: 'Integer of the gas provided for the transaction execution. It will return unused gas.',
             optional: true,
             default: 90000
           },
           gasPrice: {
             type: Quantity,
-            desc: 'Integer of the gasPrice used for each paid gas',
+            desc: 'Integer of the gasPrice used for each paid gas.',
             optional: true,
             default: 'To-Be-Determined'
           },
           value: {
             type: Quantity,
-            desc: 'Integer of the value send with this transaction',
+            desc: 'Integer of the value send with this transaction.',
             optional: true
           },
           data: {
             type: Data,
-            desc: 'The compiled code of a contract OR the hash of the invoked method signature and encoded parameters. For details see [Ethereum Contract ABI](https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI)'
+            desc: 'The compiled code of a contract OR the hash of the invoked method signature and encoded parameters. For details see [Ethereum Contract ABI](https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI).'
           },
           nonce: {
             type: Quantity,
             desc: 'Integer of a nonce. This allows to overwrite your own pending transactions that use the same nonce.',
             optional: true
           }
+        },
+        example: {
+          from: '0x407d73d8a49eeb85d32cf465507dd71d507100c1',
+          to: '0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b',
+          data: '0x41cd5add4fd13aedd64521e363ea279923575ff39718065d38bd46f0e6632e8e',
+          value: '0x186a0'
         }
       },
       {
         type: String,
-        desc: 'Passphrase to unlock `from` account.'
+        desc: 'Passphrase to unlock the `from` account.',
+        example: 'hunter2'
       }
     ],
     returns: {
       type: Data,
-      desc: '32 Bytes - the transaction hash, or the zero hash if the transaction is not yet available'
+      desc: '32 Bytes - the transaction hash, or the zero hash if the transaction is not yet available',
+      example: '0x62e05075829655752e146a129a044ad72e95ce33e48ff48118b697e15e7b41e4'
     }
   },
 
   unlockAccount: {
-    desc: '?',
+    desc: 'Unlocks specified account for use.\n\nIf permanent unlocking is disabled (the default) then the duration argument will be ignored, and the account will be unlocked for a single signing. With permanent locking enabled, the duration sets the number of seconds to hold the account open for. It will default to 300 seconds. Passing 0 unlocks the account indefinitely.\n\nThere can only be one unlocked account at a time.',
     params: [
-      '?', '?', '?'
+      {
+        type: Address,
+        desc: '20 Bytes - The address of the account to unlock.',
+        example: '0x8f0227d45853a50eefd48dd4fec25d5b3fd2295e'
+      },
+      {
+        type: String,
+        desc: 'Passphrase to unlock the account.',
+        example: 'hunter2'
+      },
+      {
+        type: Quantity,
+        default: 300,
+        desc: 'Integer or `null` - Duration in seconds how long the account should remain unlocked for.',
+        example: null
+      }
     ],
     returns: {
       type: Boolean,
-      desc: 'whether the call was successful'
+      desc: 'whether the call was successful',
+      example: true
     }
   }
 };

js/src/jsonrpc/interfaces/shh.js

@@ -41,7 +41,7 @@ export default {
             optional: true
           },
           topics: {
-            type: Array, desc: 'Array of `DATA` topics, for the receiver to identify messages'
+            type: Array, desc: 'Array of `Data` topics, for the receiver to identify messages'
           },
           payload: {
             type: Data, desc: 'The payload of the message'
@@ -117,7 +117,7 @@ export default {
             optional: true
           },
           topics: {
-            type: Array, desc: 'Array of `DATA` topics which the incoming message\'s topics should match.  You can use the following combinations'
+            type: Array, desc: 'Array of `Data` topics which the incoming message\'s topics should match.  You can use the following combinations'
           }
         }
       }

js/src/jsonrpc/interfaces/signer.js

@@ -14,33 +14,38 @@
 // You should have received a copy of the GNU General Public License
 // along with Parity.  If not, see <http://www.gnu.org/licenses/>.
 
-import { Quantity, Data } from '../types';
+import { Quantity, Data, BlockNumber } from '../types';
+import { fromDecimal } from '../helpers';
 
 export default {
   generateAuthorizationToken: {
-    desc: 'Generates a new authorization token',
+    desc: 'Generates a new authorization token.',
     params: [],
     returns: {
       type: String,
-      desc: 'The new authorization token'
+      desc: 'The new authorization token.',
+      example: 'bNGY-iIPB-j7zK-RSYZ'
     }
   },
 
   generateWebProxyAccessToken: {
-    desc: 'Generates a new web proxy access token',
+    desc: 'Generates a new web proxy access token.',
     params: [],
     returns: {
       type: String,
-      desc: 'The new web proxy access token'
+      desc: 'The new web proxy access token.',
+      example: 'MOWm0tEJjwthDiTU'
     }
   },
 
   requestsToConfirm: {
-    desc: 'Returns a list of the transactions requiring authorization',
+    desc: 'Returns a list of the transactions awaiting authorization.',
     params: [],
     returns: {
+      // TODO: Types of the fields of transaction objects? Link to a transaction object in another page?
       type: Array,
-      desc: 'A list of the outstanding transactions'
+      desc: 'A list of the outstanding transactions.',
+      example: []
     }
   },
 
@@ -49,20 +54,41 @@ export default {
     params: [
       {
         type: Quantity,
-        desc: 'The request id'
+        desc: 'The request id.',
+        example: fromDecimal(1)
       },
       {
         type: Object,
-        desc: 'The request options'
+        desc: 'Modify the transaction before confirmation.',
+        details: {
+          gasPrice: {
+            type: Quantity,
+            desc: 'Modify the gas price provided by the sender in Wei.',
+            optional: true
+          },
+          gas: {
+            type: Quantity,
+            desc: 'Gas provided by the sender in Wei.',
+            optional: true
+          },
+          minBlock: {
+            type: BlockNumber,
+            desc: 'Integer block number, or the string `\'latest\'`, `\'earliest\'` or `\'pending\'`. Request will not be propagated till the given block is reached.',
+            optional: true
+          }
+        },
+        example: {}
       },
       {
         type: String,
-        desc: 'The account password'
+        desc: 'The account password',
+        example: 'hunter2'
       }
     ],
     returns: {
       type: Boolean,
-      desc: 'The status of the confirmation'
+      desc: 'The status of the confirmation',
+      example: true
     }
   },
 
@@ -71,16 +97,19 @@ export default {
     params: [
       {
         type: Quantity,
-        desc: 'The request id'
+        desc: 'Integer - The request id',
+        example: fromDecimal(1)
       },
       {
         type: Data,
-        desc: 'Signed request (transaction RLP)'
+        desc: 'Signed request (RLP encoded transaction)',
+        example: '0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675'
       }
     ],
     returns: {
       type: Boolean,
-      desc: 'The status of the confirmation'
+      desc: 'The status of the confirmation',
+      example: true
     }
   },
 
@@ -89,12 +118,14 @@ export default {
     params: [
       {
         type: Quantity,
-        desc: 'The request id'
+        desc: 'Integer - The request id',
+        example: fromDecimal(1)
       }
     ],
     returns: {
       type: Boolean,
-      desc: 'The status of the rejection'
+      desc: 'The status of the rejection',
+      example: true
     }
   },
 
@@ -103,7 +134,8 @@ export default {
     params: [],
     returns: {
       type: Boolean,
-      desc: 'true when enabled, false when disabled'
+      desc: '`true` when enabled, `false` when disabled.',
+      example: true
     }
   }
 };

js/src/jsonrpc/interfaces/web3.js

@@ -15,6 +15,7 @@
 // along with Parity.  If not, see <http://www.gnu.org/licenses/>.
 
 import { Data } from '../types';
+import { withComment } from '../helpers';
 
 export default {
   clientVersion: {
@@ -22,21 +23,24 @@ export default {
     params: [],
     returns: {
       type: String,
-      desc: 'The current client version'
+      desc: 'The current client version',
+      example: 'Parity//v1.5.0-unstable-9db3f38-20170103/x86_64-linux-gnu/rustc1.14.0'
     }
   },
 
   sha3: {
-    desc: 'Returns Keccak-256 (*not* the standardized SHA3-256) of the given data.',
+    desc: 'Returns Keccak-256 (**not** the standardized SHA3-256) of the given data.',
     params: [
       {
         type: String,
-        desc: 'The data to convert into a SHA3 hash'
+        desc: 'The data to convert into a SHA3 hash.',
+        example: withComment('0x68656c6c6f20776f726c64', '"hello world"')
       }
     ],
     returns: {
       type: Data,
-      desc: 'The SHA3 result of the given string'
+      desc: 'The Keccak-256 hash of the given string.',
+      example: '0x47173285a8d7341e5e972fc677286384f802f8ef42a5ec5f03bbfa254cb01fad'
     }
   }
 };