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

fix(dsproof): Adding documentation

package.json

@@ -22,7 +22,7 @@
     "test:integration:temp:bchn": "export RESTURL=http://157.90.174.219:3000/v5/ && mocha --timeout 30000 test/integration/",
     "test:temp": "export RESTURL=http://localhost:3000/v5/ && mocha --timeout 30000 -g '#Encryption' test/integration/",
     "test:temp2": "mocha --timeout=30000 -g '#TransactionLib' test/unit/",
-    "test:temp3": "export RESTURL=https://bchn.fullstack.cash/v5/ && mocha --timeout 30000 -g '#Transaction' test/integration/",
+    "test:temp3": "export RESTURL=https://bchn.fullstack.cash/v5/ && mocha --timeout 30000 -g '#DSProof' test/integration/chains/",
     "test:temp4": "export RESTURL=http://localhost:3000/v5/ && mocha --timeout 30000 -g '#decodeOpReturn' test/integration/",
     "coverage": "nyc report --reporter=text-lcov | coveralls",
     "coverage:report": "nyc --reporter=html mocha --timeout 25000 test/unit/",

src/bch-js.js

@@ -32,6 +32,7 @@ const IPFS = require('./ipfs')
 const Encryption = require('./encryption')
 const Utxo = require('./utxo')
 const Transaction = require('./transaction')
+const DSProof = require('./dsproof')
 
 // Indexers
 const Ninsight = require('./ninsight')
@@ -115,6 +116,8 @@ class BCHJS {
     this.IPFS = new IPFS()
     this.Utxo = new Utxo(libConfig)
     this.Transaction = new Transaction(libConfig)
+
+    this.DSProof = new DSProof(libConfig)
   }
 }
 

src/dsproof.js

@@ -0,0 +1,81 @@
+const axios = require('axios')
+
+let _this
+
+class DSProof {
+  constructor (config) {
+    this.restURL = config.restURL
+    this.apiToken = config.apiToken
+    this.authToken = config.authToken
+    this.axios = axios
+
+    if (this.authToken) {
+      // Add Basic Authentication token to the authorization header.
+      this.axiosOptions = {
+        headers: {
+          authorization: this.authToken
+        }
+      }
+    } else {
+      // Add JWT token to the authorization header.
+      this.axiosOptions = {
+        headers: {
+          authorization: `Token ${this.apiToken}`
+        }
+      }
+    }
+
+    _this = this
+  }
+
+  /**
+   * @api DSProof.getDSProof() getDSProof()
+   * @apiName getDSProof
+   * @apiGroup DSProof
+   * @apiDescription Checks if a transaction generated a double-spend proof.
+   *
+   * If a double-spend is attempted, one of the transactions will generate a
+   * 'double spend proof'. This call can be used to check if a transaction
+   * generated such a proof.
+   *
+   * Merchants should wait 3-5 seconds after receiving notification of a
+   * transaction before calling this endpoint, to see if the TXID generated a
+   * proof. If this method returns no data, then the TX can be considered 'safe'
+   * and not a double spend. If proof data is returned by this method, then
+   * the transaction generated a proof and can be considered a 'double spend'.
+   *
+   * @apiExample Example usage:
+   * (async () => {
+   *   try {
+   *     const txid = 'ee0df780b58f6f24467605b2589c44c3a50fc849fb8f91b89669a4ae0d86bc7e'
+   *     const result = await bchjs.DSProof.getDSProof(txid)
+   *     console.log(result);
+   *   } catch(error) {
+   *    console.error(error)
+   *   }
+   * })()
+   *
+   * // returns
+   * null
+   */
+  async getDSProof (txid) {
+    try {
+      if (!txid) {
+        throw new Error('txid is required')
+      }
+      if (txid.length !== 64) {
+        throw new Error(`txid must be of length 64 (not ${txid.length})`)
+      }
+      const response = await _this.axios.get(
+        `${this.restURL}dsproof/getdsproof/${txid}`,
+        _this.axiosOptions
+      )
+      return response.data
+    } catch (error) {
+      if (error.response && error.response.data) throw error.response.data
+      else throw error
+    }
+  }
+}
+
+module.exports = DSProof

src/raw-transactions.js

