Fix generateAddress docs and add error event listener to boilerplate

docs/index.md

@@ -86,6 +86,9 @@ const {RippleAPI} = require('ripple-lib');
 const api = new RippleAPI({
   server: 'wss://s1.ripple.com' // Public rippled server hosted by Ripple, Inc.
 });
+api.on('error', (errorCode, errorMessage) => {
+  console.log(errorCode + ': ' + errorMessage);
+});
 api.connect().then(() => {
   /* insert code here */
 }).then(() => {
@@ -105,6 +108,10 @@ All the code snippets in this documentation assume that you have surrounded them
 If you omit the "catch" section, errors may not be visible.
 </aside>
 
+<aside class="notice">
+The "error" event is emitted whenever an error occurs that cannot be associated with a specific request. If the listener is not registered, an exception will be thrown whenever the event is emitted.
+</aside>
+
 ### Parameters
 
 The RippleAPI constructor optionally takes one argument, an object with the following options:
@@ -3355,7 +3362,11 @@ Generate a new Ripple address and corresponding secret.
 
 ### Parameters
 
-This method has no parameters.
+Name | Type | Description
+---- | ---- | -----------
+options | object | *Optional* Options to control how the address and secret are generated.
+*options.* algorithm | string | *Optional* The digital signature algorithm to generate an address for. Can be `ecdsa-secp256k1` (default) or `ed25519`.
+*options.* entropy | array\<integer\> | *Optional* The entropy to use to generate the seed.
 
 ### Return Value
 
@@ -3369,8 +3380,7 @@ secret | secret string | The secret corresponding to the `address`.
 ### Example
 
 ```javascript
-return api.generateAddress()
-  .then(result => {/* ... */});
+return api.generateAddress();
 ```
 
 
@@ -3482,7 +3492,7 @@ api.on('ledger', ledger => {
 
 ## error
 
-This event is emitted when there is an error on the connection to the server.
+This event is emitted when there is an error on the connection to the server that cannot be associated to a specific request.
 
 ### Return Value
 

docs/src/boilerplate.md.ejs

@@ -8,6 +8,9 @@ const {RippleAPI} = require('ripple-lib');
 const api = new RippleAPI({
   server: 'wss://s1.ripple.com' // Public rippled server hosted by Ripple, Inc.
 });
+api.on('error', (errorCode, errorMessage) => {
+  console.log(errorCode + ': ' + errorMessage);
+});
 api.connect().then(() => {
   /* insert code here */
 }).then(() => {
@@ -27,6 +30,10 @@ All the code snippets in this documentation assume that you have surrounded them
 If you omit the "catch" section, errors may not be visible.
 </aside>
 
+<aside class="notice">
+The "error" event is emitted whenever an error occurs that cannot be associated with a specific request. If the listener is not registered, an exception will be thrown whenever the event is emitted.
+</aside>
+
 ### Parameters
 
 The RippleAPI constructor optionally takes one argument, an object with the following options:

docs/src/events.md.ejs

@@ -20,7 +20,7 @@ api.on('ledger', ledger => {
 
 ## error
 
-This event is emitted when there is an error on the connection to the server.
+This event is emitted when there is an error on the connection to the server that cannot be associated to a specific request.
 
 ### Return Value
 

docs/src/generateAddress.md.ejs

@@ -6,7 +6,7 @@ Generate a new Ripple address and corresponding secret.
 
 ### Parameters
 
-This method has no parameters.
+<%- renderSchema('input/generate-address.json') %>
 
 ### Return Value
 
@@ -17,8 +17,7 @@ This method returns an object with the following structure:
 ### Example
 
 ```javascript
-return api.generateAddress()
-  .then(result => {/* ... */});
+return api.generateAddress();
 ```
 
 <%- renderFixture('responses/generate-address.json') %>

src/api.js

@@ -46,7 +46,8 @@ const prepareSettings = require('./transaction/settings');
 const sign = require('./transaction/sign');
 const submit = require('./transaction/submit');
 const errors = require('./common').errors;
-const generateAddress = common.generateAddressAPI;
+const generateAddress =
+  require('./offline/generate-address').generateAddressAPI;
 const computeLedgerHash = require('./offline/ledgerhash');
 const getLedger = require('./ledger/ledger');
 

src/common/schema-validator.js

@@ -92,8 +92,9 @@ function loadSchemas() {
     require('./schemas/input/prepare-suspended-payment-cancellation.json'),
     require('./schemas/input/prepare-suspended-payment-execution.json'),
     require('./schemas/input/compute-ledger-hash'),
-    require('./schemas/input/sign'),
-    require('./schemas/input/submit')
+    require('./schemas/input/sign.json'),
+    require('./schemas/input/submit.json'),
+    require('./schemas/input/generate-address.json')
   ];
   const titles = _.map(schemas, schema => schema.title);
   const duplicates = _.keys(_.pick(_.countBy(titles), count => count > 1));

src/common/schemas/input/generate-address.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "title": "generateAddressParameters",
+  "type": "object",
+  "properties": {
+    "options": {
+      "type": "object",
+      "description": "Options to control how the address and secret are generated.",
+      "properties": {
+        "entropy": {
+          "type": "array",
+          "items": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 255
+          },
+          "description": "The entropy to use to generate the seed."
+        },
+        "algorithm": {
+          "type": "string",
+          "enum": ["ecdsa-secp256k1", "ed25519"],
+          "description": "The digital signature algorithm to generate an address for. Can be `ecdsa-secp256k1` (default) or `ed25519`."
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

src/common/utils.js

@@ -2,8 +2,6 @@
 'use strict';
 const _ = require('lodash');
 const BigNumber = require('bignumber.js');
-const errors = require('./errors');
-const keypairs = require('ripple-keypairs');
 const {deriveKeypair} = require('ripple-keypairs');
 
 import type {Amount, RippledAmount} from './types.js';
@@ -37,21 +35,6 @@ function toRippledAmount(amount: Amount): RippledAmount {
   };
 }
 
-function generateAddress(options?: Object): Object {
-  const secret = keypairs.generateSeed(options);
-  const keypair = keypairs.deriveKeypair(secret);
-  const address = keypairs.deriveAddress(keypair.publicKey);
-  return {secret, address};
-}
-
-function generateAddressAPI(options?: Object): Object {
-  try {
-    return generateAddress(options);
-  } catch (error) {
-    throw new errors.UnexpectedError(error.message);
-  }
-}
-
 const FINDSNAKE = /([a-zA-Z]_[a-zA-Z])/g;
 function convertKeysFromSnakeCaseToCamelCase(obj: any): any {
   if (typeof obj === 'object') {
@@ -101,8 +84,6 @@ module.exports = {
   dropsToXrp,
   xrpToDrops,
   toRippledAmount,
-  generateAddress,
-  generateAddressAPI,
   convertKeysFromSnakeCaseToCamelCase,
   removeUndefined,
   rippleTimeToISO8601,

src/common/validate.js

@@ -49,6 +49,7 @@ module.exports = {
   sign: _.partial(schemaValidate, 'signParameters'),
   submit: _.partial(schemaValidate, 'submitParameters'),
   computeLedgerHash: _.partial(schemaValidate, 'computeLedgerHashParameters'),
+  generateAddress: _.partial(schemaValidate, 'generateAddressParameters'),
   apiOptions: _.partial(schemaValidate, 'api-options'),
   instructions: _.partial(schemaValidate, 'instructions')
 };

src/offline/generate-address.js

@@ -0,0 +1,24 @@
+'use strict';
+const keypairs = require('ripple-keypairs');
+const common = require('../common');
+const {errors, validate} = common;
+
+function generateAddress(options?: Object): Object {
+  const secret = keypairs.generateSeed(options);
+  const keypair = keypairs.deriveKeypair(secret);
+  const address = keypairs.deriveAddress(keypair.publicKey);
+  return {secret, address};
+}
+
+function generateAddressAPI(options?: Object): Object {
+  validate.generateAddress({options});
+  try {
+    return generateAddress(options);
+  } catch (error) {
+    throw new errors.UnexpectedError(error.message);
+  }
+}
+
+module.exports = {
+  generateAddressAPI
+};