@abcpros/bitcore-wallet-service 中文文档教程

Question

Bitcore Wallet Service

Multisig HD Bitcore Wallet Service。

Description

Bitcore Wallet Service 通过（希望）简单的方式促进 multisig HD 钱包的创建和操作和直观的 REST API。

BWS 通常可以在几分钟内安装完毕，并为多重签名钱包中的对等方提供通信和操作所需的所有基础设施——对服务器的信任度最低。

请参阅 bitcore-wallet-client 官方与 BWS 通信并验证其响应的客户端库。 另请检查 bitcore-wallet 以了解依赖于 BWS 的简单 CLI 钱包实现。

BWS 被用于 Copay Wallet、Bitpay App 钱包 和其他人。

有关 BWS 的更多信息，请访问 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

这将在 http://localhost:3232/bws/api 启动 BWS 服务（使用默认设置） 。

BWS 需要 mongoDB。 您可以在 config.js 配置连接

BWS 支持 SSL 和集群。 有关安装具有额外功能的 BWS 的详细指南，请参阅安装 BWS。

BWS 默认使用对 CreateWallet 端点的请求速率限制。 如果你需要修改它，检查 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

• Private keys are never sent to BWS. Copayers store them locally.
• Extended public keys are stored on BWS. This allows BWS to easily check wallet balance, send offline notifications to copayers, etc.
• During wallet creation, the initial copayer creates a wallet secret that contains a private key. All copayers need to prove they have the secret by signing their information with this private key when joining the wallet. The secret should be shared using secured channels.
• A copayer could join the wallet more than once, and there is no mechanism to prevent this. See wallet's confirm command, for a method for confirming copayers.
• All BWS responses are verified:
• Addresses and change addresses are derived independently and locally by the copayers from their local data.
• TX Proposals templates are signed by copayers and verified by others, so the BWS cannot create or tamper with them.

Using SSL

You can add your certificates at the config.js 使用：

  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 做了一份关于如何将 letsencrypt 与 BWS 一起使用的报告：https://github.com/bitpay/bitcore-wallet-service/issues/423

TX proposal life cycle

Tx proposal needs:

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 /test/integration 代码中的建议。

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 拓扑有时会崩溃 bitcore-wallet-service/lib/notificationbroadcaster.js 注意：如果在 PC 浏览器上测试，请注释掉 notificationbroadcaster.js 以禁用通知。

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/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.

Testing on mobile

要求：

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

要查找 PC 运行的 ip 地址：

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

注意：所有货币金额均以聪为单位（比特币的 1/100,000,000）。

Authentication

为了访问钱包，客户端需要发送标头：

  x-identity
  x-signature

身份是对等 ID，这将标识对等点及其钱包。 Signature 是当前请求签名，使用requestSigningKey，扩展私钥的m/1/1派生。

有关实施细节，请参阅 Bitcore Wallet Client。

GET Endpoints

/v1/wallets/: Get wallet information

返回：

• Wallet object. (see fields on the source code).

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

可选参数：

• skip: Records to skip from the result (defaults to 0)
• limit: Total number of records to return (return all available records if not specified).

返回：

• History of incoming and outgoing transactions of the wallet. The list is paginated using the skip & limit params. Each item has the following fields:
• action ('sent', 'received', 'moved')
• amount
• fees
• time
• addressTo
• confirmations
• proposalId
• creatorName
• message
• actions array ['createdOn', 'type', 'copayerId', 'copayerName', 'comment']

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

返回：

• 未决 TX 提案列表。 （参见源代码中的字段)

• 对 BCH 使用不带前缀的 cashaddr

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

可选参数：

• ignoreMaxGap: [false] Ignore checking less that 20 unused addresses (BIP44 GAP)

返回：

• List of Addresses object: (https://github.com/bitpay/bitcore/blob/master/packages/bitcore-wallet-service/src/lib/model/address.ts). This call is mainly provided so the client check this addresses for incoming transactions (using a service like Insight
• Returns cashaddr without prefix for BCH

/v1/balance/: Get Wallet's balance

返回：

• totalAmount: Wallet's total balance
• lockedAmount: Current balance of outstanding transaction proposals, that cannot be used on new transactions.
• availableAmount: Funds available for new proposals.
• totalConfirmedAmount: Same as totalAmount for confirmed UTXOs only.
• lockedConfirmedAmount: Same as lockedAmount for confirmed UTXOs only.
• availableConfirmedAmount: Same as availableAmount for confirmed UTXOs only.
• 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

返回：

• The note associated to the txid as a string.

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

可选参数：

• provider: An identifier representing the source of the rates.
• ts: The timestamp for the fiat rate (defaults to now).

返回：

• The fiat exchange rate.

POST Endpoints

/v1/wallets/: Create a new Wallet

必需参数：

• 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).

返回：

• walletId: Id of the new created wallet

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

必需参数：

• walletId: Id of the wallet to join
• name: Copayer Name
• xPubKey - Extended Public Key for this copayer.
• requestPubKey - Public Key used to check requests from this copayer.
• copayerSignature - Signature used by other copayers to verify that the copayer joining knows the wallet secret.

返回：

• copayerId: Assigned ID of the copayer (to be used on x-identity header)
• wallet: Object with wallet's information

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

必需参数：

• toAddress: RCPT Bitcoin address.
• amount: amount (in satoshis) of the mount proposed to be transfered
• proposalsSignature: Signature of the proposal by the creator peer, using proposalSigningKey.
• (opt) message: Encrypted private message to peers.
• (opt) payProUrl: Paypro URL for peers to verify TX
• (opt) feePerKb: Use an alternative fee per KB for this TX.
• (opt) excludeUnconfirmedUtxos: Do not use UTXOs of unconfirmed transactions as inputs for this TX.
• BCH addresses need to be cashaddr without prefix.

返回：

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

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

返回：

• TX Proposal object. (see fields on the source code).

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

返回：

• Address object: (https://github.com/bitpay/bitcore/blob/master/packages/bitcore-wallet-service/src/lib/model/address.ts). Note that path is returned so client can derive the address independently and check server's response.

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

必需参数：

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

返回：

• TX Proposal object. (see fields on the source code). .status is probably needed in this case.

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

返回：

• TX Proposal object. (see fields on the source code). .status is probably needed in this case.

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

返回：

• TX Proposal object. (see fields on the source code). .status is probably needed in this case.

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

可选参数：

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

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

必需参数：

• txid: The transaction to subscribe to.

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

返回：

• TX Proposal object. (see fields on the source code). .id is probably needed in this case.

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

Push Notifications

建议完成 config.js 文件：

• FCM documentation
• Apple's Notification

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

参见 CONTRIBUTING.md在主要的 bitcore repo 上获取有关如何贡献的信息。

License

代码根据 MIT 许可证发布。

版权所有 2013-2019 BitPay, Inc. Bitcore 是 BitPay, Inc. 维护的商标。