@@ -120,7 +120,8 @@ class RawTransactions {
 
       throw new Error('Input must be a string or array of strings.')
     } catch (error) {
-      if (error.response && error.response.data) throw error.response.data
+      if (error.error) throw new Error(error.error)
+      else if (error.response && error.response.data) throw error.response.data
       else throw error
     }
   }
@@ -185,7 +186,8 @@ class RawTransactions {
 
       throw new Error('Input must be a string or array of strings.')
     } catch (error) {
-      if (error.response && error.response.data) throw error.response.data
+      if (error.error) throw new Error(error.error)
+      else if (error.response && error.response.data) throw error.response.data
       else throw error
     }
   }
@@ -281,7 +283,8 @@ class RawTransactions {
 
       throw new Error('Input must be a string or array of strings.')
     } catch (error) {
-      if (error.response && error.response.data) throw error.response.data
+      if (error.error) throw new Error(error.error)
+      else if (error.response && error.response.data) throw error.response.data
       else throw error
     }
   }
@@ -326,7 +329,8 @@ class RawTransactions {
 
       return retArray
     } catch (error) {
-      if (error.response && error.response.data) throw error.response.data
+      if (error.error) throw new Error(error.error)
+      else if (error.response && error.response.data) throw error.response.data
       else throw error
     }
   }
@@ -379,7 +383,8 @@ class RawTransactions {
 
       return txDetails
     } catch (error) {
-      if (error.response && error.response.data) throw error.response.data
+      if (error.error) throw new Error(error.error)
+      else if (error.response && error.response.data) throw error.response.data
       else throw error
     }
   }
@@ -452,7 +457,8 @@ class RawTransactions {
 
       throw new Error('Input hex must be a string or array of strings.')
     } catch (error) {
-      if (error.response && error.response.data) throw error.response.data
+      if (error.error) throw new Error(error.error)
+      else if (error.response && error.response.data) throw error.response.data
       else throw error
     }
   }

src/transaction.js

@@ -137,6 +137,8 @@ class Transaction {
       return txDetails
     } catch (err) {
       console.error('Error in transactions.js/get()')
+
+      if (err.error) throw new Error(err.error)
       throw err
     }
   }

src/util.js

@@ -28,7 +28,7 @@ class Util {
   }
 
   /**
-   * @api util.floor8() floor8()
+   * @api Util.floor8() floor8()
    * @apiName floor8
    * @apiGroup Util
    * @apiDescription Round a number down to 8 decimal places.
@@ -63,7 +63,7 @@ class Util {
   }
 
   /**
-   * @api util.floor2() floor2()
+   * @api Util.floor2() floor2()
    * @apiName floor2
    * @apiGroup Util
    * @apiDescription Round a number down to 2 decimal places.
@@ -98,7 +98,7 @@ class Util {
   }
 
   /**
-   * @api util.chunk20() chunk20()
+   * @api Util.chunk20() chunk20()
    * @apiName chunk20
    * @apiGroup Util
    * @apiDescription chunk up an array into multiple arrays of 20 elements each.
@@ -151,7 +151,7 @@ class Util {
   }
 
   /**
-   * @api util.sleep() sleep()
+   * @api Util.sleep() sleep()
    * @apiName sleep
    * @apiGroup Util
    * @apiDescription Promise-based delay.
@@ -175,7 +175,7 @@ class Util {
   }
 
   /**
-   * @api util.validateAddress() validateAddress()
+   * @api Util.validateAddress() validateAddress()
    * @apiName Validate Address.
    * @apiGroup Util
    * @apiDescription Return information about the given bitcoin address.

src/utxo.js

@@ -276,6 +276,8 @@ class UTXO {
       return retAry
     } catch (err) {
       console.error('Error in bchjs.utxo.get()')
+
+      if (err.error) throw new Error(err.error)
       throw err
     }
   }

test/integration/chains/bchn/dsproof.js

@@ -0,0 +1,25 @@
+/*
+  Integration tests for bchjs dsproof library.
+*/
+
+const assert = require('chai').assert
+
+const BCHJS = require('../../../../src/bch-js')
+const bchjs = new BCHJS()
+
+describe('#DSProof', () => {
+  beforeEach(async () => {
+    if (process.env.IS_USING_FREE_TIER) await bchjs.Util.sleep(1000)
+  })
+
+  describe('#getDSProof', () => {
+    it('should get TX info from the full node', async () => {
+      const txid =
+        'ee0df780b58f6f24467605b2589c44c3a50fc849fb8f91b89669a4ae0d86bc7e'
+      const result = await bchjs.DSProof.getDSProof(txid)
+      // console.log(`result: ${JSON.stringify(result, null, 2)}`)
+
+      assert.equal(result, null)
+    })
+  })
+})

