diff --git a/README.md b/README.md index 7c8ceff..b56e9c2 100644 --- a/README.md +++ b/README.md @@ -4,27 +4,32 @@ btcwallet [![Build Status](https://travis-ci.org/conformal/btcwallet.png?branch=master)] (https://travis-ci.org/conformal/btcwallet) -btcwallet is a daemon handling bitcoin wallet functions. It relies on -a running btcd instance for asynchronous blockchain queries and -notifications over websockets. +btcwallet is a daemon handling bitcoin wallet functionality for a +single user. It acts as both an RPC client to btcd and an RPC server +for wallet frontends and legacy RPC applications. -Full btcd installation instructions can be found -[here](https://github.com/conformal/btcd). +The wallet file format is based on +[Armory](https://github.com/etotheipi/BitcoinArmory) and provides a +deterministic wallet where all future generated private keys can be +recovered from a previous wallet backup. Unencrypted wallets are +unsupported and are never written to disk. This design decision has +the consequence of generating new wallets on the fly impossible: a +frontend is required to provide a wallet encryption passphrase. -btcwallet runs as a daemon and provides no user interface for a -wallet. A btcwallet frontend, such as -[btcgui](https://github.com/conformal/btcgui), is required to use -btcwallet. +btcwallet is not an SPV client and requires connecting to a local or +remote btcd instance for asynchronous blockchain queries and +notifications over websockets. Full btcd installation instructions +can be found [here](https://github.com/conformal/btcd). -In addition to the HTTP server run by btcd to provide HTTP and -websocket RPC, btcwallet requires an HTTP server of its own to provide -websocket connections to wallet frontends. Websockets allow for -asynchronous queries, replies, and notifications between btcd and -btcwallet, as well as between btcwallet and any number of frontends. +As a daemon, btcwallet provides no user interface and an additional +graphical or command line client is required for normal, personal +wallet usage. Conformal has written +[btcgui](https://github.com/conformal/btcgui) as a graphical frontend +to btcwallet. This project is currently under active development is not production -ready yet. Because of this, support for using the main Bitcoin netowrk -is currently disabled, and testnet must be used instead. +ready yet. Support for creating and using wallets the main Bitcoin +netowrk is currently disabled by default. ## Installation @@ -39,7 +44,7 @@ https://opensource.conformal.com/packages/windows/btcdsuite/ - Install Go according to the installation instructions here: http://golang.org/doc/install -- Run the following commands to obtain btcwallet, all dependencies, and install it: +- Run the following commands to obtain and install btcwallet andall dependencies: ```bash $ go get -u -v github.com/conformal/btcd/... $ go get -u -v github.com/conformal/btcwallet/... @@ -68,6 +73,9 @@ $ go get -u -v github.com/conformal/btcwallet/... ## Getting Started +The follow instructions detail how to get started with btcwallet +connecting to a localhost btcd. + ### Windows (Installed from MSI) Open ```Btcd Suite``` from the ```Btcd Suite``` menu in the Start @@ -82,41 +90,41 @@ want btcd and btcwallet running. $ btcd --testnet -u rpcuser -P rpcpass ``` -- Copy btcd's autogenerated rpc.cert to ~/.btcwallet/ so btcwallet can - securely communicate with btcd over a TLS-encrypted websocket. This - step is only necessary for the first time starting btcwallet or if - btcd's autogenerated cert and key are removed and regenerated. - -```bash -$ mkdir ~/.btcwallet/ -$ cp ~/.btcd/rpc.cert ~/.btcwallet/btcd.cert -``` - - Run the following command to start btcwallet: ```bash $ btcwallet -u rpcuser -P rpcpass ``` +If everything appears to be working, it is recommended at this point to +copy the sample btcd and btcwallet configurations and update with your +RPC username and password. + +```bash +$ cp $GOPATH/src/github.com/conformal/btcd/sample-btcd.conf ~/.btcd/btcd.conf +$ cp $GOPATH/src/github.com/conformal/btcwallet/sample-btcwallet.conf ~/.btcwallet/btcwallet.conf +$ $EDITOR ~/.btcd/btcd.conf +$ $EDITOR ~/.btcwallet/btcwallet.conf +``` + ## Frontend Usage -Frontends wishing to use btcwallet must connect to the websocket -`/frontend`. Messages sent to btcwallet over this websocket are -expected to follow the standard [Bitcoin JSON -API](https://en.bitcoin.it/wiki/Original_Bitcoin_client/API_Calls_list) -and replies follow the same API. The btcd package `btcjson` provides -types and functions for creating messages that this API. However, due -to taking a synchronous protocol like HTTP and using it asynchronously -with websockets, it is recommend for frontends to use the JSON `id` -field as a sequence number so replies can be mapped back to the -messages they originated from. +Frontends wishing to use btcwallet must connect to the path +`/frontend` over a websocket connection. Messages sent to btcwallet +over this websocket are expected to follow the standard Bitcoin JSON +API (partially documented +[here](https://en.bitcoin.it/wiki/Original_Bitcoin_client/API_Calls_list)). +Websocket connections also enable additional API extensions and +JSON-RPC notifications (currently undocumented). The btcd packages +`btcjson` and `btcws` provide types and functions for creating and +JSON (un)marshaling these requests and notifications. ## TODO -- Documentation (specifically the websocket API additions) -- Code cleanup -- Optimize -- Much much more. Stay tuned. +- Full RPC compatibility with bitcoind, including mining support +- RPC Documentation (both bitcoind commands and btcwallet extensions available + for websocket connections) +- Improved test coverage ## GPG Verification Key