bitcore

A full stack for bitcoin and blockchain-based applications

View the Project on GitHub bitpay/bitcore

Bitcore Wallet Service

NPM Package Build Status Coverage Status

A Multisig HD Bitcore Wallet Service.

Description

Bitcore Wallet Service facilitates multisig HD wallets creation and operation through a (hopefully) simple and intuitive REST API.

BWS can usually be installed within minutes and accommodates all the needed infrastructure for peers in a multisig wallet to communicate and operate – with minimum server trust.

See bitcore-wallet-client for the official client library that communicates to BWS and verifies its response. Also check bitcore-wallet for a simple CLI wallet implementation that relies on BWS.

BWS is been used in production enviroments for Copay Wallet, Bitpay App wallet and others.

More about BWS at https://blog.bitpay.com/announcing-the-bitcore-wallet-suite/

Getting Started

 git clone https://github.com/bitpay/bitcore-wallet-service.git
 cd bitcore-wallet-service
 npm install
 npm start

This will launch the BWS service (with default settings) at http://localhost:3232/bws/api.

BWS needs mongoDB. You can configure the connection at bws.config.js

BWS supports SSL and Clustering. For a detailed guide on installing BWS with extra features see Installing BWS.

BWS uses by default a Request Rate Limitation to CreateWallet endpoint. If you need to modify it, check defaults.js’ Defaults.RateLimit

Using BWS with PM2

BWS can be used with PM2 with the provided app.js script:

  pm2 start app.js --name "bitcoin-wallet-service"

Security Considerations

Using SSL

You can add your certificates at the bws.config.js using:

  https: true,
  privateKeyFile: 'private.pem',
  certificateFile: 'cert.pem',
  ////// The following is only for certs which are not
  ////// trusted by nodejs 'https' by default
  ////// CAs like Verisign do not require this
  // CAinter1: '', // ex. 'COMODORSADomainValidationSecureServerCA.crt'
  // CAinter2: '', // ex. 'COMODORSAAddTrustCA.crt'
  // CAroot: '', // ex. 'AddTrustExternalCARoot.crt'

@dabura667 made a report about how to use letsencrypt with BWS: https://github.com/bitpay/bitcore-wallet-service/issues/423

TX proposal life cycle

Tx proposal need to be:

  1. First created via /v?/txproposal -> This will create a ‘temporary’ TX proposal, returning the object, but not locking the inputs
  2. Then published via /v?/txproposal/:id/publish -> This publish the tx proposal to all copayers, looking the inputs. The TX proposal can be deleted also, after been published.
  3. Then signed via /v?/txproposal/:id/signature for each copayer
  4. Then broadcasted to the p2p network via /v?/txproposal/:id/broadcast

The are plenty example creating and sending proposals in the /test/integration code.

Enabling Regtest Mode for BWS and Copay

Requirements

mongo topology crashes sometimes due to notifications being incompatible in a web browser bitcore-wallet-service/lib/notificationbroadcaster.js Note: If testing on a PC browser, comment out notificationbroadcaster.js to disable notifications.

Steps:

bitcore.config.json

  1. Add regtest to bitcore.config.json.
"regtest": {
          "chainSource": "p2p",
          "trustedPeers": [
            {
              "host": "127.0.0.1",
              "port": 20020
            }
          ],
          "rpc": {
            "host": "127.0.0.1",
            "port": 20021,
            "username": "bitpaytest",
            "password": "local321"
          }
        }

bitcore-wallet-service/bws.config.js

  1. Point testnet to http://localhost:3000 in BWS/bws.config.js and set regtestEnabled to true.
blockchainExplorerOpts: {
    btc: {
      livenet: {
        url: 'https://api.bitcore.io'
      },
      testnet: {
        // set url to http://localhost:3000 here
        url: 'http://localhost:3000',
        // set regtestEnabled to true here
        regtestEnabled: true
      }
    },
...

Copay changes

copay/app-template/index-template.html

  1. Comment out content security meta tag in the <head>
// <meta http-equiv="Content-Security-Policy" content="default-src 'self'  ... >

Creating a wallet on regtest network

Steps:

  1. Set the wallet service URL to
http://localhost:3232/bws/api
  1. Select Testnet by pressing the slider button.

screen shot 2019-03-06 at 10 50 29 am

Testing on mobile

Requirements:

To find ip address for PC run:

// 127.0.0.1 is equal to localhost
ifconfig | grep "inet " | grep -v 127.0.0.1
  1. Inside copay project root directory run:
npm run apply:copay
  1. Enter PC ip address followed by port in the mobile phone browser:
10.10.11.73:8100
  1. Set wallet service url to PC ip address /bws/api when creating a new wallet
http://10.10.11.73:3232/bws/api

REST API

Note: all currency amounts are in units of satoshis (1/100,000,000 of a bitcoin).

Authentication

In order to access a wallet, clients are required to send the headers:

  x-identity
  x-signature

Identity is the Peer-ID, this will identify the peer and its wallet. Signature is the current request signature, using requestSigningKey, the m/1/1 derivative of the Extended Private Key.

See Bitcore Wallet Client for implementation details.

GET Endpoints

/v1/wallets/: Get wallet information

Returns:

/v1/txhistory/: Get Wallet’s transaction history

Optional Arguments:

Returns:

/v2/txproposals/: Get Wallet’s pending transaction proposals and their status

Returns:

/v4/addresses/: Get Wallet’s main addresses (does not include change addresses)

Optional Arguments:

Returns:

/v1/balance/: Get Wallet’s balance

Returns:

/v1/txnotes/:txid: Get user notes associated to the specified transaction

Returns:

/v1/fiatrates/:code: Get the fiat rate for the specified ISO 4217 code

Optional Arguments:

Returns:

POST Endpoints

/v1/wallets/: Create a new Wallet

Required Arguments:

Returns:

/v1/wallets/:id/copayers/: Join a Wallet in creation

Required Arguments:

Returns:

/v3/txproposals/: Add a new temporary transaction proposal

Required Arguments:

Returns:

/v2/txproposals/:id/publish: Publish the previously created temporary tx proposal

Returns:

/v3/addresses/: Request a new main address from wallet . (creates an address on normal conditions)

Returns:

/v1/txproposals/:id/signatures/: Sign a transaction proposal

Required Arguments:

Returns:

/v1/txproposals/:id/broadcast/: Broadcast a transaction proposal

Returns:

/v1/txproposals/:id/rejections: Reject a transaction proposal

Returns:

/v1/addresses/scan: Start an address scan process looking for activity.

Optional Arguments:

/v1/txconfirmations/: Subscribe to receive push notifications when the specified transaction gets confirmed

Required Arguments:

PUT Endpoints

/v1/txnotes/:txid/: Modify a note for a tx

DELETE Endpoints

/v1/txproposals/:id/: Deletes a transaction proposal. Only the creator can delete a TX Proposal, and only if it has no other signatures or rejections

Returns:

/v1/txconfirmations/:txid: Unsubscribe from transaction txid and no longer listen to its confirmation

Push Notifications

Recomended to complete config.js file:

POST Endpoints

/v1/pushnotifications/subscriptions/: Adds subscriptions for push notifications service at database

DELETE Endpoints

/v2/pushnotifications/subscriptions/: Remove subscriptions for push notifications service from database

Contributing

See CONTRIBUTING.md on the main bitcore repo for information about how to contribute.

License

Code released under the MIT license.

Copyright 2013-2019 BitPay, Inc. Bitcore is a trademark maintained by BitPay, Inc.