RanchiMall/fcoin
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: formatting and consistency

Browse Source
This commit is contained in:
Braydon Fuller 2019-02-28 21:33:09 -08:00
parent c64ccf215e
commit e736a7ee39
No known key found for this signature in database
GPG Key ID: F24F232D108B3AD4
18 changed files with 242 additions and 145 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
README.md
View File

@ -36,13 +36,14 @@ $ npm install
$ ./bin/bcoin
```
See the [Beginner's Guide][guide] for more in-depth installation instructions.
See the [Getting started][guide] guide for more in-depth installation
instructions, including verifying releases.
## Documentation
- API Docs: https://bcoin.io/docs/
- REST Docs: https://bcoin.io/api-docs/
- Docs: [docs/](docs/README.md)
- General docs: [docs/](docs/README.md)
- Wallet and node API docs: https://bcoin.io/api-docs/
- Library API docs: https://bcoin.io/docs/
## Support
@ -68,10 +69,10 @@ all code is your original work. `</legalese>`
See LICENSE for more info.
[purse]: https://purse.io
[guide]: https://github.com/bcoin-org/bcoin/blob/master/docs/Beginner's-Guide.md
[guide]: docs/getting-started.md
[freenode]: https://freenode.net/
[irc]: irc://irc.freenode.net/bcoin
[changelog]: https://github.com/bcoin-org/bcoin/blob/master/CHANGELOG.md
[changelog]: CHANGELOG.md
[coverage-status-img]: https://codecov.io/gh/bcoin-org/bcoin/badge.svg?branch=master
[coverage-status-url]: https://codecov.io/gh/bcoin-org/bcoin?branch=master

60
docs/README.md
View File

@ -1,28 +1,44 @@
## Getting Started
- [Getting Started](Beginner's-Guide.md)
- [Configuration](Configuration.md)
- [Wallet System](Wallet-System.md)
- [Design](Design.md)
# Documentation
## Table of contents
- [Getting started](getting-started.md)
- [Configuration](configuration.md)
- [Wallet system](wallet-system.md)
- [Design](design.md)
- [Node and wallet CLI](cli.md)
## External links
- [Guides](https://bcoin.io/guides.html)
- [Running in the browser](https://bcoin.io/guides/browser.html)
- [Node and wallet REST and RPC API](https://bcoin.io/api-docs/index.html)
## Running
- [Bcoin CLI](CLI.md)
- [Running in the Browser](https://bcoin.io/guides/browser.html)
- [REST and RPC API](https://bcoin.io/api-docs/index.html#introduction)
## Code Examples
## Library examples
These code examples are designed to demonstrate how to integrate bcoin modules
with minimal configuration.
- [Simple Fullnode](Examples/fullnode.js) - Creates a `FullNode` object and connects to `testnet`.
- [Connect to Peer](Examples/connect-to-peer.js) - Connects to a user-defined peer in `regtest` mode.
- [Connecting to the P2P Network](Examples/connect-to-the-p2p-network.js) - Creates `chain`, `pool`, and `mempool` objects for both main and testnet networks.
- [Creating a Blockchain and Mempool](Examples/create-a-blockchain-and-mempool.js) - Mines a block from the mempool to the chain.
- [Wallet with Dummy TX](Examples/wallet.js) - Adds a "dummy" transaction to the wallet and `tx` event is handled.
- [SPV Sync](Examples/spv-sync-wallet.js) - A transaction matching the SPV node's bloom filter is broadcast by a minimal full node to the SPV node.
- [Plugin Example](Examples/peers-plugin.js) - Demonstrates the `plugin` feature of bcoin's `node` object.
- [Client API Usage](Examples/client-api.js) - Demonstrates usage of the node and wallet API.
- [Create and Sign TX](Examples/create-sign-tx.js) - Demonstrates how to use `mtx` and `keyring` modules to sign a transaction.
- [Get Transaction from Chain](Examples/get-tx-from-chain.js) - Connects to live testnet network and syncs the first 1000 blocks with tx indexing active.
- [Create Watch Only Wallet](Examples/watch-only-wallet.js) - Imports an `xpub` into a new watch-only wallet that can derive addresses.
- [Simple fullnode](examples/fullnode.js) - Creates a `FullNode` object and
connects to `testnet`.
- [Connect to peer](examples/connect-to-peer.js) - Connects to a user-defined
peer in `regtest` mode.
- [Connecting to the P2P network](examples/connect-to-the-p2p-network.js) -
Creates `chain`, `pool`, and `mempool` objects for both main and
testnet networks.
- [Creating a blockchain and mempool](examples/create-a-blockchain-and-mempool.js) -
Mines a block from the mempool to the chain.
- [Wallet with dummy TX](examples/wallet.js) - Adds a "dummy" transaction to
the wallet and `tx` event is handled.
- [SPV sync](examples/spv-sync-wallet.js) - A transaction matching the SPV
node's bloom filter is broadcast by a minimal full node to the SPV node.
- [Plugin example](examples/peers-plugin.js) - Demonstrates the `plugin`
feature of bcoin's `node` object.
- [Client API usage](examples/client-api.js) - Demonstrates usage of the node
and wallet API.
- [Create and sign TX](examples/create-sign-tx.js) - Demonstrates how to use
`mtx` and `keyring` modules to sign a transaction.
- [Get transaction from chain](examples/get-tx-from-chain.js) - Connects to
live testnet network and syncs the first 1000 blocks with tx indexing active.
- [Create watch only wallet](examples/watch-only-wallet.js) - Imports an `xpub`
into a new watch-only wallet that can derive addresses.

12
docs/CLI.md → docs/cli.md
View File

@ -1,5 +1,8 @@
Bcoin ships with [bclient](https://github.com/bcoin-org/bclient) as its default client
to the [API](https://bcoin.io/api-docs) for command line access.
# Node and wallet CLI
Bcoin ships with [bclient](https://github.com/bcoin-org/bclient) as its
default client to the [API](https://bcoin.io/api-docs) for command
line access.
## Configuration
@ -17,7 +20,8 @@ With command-line arguments:
$ bcoin-cli --network=testnet --api-key=hunter2 info
```
You can also use `~/.bcoin/bcoin.conf` for configuration options, see [Configuration](Configuration.md) for the full details.
You can also use `~/.bcoin/bcoin.conf` for configuration options,
see [Configuration](configuration.md) for the full details.
## Examples
@ -66,4 +70,4 @@ $ bcoin-cli help
$ bcoin-cli rpc help
$ bwallet-cli help
$ bwallet-cli rpc help
```
```