test/integration/chains/testnet/electrumx.js

@@ -68,7 +68,9 @@ describe('#ElectrumX', () => {
     it('should throw error on array size rate limit', async () => {
       try {
         const addr = []
-        for (let i = 0; i < 25; i++) { addr.push('bchtest:qrvn2n228aa39xupcw9jw0d3fj8axxky656e4j62z2') }
+        for (let i = 0; i < 25; i++) {
+          addr.push('bchtest:qrvn2n228aa39xupcw9jw0d3fj8axxky656e4j62z2')
+        }
 
         // const result = await bchjs.Electrumx.utxo(addr)
         // console.log(`result: ${util.inspect(result)}`)
@@ -121,7 +123,9 @@ describe('#ElectrumX', () => {
     it('should throw error on array size rate limit', async () => {
       try {
         const addr = []
-        for (let i = 0; i < 25; i++) { addr.push('bchtest:qrvn2n228aa39xupcw9jw0d3fj8axxky656e4j62z2') }
+        for (let i = 0; i < 25; i++) {
+          addr.push('bchtest:qrvn2n228aa39xupcw9jw0d3fj8axxky656e4j62z2')
+        }
 
         const result = await bchjs.Electrumx.balance(addr)
 
@@ -175,7 +179,9 @@ describe('#ElectrumX', () => {
     it('should throw error on array size rate limit', async () => {
       try {
         const addr = []
-        for (let i = 0; i < 25; i++) { addr.push('bchtest:qrvn2n228aa39xupcw9jw0d3fj8axxky656e4j62z2') }
+        for (let i = 0; i < 25; i++) {
+          addr.push('bchtest:qrvn2n228aa39xupcw9jw0d3fj8axxky656e4j62z2')
+        }
 
         const result = await bchjs.Electrumx.transactions(addr)
 
@@ -236,7 +242,9 @@ describe('#ElectrumX', () => {
     it('should throw error on array size rate limit', async () => {
       try {
         const addr = []
-        for (let i = 0; i < 25; i++) { addr.push('bchtest:qrvn2n228aa39xupcw9jw0d3fj8axxky656e4j62z2') }
+        for (let i = 0; i < 25; i++) {
+          addr.push('bchtest:qrvn2n228aa39xupcw9jw0d3fj8axxky656e4j62z2')
+        }
 
         await bchjs.Electrumx.unconfirmed(addr)
         // console.log(`result: ${util.inspect(result)}`)
@@ -355,7 +363,7 @@ describe('#ElectrumX', () => {
         assert.property(err, 'success')
         assert.equal(err.success, false)
         assert.include(
-          err.error,
+          err.error.error,
           'the transaction was rejected by network rules'
         )
       }

test/integration/electrumx.js

@@ -359,10 +359,12 @@ describe('#ElectrumX', () => {
       try {
         await bchjs.Electrumx.broadcast(txHex)
       } catch (err) {
+        // console.log('err: ', err)
+
         assert.property(err, 'success')
         assert.equal(err.success, false)
         assert.include(
-          err.error,
+          err.error.error,
           'the transaction was rejected by network rules'
         )
       }

test/integration/rawtransaction.js

@@ -251,9 +251,13 @@ describe('#rawtransaction', () => {
   describe('#_getInputAddrs', () => {
     it('should return an array of input addresses', async () => {
       // const txid = '32233db13f2ae6d82b6262f335643dccf09fc0bcfcef4bc3fbe023355f02e112'
-      const txid = '05f7d4a4e25f53d63a360434eb54f221abf159112b7fffc91da1072a079cded3'
+      const txid =
+        '05f7d4a4e25f53d63a360434eb54f221abf159112b7fffc91da1072a079cded3'
 
-      const txDetails = await bchjs.RawTransactions.getRawTransaction(txid, true)
+      const txDetails = await bchjs.RawTransactions.getRawTransaction(
+        txid,
+        true
+      )
 
       const result = await bchjs.RawTransactions._getInputAddrs(txDetails)
       // console.log(`result: ${JSON.stringify(result, null, 2)}`)
@@ -268,7 +272,8 @@ describe('#rawtransaction', () => {
 
   describe('#getTxData', () => {
     it('should return tx data with input addresses', async () => {
-      const txid = '05f7d4a4e25f53d63a360434eb54f221abf159112b7fffc91da1072a079cded3'
+      const txid =
+        '05f7d4a4e25f53d63a360434eb54f221abf159112b7fffc91da1072a079cded3'
 
       const result = await bchjs.RawTransactions.getTxData(txid)
       // console.log(`result: ${JSON.stringify(result, null, 2)}`)

test/unit/dsproof.js

@@ -0,0 +1,66 @@
+// Public npm libraries
+const assert = require('chai').assert
+const sinon = require('sinon')
+
+// Unit under test (uut)
+const BCHJS = require('../../src/bch-js')
+const mockData = require('./fixtures/dsproof-mock')
+
+let bchjs
+const txid = 'ee0df780b58f6f24467605b2589c44c3a50fc849fb8f91b89669a4ae0d86bc7e'
+describe('#DSProof', () => {
+  let sandbox
+  beforeEach(() => {
+    bchjs = new BCHJS()
+    sandbox = sinon.createSandbox()
+  })
+  afterEach(() => sandbox.restore())
+
+  describe('#getDSProof', () => {
+    it('should throw error if input is not provided', async () => {
+      try {
+        await bchjs.DSProof.getDSProof()
+        assert.equal(false, true, 'unexpected error')
+      } catch (err) {
+        assert.include(err.message, 'txid is required')
+      }
+    })
+    it('should throw error txid is invalid', async () => {
+      try {
+        await bchjs.DSProof.getDSProof('txid')
+        assert.equal(false, true, 'unexpected error')
+      } catch (err) {
+        assert.include(err.message, 'txid must be of length 64')
+      }
+    })
+    it('should handle error', async () => {
+      try {
+        sandbox.stub(bchjs.DSProof.axios, 'get').throws(new Error('test error'))
+        await bchjs.DSProof.getDSProof(txid)
+
+        assert.equal(false, true, 'unexpected error')
+      } catch (err) {
+        assert.include(err.message, 'test error')
+      }
+    })
+    it('should get double spend proof', async () => {
+      try {
+        sandbox
+          .stub(bchjs.DSProof.axios, 'get')
+          .resolves({ data: mockData.dsproof })
+        const result = await bchjs.DSProof.getDSProof(txid)
+
+        assert.property(result, 'dspid')
+        assert.property(result, 'txid')
+        assert.property(result, 'outpoint')
+        assert.property(result, 'path')
+        assert.property(result, 'descendants')
+
+        assert.property(result.outpoint, 'txid')
+        assert.property(result.outpoint, 'vout')
+      } catch (error) {
+        assert.equal(false, true, 'unexpected error')
+      }
+    })
+  })
+})

test/unit/fixtures/dsproof-mock.js

@@ -0,0 +1,19 @@
+/*
+  Mock data used for unit testing.
+*/
+const dsproof = {
+  dspid: '6234fff2a9dbcaa50e2c50d74e1d725a2bed1757d7a05a2db7a82df659554397',
+  txid: 'ee0df780b58f6f24467605b2589c44c3a50fc849fb8f91b89669a4ae0d86bc7e',
+  outpoint: {
+    txid: '17ebef34f7e9a0692317dd6fbb43ffccff45b7d688a2a754dbccfc5e6d93ce3e',
+    vout: 1
+  },
+  path: ['ee0df780b58f6f24467605b2589c44c3a50fc849fb8f91b89669a4ae0d86bc7e'],
+  descendants: [
+    'ee0df780b58f6f24467605b2589c44c3a50fc849fb8f91b89669a4ae0d86bc7e'
+  ]
+}
+
+module.exports = {
+  dsproof
+}