Merge pull request #105 from Permissionless-Software-Foundation/ct-unstable

Porting bch-util into bch-js

package.json

@@ -17,7 +17,7 @@
     "test:integration:local:bchn": "export RESTURL=http://localhost:3000/v4/ && mocha --timeout 30000 test/integration/ && mocha --timeout 30000 test/integration/chains/bchn/",
     "test:integration:local:testnet": "RESTURL=http://localhost:4000/v4/ mocha --timeout 30000 test/integration/chains/testnet",
     "test:temp": "export RESTURL=https://bchn.fullstack.cash/v4/ && mocha --timeout 30000 -g '#UTXO' test/integration/chains/bchn/",
-    "test:temp2": "mocha --timeout=30000 -g '#utxo' test/unit/",
+    "test:temp2": "mocha --timeout=30000 -g '#Util' test/unit/",
     "coverage": "nyc report --reporter=text-lcov | coveralls",
     "coverage:report": "nyc --reporter=html mocha --timeout 25000 test/unit/",
     "docs": "./node_modules/.bin/apidoc -i src/ -o docs",

src/util.js

@@ -27,6 +27,129 @@ class Util {
     _this = this
   }
 
+  /**
+   * @api util.floor8() floor8()
+   * @apiName floor8
+   * @apiGroup Util
+   * @apiDescription Round a number down to 8 decimal places.
+   *
+   *
+   * @apiExample Example usage:
+   * (async () => {
+   *   try {
+   *     const num = 1.234567891111
+   *     const result = bchjs.Util.floor8(num)
+   *     console.log(result)
+   *   } catch(error) {
+   *    console.error(error)
+   *   }
+   * })()
+   *
+   * // returns
+   *  1.23456789
+   */
+  // floor8 - round to 8 decimal places
+  // Takes a number and returns it, rounded to the nearest 8 decimal place.
+  floor8 (num) {
+    const thisNum = Number(num)
+
+    if (isNaN(thisNum)) throw new Error('input must be a number')
+
+    let tempNum = thisNum * 100000000
+    tempNum = Math.floor(tempNum)
+    tempNum = tempNum / 100000000
+
+    return tempNum
+  }
+
+  /**
+   * @api util.floor2() floor2()
+   * @apiName floor2
+   * @apiGroup Util
+   * @apiDescription Round a number down to 2 decimal places.
+   *
+   *
+   * @apiExample Example usage:
+   * (async () => {
+   *   try {
+   *     const num = 1.234567891111
+   *     const result = bchjs.Util.floor2(num)
+   *     console.log(result)
+   *   } catch(error) {
+   *    console.error(error)
+   *   }
+   * })()
+   *
+   * // returns
+   *  1.23
+   */
+  // floor2 - round down to 2 decimal places
+  // Takes a number and returns it, rounded to the nearest 2 decimal place.
+  floor2 (num) {
+    const thisNum = Number(num)
+
+    if (isNaN(thisNum)) throw new Error('input must be a number')
+
+    let tempNum = thisNum * 100
+    tempNum = Math.floor(tempNum)
+    tempNum = tempNum / 100
+
+    return tempNum
+  }
+
+  /**
+   * @api util.chunk20() chunk20()
+   * @apiName chunk20
+   * @apiGroup Util
+   * @apiDescription chunk up an array into multiple arrays of 20 elements each.
+   * Input: arrayToSlice - a one-dimensional array of elements.
+   * Returns a two-dimensional array. An array of 20-element arrays.
+   *
+   * @apiExample Example usage:
+   * (async () => {
+   *   try {
+   *      const bigArray = [0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26]
+   *
+   *      const chunked = bchjs.Util.chunk20(bigArray)
+   *      console.log(chunked)
+   *   } catch(error) {
+   *      console.error(error)
+   *   }
+   * })()
+   *
+   * // returns
+   *  [
+   *    [0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19],
+   *    [20,21,22,23,24,25,26]
+   *  ]
+   */
+  // chunk20 - chunk up an array into multiple arrays of 20 elements each.
+  // Input: arrayToSlice - a one-dimensional array of elements.
+  // Returns a two-dimensional array. An array of 20-element arrays.
+  chunk20 (arrayToSlice) {
+    try {
+      // Validate inputs
+      if (!Array.isArray(arrayToSlice)) {
+        throw new Error('input must be an array')
+      }
+
+      let offset = 0
+      const result = []
+
+      // Loop over the array and slice off chunks of 20 elements.
+      while (offset < arrayToSlice.length) {
+        const chunk = arrayToSlice.slice(offset, offset + 20)
+        result.push(chunk)
+        offset = offset + 20
+      }
+
+      return result
+    } catch (err) {
+      console.error('Error in chunk20()')
+      throw err
+    }
+  }
+
   /**
    * @api util.validateAddress() validateAddress()
    * @apiName Validate Address.

src/utxo.js

@@ -22,16 +22,30 @@ class UTXO {
    * @apiGroup UTXO
    * @apiDescription Get UTXOs for an address
    *
-   * Given an address, this function will return an object with three arrays:
-   * - bchUtxos - UTXOs confirmed to be spendable as normal BCH
-   * - slpUtxos - UTXOs confirmed to be colored as valid SLP tokens
-   * - nullUtxo - UTXOs that did not pass SLP validation. Should be ignored and
+   * Given an address, this function will return an object with thre following
+   * properties:
+   * - address: "" - the address these UTXOs are associated with
+   * - bchUtxos: [] - UTXOs confirmed to be spendable as normal BCH
+   * - nullUtxo: [] - UTXOs that did not pass SLP validation. Should be ignored and
    *   not spent, to be safe.
+   * - slpUtxos: {} - UTXOs confirmed to be colored as valid SLP tokens
+   *   - type1: {}
+   *     - tokens: [] - SLP token Type 1 tokens.
+   *     - mintBatons: [] - SLP token Type 1 mint batons.
+   *   - nft: {}
+   *     - tokens: [] - NFT tokens
+   *     - groupTokens: [] - NFT Group tokens, used to create NFT tokens.
+   *     - groupMintBatons: [] - Minting baton to create more NFT Group tokens.
+   *
+   * Note: You can pass in an optional second Boolean argument. The default
+   * `false` will use the normal waterfall validation method. Set to `true`,
+   * SLP UTXOs will be validated with the whitelist filtered SLPDB. This will
+   * result is many more UTXOs in the `nullUtxos` array.
    *
    * @apiExample Example usage:
    * (async () => {
    *   try {
-   *     let utxos = await bchjs.Utxo.get('simpleledger:qzv3zz2trz0xgp6a96lu4m6vp2nkwag0kvyucjzqt9');
+   *     let utxos = await bchjs.Utxo.get('simpleledger:qrm0c67wwqh0w7wjxua2gdt2xggnm90xwsr5k22euj');
    *     console.log(utxos);
    *   } catch(error) {
    *    console.error(error)
@@ -39,71 +53,296 @@ class UTXO {
    * })()
    *
    * // returns
-   * {
-   *  "bchUtxos": [
-   *   {
-   *    "height": 674331,
-   *    "tx_hash": "5e86cd911110e4f5db0cc3e8f459d5e8850b49adf57059a71daee674b2867b31",
-   *    "tx_pos": 0,
-   *    "value": 1000,
-   *    "txid": "5e86cd911110e4f5db0cc3e8f459d5e8850b49adf57059a71daee674b2867b31",
-   *    "vout": 0,
-   *    "isValid": false
+   * [
+   *  {
+   *   "address": "bitcoincash:qrm0c67wwqh0w7wjxua2gdt2xggnm90xws00a3lezv",
+   *   "bchUtxos": [
+   *    {
+   *      "height": 674513,
+   *      "tx_hash": "705bcc442e5a2770e560b528f52a47b1dcc9ce9ab6a8de9dfdefa55177f00d04",
+   *      "tx_pos": 3,
+   *      "value": 38134,
+   *      "txid": "705bcc442e5a2770e560b528f52a47b1dcc9ce9ab6a8de9dfdefa55177f00d04",
+   *      "vout": 3,
+   *      "isValid": false
+   *    }
+   *   ],
+   *   "nullUtxos": [],
+   *   "slpUtxos": {
+   *    "type1": {
+   *      "mintBatons": [
+   *        {
+   *          "height": 674512,
+   *          "tx_hash": "acbb0d3ceef55aa3e5fafc19335ae4bf2f8edba3c0567547dfd402391db32230",
+   *          "tx_pos": 2,
+   *          "value": 546,
+   *          "txid": "acbb0d3ceef55aa3e5fafc19335ae4bf2f8edba3c0567547dfd402391db32230",
+   *          "vout": 2,
+   *          "utxoType": "minting-baton",
+   *          "tokenId": "acbb0d3ceef55aa3e5fafc19335ae4bf2f8edba3c0567547dfd402391db32230",
+   *          "tokenTicker": "SLPTEST",
+   *          "tokenName": "SLP Test Token",
+   *          "tokenDocumentUrl": "https://FullStack.cash",
+   *          "tokenDocumentHash": "",
+   *          "decimals": 8,
+   *          "tokenType": 1,
+   *          "isValid": true
+   *        }
+   *      ],
+   *      "tokens": [
+   *        {
+   *          "height": 674512,
+   *          "tx_hash": "acbb0d3ceef55aa3e5fafc19335ae4bf2f8edba3c0567547dfd402391db32230",
+   *          "tx_pos": 1,
+   *          "value": 546,
+   *          "txid": "acbb0d3ceef55aa3e5fafc19335ae4bf2f8edba3c0567547dfd402391db32230",
+   *          "vout": 1,
+   *          "utxoType": "token",
+   *          "tokenQty": "100",
+   *          "tokenId": "acbb0d3ceef55aa3e5fafc19335ae4bf2f8edba3c0567547dfd402391db32230",
+   *          "tokenTicker": "SLPTEST",
+   *          "tokenName": "SLP Test Token",
+   *          "tokenDocumentUrl": "https://FullStack.cash",
+   *          "tokenDocumentHash": "",
+   *          "decimals": 8,
+   *          "tokenType": 1,
+   *          "isValid": true
+   *        }
+   *      ]
+   *   },
+   *   "nft": {
+   *      "groupMintBatons": [
+   *        {
+   *          "height": 674513,
+   *          "tx_hash": "705bcc442e5a2770e560b528f52a47b1dcc9ce9ab6a8de9dfdefa55177f00d04",
+   *          "tx_pos": 2,
+   *          "value": 546,
+   *          "txid": "705bcc442e5a2770e560b528f52a47b1dcc9ce9ab6a8de9dfdefa55177f00d04",
+   *          "vout": 2,
+   *          "utxoType": "minting-baton",
+   *          "transactionType": "mint",
+   *          "tokenId": "a9a2458a0f9f0761d5b8725c256f2e7fa35b9de4dec6f47b46e9f20d92d0e395",
+   *          "tokenType": 129,
+   *          "tokenTicker": "NFTGT",
+   *          "tokenName": "NFT Test Group Token",
+   *          "tokenDocumentUrl": "https://FullStack.cash",
+   *          "tokenDocumentHash": "",
+   *          "decimals": 0,
+   *          "mintBatonVout": 2,
+   *          "isValid": true
+   *        }
+   *      ],
+   *      "groupTokens": [
+   *        {
+   *          "height": 674513,
+   *          "tx_hash": "705bcc442e5a2770e560b528f52a47b1dcc9ce9ab6a8de9dfdefa55177f00d04",
+   *          "tx_pos": 1,
+   *          "value": 546,
+   *          "txid": "705bcc442e5a2770e560b528f52a47b1dcc9ce9ab6a8de9dfdefa55177f00d04",
+   *          "vout": 1,
+   *          "utxoType": "token",
+   *          "tokenQty": "10",
+   *          "transactionType": "mint",
+   *          "tokenId": "a9a2458a0f9f0761d5b8725c256f2e7fa35b9de4dec6f47b46e9f20d92d0e395",
+   *          "tokenType": 129,
+   *          "tokenTicker": "NFTGT",
+   *          "tokenName": "NFT Test Group Token",
+   *          "tokenDocumentUrl": "https://FullStack.cash",
+   *          "tokenDocumentHash": "",
+   *          "decimals": 0,
+   *          "mintBatonVout": 2,
+   *          "isValid": true
+   *        }
+   *      ],
+   *      "tokens": [
+   *        {
+   *          "height": 674512,
+   *          "tx_hash": "eeddccc4d716f04157ea132ac93a48040fea34a6b57f3d8f0cccb7d1a731ab2b",
+   *          "tx_pos": 1,
+   *          "value": 546,
+   *          "txid": "eeddccc4d716f04157ea132ac93a48040fea34a6b57f3d8f0cccb7d1a731ab2b",
+   *          "vout": 1,
+   *          "utxoType": "token",
+   *          "tokenQty": "1",
+   *          "tokenId": "eeddccc4d716f04157ea132ac93a48040fea34a6b57f3d8f0cccb7d1a731ab2b",
+   *          "tokenTicker": "NFT004",
+   *          "tokenName": "NFT Child",
+   *          "tokenDocumentUrl": "https://FullStack.cash",
+   *          "tokenDocumentHash": "",
+   *          "decimals": 0,
+   *          "tokenType": 65,
+   *          "isValid": true
+   *        }
+   *      ]
+   *    }
    *   }
-   *  ],
-   *  "slpUtxos": [
-   *   {
-   *    "height": 569108,
-   *    "tx_hash": "384e1b8197e8de7d38f98317af2cf5f6bcb50007c46943b3498a6fab6e8aeb7c",
-   *    "tx_pos": 1,
-   *    "value": 546,
-   *    "txid": "384e1b8197e8de7d38f98317af2cf5f6bcb50007c46943b3498a6fab6e8aeb7c",
-   *    "vout": 1,
-   *    "utxoType": "token",
-   *    "transactionType": "send",
-   *    "tokenId": "a436c8e1b6bee3d701c6044d190f76f774be83c36de8d34a988af4489e86dd37",
-   *    "tokenTicker": "sleven",
-   *    "tokenName": "sleven",
-   *    "tokenDocumentUrl": "sleven",
-   *    "tokenDocumentHash": "",
-   *    "decimals": 7,
-   *    "tokenType": 1,
-   *    "tokenQty": "1",
-   *    "isValid": true
-   *   }
-   *  ],
-   *  "nullUtxos": []
-   * }
+   *  }
+   * ]
    *
    *
    */