134
docs/Configuration.md → docs/configuration.md
View File

@ -1,8 +1,10 @@
# Configuration
By default, the mainnet bcoin config files will reside in `~/.bcoin/bcoin.conf` and `~/.bcoin/wallet.conf`.
Any parameter passed to bcoin at startup will have precedence over the config file.
Even if you are just running `bclient` without bcoin installed (to access a remote server, for example)
the configuration files would still reside in `~/.bcoin/`
By default, the mainnet bcoin config files will reside in `~/.bcoin/bcoin.conf`
and `~/.bcoin/wallet.conf`. Any parameter passed to bcoin at startup will have
precedence over the config file. Even if you are just running `bclient` without
bcoin installed (to access a remote server, for example) the configuration
files would still reside in `~/.bcoin/`
For example:
@ -10,12 +12,14 @@ For example:
bcoin --network=regtest --api-key=menace --daemon
```
...will read the config file at `~/.bcoin/regtest/bcoin.conf`
and ignore any `network` or `api-key` parameters listed in that file.
...will read the config file at `~/.bcoin/regtest/bcoin.conf` and ignore any
`network` or `api-key` parameters listed in that file.
All bcoin configuration options work in the config file, CLI arguments,
process environment, and in the constructor parameters when instantiating
new `node` objects in JavaScript. Each method has slightly different
formatting. Note specifically the usage of hyphens and capital letters.
All bcoin configuration options work in the config file, CLI arguments,
process environment, and in the constructor parameters when instantiating new `node` objects in JavaScript.
Each method has slightly different formatting. Note specifically the usage of hyphens and capital letters.
See the examples below:
| config file | CLI parameter | environment variable | JS object constructor |
@ -24,10 +28,9 @@ See the examples below:
| `log-level: debug` | `--log-level=debug` | `BCOIN_LOG_LEVEL=debug` | `{logLevel: 'debug'}` |
| `max-outbound: 8` | `--max-outbound=8` | `BCOIN_MAX_OUTBOUND=8` | `{maxOutbound: 8}`|
## Prefix
## Datadir/Prefix
Bcoin's datadir is determined by the `prefix` option.
Bcoin's data directory is determined by the `prefix` option.
Example:
@ -35,56 +38,73 @@ Example:
$ bcoin --prefix ~/.bcoin_spv --spv
```
Will create a datadir of `~/.bcoin_spv`, containing a chain database, wallet database and log file.
Will create a datadir of `~/.bcoin_spv`, containing a chain database, wallet
database and log file.
## Common Options
## Common options
- `config`: Points to a custom config file, not in the prefix directory.
- `network`: Which network's chainparams to use for the node (main, testnet, regtest, or simnet) (default: main).
- `workers`: Whether to use a worker process pool for transaction verification (default: true).
- `workers-size`: Number of worker processes to spawn for transaction verification. By default, the worker pool will be sized based on the number of CPUs/cores in the machine.
- `workers-timeout`: Worker process execution timeout in milliseconds (default: 120000).
- `network`: Which network's chainparams to use for the node (main, testnet,
regtest, or simnet) (default: main).
- `workers`: Whether to use a worker process pool for transaction
verification (default: true).
- `workers-size`: Number of worker processes to spawn for transaction
verification. By default, the worker pool will be sized based on the number
of CPUs/cores in the machine.
- `workers-timeout`: Worker process execution timeout in
milliseconds (default: 120000).
- `sigcache-size`: Max number of items in signature cache.
## Node Options
## Node options
- `prefix`: The data directory (stores databases, logs, and configs) (default=~/.bcoin).
- `prefix`: The data directory (stores databases, logs, and configs)
(default=~/.bcoin).
- `db`: Which database backend to use (default=leveldb).
- `max-files`: Max open files for leveldb. Higher generally means more disk page cache benefits, but also more memory usage (default: 64).
- `cache-size`: Size (in MB) of leveldb cache and write buffer (default: 32mb).
- `max-files`: Max open files for leveldb. Higher generally means more disk
page cache benefits, but also more memory usage (default: 64).
- `cache-size`: Size (in MB) of leveldb cache and write buffer
(default: 32mb).
- `spv`: Enable Simplified Payments Verification (SPV) mode
*Note: The `spv` and `daemon` options can not be entered in `bcoin.conf`. They will only work when passed as a launch argument:*
*Note: The `spv` and `daemon` options can not be entered in `bcoin.conf`.
They will only work when passed as a launch argument:*
```
bcoin --spv --daemon
```
## Logger Options
## Logger options
- `log-level`: `error`, `warning`, `info`, `debug`, or `spam` (default: debug).
- `log-console`: `true` or `false` - whether to actually write to stdout/stderr
if foregrounded (default: true).
- `log-file`: Whether to use a log file (default: true).
## Chain Options
## Chain options
Note that certain chain options affect the format and indexing of the chain database and must be passed in consistently each time.
Note that certain chain options affect the format and indexing of the chain
database and must be passed in consistently.
- `prune`: Prune from the last 288 blocks (default: false).
- `checkpoints`: Use checkpoints and getheaders for the initial sync (default: true).
- `coin-cache`: The size (in MB) of the in-memory UTXO cache. By default, there is no UTXO cache enabled. To get a good number of cache hits per block, the coin cache has to be fairly large (60-100mb recommended at least).
- `index-tx`: Index transactions (enables transaction endpoints in REST api) (default: false).
- `checkpoints`: Use checkpoints and getheaders for the initial
sync (default: true).
- `coin-cache`: The size (in MB) of the in-memory UTXO cache. By default,
there is no UTXO cache enabled. To get a good number of cache hits per
block, the coin cache has to be fairly large (60-100mb recommended at least).
- `index-tx`: Index transactions (enables transaction endpoints in REST api)
(default: false).
- `index-address`: Index transactions and utxos by address (default: false).
## Mempool Options
## Mempool options
- `mempool-size`: Max mempool size in MB (default: 100).
- `replace-by-fee`: Allow replace-by-fee transactions (default: false).
- `persistent-mempool`: Save mempool to disk and read into memory on boot (default: false).
- `persistent-mempool`: Save mempool to disk and read into memory on boot
(default: false).
## Pool Options
## Pool options
- `selfish`: Enable "selfish" mode (no relaying of txes or blocks) (default: false).
- `selfish`: Enable "selfish" mode (no relaying of txes or blocks)
(default: false).
- `compact`: Enable compact block relay (default: true).
- `bip37`: Enable serving of bip37 merkleblocks (default: false).
- `listen`: Accept incoming connections (default: true).
@ -96,15 +116,19 @@ Note that certain chain options affect the format and indexing of the chain data
- `public-host`: Public host to advertise on network.
- `public-port`: Public port to advertise on network.
- `nodes`: List of target nodes to connect to (comma-separated).
- `only`: List of nodes to ONLY connect to (no other nodes or dns seeds will be contacted).
- `only`: List of nodes to ONLY connect to (no other nodes or dns seeds will
be contacted).
## Miner Options
## Miner options
- `coinbase-flags`: Coinbase flags (default: mined by bcoin).
- `coinbase-address`: List of payout addresses, randomly selected during block creation (comma-separated).
- `coinbase-address`: List of payout addresses, randomly selected during block
creation (comma-separated).
- `max-block-weight`: Max block weight to mine (default: 4000000).
- `reserved-block-weight`: Amount of space reserved for coinbase (default: 4000).
- `reserved-block-sigops`: Amount of sigops reserved for coinbase (default: 400).
- `reserved-block-weight`: Amount of space reserved for coinbase
(default: 4000).
- `reserved-block-sigops`: Amount of sigops reserved for coinbase
(default: 400).
## HTTP
@ -113,25 +137,30 @@ Note that certain chain options affect the format and indexing of the chain data
- `ssl-cert`: Path to SSL cert.
- `ssl-key`: Path to SSL key.
- `service-key`: Service key (used for accessing wallet system only).
- `api-key`: API key (used for accessing all node APIs, may be different than API key for wallet server).
- `api-key`: API key (used for accessing all node APIs, may be different than
API key for wallet server).
- `cors`: Enable "Cross-Origin Resource Sharing" HTTP headers (default: false).
Note: For security `cors` should not be used with `no-auth`.\
Note: For security `cors` should not be used with `no-auth`. \
If enabled you should also enable `wallet-auth` and set `api-key`.
## Wallet options
These options must be saved in `wallet.conf`. They can also be passed as environment variables or command-line variables
if they are preceeded with a `wallet-` prefix. (See https://github.com/bcoin-org/bcoin/blob/master/CHANGELOG.md#configuration-changes)
These options must be saved in `wallet.conf`. They can also be passed as
environment variables or command-line variables if they are preceeded with
a `wallet-` prefix. (See [CHANGELOG.md](https://github.com/bcoin-org/bcoin/blob/master/CHANGELOG.md#configuration-changes))
For example, to run a bcoin and wallet node on a remote server that you can access from a local machine, you would launch bcoin with the command:
For example, to run a bcoin and wallet node on a remote server that you can
access from a local machine, you would launch bcoin with the command:
`bcoin --network=testnet --http-host=0.0.0.0 --wallet-http-host=0.0.0.0 --wallet-api-key=hunter2 --wallet-wallet-auth=true`
`bcoin --network=testnet --http-host=0.0.0.0 --wallet-http-host=0.0.0.0
--wallet-api-key=hunter2 --wallet-wallet-auth=true`
### bcoin client:
### Bcoin client:
- `node-host`: Location of bcoin node HTTP server (default: localhost).
- `node-port`: Port of bcoin node HTTP server (defaults to RPC port of network).
- `node-port`: Port of bcoin node HTTP server (defaults to RPC port
of network).
- `node-ssl`: Whether to use SSL (default: false).
- `node-api-key`: API-key for bcoin HTTP server.
@ -150,14 +179,15 @@ For example, to run a bcoin and wallet node on a remote server that you can acce
- `ssl-cert`: Path to SSL cert.
- `http-host`: HTTP host to listen on (default: 127.0.0.1).
- `http-port`: HTTP port to listen on (default: 8334 for mainnet).
- `api-key`: API key (used for accessing all wallet APIs, may be different than API key for node server).
- `api-key`: API key (used for accessing all wallet APIs, may be different
than API key for node server).
- `cors`: Enable "Cross-Origin Resource Sharing" HTTP headers (default: false).
- `no-auth`: Disable auth for API server and wallets (default: false).
- `wallet-auth`: Enable token auth for wallets (default: false).
- `admin-token`: Token required if `wallet-auth` is enabled: restricts access to [all wallet admin routes.](http://bcoin.io/api-docs/#wallet-admin-commands)
- `admin-token`: Token required if `wallet-auth` is enabled: restricts access
to [all wallet admin routes.](https://bcoin.io/api-docs/#wallet-admin-commands)
## Sample config files
## Sample Config Files
See https://github.com/bcoin-org/bcoin/blob/master/etc/sample.conf
and https://github.com/bcoin-org/bcoin/blob/master/etc/sample.wallet.conf
- Node https://github.com/bcoin-org/bcoin/blob/master/etc/sample.conf
- Wallet https://github.com/bcoin-org/bcoin/blob/master/etc/sample.wallet.conf

24
docs/Design.md → docs/design.md
View File

@ -1,4 +1,4 @@
## Notes on Design
# Design
Bcoin is thoroughly event driven. It has a fullnode object, but Bcoin was
specifically designed so the mempool, blockchain, p2p pool, and wallet database
@ -21,23 +21,23 @@ http client -> tx -> http server -> mempool
Not only does the loose coupling make testing easier, it ensures people can
utilize bcoin for many use cases. Learn more about specific events and
event emitters at http://bcoin.io/guides/events.html
event emitters at https://bcoin.io/guides/events.html
### Performance
## Performance
Non-javscript people reading this may think using javascript isn't a wise
Non-javscript people reading this may think using JavaScript isn't a wise
decision.
#### Javascript
### JavaScript
Javascript is inherently slow due to how dynamic it is, but modern JITs have
JavaScript is inherently slow due to how dynamic it is, but modern JITs have
solved this issue using very clever optimization and dynamic recompilation
techniques. v8 in some cases can [rival the speed of C++][v8] if the code is
well-written.
#### Concurrency
### Concurrency
Bcoin runs in node.js, so the javascript code is limited to one thread. We
Bcoin runs in node.js, so the JavaScript code is limited to one thread. We
solve this limitation by spinning up persistent worker processes for
transaction verification (webworkers when in the browser). This ensures the
blockchain and mempool do not block the master process very much. It also means
@ -55,13 +55,13 @@ Bcoin uses [secp256k1-node][secp256k1-node] for ECDSA verification, which is a
node.js binding to Pieter Wuille's blazingly fast [libsecp256k1][libsecp256k1]
library.
In the browser, bcoin will use [elliptic][elliptic], the fastest javascript
In the browser, bcoin will use [elliptic][elliptic], the fastest JavaScript
ECDSA implementation. It will obviously never beat C and hand-optimized
assembly, but it's still usable.
#### Benefits
### Benefits
The real feature of javascript is that your code will run almost anywhere. With
The real feature of JavaScript is that your code will run almost anywhere. With
bcoin, we now have a full node that will run on almost any browser, on laptops,
on servers, on smartphones, on most devices you can imagine, even by simply
visiting a webpage.
@ -69,4 +69,4 @@ visiting a webpage.
[v8]: https://www.youtube.com/watch?v=UJPdhx5zTaw
[libsecp256k1]: https://github.com/bitcoin-core/secp256k1
[secp256k1-node]: https://github.com/cryptocoinjs/secp256k1-node
[elliptic]: https://github.com/indutny/elliptic
[elliptic]: https://github.com/indutny/elliptic

0
docs/Examples/client-api.js → docs/examples/client-api.js
View File

0
docs/Examples/connect-to-peer.js → docs/examples/connect-to-peer.js
View File

0
docs/Examples/connect-to-the-p2p-network.js → docs/examples/connect-to-the-p2p-network.js
View File

0
docs/Examples/create-a-blockchain-and-mempool.js → docs/examples/create-a-blockchain-and-mempool.js
View File

0
docs/Examples/create-sign-tx.js → docs/examples/create-sign-tx.js
View File

0
docs/Examples/fullnode.js → docs/examples/fullnode.js
View File

0
docs/Examples/get-tx-from-chain.js → docs/examples/get-tx-from-chain.js
View File

0
docs/Examples/peers-plugin.js → docs/examples/peers-plugin.js
View File

0
docs/Examples/spv-sync-wallet.js → docs/examples/spv-sync-wallet.js
View File

0
docs/Examples/wallet.js → docs/examples/wallet.js
View File

0
docs/Examples/watch-only-wallet.js → docs/examples/watch-only-wallet.js
View File

100
docs/Beginner's-Guide.md → docs/getting-started.md
View File

@ -1,6 +1,10 @@
# Getting started
## Introduction
Bcoin is an _alternative_ implementation of the bitcoin protocol, written in node.js. It is a full node which can be used for full blockchain validation and is aware of all known consensus rules.
Bcoin is an _alternative_ implementation of the bitcoin protocol, written in
node.js. It is a full node which can be used for full blockchain validation
and is aware of all known consensus rules.
## Requirements
@ -11,13 +15,20 @@ Bcoin is an _alternative_ implementation of the bitcoin protocol, written in nod
- gcc/g++ (for leveldb and secp256k1)
- git (optional, see below)
(\*): Note that bcoin works best with unix-like OSes, and has not yet been thoroughly tested on windows.
(\*): Note that bcoin works best with unix-like OSes, and has not yet been
thoroughly tested on windows.
(\*\*): The BSDs and Solaris have also not been tested yet, but should work in theory.
(\*\*): The BSDs and Solaris have also not been tested yet, but should work
in theory.
## Build & Install
## Build & install
Bcoin is meant to be installed via git for security purposes, as there are security issues when installing via npm. All tagged commits for release should be signed by @chjj's [PGP key][keybase] (`B4B1F62DBAC084E333F3A04A8962AB9DE6666BBD`). Signed copies of node.js are available from [nodejs.org][node], or from your respective OS's package repositories.
Bcoin is meant to be installed via git for security purposes, as there
are security issues when installing via npm. All tagged commits for
release should be signed by @chjj's [PGP key][keybase]
(`B4B1F62DBAC084E333F3A04A8962AB9DE6666BBD`). Signed copies of node.js
are available from [nodejs.org][node], or from your respective OS's
package repositories.
### Installing via Git
@ -39,7 +50,10 @@ Install dependencies:
$ npm install
$ npm install -g # link globally
```
**Note:** Dependencies are checked for integrity using `package-lock.json`. However `npm` _will not_ make these checks with `npm install -g` and it will link your installation globally so that `bcoin` is in your path _(e.g. $ bcoin)_.
**Note:** Dependencies are checked for integrity using `package-lock.json`.
However `npm` _will not_ make these checks with `npm install -g` and it
will link your installation globally so that `bcoin` is in your
path _(e.g. $ bcoin)_.
### Installing via Docker
@ -67,11 +81,16 @@ bcoin.
### Troubleshooting
If the build fails compilation for `bcoin-native` or `secp256k1-node` __validation will be slow__ (a block verification which should take 1 second on consumer grade hardware may take up to 15 seconds). Bcoin will throw a warning on boot if it detects a build failure. If you run into this issue, please post an issue on the repo.
If the build fails compilation for `bcoin-native` or `secp256k1-node`
__validation will be slow__ (a block verification which should take 1 second
on consumer grade hardware may take up to 15 seconds). Bcoin will throw a
warning on boot if it detects a build failure. If you run into this issue,
please post an issue on the repo.
## Starting up your first bcoin node
If bcoin is installed globally, `$ bcoin` should be in your PATH. If not, the bcoin bootstrap script resides in `/path/to/bcoin/bin/bcoin`.
If bcoin is installed globally, `$ bcoin` should be in your PATH. If not,
the bcoin bootstrap script resides in `/path/to/bcoin/bin/bcoin`.
``` bash
$ bcoin
@ -85,21 +104,30 @@ To run as a daemon:
$ bcoin --daemon
```
This will start up a full node, complete with: a blockchain, mempool, miner, p2p server, wallet server, and an HTTP REST+RPC server.
This will start up a full node, complete with: a blockchain, mempool, miner,
p2p server, wallet server, and an HTTP REST+RPC server.
All logs will be written to `~/.bcoin/debug.log` by default.
By default, the http server will only listen on `127.0.0.1:8332`. No auth will be required if an API key was not passed in. If you listen on any other host, auth will be required and an API key will be auto-generated if one was not passed in.
By default, the http server will only listen on `127.0.0.1:8332`. No auth
will be required if an API key was not passed in. If you listen on any other
host, auth will be required and an API key will be auto-generated if one was
not passed in.
## Listening Externally
## Listening externally
To listen publicly on the HTTP server, `--http-host=0.0.0.0` (ipv4) or `--http-host=::` (ipv4 and ipv6) can be passed. Additionally this: `--http-port=1337` can set the port.
To listen publicly on the HTTP server, `--http-host=0.0.0.0` (ipv4) or
`--http-host=::` (ipv4 and ipv6) can be passed. Additionally this:
`--http-port=1337` can set the port.
To advertise your node on the P2P network `--public-host=[your-public-ip]` and `--public-port=[your-public-port]` may be passed.
To advertise your node on the P2P network `--public-host=[your-public-ip]`
and `--public-port=[your-public-port]` may be passed.
## Using an API Key
If listening publicly on the HTTP server, an API key is required. One will be randomly generated if no key was chosen, but not explicitly reported to the user. An API key can be chosen with the `--api-key` option.
If listening publicly on the HTTP server, an API key is required. One will
be randomly generated if no key was chosen, but not explicitly reported to
the user. An API key can be chosen with the `--api-key` option.
Example:
@ -113,7 +141,9 @@ API keys are used with HTTP Basic Auth:
$ curl http://x:hunter2@localhost:8332/
```
[bclient](https://github.com/bcoin-org/bclient) is the prepackaged tool for querying both the REST and RPC APIs. If bcoin is installed globally, both `bcoin-cli` and `bwallet-cli` should be on your path.
[bclient](https://github.com/bcoin-org/bclient) is the prepackaged tool for
querying both the REST and RPC APIs. If bcoin is installed globally, both
`bcoin-cli` and `bwallet-cli` should be on your path.
``` bash
$ bcoin-cli info --api-key hunter2
@ -123,9 +153,12 @@ $ bwallet-cli balance
## Using Tor/SOCKS
Bcoin has native support for SOCKS proxies, and will accept a `--proxy` option in the format of `--proxy=[user]:[pass]@host:port`.
Bcoin has native support for SOCKS proxies, and will accept a `--proxy` option
in the format of `--proxy=[user]:[pass]@host:port`.
Passing the `--onion` option tells bcoin that the SOCKS proxy is a Tor socks proxy, and will enable Tor resolution for DNS lookups, as well as try to connect to `.onion` addresses found on the P2P network.
Passing the `--onion` option tells bcoin that the SOCKS proxy is a Tor socks
proxy, and will enable Tor resolution for DNS lookups, as well as try to
connect to `.onion` addresses found on the P2P network.
``` bash
$ bcoin --proxy joe:hunter2@127.0.0.1:9050 --onion
@ -133,17 +166,22 @@ $ bcoin --proxy joe:hunter2@127.0.0.1:9050 --onion
### Running bcoin as a tor hidden service
Your hidden service must first be configured with `tor`. Once you have the `.onion` address, it can be passed into `--public-host` in the form of `--public-host foo.onion`.
Your hidden service must first be configured with `tor`. Once you have the
`.onion` address, it can be passed into `--public-host` in the form
of `--public-host foo.onion`.
## Target Nodes
## Target nodes
It's often desirable to run behind several trusted bitcoin nodes. To select permanent nodes to connect to, the `--nodes` option is available:
It's often desirable to run behind several trusted bitcoin nodes. To select
permanent nodes to connect to, the `--nodes` option is available:
``` bash
$ bcoin --nodes foo.example.com:8333,1.2.3.4:8333,5.6.7.8:8333
```
If chosen, bcoin will _always_ try to connect to these nodes as outbound peers. They are top priority and whitelisted (not susceptible to permanent bans, only disconnections).
If chosen, bcoin will _always_ try to connect to these nodes as outbound
peers. They are top priority and whitelisted (not susceptible to permanent
bans, only disconnections).
To _only_ connect to these nodes, use `--only`
@ -151,24 +189,30 @@ To _only_ connect to these nodes, use `--only`
$ bcoin --only foo.example.com,1.2.3.4,5.6.7.8
```
## Disabling Listening
## Disabling listening
To avoid accepting connections on the P2P network altogether, `--listen=false` can be passed to bcoin.
To avoid accepting connections on the P2P network altogether,
`--listen=false` can be passed to bcoin.
### Selfish Mode
### Selfish mode
Bcoin also supports a "selfish" mode. In this mode, bcoin still has full blockchain and mempool validation, but network services are disabled: it will not relay transactions or serve blocks to anyone.
Bcoin also supports a "selfish" mode. In this mode, bcoin still has full
blockchain and mempool validation, but network services are disabled: it
will not relay transactions or serve blocks to anyone.
``` bash
$ bcoin --selfish --listen=false
```
Note: Selfish mode is not recommended. We encourage you to _help_ the network by relaying transactions and blocks. At the same time, selfish mode does have its uses if you do not have the bandwidth to spare, or if you're absolutely worried about potential DoS attacks.
Note: Selfish mode is not recommended. We encourage you to _help_ the network
by relaying transactions and blocks. At the same time, selfish mode does have
its uses if you do not have the bandwidth to spare, or if you're absolutely
worried about potential DoS attacks.
## Further Configuration
## Further configuration
See [Configuration][configuration].
[keybase]: https://keybase.io/chjj#show-public
[node]: https://nodejs.org
[configuration]: Configuration.md
[configuration]: configuration.md

44
docs/Wallet-System.md → docs/wallet-system.md
View File

@ -1,31 +1,33 @@
## Notes on wallet system
# Wallet system
Bcoin maintains a wallet database which contains every wallet. Wallets are _not
usable_ without also using a wallet database. For testing, the wallet database
can be in-memory, but it must be there.
Bcoin maintains a wallet database which contains every wallet. Wallets are
_not usable_ without also using a wallet database. For testing, the wallet
database can be in-memory, but it must be there.
Wallets in bcoin are based on BIP44. They also originally supported BIP45 for
multisig, but support was removed to reduce code complexity, and also because BIP45
doesn't seem to add any benefit in practice.
multisig, but support was removed to reduce code complexity, and also because
BIP45 doesn't seem to add any benefit in practice.
The wallet database can contain many wallets, with many accounts, with many
addresses for each account. Bcoin should theoretically be able to scale to
hundreds of thousands of wallets/accounts/addresses.
### Deviation from BIP44
## Deviation from BIP44
**It's important to backup the wallet database.** There are several deviations from
[BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki) that break
determinism, and therefore it's recommended to backup the wallet database any time
an account is created, as there are several possible configurations of an account.
**It's important to backup the wallet database.** There are several deviations
from [BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki)
that break the determinsitic algorithm, and therefore it's recommended to
backup the wallet database any time an account is created, as there are several
possible configurations of an account.
There is a command available via the wallet RPC called `backupwallet` that can clone
the database to a new destination. There are also the RPC calls `dumpwallet` and
`dumpprivkey` for exporting private keys. After shutting down the wallet process,
it's also possible to copy the LevelDB database from the default location at
`~/.bcoin/wallet` for main net or `~/.bcoin/<network>/wallet` for others. Copying
LevelDB while the process is running can result in a corrupted copy. LevelDB is
also prone to [database corruption](https://en.wikipedia.org/wiki/LevelDB#Bugs_and_reliability).
There is a command available via the wallet RPC called `backupwallet` that can
clone the database to a new destination. There are also the RPC calls
`dumpwallet` and `dumpprivkey` for exporting private keys. After shutting down
the wallet process, it's also possible to copy the LevelDB database from the
default location at `~/.bcoin/wallet` for main net or
`~/.bcoin/<network>/wallet` for others. Copying LevelDB while the process is
running can result in a corrupted copy. LevelDB is also prone to
[database corruption](https://en.wikipedia.org/wiki/LevelDB#Bugs_and_reliability).
Each account can be of a different type. You could have a pubkeyhash account,
a multisig account, and a witness pubkeyhash account all in the same wallet.
@ -34,8 +36,8 @@ Accounts can be configured with or without Segregated Witness and both base58
same account.
Bcoin adds a third branch to each account for nested SegWit addresses.
Branch `0` and `1` are for `receive` and `change` addresses respectively (which
is BIP44 standard) but branch `2` is used by bcoin to derive
Branch `0` and `1` are for `receive` and `change` addresses respectively
(which is BIP44 standard) but branch `2` is used by bcoin to derive
[nested SegWit addresses.](https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki#P2WPKH_nested_in_BIP16_P2SH)
Accounts in a bcoin wallet can be configured for multisig and import xpubs
@ -48,4 +50,4 @@ Unlike [BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki),
bcoin does not limit account depth and a new account can be created
after an empty account. This can create issues with deterministic account
discovery from the master node (seed) as there are `2 ^ 31 - 1` _(worst case)_
possible accounts to search.
possible accounts to search.