Skip to content

Commit a534d7c

Browse files
nodechnodech
committed
Move docs from wiki
1 parent 7ef6580 commit a534d7c

16 files changed

+2025
-2
lines changed

‎.gitignore

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
node_modules/
2-
docs/
2+
docs/reference/
33
docker_data/
44
browser/bcoin*
55
bcoin*

‎docs/Beginner's-Guide.md

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
## Introduction
2+
3+
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.
4+
5+
## Requirements
6+
7+
- Linux, OSX, or Windows (\*) (\*\*)
8+
- node.js >=v5.0.0
9+
- npm >=v4.0.0
10+
- python2 (for node-gyp)
11+
- gcc/g++ (for leveldb and secp256k1)
12+
- git (optional, see below)
13+
14+
(\*): Note that bcoin works best with unix-like OSes, and has not yet been thoroughly tested on windows.
15+
16+
(\*\*): The BSDs and Solaris have also not been tested yet, but should work in theory.
17+
18+
## Build & Install
19+
20+
Bcoin is meant to be installed via npm, but for the security conscious, it may be better to clone from github. 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.
21+
22+
### Installing via NPM
23+
24+
``` bash
25+
$ npm install -g bcoin --production
26+
```
27+
28+
### Installing via Git
29+
30+
``` bash
31+
$ curl https://keybase.io/chjj/pgp_keys.asc | gpg --import
32+
$ git clone git://github.com/bcoin-org/bcoin.git
33+
$ cd bcoin
34+
$ git tag
35+
...
36+
v1.0.0-alpha # latest version
37+
$ git tag -v v1.0.0-alpha # verify signature
38+
$ git checkout v1.0.0-alpha
39+
$ npm install -g --production
40+
```
41+
42+
### Troubleshooting
43+
44+
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.
45+
46+
## Starting up your first bcoin node
47+
48+
If bcoin is installed globally, `$ bcoin` should be in your PATH. If not, the bcoin bootstrap script resides in `/path/to/bcoin/bin/bcoin`.
49+
50+
``` bash
51+
$ bcoin
52+
```
53+
54+
Will run a bcoin node as the foreground process, displaying all debug logs.
55+
56+
To run as a daemon:
57+
58+
``` bash
59+
$ bcoin --daemon
60+
```
61+
62+
This will start up a full node, complete with: a blockchain, mempool, miner, p2p server, wallet server, and an HTTP REST+RPC server.
63+
64+
All logs will be written to `~/.bcoin/debug.log` by default.
65+
66+
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.
67+
68+
## Listening Externally
69+
70+
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.
71+
72+
To advertise your node on the P2P network `--public-host=[your-public-ip]` and `--public-port=[your-public-port]` may be passed.
73+
74+
## Using an API Key
75+
76+
If listening publicly on the HTTP server, an API key is required. One will be generated and reported in the logs automatically if no key was chosen. An api key can be chosen with the `--api-key` option.
77+
78+
Example:
79+
80+
``` bash
81+
$ bcoin --http-host=0.0.0.0 --api-key hunter2 --daemon
82+
```
83+
84+
API keys are used with HTTP Basic Auth:
85+
86+
``` bash
87+
$ curl http://x:hunter2@localhost:8332/
88+
```
89+
90+
Bcoin CLI is the prepackaged tool for hitting both the REST and RPC api.
91+
92+
``` bash
93+
$ bcoin cli info --api-key hunter2
94+
$ bcoin rpc getblockchaininfo --api-key hunter2
95+
```
96+
97+
## Using Tor/SOCKS
98+
99+
Bcoin has native support for SOCKS proxies, and will accept a `--proxy` option in the format of `--proxy=[user]:[pass]@host:port`.
100+
101+
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.
102+
103+
``` bash
104+
$ bcoin --proxy joe:[email protected]:9050 --onion
105+
```
106+
107+
### Running bcoin as a tor hidden service
108+
109+
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`.
110+
111+
## Target Nodes
112+
113+
It's often desirable to run behind several trusted bitcoin nodes. To select permanent nodes to connect to, the `--nodes` option is available:
114+
115+
``` bash
116+
$ bcoin --nodes foo.example.com:8333,1.2.3.4:8333,5.6.7.8:8333
117+
```
118+
119+
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).
120+
121+
To _only_ connect to these nodes. `--max-outbound` could be set to 3:
122+
123+
``` bash
124+
$ bcoin --nodes foo.example.com,1.2.3.4,5.6.7.8 --max-outbound 3
125+
```
126+
127+
## Disabling Listening
128+
129+
To avoid accepting connections on the P2P network altogether, `--listen=false` can be passed to bcoin.
130+
131+
### Selfish Mode
132+
133+
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.
134+
135+
``` bash
136+
$ bcoin --selfish --listen=false
137+
```
138+
139+
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.
140+
141+
## Further Configuration
142+
143+
See [Configuration][configuration].
144+
145+
[keybase]: https://keybase.io/chjj#show-public
146+
[node]: https://nodejs.org/dist/v7.5.0/
147+
[configuration]: Configuration.md

‎docs/CLI.md

Lines changed: 235 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,235 @@
1+
Bcoin ships with bcoin-cli as its default HTTP client for command line access.
2+
3+
## Configuration
4+
5+
Examples:
6+
7+
``` bash
8+
$ export BCOIN_API_KEY=hunter2
9+
$ export BCOIN_NETWORK=main
10+
$ export BCOIN_URI=http://localhost:8332
11+
$ bcoin cli info
12+
```
13+
14+
``` bash
15+
$ bcoin cli info --api-key=hunter2 --uri=http://localhost
16+
```
17+
18+
``` bash
19+
$ echo 'api-key: hunter2' > ~/cli.conf
20+
$ bcoin cli info --config=~/cli.conf
21+
```
22+
23+
## Examples
24+
25+
``` bash
26+
$ export BCOIN_API_KEY=your-api-key
27+
28+
# View the genesis block
29+
$ bcoin cli block 0
30+
31+
# View the mempool
32+
$ bcoin cli mempool
33+
34+
# View primary wallet
35+
$ bcoin wallet get
36+
37+
# View transaction history
38+
$ bcoin wallet history
39+
40+
# Send a transaction
41+
$ bcoin wallet send [address] 0.01
42+
43+
# View balance
44+
$ bcoin wallet balance
45+
46+
# Derive new address
47+
$ bcoin wallet address
48+
49+
# Create a new account
50+
$ bcoin wallet account create foo
51+
52+
# Send from account
53+
$ bcoin wallet send [address] 0.01 --account=foo
54+
```
55+
56+
RPC examples:
57+
58+
``` bash
59+
$ bcoin rpc getblockchaininfo
60+
$ bcoin rpc getwalletinfo
61+
$ bcoin rpc getpeerinfo
62+
$ bcoin rpc getbalance
63+
$ bcoin rpc listtransactions
64+
$ bcoin rpc sendtoaddress [address] 0.01
65+
```
66+
67+
## Commands
68+
69+
bcoin-cli commands are split into 3 categories: cli, rpc, and wallet.
70+
71+
### Top-level Commands
72+
73+
- `info`: Get server info.
74+
- `wallets`: List all wallets.
75+
- `wallet create [id]`: Create wallet.
76+
- `broadcast [tx-hex]`: Broadcast transaction.
77+
- `mempool`: Get mempool snapshot.
78+
- `tx [hash/address]`: View transactions.
79+
- `coin [hash+index/address]`: View coins.
80+
- `block [hash/height]`: View block.
81+
- `rescan [height]`: Rescan for transactions.
82+
- `reset [height/hash]`: Reset chain to desired block.
83+
- `resend`: Resend pending transactions.
84+
- `backup [path]`: Backup the wallet db.
85+
- `wallet [command]`: Execute wallet command.
86+
- `rpc [command] [args]`: Execute RPC command.
87+
88+
### Wallet Commands
89+
90+
- `listen`: Listen for events.
91+
- `get`: View wallet.
92+
- `master`: View wallet master key.
93+
- `shared add [xpubkey]`: Add key to wallet.
94+
- `shared remove [xpubkey]`: Remove key from wallet.
95+
- `balance`: Get wallet balance.
96+
- `history`: View TX history.
97+
- `pending`: View pending TXs.
98+
- `coins`: View wallet coins.
99+
- `account list`: List account names.
100+
- `account create [account-name]`: Create account.
101+
- `account get [account-name]`: Get account details.
102+
- `address`: Derive new receiving address.
103+
- `change`: Derive new change address.
104+
- `nested`: Derive new nested address.
105+
- `retoken`: Create new api key.
106+
- `send [address] [value]`: Send transaction.
107+
- `mktx [address] [value]`: Create transaction.
108+
- `sign [tx-hex]`: Sign transaction.
109+
- `zap [age?]`: Zap pending wallet TXs.
110+
- `tx [hash]`: View transaction details.
111+
- `blocks`: List wallet blocks.
112+
- `block [height]`: View wallet block.
113+
- `view [tx-hex]`: Parse and view transaction.
114+
- `import [wif|hex]`: Import private or public key.
115+
- `watch [address]`: Import an address.
116+
- `key [address]`: Get wallet key by address.
117+
- `dump [address]`: Get wallet key WIF by address.
118+
- `lock`: Lock wallet.
119+
- `unlock [passphrase] [timeout?]`: Unlock wallet.
120+
- `resend`: Resend pending transactions.
121+
122+
### RPC Commands
123+
124+
Bcoin implements nearly all bitcoind calls along with some custom calls.
125+
126+
- `stop`
127+
- `help`
128+
- `getblockchaininfo`
129+
- `getbestblockhash`
130+
- `getblockcount`
131+
- `getblock`
132+
- `getblockhash`
133+
- `getblockheader`
134+
- `getchaintips`
135+
- `getdifficulty`
136+
- `getmempoolancestors`
137+
- `getmempooldescendants`
138+
- `getmempoolentry`
139+
- `getmempoolinfo`
140+
- `getrawmempool`
141+
- `gettxout`
142+
- `gettxoutsetinfo`
143+
- `verifychain`
144+
- `invalidateblock`
145+
- `reconsiderblock`
146+
- `getnetworkhashps`
147+
- `getmininginfo`
148+
- `prioritisetransaction`
149+
- `getwork`
150+
- `getworklp`
151+
- `getblocktemplate`
152+
- `submitblock`
153+
- `setgenerate`
154+
- `getgenerate`
155+
- `generate`
156+
- `generatetoaddress`
157+
- `estimatefee`
158+
- `estimatepriority`
159+
- `estimatesmartfee`
160+
- `estimatesmartpriority`
161+
- `getinfo`
162+
- `validateaddress`
163+
- `createmultisig`
164+
- `createwitnessaddress`
165+
- `verifymessage`
166+
- `signmessagewithprivkey`
167+
- `setmocktime`
168+
- `getconnectioncount`
169+
- `ping`
170+
- `getpeerinfo`
171+
- `addnode`
172+
- `disconnectnode`
173+
- `getaddednodeinfo`
174+
- `getnettotals`
175+
- `getnetworkinfo`
176+
- `setban`
177+
- `listbanned`
178+
- `clearbanned`
179+
- `getrawtransaction`
180+
- `createrawtransaction`
181+
- `decoderawtransaction`
182+
- `decodescript`
183+
- `sendrawtransaction`
184+
- `signrawtransaction`
185+
- `gettxoutproof`
186+
- `verifytxoutproof`
187+
- `fundrawtransaction`
188+
- `resendwallettransactions`
189+
- `abandontransaction`
190+
- `addmultisigaddress`
191+
- `addwitnessaddress`
192+
- `backupwallet`
193+
- `dumpprivkey`
194+
- `dumpwallet`
195+
- `encryptwallet`
196+
- `getaccountaddress`
197+
- `getaccount`
198+
- `getaddressesbyaccount`
199+
- `getbalance`
200+
- `getnewaddress`
201+
- `getrawchangeaddress`
202+
- `getreceivedbyaccount`
203+
- `getreceivedbyaddress`
204+
- `gettransaction`
205+
- `getunconfirmedbalance`
206+
- `getwalletinfo`
207+
- `importprivkey`
208+
- `importwallet`
209+
- `importaddress`
210+
- `importprunedfunds`
211+
- `importpubkey`
212+
- `keypoolrefill`
213+
- `listaccounts`
214+
- `listaddressgroupings`
215+
- `listlockunspent`
216+
- `listreceivedbyaccount`
217+
- `listreceivedbyaddress`
218+
- `listsinceblock`
219+
- `listtransactions`
220+
- `listunspent`
221+
- `lockunspent`
222+
- `move`
223+
- `sendfrom`
224+
- `sendmany`
225+
- `sendtoaddress`
226+
- `setaccount`
227+
- `settxfee`
228+
- `signmessage`
229+
- `walletlock`
230+
- `walletpassphrasechange`
231+
- `walletpassphrase`
232+
- `removeprunedfunds`
233+
- `getmemory`
234+
- `selectwallet`
235+
- `setloglevel`

0 commit comments

Comments
 (0)