-  async get (address) {
+  async get (address, useWhitelist = false) {
     try {
-      const addr = this.slp.Address.toCashAddress(address)
+      // Convert address to an array if it is a string.
+      if (typeof address === 'string') address = [address]
+
+      // Throw an error if there are more than 20 addresses passed in at a time.
+      if (address.length > 20) throw new Error('Too many elements, 20 max.')
+
+      // Covert each address to a BCH address.
+      const addr = address.map(elem => this.slp.Address.toCashAddress(elem))
 
       // Get the UTXOs associated with the address.
-      const utxoData = await this.electrumx.utxo([addr])
+      const utxoData = await this.electrumx.utxo(addr)
       // console.log(`utxoData: ${JSON.stringify(utxoData, null, 2)}`)
 
       // Hydate the utxos with token information.
-      const hydratedUtxos = await this.slp.Utils.hydrateUtxos(utxoData.utxos)
+      let hydratedUtxos
+      if (useWhitelist) {
+        hydratedUtxos = await this.slp.Utils.hydrateUtxosWL(utxoData.utxos)
+      } else {
+        hydratedUtxos = await this.slp.Utils.hydrateUtxos(utxoData.utxos)
+      }
       // console.log(`hydratedUtxos: ${JSON.stringify(hydratedUtxos, null, 2)}`)
 
-      const retObj = {} // return object
+      const retAry = [] // Return array
 
-      // Filter out the different types of UTXOs.
-      retObj.bchUtxos = hydratedUtxos.slpUtxos[0].utxos.filter(elem => elem.isValid === false)
-      retObj.slpUtxos = hydratedUtxos.slpUtxos[0].utxos.filter(elem => elem.isValid === true)
-      retObj.nullUtxos = hydratedUtxos.slpUtxos[0].utxos.filter(elem => elem.isValid === null)
-      // Note: true, false, and null should be only values. An element with
-      // isValid set to any other value should be ignored.
+      // Loop through each address.
+      for (let i = 0; i < hydratedUtxos.slpUtxos.length; i++) {
+        const thisAddr = hydratedUtxos.slpUtxos[i]
 
-      return retObj
+        const addrObj = {
+          address: thisAddr.address
+        }
+
+        // Filter out the different types of UTXOs.
+        addrObj.bchUtxos = thisAddr.utxos.filter(elem => elem.isValid === false)
+        addrObj.nullUtxos = thisAddr.utxos.filter(elem => elem.isValid === null)
+
+        // Break down the SLP UTXOs.
+        addrObj.slpUtxos = {
+          type1: {},
+          nft: {}
+        }
+
+        // Token Type 1 Minting Batons.
+        addrObj.slpUtxos.type1.mintBatons = thisAddr.utxos.filter(elem => {
+          const isValid = elem.isValid === true
+          const tokenTypeIs1 = elem.tokenType === 1
+          const isMintingBaton = elem.utxoType === 'minting-baton'
+
+          return isValid && tokenTypeIs1 && isMintingBaton
+        })
+
+        // Token Type 1 tokens.
+        addrObj.slpUtxos.type1.tokens = thisAddr.utxos.filter(elem => {
+          const isValid = elem.isValid === true
+          const tokenTypeIs1 = elem.tokenType === 1
+          const isToken = elem.utxoType === 'token'
+
+          return isValid && tokenTypeIs1 && isToken
+        })
+
+        // NFT Group Minting Batons
+        addrObj.slpUtxos.nft.groupMintBatons = thisAddr.utxos.filter(elem => {
+          const isValid = elem.isValid === true
+          const tokenTypeIs129 = elem.tokenType === 129
+          const isMintingBaton = elem.utxoType === 'minting-baton'
+
+          return isValid && tokenTypeIs129 && isMintingBaton
+        })
+
+        // NFT Group tokens
+        addrObj.slpUtxos.nft.groupTokens = thisAddr.utxos.filter(elem => {
+          const isValid = elem.isValid === true
+          const tokenTypeIs129 = elem.tokenType === 129
+          const isToken = elem.utxoType === 'token'
+
+          return isValid && tokenTypeIs129 && isToken
+        })
+
+        // NFT (Child) tokens
+        addrObj.slpUtxos.nft.tokens = thisAddr.utxos.filter(elem => {
+          const isValid = elem.isValid === true
+          const tokenTypeIs65 = elem.tokenType === 65
+          const isToken = elem.utxoType === 'token'
+
+          return isValid && tokenTypeIs65 && isToken
+        })
+
+        retAry.push(addrObj)
+      }
+
+      return retAry
     } catch (err) {
       console.error('Error in bchjs.utxo.get()')
       throw err
     }
   }
+
+  /**
+   * @api Utxo.findBiggestUtxo() findBiggestUtxo()
+   * @apiName findBiggestUtxo
+   * @apiGroup UTXO
+   * @apiDescription Get the biggest UTXO in an array.
+   *
+   * Given an array of BCH UTXOs, this method will return the biggest UTXO.
+   * This is often the simplest way to pick a UTXO for generating a transaction.
+   *
+   * @apiExample Example usage:
+   * (async () => {
+   *   try {
+   *     const utxos = await bchjs.Utxo.get('bitcoincash:qq54fgjn3hz0357n8a6guy4demw9xfkjk5jcj0xr0z');
+   *     const utxo = bchjs.Utxo.findBiggestUtxo(utxos[0].bchUtxos)
+   *     console.log(utxo);
+   *   } catch(error) {
+   *    console.error(error)
+   *   }
+   * })()
+   *
+   * // returns
+   *  {
+   *   "height": 655431,
+   *   "tx_hash": "7a091716f8137e94f87e7760648cd34a17e32754ef95f7c7bda38a635c9b2b1b",
+   *   "tx_pos": 0,
+   *   "value": 800,
+   *   "txid": "7a091716f8137e94f87e7760648cd34a17e32754ef95f7c7bda38a635c9b2b1b",
+   *   "vout": 0,
+   *   "isValid": false,
+   *   "satoshis": 800
+   *  }
+   */
+  // Returns the utxo with the biggest balance from an array of utxos.
+  findBiggestUtxo (utxos) {
+    let largestAmount = 0
+    let largestIndex = 0
+
+    if (!Array.isArray(utxos)) {
+      throw new Error('utxos input to findBiggestUtxo() must be an array')
+    }
+
+    for (let i = 0; i < utxos.length; i++) {
+      const thisUtxo = utxos[i]
+
+      // Give Elecrumx utxos a satoshis property.
+      if (thisUtxo.value) {
+        if (!thisUtxo.satoshis) thisUtxo.satoshis = Number(thisUtxo.value)
+      }
+
+      if (!thisUtxo.satoshis) {
+        throw new Error(
+          'UTXOs require a satoshis or value property for findBiggestUtxo()'
+        )
+      }
+
+      if (thisUtxo.satoshis > largestAmount) {
+        largestAmount = thisUtxo.satoshis
+        largestIndex = i
+      }
+    }
+
+    return utxos[largestIndex]
+  }
 }
 
 module.exports = UTXO

