bitcore-wallet-service

A Multisig HD Wallet Service, with minimun server trust.

Quick Guide

 # Start the server
 npm ./app.js
 
 # Try the CLI interface
 cd bit-wallet
 
 # Create a 2-of-2 wallet (john.dat is the file where the wallet critical data will be stored, add -t for testnet)
 ./bit  create 2-2 john 
  * Secret to share:
    0a18bed5-5607-4fde-a809-dc6561bc0664:L3WtafRAEHty7h2J7VCHdiyzFboAdVFnNZXMmqDGw4yiu5kW9Tp4:T
 ./bit  status
 
 # Use -h or BIT_HOST to setup the base URL for your server.
 
 # Join the wallet from other copayer
   ./bit -f pete.dat join 0a18bed5-5607-4fde-a809-dc6561bc0664:L3WtafRAEHty7h2J7VCHdiyzFboAdVFnNZXMmqDGw4yiu5kW9Tp4:T
   ./bit -f pete.dat status
   
 # Set default file to use  
   export BIT_FILE=pete.dat
   ./bit address 
     [1bitcoinaddress]
   ./bit balance
   
 # Spend coins. Amount can be specified in btc, bit or sat (default)
   ./bit send 1xxxxx 100bit "100 bits to mother"
 
 # List pending TX Proposals
   ./bit status
   
 # Sign or reject TXs from other copayers
   ./bit -f pete.data reject <id>
   ./bit -f pete.data sign <id>
   
   # List all commands:
    ./bit --help
    
    

Server API

create a wallet

POST /v1/wallets

join a wallet

POST /v1/wallets/:id/copayers

...

[To be completed, see app.js]

Advanced Operation

Export, with different access levels

It is possible to export a wallet with restricted access level. The levels are:

readonly : allows to read wallet data: balance, tx proposals 
readwrite: + allows to create addresses and unsigned tx prposals 
full     : + allows sign tx prposals 

readonly will only export the Wallet's Extended PublicKeys, and only the derived private key required for signing 'GET' request (readonly) to the server. readwrite will add the derived private key required for signing all other requests (as POST) so readwrite access will be possible. And full will export also the Extended Private Key, which is necesary for signing wallet's transactions. bit import can handle any for the levels correctly.

full access

bit export -o wallet.dat

readonly access

bit export -o wallet.dat --access readonly

readwrite access (can create addresses, propose transactions, reject TX, but does not have signing keys)

bit export -o wallet.dat --access readwrite

Import profile on other device, with giveng access level

bit import wallet.dat

Export / Import with a new given password (TODO)

bit export -o output.dat -e
bit import output.dat 

If you need to migrate to other server, after importing the wallet use recreate

bit recreate 

Airgapped Operation (TODO)

On the Air-gapped device

git genkey
git export -o wallet.dat --readonly  (or --nosigning)

Proxy machine

git join secret -i wallet.dat
git balance
git txproposals -o txproposals.dat

(export with filter)

git txproposals  e01e -o txprosals.dat

Back to air-gapped device

To recheck tx proposals:

git txproposals -i txproposals.dat

Sign them

git sign  -i txproposals.dat -o txproposals-signed.dat
# Or With filter
git sign  e01e -i txproposals.dat -o txproposals-signed.dat

Back to proxy machine

git sign -i txproposals-signed.dat

Password protection (TODO)

encrypts everything by default

git create myWallet 2-3 -p password  
# Or (interactive mode)
git create myWallet 2-3 -p
Enter password:

allows readonly operations without password (encrypts xpriv, and leave readonlySigningKey unencrypted)

git create myWallet 2-3 -p --nopasswd:ro

allows readwrite operations without password (only encrypts xpriv)

git create myWallet 2-3 -p --nopasswd:rw

Local data

Copayers store its extended private key and their copayer's extended public key locally. We call this the Wallet Critical Data.

Security Considerations

• Private keys are never send to the server. Copayers store them locally.
• Extended public keys are stored on the server. This allows the server to easily check wallet balance, send offline notifications to copayers, etc.
• During wallet creation a wallet secret is created by the initial copayer containg 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.

All server responses are verified:

• Addresses, 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 server cannot create / tamper them

Notes

• A copayer could join the wallet more than once, and there is no mechanism to prevent it. Copayers should use the command 'confirm' to check other copayer's identity.

In case the server is compromised

• It could be possible to see past (and future) wallet's transactions.
• It is not possible to spend wallet funds, since private keys are never sent nor stored at the server
• It is not possible to tamper tx proposals or wallet addresses since they are computed and verified by copayers
• Copayers could switch to another server using their local data (see recreate command). In this case only the wallet extended data will be lost (pending and past transaction proposals, some copayer metadata).