Add working bitcoinRpc example. Update packages, update readme to match v2 api, remove request.js dependency, update jsdoc comments

Author: unusualbob

.jshintrc

@@ -1,12 +1,20 @@
 module.exports = {
   network: 'test',
-  currency: 'BTC',
   rpcServer: {
-    // should set this to match your own bitcoin rpc settings
-    username: 'fakeUser',
-    password: 'fakePassword',
-    ipAddress: '127.0.0.1',
-    port: '18332'
+    BTC: {
+      // should set this to match your own bitcoin-core rpc settings
+      username: 'fakeUser',
+      password: 'fakePassword',
+      ipAddress: '127.0.0.1',
+      port: '18332'
+    },
+    BCH: {
+      // should set this to match your own bitcoin-abc rpc settings
+      username: 'fakeUser',
+      password: 'fakePassword',
+      ipAddress: '127.0.0.1',
+      port: '18332'
+    }
   },
   trustedKeys: {
     // The idea is that you or the wallet provider will populate this with keys that are trusted, we have provided a few possible approaches
@@ -16,8 +24,6 @@ module.exports = {
     'mh65MN7drqmwpCRZcEeBEE9ceQCQ95HtZc': {
       // This is displayed to the user, somewhat like the organization field on an SSL certificate
       owner: 'BitPay (TESTNET ONLY - DO NOT TRUST FOR ACTUAL BITCOIN)',
-      // Which bitcoin networks is this key valid for (regtest, test, main)
-      networks: ['test'],
       // Which domains this key is valid for
       domains: ['test.bitpay.com'],
       // The actual public key which should be used to validate the signatures

examples/bitcoinRpc.js

@@ -1,19 +1,19 @@
 {
   "name": "json-payment-protocol",
-  "version": "0.2.0",
+  "version": "2.0.0",
   "description": "Simple interface for retrieving JSON payment requests and submitting payments",
   "main": "index.js",
   "dependencies": {
-    "lodash": "^4.17.4",
-    "request": "^2.83.0",
     "secp256k1": "^3.5.0"
   },
   "devDependencies": {
-    "async": "^2.6.0",
-    "bs58": "^4.0.1",
-    "kbpgp": "^2.0.77",
-    "promptly": "^2.2.0",
-    "request-promise": "^4.2.2"
+    "async": "2.6.0",
+    "bs58": "4.0.1",
+    "eslint": "6.2.1",
+    "kbpgp": "2.0.77",
+    "promptly": "2.2.0",
+    "request": "^2.83.0",
+    "request-promise": "4.2.2"
   },
   "engines": {
     "node": ">=8.0.0"

examples/config.example.js

@@ -6,102 +6,86 @@ This is the second version of the JSON payment protocol interface. If you have q
 
 
 ### Getting Started with v2
-This is actively being implemented. The plan is to:
-* Update the bitpay side to send the v2 structure
-* Change the json-payment-protocol client code to work with v1 and v2
-
-### Getting Started with v1
 
 `npm install json-payment-protocol`
 
-### v1 Usage
-
-We support both callbacks and promises. For promises just add Async to the end of the function name. Be careful to follow the notes about when to broadcast your payment. **Broadcasting a payment before getting a success notification back from the server in most cases will lead to a failed payment for the sender.** The sender will bear the cost of paying transaction fees yet again to get their money back.
+### v2 Usage
 
-#### Callbacks
+This library is now using async await structure for all functions. Be careful to follow the notes about when to broadcast your payment.
+Broadcasting a payment before getting a success notification back from the server in most cases will lead to a failed payment for the sender.
+The sender will bear the cost of paying transaction fees yet again to get their money back.
+ 
+#### Example
 ```js
 const JsonPaymentProtocol = require('json-payment-protocol');
-const paymentProtocol = new JsonPaymentProtocol();
-
-let requestUrl = 'bitcoin:?r=https://test.bitpay.com/i/Jr629pwsXKdTCneLyZja4t';
 
-paymentProtocol.getRawPaymentRequest(requestUrl, function (err, response) {
-  if (err) {
-    return console.log('Error retrieving payment request', err);
+// Options such as additional headers, etc which you want to pass to the node https client on every request
+const requestOptions = {};
+
+const trustedKeys = {
+  'mh65MN7drqmwpCRZcEeBEE9ceQCQ95HtZc': {
+    // This is displayed to the user, somewhat like the organization field on an SSL certificate
+    owner: 'BitPay (TESTNET ONLY - DO NOT TRUST FOR ACTUAL BITCOIN)',
+    // Which domains this key is valid for
+    domains: ['test.bitpay.com'],
+    // The actual public key which should be used to validate the signatures
+    publicKey: '03159069584176096f1c89763488b94dbc8d5e1fa7bf91f50b42f4befe4e45295a',
   }
-  paymentProtocol.parsePaymentRequest(response.rawBody, response.headers, function (err, paymentRequest) {
-    if (err) {
-      return console.log('Error parsing payment request', err);
-    }
-
-    console.log('Payment request retrieved');
-    console.log(paymentRequest);
-
-    //TODO: Create the rawTransaction and sign it in your wallet instead of this, do NOT broadcast yet
-    let currency = 'BTC';
-    
-    // Funded unsigned raw transaction
-    let unsignedRawTransaction = '02000000016b7bceefa3ff3bf6f3ad39a99cf6def9126a6edf8f49462bd06e4cb74366dab00100000000feffffff0248590095000000001976a9141b4f4e0c5354ce950ea702cc79be34885e7a60af88ac0c430100000000001976a914072053b485736e002f665d5fc65c443fb379256e88ac00000000'
-    // Signed version of that transaction
-    let signedRawTransaction = '02000000016b7bceefa3ff3bf6f3ad39a99cf6def9126a6edf8f49462bd06e4cb74366dab0010000006b4830450221008d8852576eb8e505832a53569dd756a1d0c304606c27e81d0ac1a83e78250969022058b2bde3f2e1ea7e6a62e69d99f7219e846f04c1c58ff163e2996669a935c31501210206e855c3cfd24a5e154cf94ff7a214d598dfc2d62966011fd83c360cf229777ffeffffff0248590095000000001976a9141b4f4e0c5354ce950ea702cc79be34885e7a60af88ac0c430100000000001976a914072053b485736e002f665d5fc65c443fb379256e88ac00000000';
-    // total size of the signed transaction (note the way shown here is incorrect for segwit, see the code in /examples for getting vsize from RPC)
-    let signedRawTransactionSize = Buffer.from(signedRawTransaction, 'hex').byteLength;
-
-    paymentProtocol.sendPaymentForVerification(currency, unsignedRawTransaction, signedRawTransactionSize, paymentRequest.paymentUrl, function(err, response) {
-      if (err) {
-        // If server rejects, stop, don't broadcast, show user the error
-        return console.log('Error verifying payment with server', err);
-      }
-
-      // Execute these in parallel
-      // Sending payment to server via payment protocol
-      paymentProtocol.broadcastPayment(currency, signedRawTransaction, paymentRequest.paymentUrl, function(err, response) {
-        console.log('Ignore any errors here if you already received verified above');
-      });
-      // Sending payment to bitcoin p2p network
-      myWallet.broadcastp2p(signedRawTransaction);
-    });
-  });
-});
-```
+};
+
+const client = new JsonPaymentProtocol(requestOptions, trustedKeys);
 
-#### Promises
-```js
-const JsonPaymentProtocol = require('json-payment-protocol');
-const paymentProtocol = new JsonPaymentProtocol();
 
 let requestUrl = 'bitcoin:?r=https://test.bitpay.com/i/Jr629pwsXKdTCneLyZja4t';
-let response = await paymentProtocol.getRawPaymentRequestAsync(requestUrl);
-let paymentRequest = await paymentProtocol.parsePaymentRequestAsync(response.rawBody, response.headers);
 
-console.log('Payment request retrieved');
-console.log(paymentRequest);
+const paymentOptions = await client.getPaymentOptions(requestUrl);
+
+// The paymentOptions response will contain one or more currency / chain options. If you are a multi-currency wallet then you should
+// display the compatible payment options to the user. If only one option is supported it is 
 
-//TODO: Create the rawTransaction and sign it in your wallet instead of this example, do NOT broadcast yet
-// Funded unsigned raw transaction
-let unsignedRawTransaction = '02000000016b7bceefa3ff3bf6f3ad39a99cf6def9126a6edf8f49462bd06e4cb74366dab00100000000feffffff0248590095000000001976a9141b4f4e0c5354ce950ea702cc79be34885e7a60af88ac0c430100000000001976a914072053b485736e002f665d5fc65c443fb379256e88ac00000000'
-// Signed version of that transaction
-let signedRawTransaction = '02000000016b7bceefa3ff3bf6f3ad39a99cf6def9126a6edf8f49462bd06e4cb74366dab0010000006b4830450221008d8852576eb8e505832a53569dd756a1d0c304606c27e81d0ac1a83e78250969022058b2bde3f2e1ea7e6a62e69d99f7219e846f04c1c58ff163e2996669a935c31501210206e855c3cfd24a5e154cf94ff7a214d598dfc2d62966011fd83c360cf229777ffeffffff0248590095000000001976a9141b4f4e0c5354ce950ea702cc79be34885e7a60af88ac0c430100000000001976a914072053b485736e002f665d5fc65c443fb379256e88ac00000000';
-// total size of the signed transaction (note the way shown here is incorrect for segwit, see the code in /examples for getting vsize from RPC)
-let signedRawTransactionSize = Buffer.from(signedRawTransaction, 'hex').byteLength;
+const { responseData: paymentRequest } = await client.selectPaymentOption(paymentOptions.requestUrl, userChoice.chain, userChoice.currency);
 
-// This sends the proposed unsigned transaction to the server
+// Parse response data instructions and create an appropriate unsigned and signed transaction
+// This is pseudocode
+let unsignedTransaction = await myWallet.createTransaction(responseData);
+let signedTransaction = await myWallet.signTransaction(unsignedTransaction);
+
+// We send the unsigned transaction(s) first with their size to verify if this payment will be accepted
 try {
-  await paymentProtocol.sendPaymentForVerificationAsync(currency, unsignedRawTransaction, signedRawTransactionSize, paymentRequest.paymentUrl);
+  await client.verifyUnsignedPayment({
+    paymentUrl: paymentOptions.requestUrl,
+    chain: userChoice.chain,
+    // For chains which can support multiple currencies via tokens, a currency code is required to identify which token is being used
+    currency: userChoice.currency,
+    unsignedTransactions: [{
+      tx: unsignedTransaction.rawHex,
+      // `vsize` for bitcoin core w/ segwit support, `size` for other clients
+      weightedSize: signedTransaction.vsize || signedTransaction.size
+    }]
+  });
 } catch (e) {
-  // Payment was rejected, do not continue, tell the user why they were rejected
-  return console.log('Proposed payment rejected', e);
+  // If an error occurs here, it is most likely an issue with the transaction (insufficient fee, rbf, unconfirmed inputs, etc)
+  // It could also be a network error or the invoice may no longer be accepting payments (already paid or expired)
+  return console.log('Error verifying payment with server', e);
 }
 
-// This sends the fully signed transaction
+// If the payment is valid we send the signed payment
 try {
-  await paymentProtocol.sendSignedPaymentAsync(currency, signedRawTransaction, paymentRequest.paymentUrl);
+  await client.sendSignedPayment({
+    paymentUrl: paymentOptions.requestUrl,
+    chain: choice.chain,
+    currency: choice.currency,
+    signedTransactions: [{
+      tx: signedTransaction,
+      // `vsize` for bitcoin core w/ segwit support, `size` for other clients
+      weightedSize: signedTransaction.vsize || signedTransaction.size
+    }]
+  });
+  await broadcastP2P(signedTransaction);
+  console.log('Payment successfully sent');
 } catch (e) {
-  // ignore errors here 
+  console.log('Error sending payment', e);
 }
-
-// Broadcast from your wallet to p2p
-myWallet.broadcastp2p(signedRawTransaction);
 ```
 
 ### Options
@@ -110,7 +94,10 @@ Options passed to `new JsonPaymentProtocol()` are passed to request, so if you n
 
 ```js
 new JsonPaymentProtocol({
-  proxy: 'socks://mySocksProxy.local'
+  proxy: 'socks://mySocksProxy.local',
+  headers: {
+    'user-agent': 'myWallet'
+  }
 })
 ```