test/integration/chains/bchn/utxo-integration.js

@@ -22,9 +22,100 @@ describe('#UTXO', () => {
       const result = await bchjs.Utxo.get(addr)
       // console.log(`result: ${JSON.stringify(result, null, 2)}`)
 
-      assert.isArray(result.bchUtxos)
-      assert.isArray(result.slpUtxos)
-      assert.isArray(result.nullUtxos)
+      assert.isArray(result)
+      assert.property(result[0], 'address')
+      assert.property(result[0], 'bchUtxos')
+      assert.property(result[0], 'nullUtxos')
+      assert.property(result[0], 'slpUtxos')
+      assert.isArray(result[0].bchUtxos)
+      assert.isArray(result[0].nullUtxos)
+    })
+
+    it('should handle an array of addresses', async () => {
+      const addr = [
+        'simpleledger:qzv3zz2trz0xgp6a96lu4m6vp2nkwag0kvyucjzqt9',
+        'bitcoincash:qqh793x9au6ehvh7r2zflzguanlme760wuzehgzjh9'
+      ]
+
+      const result = await bchjs.Utxo.get(addr)
+      // console.log(`result: ${JSON.stringify(result, null, 2)}`)
+
+      assert.isArray(result)
+      assert.property(result[0], 'address')
+      assert.property(result[0], 'bchUtxos')
+      assert.property(result[0], 'nullUtxos')
+      assert.property(result[0], 'slpUtxos')
+      assert.isArray(result[0].bchUtxos)
+      assert.isArray(result[0].nullUtxos)
+    })
+
+    it('should handle NFTs and minting batons', async () => {
+      const addr = 'simpleledger:qrm0c67wwqh0w7wjxua2gdt2xggnm90xwsr5k22euj'
+
+      const result = await bchjs.Utxo.get(addr)
+      // console.log(`result: ${JSON.stringify(result, null, 2)}`)
+
+      assert.isArray(result)
+      assert.property(result[0], 'address')
+      assert.property(result[0], 'bchUtxos')
+      assert.property(result[0], 'nullUtxos')
+      assert.property(result[0], 'slpUtxos')
+      assert.isArray(result[0].bchUtxos)
+      assert.isArray(result[0].nullUtxos)
+
+      assert.isArray(result[0].slpUtxos.type1.mintBatons)
+      assert.isArray(result[0].slpUtxos.type1.tokens)
+      assert.isArray(result[0].slpUtxos.nft.groupMintBatons)
+      assert.isArray(result[0].slpUtxos.nft.groupTokens)
+      assert.isArray(result[0].slpUtxos.nft.tokens)
+    })
+
+    it('should use the whitelist when flag is set', async () => {
+      const addr = 'simpleledger:qzv3zz2trz0xgp6a96lu4m6vp2nkwag0kvyucjzqt9'
+      const useWhitelist = true
+
+      const result = await bchjs.Utxo.get(addr, useWhitelist)
+      // console.log(`result: ${JSON.stringify(result, null, 2)}`)
+
+      assert.isArray(result)
+      assert.property(result[0], 'address')
+      assert.property(result[0], 'bchUtxos')
+      assert.property(result[0], 'nullUtxos')
+      assert.property(result[0], 'slpUtxos')
+      assert.isArray(result[0].bchUtxos)
+      assert.isArray(result[0].nullUtxos)
+
+      // Most token UTXOs should end up in the nullUtxos array.
+      assert.isAbove(result[0].bchUtxos.length, 0)
+      assert.isAbove(result[0].nullUtxos.length, 1)
+    })
+  })
+
+  describe('#findBiggestUtxo', () => {
+    it('should sort UTXOs from Electrumx', async () => {
+      const addr = 'bitcoincash:qq54fgjn3hz0357n8a6guy4demw9xfkjk5jcj0xr0z'
+
+      const electrumxUtxos = await bchjs.Electrumx.utxo(addr)
+      // console.log(`Electrumx utxos: ${JSON.stringify(electrumxUtxos, null, 2)}`)
+
+      const result = bchjs.Utxo.findBiggestUtxo(electrumxUtxos.utxos)
+      // console.log(`result: ${JSON.stringify(result, null, 2)}`)
+
+      assert.property(result, 'satoshis')
+      assert.equal(result.satoshis, 800)
+    })
+
+    it('should sort UTXOs from Utxos.get()', async () => {
+      const addr = 'bitcoincash:qq54fgjn3hz0357n8a6guy4demw9xfkjk5jcj0xr0z'
+
+      const utxos = await bchjs.Utxo.get(addr)
+      // console.log(`utxos: ${JSON.stringify(utxos, null, 2)}`)
+
+      const result = bchjs.Utxo.findBiggestUtxo(utxos[0].bchUtxos)
+      console.log(`result: ${JSON.stringify(result, null, 2)}`)
+
+      assert.property(result, 'satoshis')
+      assert.equal(result.satoshis, 800)
     })
   })
 })

