inclusionStates for getTransfers, getLatestInclusion function. Readme

Author: domschiener

README.md

@@ -2,7 +2,7 @@
 
 This is the official Javascript library for the IOTA Core. It implements both the [official API](https://iota.readme.io/), as well as newly proposed functionality (such as signing, bundles, utilities and conversion).
 
-It should be noted that the Javascript Library as it stands right now is an **early beta release**. As such, there might be some unexpected results. Please join the community (see links below) and post [issues on here](https://github.com/iotaledger/iota.lib.js/issues), to ensure that the developers of the library can improve it. 
+It should be noted that the Javascript Library as it stands right now is an **early beta release**. As such, there might be some unexpected results. Please join the community (see links below) and post [issues on here](https://github.com/iotaledger/iota.lib.js/issues), to ensure that the developers of the library can improve it.
 
 > **Join the Discussion**
 
@@ -33,11 +33,14 @@ It should be noted that this is a temporary home for the official documentation.
 
 ## Getting Started
 
-After you've successfully installed the library, it is fairly easy to get started by simply launching a new instance of the IOTA object:
+After you've successfully installed the library, it is fairly easy to get started by simply launching a new instance of the IOTA object. When instantiating the object you have the option to decide the `host` and `port` that are used for sending the requests to, as can be seen in the example below:
 
 ```
 // Create IOTA instance
-var iota = new IOTA();
+var iota = new IOTA({
+    'host': 'http://localhost',
+    'port': 14265
+});
 
 // now you can start using all of the functions
 iota.api.getNodeInfo();
@@ -72,6 +75,7 @@ iota.api.getNodeInfo(function(error, success) {
 - **[api](#api)**
     - **[Standard API](#standard-api)**
     - **[getTransactionsObjects](#gettransactionsobjects)**
+    - **[getLatestInclusion](#getlatestinclusion)**
     - **[broadcastAndStore](#broadcastandstore)**
     - **[getNewAddress](#getnewaddress)**
     - **[getInputs](#getinputs)**
@@ -127,6 +131,25 @@ iota.api.getTransactionsObjects(hashes, callback)
 
 ---
 
+### `getLatestInclusion`
+
+Wrapper function for `getNodeInfo` and `getInclusionStates`. It simply takes the most recent solid milestone as returned by getNodeInfo, and uses it to get the inclusion states of a list of transaction hashes.
+
+
+#### Input
+```
+iota.api.getLatestInclusion(hashes, callback)
+```
+
+1. **`hashes`**: `Array` List of transaction hashes
+2. **`callback`**: `Function` callback.
+
+#### Return Value
+
+1. **`Array`** - list of all the inclusion states of the transaction hashes
+
+---
+
 ### `broadcastAndStore`
 
 Wrapper function for `broadcastTransactions` and `storeTransactions`.
@@ -318,7 +341,7 @@ iota.api.getBundle(transaction, callback)
 
 ### `getTransfers`
 
-Returns the transfers which are associated with a seed. The transfers are determined by either calculating deterministically which addresses were already used, or by providing a list of indexes to get the transfers from.
+Returns the transfers which are associated with a seed. The transfers are determined by either calculating deterministically which addresses were already used, or by providing a list of indexes to get the addresses and the associated transfers from. The transfers are sorted by their timestamp. It should be noted that, because timestamps are not enforced in IOTA, that this may lead to incorrectly sorted bundles (meaning that their chronological ordering in the Tangle is different).
 
 #### Input
 ```
@@ -327,7 +350,8 @@ getTransfers(seed [, options], callback)
 
 1. **`seed`**: `String` tryte-encoded seed. It should be noted that this seed is not transferred
 2. **`options`**: `Object` which is optional:
-  - **`indexes`**: `Array` - optional. If the index of addresses is provided, it will be used to get all transfers associated with the addresses.
+  - **`start`**: `Int` Starting key index for search
+  - **`end`**: `Int` Ending key index for search
   - **`inclusionStates`**: `Bool` If True, it gets the inclusion states of the transfers.
 3. **`callback`**: `Function` Optional callback.
 

bower.json

@@ -1,6 +1,6 @@
 {
     "name": "iota.lib.js",
-    "version": "0.0.4",
+    "version": "0.0.4.1",
     "description": "Javascript Library for the IOTA API.",
     "main": "./dist/iota.js",
     "authors": [

lib/api/api.js

@@ -430,7 +430,7 @@ api.prototype.storeTransactions = function(trytes, callback) {
 
 /*************************************
 
-WRAPPER FUNCTIONS
+WRAPPER AND CUSTOM  FUNCTIONS
 
 **************************************/
 
@@ -473,6 +473,28 @@ api.prototype.getTransactionsObjects = function(hashes, callback) {
     })
 }
 
+/**
+*   Wrapper function for getNodeInfo and getInclusionStates
+*
+*   @method getLatestInclusion
+*   @param {array} hashes
+*   @returns {function} callback
+*   @returns {object} success
+**/
+api.prototype.getLatestInclusion = function(hashes, callback) {
+
+    var self = this;
+
+    self.getNodeInfo(function(e, nodeInfo) {
+
+        if (e) return callback(e);
+
+        var latestMilestone = nodeInfo.latestSolidSubtangleMilestone;
+
+        return self.getInclusionStates(hashes, latestMilestone, callback);
+    })
+}
+
 /**
 *   Broadcasts and stores transaction trytes
 *
@@ -659,11 +681,11 @@ api.prototype._newAddress = function(seed, index, checksum) {
 *   @param {string} seed
 *   @param {object} options
 *       @property {int} index Key index to start search from
-*       @property {bool} checksum
-*       @property {int} total Total number o f addresses to return
-*       @property {bool} returnAll return all searched addresses or not
+*       @property {bool} checksum add 9-tryte checksum
+*       @property {int} total Total number of addresses to return
+*       @property {bool} returnAll return all searched addresses
 *   @param {function} callback
-*   @returns {array} address List of addresses
+*   @returns {string | array} address List of addresses
 **/
 api.prototype.getNewAddress = function(seed, options, callback) {
 
@@ -737,7 +759,7 @@ api.prototype.getNewAddress = function(seed, options, callback) {
 
                 // If returnAll, return list of allAddresses
                 // else return the last address that was generated
-                var addressToReturn = options.returnAll ? allAddresses : Array(address);
+                var addressToReturn = options.returnAll ? allAddresses : address;
 
                 return callback(null, addressToReturn);
             }
@@ -1317,16 +1339,13 @@ api.prototype.getBundle = function(transaction, callback) {
 }
 
 
-
-
-
 /**
 *   @method getTransfers
 *   @param {string} seed
 *   @param {object} options
 *       @property {int} start Starting key index
 *       @property {int} end Ending key index
-*       @property {bool} inclusionStates
+*       @property {bool} inclusionStates returns confirmation status of all transactions
 *   @param {function} callback
 *   @returns {object} success
 **/
@@ -1350,12 +1369,10 @@ api.prototype.getTransfers = function(seed, options, callback) {
         return callback(new Error("Invalid inputs provided"))
     }
 
-
     // first call findTransactions
     // If a transaction is non tail, get the tail transactions associated with it
     // add it to the list of tail transactions
 
-
     var addressOptions = {
         index: start,
         total: end ? end - start : null,
@@ -1398,26 +1415,72 @@ api.prototype.getTransfers = function(seed, options, callback) {
                 var finalBundles = [];
                 var tailTxArray = Array.from(tailTransactions);
 
-                async.map(tailTxArray, function(tailTx, cb) {
 
-                     self.getBundle(tailTx, function(error, bundle) {
+                // If inclusionStates, get the confirmation status
+                // of the tail transactions, and thus the bundles
+                async.waterfall([
 
-                         if (!error) {
-                             finalBundles.push(bundle);
-                         }
-                         cb(null, true);
-                     })
-                }, function(error, results) {
+                    //
+                    // 1. Function
+                    //
+                    function(cb) {
 
-                    // credit: http://stackoverflow.com/a/8837505
-                    // Sort by timestamp
-                    finalBundles.sort(function(a, b) {
-                        var x = parseInt(a[0]['timestamp']); var y = parseInt(b[0]['timestamp']);
-                        return ((x < y) ? -1 : ((x > y) ? 1 : 0));
-                    });
+                        if (inclusionStates) {
 
-                    return callback(error, finalBundles);
-                })
+                            self.getLatestInclusion(tailTxArray, function(error, states) {
+
+                                // If error, return it to original caller
+                                if (error) return callback(error);
+
+                                cb(null, states);
+                            })
+                        } else {
+                            cb(null, []);
+                        }
+                    },
+
+                    //
+                    // 2. Function
+                    //
+                    function(tailTxStates, cb) {
+
+                        // Map each tail transaction to the getBundle function
+                        // format the returned bundles and add inclusion states if necessary
+                        async.map(tailTxArray, function(tailTx, cb2) {
+
+                             self.getBundle(tailTx, function(error, bundle) {
+
+                                 // If error returned from getBundle, simply ignore it
+                                 // because the bundle was most likely incorrect
+                                 if (!error) {
+
+                                     // If inclusion states, add to each bundle entry
+                                     if (inclusionStates) {
+                                         var thisInclusion = tailTxStates[tailTxArray.indexOf(tailTx)];
+
+                                         bundle.forEach(function(bundleTx) {
+
+                                             bundleTx['persistence'] = thisInclusion;
+                                         })
+                                     }
+
+                                     finalBundles.push(bundle);
+                                 }
+                                 cb2(null, true);
+                             })
+                        }, function(error, results) {
+
+                            // credit: http://stackoverflow.com/a/8837505
+                            // Sort bundles by timestamp
+                            finalBundles.sort(function(a, b) {
+                                var x = parseInt(a[0]['timestamp']); var y = parseInt(b[0]['timestamp']);
+                                return ((x < y) ? -1 : ((x > y) ? 1 : 0));
+                            });
+
+                            return callback(error, finalBundles);
+                        })
+                    }
+                ])
             })
         })
     })

lib/utils/inputValidator.js

@@ -67,7 +67,7 @@ var isTransfersArray = function(transfersArray) {
 
     if (!isArray(transfersArray)) return false;
 
-    for (var i = 0; i < hashesArray.length; i++) {
+    for (var i = 0; i < transfersArray.length; i++) {
 
         var transfer = transfersArray[i];
 
@@ -94,7 +94,6 @@ var isTransfersArray = function(transfersArray) {
         if (!isTrytes(tag, "0,27")) {
             return false;
         }
-
     }
 
     return true;
@@ -233,7 +232,7 @@ var isInputs = function(inputs) {
 
         var input = inputs[i];
 
-        // If input does not have keyIndex and address, return false 
+        // If input does not have keyIndex and address, return false
         if (!input.hasOwnProperty('keyIndex') || !input.hasOwnProperty('address')) return false;
     }
 

package.json

@@ -1,6 +1,6 @@
 {
     "name": "iota.lib.js",
-    "version": "0.0.4",
+    "version": "0.0.4.1",
     "description": "Javascript Library for the IOTA API.",
     "main": "./lib/iota.js",
     "scripts": {