Skip to content
Permalink
Browse files

Merge pull request bitpay#2084 from justinkook/feature/regtest-docs

Feature(BWS Docs) - Enable Regtest for bws and copay docs (BTC Only)
  • Loading branch information
matiu committed Mar 29, 2019
2 parents 7d72fb5 + d75ebc2 commit 77271ff73d6c780fac3a110457af6136a0ca4fae
Showing with 159 additions and 31 deletions.
  1. +159 −31 packages/bitcore-wallet-service/README.md
@@ -1,4 +1,3 @@

# Bitcore Wallet Service

[![NPM Package](https://img.shields.io/npm/v/bitcore-wallet-service.svg?style=flat-square)](https://www.npmjs.org/package/bitcore-wallet-service)
@@ -12,10 +11,10 @@
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](https://github.com/bitpay/bitcore/tree/master/packages/bitcore-wallet-client) for the *official* client library that communicates to BWS and verifies its response. Also check [bitcore-wallet](https://github.com/bitpay/bitcore/tree/master/packages/bitcore-wallet) for a simple CLI wallet implementation that relies on BWS.

BWS is been used in production enviroments for [Copay Wallet](https://copay.io), [Bitpay App wallet](https://bitpay.com/wallet) and others.
See [bitcore-wallet-client](https://github.com/bitpay/bitcore/tree/master/packages/bitcore-wallet-client) for the _official_ client library that communicates to BWS and verifies its response. Also check [bitcore-wallet](https://github.com/bitpay/bitcore/tree/master/packages/bitcore-wallet) for a simple CLI wallet implementation that relies on BWS.

BWS is been used in production enviroments for [Copay Wallet](https://copay.io), [Bitpay App wallet](https://bitpay.com/wallet) and others.

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

@@ -56,7 +55,7 @@ BWS can be used with PM2 with the provided `app.js` script:

## Using SSL

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

```json
https: true,
@@ -71,27 +70,156 @@ BWS can be used with PM2 with the provided `app.js` script:
```

@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
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

- bitcore-node running on http://localhost:3000
- bws running locally on http://localhost:3232/bws/api
- mongod running
- copay running on port: 8100
- bitcoin-core running on regtest mode (blue icon logo)

> 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 testnet and regtest to bitcore.config.json. Testnet config must match regtest settings.

```
"testnet": {
"chainSource": "p2p",
"trustedPeers": [
{
"host": "127.0.0.1",
"port": 20020
}
],
"rpc": {
"host": "127.0.0.1",
"port": 20021,
"username": "bitpaytest",
"password": "local321"
}
},
"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/config.js**

2. Point testnet to http://localhost:3000 in 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**

3. 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
```

2. Select Testnet by pressing the slider button.

<img width="923" alt="screen shot 2019-03-06 at 10 50 29 am" src="https://user-images.githubusercontent.com/23103037/53894324-e69f8300-3ffd-11e9-9b25-145332fe860c.png">

## Testing on mobile

Requirements:

- Mobile phone and PC must be connected to the same internet
- PC desktop ip address for localhost

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
```

2. Enter PC ip address followed by port in the mobile phone browser:

```
10.10.11.73:8100
```

3. 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:
In order to access a wallet, clients are required to send the headers:

```sh
x-identity
@@ -130,8 +258,8 @@ Returns:
- creatorName
- message
- actions array ['createdOn', 'type', 'copayerId', 'copayerName', 'comment']
### `/v2/txproposals/`: Get Wallet's pending transaction proposals and their status

### `/v2/txproposals/`: Get Wallet's pending transaction proposals and their status

Returns:

@@ -150,7 +278,7 @@ Returns:
- List of Addresses object: (https://github.com/bitpay/bitcore/blob/master/packages/bitcore-wallet-service/lib/model/address.js). This call is mainly provided so the client check this addresses for incoming transactions (using a service like [Insight](https://insight.bitcore.io)
- Returns cashaddr without prefix for BCH

### `/v1/balance/`: Get Wallet's balance
### `/v1/balance/`: Get Wallet's balance

Returns:

@@ -163,13 +291,13 @@ Returns:
- byAddress array ['address', 'path', 'amount']: A list of addresses holding funds.
- totalKbToSendMax: An estimation of the number of KiB required to include all available UTXOs in a tx (including unconfirmed).

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

Returns:

- The note associated to the `txid` as a string.

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

Optional Arguments:

@@ -184,13 +312,13 @@ Returns:

### `/v1/wallets/`: Create a new Wallet

Required Arguments:
Required Arguments:

- name: Name of the wallet
- m: Number of required peers to sign transactions
- name: Name of the wallet
- m: Number of required peers to sign transactions
- n: Number of total peers on the wallet
- pubKey: Wallet Creation Public key to check joining copayer's signatures (the private key is unknown by BWS and must be communicated
by the creator peer to other peers).
by the creator peer to other peers).

Returns:

@@ -244,18 +372,18 @@ Returns:

Required Arguments:

- signatures: All Transaction's input signatures, in order of appearance.
- signatures: All Transaction's input signatures, in order of appearance.

Returns:

- TX Proposal object. (see [fields on the source code](https://github.com/bitpay/bitcore/blob/master/packages/bitcore-wallet-service/lib/model/txproposal.js)). `.status` is probably needed in this case.

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

Returns:

- TX Proposal object. (see [fields on the source code](https://github.com/bitpay/bitcore/blob/master/packages/bitcore-wallet-service/lib/model/txproposal.js)). `.status` is probably needed in this case.

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

Returns:
@@ -264,15 +392,15 @@ Returns:

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

Optional Arguments:
Optional Arguments:

- includeCopayerBranches: Scan all copayer branches following BIP45 recommendation (defaults to false).

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

Required Arguments:

- txid: The transaction to subscribe to.
- txid: The transaction to subscribe to.

## PUT Endpoints

@@ -282,16 +410,16 @@ Required Arguments:

### `/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:
Returns:

- TX Proposal object. (see [fields on the source code](https://github.com/bitpay/bitcore/blob/master/packages/bitcore-wallet-service/lib/model/txproposal.js)). `.id` is probably needed in this case.

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

# Push Notifications

Recomended to complete config.js file:
Recomended to complete config.js file:

- [FCM documentation](https://firebase.google.com/docs/cloud-messaging/)
- [Apple's Notification](https://developer.apple.com/documentation/usernotifications)

0 comments on commit 77271ff

Please sign in to comment.
You can’t perform that action at this time.