test/unit/fixtures/utxo-mocks.js

@@ -66,7 +66,224 @@ const mockHydratedUtxos = {
   ]
 }
 
+const mockTwoHydratedAddrs = {
+  slpUtxos: [
+    {
+      utxos: [
+        {
+          height: 569108,
+          tx_hash:
+            '384e1b8197e8de7d38f98317af2cf5f6bcb50007c46943b3498a6fab6e8aeb7c',
+          tx_pos: 1,
+          value: 546,
+          txid:
+            '384e1b8197e8de7d38f98317af2cf5f6bcb50007c46943b3498a6fab6e8aeb7c',
+          vout: 1,
+          utxoType: 'token',
+          transactionType: 'send',
+          tokenId:
+            'a436c8e1b6bee3d701c6044d190f76f774be83c36de8d34a988af4489e86dd37',
+          tokenTicker: 'sleven',
+          tokenName: 'sleven',
+          tokenDocumentUrl: 'sleven',
+          tokenDocumentHash: '',
+          decimals: 7,
+          tokenType: 1,
+          tokenQty: '1',
+          isValid: true
+        },
+        {
+          height: 674331,
+          tx_hash:
+            '5e86cd911110e4f5db0cc3e8f459d5e8850b49adf57059a71daee674b2867b31',
+          tx_pos: 0,
+          value: 1000,
+          txid:
+            '5e86cd911110e4f5db0cc3e8f459d5e8850b49adf57059a71daee674b2867b31',
+          vout: 0,
+          isValid: false
+        }
+      ],
+      address: 'bitcoincash:qzv3zz2trz0xgp6a96lu4m6vp2nkwag0kvg8nfhq4m'
+    },
+    {
+      utxos: [
+        {
+          height: 602405,
+          tx_hash:
+            '2b37bdb3b63dd0bca720437754a36671431a950e684b64c44ea910ea9d5297c7',
+          tx_pos: 0,
+          value: 1000,
+          txid:
+            '2b37bdb3b63dd0bca720437754a36671431a950e684b64c44ea910ea9d5297c7',
+          vout: 0,
+          isValid: false
+        }
+      ],
+      address: 'bitcoincash:qqh793x9au6ehvh7r2zflzguanlme760wuzehgzjh9'
+    }
+  ]
+}
+
+const mockEveryUtxoType = {
+  slpUtxos: [
+    {
+      utxos: [
+        {
+          height: 674512,
+          tx_hash:
+            'acbb0d3ceef55aa3e5fafc19335ae4bf2f8edba3c0567547dfd402391db32230',
+          tx_pos: 1,
+          value: 546,
+          txid:
+            'acbb0d3ceef55aa3e5fafc19335ae4bf2f8edba3c0567547dfd402391db32230',
+          vout: 1,
+          utxoType: 'token',
+          tokenQty: '100',
+          tokenId:
+            'acbb0d3ceef55aa3e5fafc19335ae4bf2f8edba3c0567547dfd402391db32230',
+          tokenTicker: 'SLPTEST',
+          tokenName: 'SLP Test Token',
+          tokenDocumentUrl: 'https://FullStack.cash',
+          tokenDocumentHash: '',
+          decimals: 8,
+          tokenType: 1,
+          isValid: true
+        },
+        {
+          height: 674512,
+          tx_hash:
+            'acbb0d3ceef55aa3e5fafc19335ae4bf2f8edba3c0567547dfd402391db32230',
+          tx_pos: 2,
+          value: 546,
+          txid:
+            'acbb0d3ceef55aa3e5fafc19335ae4bf2f8edba3c0567547dfd402391db32230',
+          vout: 2,
+          utxoType: 'minting-baton',
+          tokenId:
+            'acbb0d3ceef55aa3e5fafc19335ae4bf2f8edba3c0567547dfd402391db32230',
+          tokenTicker: 'SLPTEST',
+          tokenName: 'SLP Test Token',
+          tokenDocumentUrl: 'https://FullStack.cash',
+          tokenDocumentHash: '',
+          decimals: 8,
+          tokenType: 1,
+          isValid: true
+        },
+        {
+          height: 674512,
+          tx_hash:
+            'eeddccc4d716f04157ea132ac93a48040fea34a6b57f3d8f0cccb7d1a731ab2b',
+          tx_pos: 1,
+          value: 546,
+          txid:
+            'eeddccc4d716f04157ea132ac93a48040fea34a6b57f3d8f0cccb7d1a731ab2b',
+          vout: 1,
+          utxoType: 'token',
+          tokenQty: '1',
+          tokenId:
+            'eeddccc4d716f04157ea132ac93a48040fea34a6b57f3d8f0cccb7d1a731ab2b',
+          tokenTicker: 'NFT004',
+          tokenName: 'NFT Child',
+          tokenDocumentUrl: 'https://FullStack.cash',
+          tokenDocumentHash: '',
+          decimals: 0,
+          tokenType: 65,
+          isValid: true
+        },
+        {
+          height: 674513,
+          tx_hash:
+            '705bcc442e5a2770e560b528f52a47b1dcc9ce9ab6a8de9dfdefa55177f00d04',
+          tx_pos: 1,
+          value: 546,
+          txid:
+            '705bcc442e5a2770e560b528f52a47b1dcc9ce9ab6a8de9dfdefa55177f00d04',
+          vout: 1,
+          utxoType: 'token',
+          tokenQty: '10',
+          transactionType: 'mint',
+          tokenId:
+            'a9a2458a0f9f0761d5b8725c256f2e7fa35b9de4dec6f47b46e9f20d92d0e395',
+          tokenType: 129,
+          tokenTicker: 'NFTGT',
+          tokenName: 'NFT Test Group Token',
+          tokenDocumentUrl: 'https://FullStack.cash',
+          tokenDocumentHash: '',
+          decimals: 0,
+          mintBatonVout: 2,
+          isValid: true
+        },
+        {
+          height: 674513,
+          tx_hash:
+            '705bcc442e5a2770e560b528f52a47b1dcc9ce9ab6a8de9dfdefa55177f00d04',
+          tx_pos: 2,
+          value: 546,
+          txid:
+            '705bcc442e5a2770e560b528f52a47b1dcc9ce9ab6a8de9dfdefa55177f00d04',
+          vout: 2,
+          utxoType: 'minting-baton',
+          transactionType: 'mint',
+          tokenId:
+            'a9a2458a0f9f0761d5b8725c256f2e7fa35b9de4dec6f47b46e9f20d92d0e395',
+          tokenType: 129,
+          tokenTicker: 'NFTGT',
+          tokenName: 'NFT Test Group Token',
+          tokenDocumentUrl: 'https://FullStack.cash',
+          tokenDocumentHash: '',
+          decimals: 0,
+          mintBatonVout: 2,
+          isValid: true
+        },
+        {
+          height: 674513,
+          tx_hash:
+            '705bcc442e5a2770e560b528f52a47b1dcc9ce9ab6a8de9dfdefa55177f00d04',
+          tx_pos: 3,
+          value: 38134,
+          txid:
+            '705bcc442e5a2770e560b528f52a47b1dcc9ce9ab6a8de9dfdefa55177f00d04',
+          vout: 3,
+          isValid: false
+        }
+      ],
+      address: 'bitcoincash:qrm0c67wwqh0w7wjxua2gdt2xggnm90xws00a3lezv'
+    }
+  ]
+}
+
+const electrumxUtxos = {
+  success: true,
+  utxos: [
+    {
+      height: 0,
+      tx_hash:
+        '192f5037bb3822afd92d6b6ab51842a5dcfbe6bff783290057342da1f27ed414',
+      tx_pos: 0,
+      value: 600
+    },
+    {
+      height: 0,
+      tx_hash:
+        'f913646f7c180f8de020cb1387951272e8a3f764a0f88e68f7fc1145a0bf02e9',
+      tx_pos: 0,
+      value: 700
+    },
+    {
+      height: 0,
+      tx_hash:
+        '7a091716f8137e94f87e7760648cd34a17e32754ef95f7c7bda38a635c9b2b1b',
+      tx_pos: 0,
+      value: 800
+    }
+  ]
+}
+
 module.exports = {
   mockUtxoData,
-  mockHydratedUtxos
+  mockHydratedUtxos,
+  mockTwoHydratedAddrs,
+  mockEveryUtxoType,
+  electrumxUtxos
 }

