diff --git a/README.md b/README.md index b670756..d947e64 100644 --- a/README.md +++ b/README.md @@ -5,15 +5,73 @@ btcwallet is a daemon handling bitcoin wallet functions. It relies on a running btcd instance for asynchronous blockchain queries and notifications over websockets. -In addition to the HTTP server run by btcd to provide RPC and -websocket connections, btcwallet requires an HTTP server of its own to -provide websocket connections to wallet frontends. Websockets allow for -asynchronous queries, replies, and notifications. +Full btcd installation instructions can be found +[here](https://github.com/conformal/btcd). + +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. + +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. This project is currently under active development is not production -ready yet. +ready yet. Because of this, support for using the main Bitcoin is +currently disabled, and testnet must be used instead. -## Usage +## Installation + +### Windows - MSI Available + +Install the btcd suite MSI here: + +https://github.com/conformal/btcd/releases + +### Linux/BSD/POSIX - Build from Source + +- 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: + ```$ go get -u -v github.com/conformal/btcd/...``` + ```$ go get -u -v github.com/conformal/btcwallet/...``` + +- btcd and btcwallet will now be installed in either ```$GOROOT/bin``` or + ```$GOPATH/bin``` depending on your configuration. If you did not already + add to your system path during the installation, we recommend you do so now. + +## Updating + +### Windows + +Install a newer btcd suite MSI here: + +https://github.com/conformal/btcd/releases + +### Linux/BSD/POSIX - Build from Source + +- Run the following commands to update btcwallet, all dependencies, and install it: + ```$ go get -u -v github.com/conformal/btcd/...``` + ```$ go get -u -v github.com/conformal/btcwallet/...``` + +## Getting Started + +### Windows (Installed from MSI) + +Open Btcd (Testnet) and Btcwallet from the Btcd Suite menu in the +Start Menu. + +### Linux/BSD/POSIX/Source + +- Run the following commands to start btcd and btcwallet: + ```$ btcd --testnet -u rpcuser -P rpcpass``` + ```$ btcwallet -u rpcuser -P rpcpass``` + +## Frontend Usage Frontends wishing to use btcwallet must connect to the websocket `/wallet`. Messages sent to btcwallet over this websocket are @@ -21,37 +79,20 @@ 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 RPC and using it asynchronously, -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. +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. -## Installation +## TODO -btcwallet can be installed with the go get command: - -```bash -go get github.com/conformal/btcwallet -``` - -## Running - -To run btcwallet, you must have btcd installed and running. By -default btcd will run its HTTP server for RPC and websocket -connections on port 8332. However, bitcoind frontends expecting -wallet functionality may require to poll on port 8332, requiring the -btcd component in a btcwallet+btcd replacement stack to run on an -alternate port. For this reason, btcwallet by default connects to -btcd on port 8334 and runs its own HTTP server on 8332. When using -both btcd and btcwallet, it is recommend to run btcd on the -non-standard port 8334 using the `-r` command line flag. - -Assumming btcd is running on port 8334, btcwallet can be -started by running: - -```bash -btcwallet -f /path/to/wallet -``` +- Require authentication before wallet functionality can be accessed +- Serve websocket connections over TLS +- Rescan the blockchain for missed transactions +- Documentation (specifically the websocket API additions) +- Code cleanup +- Optimize +- Much much more. Stay tuned. ## GPG Verification Key @@ -73,21 +114,6 @@ signature perform the following: git tag -v TAG_NAME ``` -## What works -- New addresses can be queried if they are in the wallet file address pool -- Unknown commands are sent to btcd -- Unhandled btcd notifications (i.e. new blockchain height) are sent to each - connected frontend -- btcd replies are routed back to the correct frontend who initiated the request - -## TODO -- Require authentication before wallet functionality can be accessed -- Serve websocket connections over TLS -- Documentation -- Code cleanup -- Optimize -- Much much more. Stay tuned. - ## License btcwallet is licensed under the liberal ISC License.