lbcwallet/README.md

141 lines
4.2 KiB
Markdown
Raw Normal View History

2013-08-21 16:37:30 +02:00
btcwallet
=========
btcwallet is a daemon handling bitcoin wallet functions. It relies on
a running btcd instance for asynchronous blockchain queries and
notifications over websockets.
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.
2013-08-21 16:37:30 +02:00
This project is currently under active development is not production
2013-11-12 18:11:29 +01:00
ready yet. Because of this, support for using the main Bitcoin netowrk
is currently disabled, and testnet must be used instead.
## Installation
### Windows - MSI Available
Install the btcd suite MSI here:
https://opensource.conformal.com/packages/windows/btcdsuite/
### 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:
2013-10-29 01:29:53 +01:00
```bash
$ 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://opensource.conformal.com/packages/windows/btcdsuite/
### Linux/BSD/POSIX - Build from Source
- Run the following commands to update btcwallet, all dependencies, and install it:
2013-10-29 01:29:53 +01:00
```bash
$ go get -u -v github.com/conformal/btcd/...
$ go get -u -v github.com/conformal/btcwallet/...
```
## Getting Started
### Windows (Installed from MSI)
Open ```Btcd Suite``` from the ```Btcd Suite``` menu in the Start
Menu. This will also open btcgui, which can be closed if you only
want btcd and btcwallet running.
### Linux/BSD/POSIX/Source
2013-08-21 16:37:30 +02:00
- Run the following command to start btcd:
2013-10-29 01:29:53 +01:00
```bash
$ 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/cert.pem
```
- Run the following command to start btcwallet:
```bash
2013-10-29 01:29:53 +01:00
$ btcwallet -u rpcuser -P rpcpass
```
## Frontend Usage
2013-08-21 16:37:30 +02:00
Frontends wishing to use btcwallet must connect to the websocket
2013-11-21 15:54:03 +01:00
`/frontend`. Messages sent to btcwallet over this websocket are
2013-08-21 16:37:30 +02:00
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.
2013-08-21 16:37:30 +02:00
## TODO
2013-08-21 16:37:30 +02:00
- Documentation (specifically the websocket API additions)
- Code cleanup
- Optimize
- Much much more. Stay tuned.
2013-08-21 16:37:30 +02:00
## GPG Verification Key
All official release tags are signed by Conformal so users can ensure the code
has not been tampered with and is coming from Conformal. To verify the
signature perform the following:
- Download the public key from the Conformal website at
https://opensource.conformal.com/GIT-GPG-KEY-conformal.txt
- Import the public key into your GPG keyring:
```bash
gpg --import GIT-GPG-KEY-conformal.txt
```
- Verify the release tag with the following command where `TAG_NAME` is a
placeholder for the specific tag:
```bash
git tag -v TAG_NAME
```
## License
btcwallet is licensed under the liberal ISC License.