test/unit/util.js

@@ -1,4 +1,5 @@
 const assert = require('assert')
+const assert2 = require('chai').assert
 const axios = require('axios')
 const BCHJS = require('../../src/bch-js')
 const bchjs = new BCHJS()
@@ -32,4 +33,143 @@ describe('#Util', () => {
         .then(done, done)
     })
   })
+
+  describe('#floor8', () => {
+    it('should floor a number to 8 decimals', () => {
+      const num = 1.234567891111
+
+      const result = bchjs.Util.floor8(num)
+      // console.log(result)
+
+      assert2.equal(result, 1.23456789)
+    })
+
+    it('should throw an error for non-number input', () => {
+      try {
+        const num = 'string'
+
+        bchjs.Util.floor8(num)
+
+        assert2.equal(true, false, 'Unexpected result')
+      } catch (err) {
+        // console.log(err)
+        assert2.include(err.message, 'input must be a number')
+      }
+    })
+
+    it('should not effect a number with less than 8 decimals', () => {
+      const num = 1.23
+
+      const result = bchjs.Util.floor8(num)
+      // console.log(result)
+
+      assert2.equal(result, 1.23)
+    })
+  })
+
+  describe('#floor2', () => {
+    it('should round a number to 2 decimals', () => {
+      const num = 1.234567891111
+
+      const result = bchjs.Util.floor2(num)
+      // console.log(result)
+
+      assert2.equal(result, 1.23)
+    })
+
+    it('should throw an error for non-number input', () => {
+      try {
+        const num = 'string'
+
+        bchjs.Util.floor2(num)
+
+        assert2.equal(true, false, 'Unexpected result')
+      } catch (err) {
+        // console.log(err)
+        assert2.include(err.message, 'input must be a number')
+      }
+    })
+
+    it('should not effect a number with less than 8 decimals', () => {
+      const num = 1.2
+
+      const result = bchjs.Util.floor2(num)
+      // console.log(result)
+
+      assert2.equal(result, 1.2)
+    })
+  })
+
+  describe('#chunk20', () => {
+    const thirtyFiveElements = [
+      0,
+      1,
+      2,
+      3,
+      4,
+      5,
+      6,
+      7,
+      8,
+      9,
+      10,
+      11,
+      12,
+      13,
+      14,
+      15,
+      16,
+      17,
+      18,
+      19,
+      20,
+      21,
+      22,
+      23,
+      24,
+      25,
+      26,
+      27,
+      28,
+      29,
+      30,
+      31,
+      32,
+      33,
+      34
+    ]
+
+    it('should split 35 elements into 2 arrays', () => {
+      const result = bchjs.Util.chunk20(thirtyFiveElements)
+      // console.log(`result: ${JSON.stringify(result, null, 2)}`)
+
+      assert2.isArray(result)
+      assert2.isArray(result[0])
+      assert2.equal(result.length, 2)
+      assert2.equal(result[0].length, 20)
+    })
+
+    it('should return accurately with an array of less than 20 elements', () => {
+      const elems = [0, 1, 2, 3, 4, 5]
+
+      const result = bchjs.Util.chunk20(elems)
+      // console.log(`result: ${JSON.stringify(result, null, 2)}`)
+
+      assert2.isArray(result)
+      assert2.isArray(result[0])
+      assert2.equal(result.length, 1)
+      assert2.equal(result[0].length, 6)
+    })
+
+    it('should throw an error for non-array input', () => {
+      try {
+        bchjs.Util.chunk20('string')
+
+        assert2.equal(true, false, 'Unexpected result')
+      } catch (err) {
+        // console.log(err)
+        assert2.include(err.message, 'input must be an array')
+      }
+    })
+  })
 })

test/unit/utxo-unit.js

@@ -19,22 +19,30 @@ describe('#utxo', () => {
     it('should get hydrated and filtered UTXOs for an address', async () => {
       // Mock dependencies.
       sandbox.stub(bchjs.Utxo.electrumx, 'utxo').resolves(mockData.mockUtxoData)
-      sandbox.stub(bchjs.Utxo.slp.Utils, 'hydrateUtxos').resolves(mockData.mockHydratedUtxos)
+      sandbox
+        .stub(bchjs.Utxo.slp.Utils, 'hydrateUtxos')
+        .resolves(mockData.mockHydratedUtxos)
 
       const addr = 'simpleledger:qzv3zz2trz0xgp6a96lu4m6vp2nkwag0kvyucjzqt9'
 
       const result = await bchjs.Utxo.get(addr)
       // console.log(`result: ${JSON.stringify(result, null, 2)}`)
 
-      assert.isArray(result.bchUtxos)
-      assert.isArray(result.slpUtxos)
-      assert.isArray(result.nullUtxos)
+      assert.isArray(result)
+      assert.property(result[0], 'address')
+      assert.property(result[0], 'bchUtxos')
+      assert.property(result[0], 'nullUtxos')
+      assert.property(result[0], 'slpUtxos')
+      assert.isArray(result[0].bchUtxos)
+      assert.isArray(result[0].nullUtxos)
     })
 
     it('should catch and throw an error', async () => {
       try {
         // Force an error
-        sandbox.stub(bchjs.Utxo.electrumx, 'utxo').rejects(new Error('test error'))
+        sandbox
+          .stub(bchjs.Utxo.electrumx, 'utxo')
+          .rejects(new Error('test error'))
 
         const addr = 'simpleledger:qzv3zz2trz0xgp6a96lu4m6vp2nkwag0kvyucjzqt9'
 
@@ -45,5 +53,139 @@ describe('#utxo', () => {
         assert.include(err.message, 'test error')
       }
     })
+
+    it('should handle an array of addresses', async () => {
+      // Mock dependencies.
+      sandbox.stub(bchjs.Utxo.electrumx, 'utxo').resolves({ utxos: {} })
+      sandbox
+        .stub(bchjs.Utxo.slp.Utils, 'hydrateUtxos')
+        .resolves(mockData.mockTwoHydratedAddrs)
+
+      const addr = [
+        'simpleledger:qzv3zz2trz0xgp6a96lu4m6vp2nkwag0kvyucjzqt9',
+        'bitcoincash:qqh793x9au6ehvh7r2zflzguanlme760wuzehgzjh9'
+      ]
+
+      const result = await bchjs.Utxo.get(addr)
+      // console.log(`result: ${JSON.stringify(result, null, 2)}`)
+
+      assert.isArray(result)
+      assert.equal(result.length, 2)
+      assert.property(result[0], 'address')
+      assert.property(result[0], 'bchUtxos')
+      assert.property(result[0], 'nullUtxos')
+      assert.property(result[0], 'slpUtxos')
+      assert.isArray(result[0].bchUtxos)
+      assert.isArray(result[0].nullUtxos)
+    })
+
+    it('should throw an error for array of 21 elements', async () => {
+      try {
+        const addr = 'simpleledger:qzv3zz2trz0xgp6a96lu4m6vp2nkwag0kvyucjzqt9'
+
+        const addrs = []
+        for (let i = 0; i < 21; i++) {
+          addrs.push(addr)
+        }
+
+        await bchjs.Utxo.get(addrs)
+
+        assert.fail('Unexpected code path')
+      } catch (err) {
+        assert.include(err.message, 'Too many elements, 20 max.')
+      }
+    })
+
+    it('should handle NFTs and minting batons', async () => {
+      // Mock dependencies.
+      sandbox.stub(bchjs.Utxo.electrumx, 'utxo').resolves({ utxos: {} })
+      sandbox
+        .stub(bchjs.Utxo.slp.Utils, 'hydrateUtxos')
+        .resolves(mockData.mockEveryUtxoType)
+
+      const addr = 'simpleledger:qrm0c67wwqh0w7wjxua2gdt2xggnm90xwsr5k22euj'
+
+      const result = await bchjs.Utxo.get(addr)
+      // console.log(`result: ${JSON.stringify(result, null, 2)}`)
+
+      assert.isArray(result)
+      assert.property(result[0], 'address')
+      assert.property(result[0], 'bchUtxos')
+      assert.property(result[0], 'nullUtxos')
+      assert.property(result[0], 'slpUtxos')
+      assert.isArray(result[0].bchUtxos)
+      assert.isArray(result[0].nullUtxos)
+
+      assert.isArray(result[0].slpUtxos.type1.mintBatons)
+      assert.isArray(result[0].slpUtxos.type1.tokens)
+      assert.isArray(result[0].slpUtxos.nft.groupMintBatons)
+      assert.isArray(result[0].slpUtxos.nft.groupTokens)
+      assert.isArray(result[0].slpUtxos.nft.tokens)
+    })
+
+    it('should use the whitelist when flag is set', async () => {
+      // Mock dependencies.
+      sandbox.stub(bchjs.Utxo.electrumx, 'utxo').resolves(mockData.mockUtxoData)
+      sandbox
+        .stub(bchjs.Utxo.slp.Utils, 'hydrateUtxosWL')
+        .resolves(mockData.mockHydratedUtxos)
+
+      const addr = 'simpleledger:qzv3zz2trz0xgp6a96lu4m6vp2nkwag0kvyucjzqt9'
+      const useWhitelist = true
+
+      const result = await bchjs.Utxo.get(addr, useWhitelist)
+      // console.log(`result: ${JSON.stringify(result, null, 2)}`)
+
+      assert.isArray(result)
+      assert.property(result[0], 'address')
+      assert.property(result[0], 'bchUtxos')
+      assert.property(result[0], 'nullUtxos')
+      assert.property(result[0], 'slpUtxos')
+      assert.isArray(result[0].bchUtxos)
+      assert.isArray(result[0].nullUtxos)
+    })
+  })
+
+  describe('#findBiggestUtxo', () => {
+    it('should throw error for non-array input', async () => {
+      try {
+        await bchjs.Utxo.findBiggestUtxo({})
+
+        assert.equal(true, false, 'Unexpected result!')
+      } catch (err) {
+        assert.include(
+          err.message,
+          'utxos input to findBiggestUtxo() must be an array'
+        )
+      }
+    })
+
+    it('should throw an error if input does not have a value or satoshis property', async () => {
+      try {
+        const badUtxos = [
+          {
+            height: 0,
+            tx_hash:
+              '192f5037bb3822afd92d6b6ab51842a5dcfbe6bff783290057342da1f27ed414',
+            tx_pos: 0
+          }
+        ]
+
+        await bchjs.Utxo.findBiggestUtxo(badUtxos)
+      } catch (err) {
+        assert.include(
+          err.message,
+          'UTXOs require a satoshis or value property for findBiggestUtxo()'
+        )
+      }
+    })
+
+    it('should sort UTXOs from Electrumx', async () => {
+      const result = bchjs.Utxo.findBiggestUtxo(mockData.electrumxUtxos.utxos)
+      // console.log(`result: ${JSON.stringify(result, null, 2)}`)
+
+      assert.property(result, 'satoshis')
+      assert.equal(result.satoshis, 800)
+    })
   })
 })