LBRYCommunity/lbcd
1
0
Fork 0
Code Issues 17 Pull requests 4 Packages Projects Releases 28 Wiki Activity

Move all wiki docs into docs folder of the repo.

Browse source 
This allows the docs to be updated via pull requests and makes it easier
to keep it in sync as a part of normal code updates.
This commit is contained in:
Dave Collins 2015-01-18 11:16:43 -06:00
parent f9f4d37976
commit 8a50187bf1
9 changed files with 1944 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
README.md
View file

@ -103,7 +103,7 @@ is used for this project.
## Documentation ## Documentation
The documentation is a work-in-progress. It uses the [github wiki](https://github.com/btcsuite/btcd/wiki) facility. The documentation is a work-in-progress. It is located in the [docs](https://github.com/btcsuite/btcd/tree/master/docs) folder.
## GPG Verification Key ## GPG Verification Key

209
docs/README.md Normal file
View file

@ -0,0 +1,209 @@
### Table of Contents
1. [About](#About)
2. [Getting Started](#GettingStarted)
1. [Installation](#Installation)
1. [Windows](#WindowsInstallation)
2. [Linux/BSD/MacOSX/POSIX](#PosixInstallation)
2. [Configuration](#Configuration)
3. [Controlling and Querying btcd via btcctl](#BtcctlConfig)
4. [Mining](#Mining)
3. [Help](#Help)
1. [Startup](#Startup)
1. [Using bootstrap.dat](#BootstrapDat)
2. [Network Configuration](#NetworkConfig)
3. [Wallet](#Wallet)
4. [Contact](#Contact)
1. [IRC](#ContactIRC)
2. [Mailing Lists](#MailingLists)
5. [Developer Resources](#DeveloperResources)
1. [Code Contribution Guidelines](#ContributionGuidelines)
2. [JSON-RPC Reference](#JSONRPCReference)
3. [Conformal Bitcoin-related Go Packages](#GoPackages)
<a name="About" />
### 1. About
btcd is a full node bitcoin implementation written in [Go](http://golang.org),
licensed under the [copyfree](http://www.copyfree.org) ISC License.
This project is currently under active development and is in a Beta state. It is
extremely stable and has been in production use for over 6 months as of May
2014, however there are still a couple of major features we want to add before
we come out of beta.
It currently properly downloads, validates, and serves the block chain using the
exact rules (including bugs) for block acceptance as the reference
implementation, [bitcoind](https://github.com/bitcoin/bitcoin). We have taken
great care to avoid btcd causing a fork to the block chain. It passes all of
the '[official](https://github.com/TheBlueMatt/test-scripts/)' block acceptance
tests.
It also properly relays newly mined blocks, maintains a transaction pool, and
relays individual transactions that have not yet made it into a block. It
ensures all individual transactions admitted to the pool follow the rules
required into the block chain and also includes the vast majority of the more
strict checks which filter transactions based on miner requirements ("standard"
transactions).
One key difference between btcd and bitcoind is that btcd does NOT include
wallet functionality and this was a very intentional design decision. See the
[blog entry](https://blog.conformal.com/btcd-not-your-moms-bitcoin-daemon) for
more details. This means you can't actually make or receive payments directly
with btcd. That functionality is provided by the
[btcwallet](https://github.com/btcsuite/btcwallet) and
[btcgui](https://github.com/btcsuite/btcgui) projects which are both under
active development.
<a name="GettingStarted" />
### 2. Getting Started
<a name="Installation" />
**2.1 Installation**<br />
The first step is to install btcd. See one of the following sections for
details on how to install on the supported operating systems.
<a name="WindowsInstallation" />
**2.1.1 Windows Installation**<br />
* Install the MSI available at: https://github.com/btcsuite/btcd/releases
* Launch btcd from the Start Menu
<a name="PosixInstallation" />
**2.1.2 Linux/BSD/MacOSX/POSIX Installation**<br />
* Install Go according to the installation instructions here: http://golang.org/doc/install
* Run the following command to ensure your Go version is at least version 1.2: `$ go version`
* Run the following command to obtain btcd, its dependencies, and install it: `$ go get github.com/btcsuite/btcd/...`<br />
* To upgrade, run the following command: `$ go get -u github.com/btcsuite/btcd/...`
* Run btcd: `$ btcd`
<a name="Configuration" />
**2.2 Configuration**<br />
btcd has a number of [configuration](http://godoc.org/github.com/btcsuite/btcd)
options, which can be viewed by running: `$ btcd --help`.
<a name="BtcctlConfig" />
**2.3 Controlling and Querying btcd via btcctl**<br />
btcctl is a command line utility that can be used to both control and query btcd
via [RPC](http://www.wikipedia.org/wiki/Remote_procedure_call). btcd does
**not** enable its RPC server by default; You must configure at minimum both an
RPC username and password:
* btcd.conf configuration file
```
[Application Options]
rpcuser=myuser
rpcpass=SomeDecentp4ssw0rd
```
* btcctl.conf configuration file
```
[Application Options]
rpcuser=myuser
rpcpass=SomeDecentp4ssw0rd
```
For a list of available options, run: `$ btcctl --help`
<a name="Mining" />
**2.4 Mining**<br />
btcd supports both the `getwork` and `getblocktemplate` RPCs although the
`getwork` RPC is deprecated and will likely be removed in a future release.<br />
**1. Add the payment addresses with the `miningaddr` option.**<br />
```
[Application Options]
rpcuser=myuser
rpcpass=SomeDecentp4ssw0rd
miningaddr=12c6DSiU4Rq3P4ZxziKxzrL5LmMBrzjrJX
miningaddr=1M83ju3EChKYyysmM2FXtLNftbacagd8FR
```
**2. Add btcd's RPC TLS certificate to system Certificate Authority list.**<br />
`cgminer` uses [curl](http://curl.haxx.se/) to fetch data from the RPC server.
Since curl validates the certificate by default, we must install the `btcd` RPC
certificate into the default system Certificate Authority list.
**Ubuntu**<br />
1. Copy rpc.cert to /usr/share/ca-certificates: `# cp /home/user/.btcd/rpc.cert /usr/share/ca-certificates/btcd.crt`<br />
2. Add btcd.crt to /etc/ca-certificates.conf: `# echo btcd.crt >> /etc/ca-certificates.conf`<br />
3. Update the CA certificate list: `# update-ca-certificates`<br />
**3. Set your mining software url to use https.**<br />
`$ cgminer -o https://127.0.0.1:8334 -u rpcuser -p rpcpassword`
<a name="Help" />
### 3. Help
<a name="Startup" />
**3.1 Startup**<br />
Typically btcd will run and start downloading the block chain with no extra
configuration necessary, however, there is an optional method to use a
`bootstrap.dat` file that may speed up the initial block chain download process.
<a name="BootstrapDat" />
**3.1.1 bootstrap.dat**<br />
* [Using bootstrap.dat](https://github.com/btcsuite/btcd/tree/master/docs/using_bootstrap_dat.md)
<a name="NetworkConfig" />
**3.1.2 Network Configuration**<br />
* [What Ports Are Used by Default?](https://github.com/btcsuite/btcd/tree/master/docs/default_ports.md)
* [How To Listen on Specific Interfaces](https://github.com/btcsuite/btcd/tree/master/docs/configure_peer_server_listen_interfaces.md)
* [How To Configure RPC Server to Listen on Specific Interfaces](https://github.com/btcsuite/btcd/tree/master/docs/configure_rpc_server_listen_interfaces.md)
* [Configuring btcd with Tor](https://github.com/btcsuite/btcd/tree/master/docs/configuring_tor.md)
<a name="Wallet" />
**3.1 Wallet**<br />
btcd was intentionally developed without an integrated wallet for security
reasons. Please see [btcwallet](https://github.com/btcsuite/btcwallet) for more
information.
<a name="Contact" />
### 4. Contact
<a name="ContactIRC" />
**4.1 IRC**<br />
* [irc.conformal.com](irc://irc.conformal.com:+6697), port 6697, tls, channel #btcd
<a name="MailingLists" />
**4.2 Mailing Lists**<br />
* <a href="mailto:btcd+subscribe@opensource.conformal.com">btcd</a>: discussion
of btcd and its packages.
* <a href="mailto:btcd-commits+subscribe@opensource.conformal.com">btcd-commits</a>:
readonly mail-out of source code changes.
<a name="DeveloperResources" />
### 5. Developer Resources
<a name="ContributionGuidelines" />
* [Code Contribution Guidelines](https://github.com/btcsuite/btcd/tree/master/docs/code_contribution_guidelines.md)
<a name="JSONRPCReference" />
* [JSON-RPC Reference](https://github.com/btcsuite/btcd/tree/master/docs/json_rpc_api.md)
* [RPC Examples](https://github.com/btcsuite/btcd/tree/master/docs/json_rpc_api.md#ExampleCode)
<a name="GoPackages" />
* Conformal Bitcoin-related Go Packages:
* [btcrpcclient](https://github.com/btcsuite/btcrpcclient) - Implements a
robust and easy to use Websocket-enabled Bitcoin JSON-RPC client
* [btcjson](https://github.com/btcsuite/btcjson) - Provides an extensive API
for the underlying JSON-RPC command and return values
* [btcws](https://github.com/btcsuite/btcws) - Custom types for btcd
websocket extension commands (registers the extension commands with
[btcjson](https://github.com/btcsuite/btcjson))
* [btcwire](https://github.com/btcsuite/btcwire) - Implements the Bitcoin
wire protocol
* [btcchain](https://github.com/btcsuite/btcchain) - Implements Bitcoin
block handling and chain selection rules
* [btcscript](https://github.com/btcsuite/btcscript) - Implements the
Bitcoin transaction scripting language
* [btcec](https://github.com/btcsuite/btcec) - Implements support for the
elliptic curve cryptographic functions needed for the Bitcoin scripts
* [btcdb](https://github.com/btcsuite/btcdb) - Provides a database interface
for the Bitcoin block chain
* [btcutil](https://github.com/btcsuite/btcutil) - Provides Bitcoin-specific
convenience functions and types

287
docs/code_contribution_guidelines.md Normal file
View file

@ -0,0 +1,287 @@
### Table of Contents
1. [Overview](#Overview)<br />
2. [Minimum Recommended Skillset](#MinSkillset)<br />
3. [Required Reading](#ReqReading)<br />
4. [Development Practices](#DevelopmentPractices)<br />
4.1. [Share Early, Share Often](#ShareEarly)<br />
4.2. [Testing](#Testing)<br />
4.3. [Code Documentation and Commenting](#CodeDocumentation)<br />
5. [Code Approval Process](#CodeApproval)<br />
5.1 [Code Review](#CodeReview)<br />
5.2 [Rework Code (if needed)](#CodeRework)<br />
5.3 [Acceptance](#CodeAcceptance)<br />
6. [Contribution Standards](#Standards)<br />
6.1. [Contribution Checklist](#Checklist)<br />
6.2. [Licensing of Contributions](#Licensing)<br />
<a name="Overview" />
### 1. Overview
Developing cryptocurrencies is an exciting endeavor that touches a wide variety
of areas such as wire protocols, peer-to-peer networking, databases,
cryptography, language interpretation (transaction scripts), RPC, and
websockets. They also represent a radical shift to the current fiscal system
and as a result provide an opportunity to help reshape the entire financial
system. There are few projects that offer this level of diversity and impact
all in one code base.
However, as exciting as it is, one must keep in mind that cryptocurrencies
represent real money and introducing bugs and security vulnerabilities can have
far more dire consequences than in typical projects where having a small bug is
minimal by comparison. In the world of cryptocurrencies, even the smallest bug
in the wrong area can cost people a significant amount of money. For this
reason, the btcd suite has a formalized and rigorous development process which
is outlined on this page.
We highly encourage code contributions, however it is imperative that you adhere
to the guidelines established on this page.
<a name="MinSkillset" />
### 2. Minimum Recommended Skillset
The following list is a set of core competencies that we recommend you possess
before you really start attempting to contribute code to the project. These are
not hard requirements as we will gladly accept code contributions as long as
they follow the guidelines set forth on this page. That said, if you don't have
the following basic qualifications you will likely find it quite difficult to
contribute.
- A reasonable understanding of bitcoin at a high level (see the
[Required Reading](#ReqReading) section for the original white paper)
- Experience in some type of C-like language
- An understanding of data structures and their performance implications
- Familiarity with unit testing
- Debugging experience
- Ability to understand not only the area you are making a change in, but also
the code your change relies on, and the code which relies on your changed code
Building on top of those core competencies, the recommended skill set largely
depends on the specific areas you are looking to contribute to. For example,
if you wish to contribute to the cryptography code, you should have a good
understanding of the various aspects involved with cryptography such as the
security and performance implications.
<a name="ReqReading" />
### 3. Required Reading
- [Effective Go](http://golang.org/doc/effective_go.html) - The entire btcd
suite follows the guidelines in this document. For your code to be accepted,
it must follow the guidelinestherein.
- [Original Satoshi Whitepaper](http://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=1&cad=rja&ved=0CCkQFjAA&url=http%3A%2F%2Fbitcoin.org%2Fbitcoin.pdf&ei=os3VUuH8G4SlsASV74GoAg&usg=AFQjCNEipPLigou_1MfB7DQjXCNdlylrBg&sig2=FaHDuT5z36GMWDEnybDJLg&bvm=bv.59378465,d.b2I) - This is the white paper that started it all. Having a solid
foundation to build on will make the code much more comprehensible.
<a name="DevelopmentPractices" />
### 4. Development Practices
Developers are expected to work in their own trees and submit pull requests when
they feel their feature or bug fix is ready for integration into the master
branch.
<a name="ShareEarly" />
### 4.1 Share Early, Share Often
We firmly believe in the share early, share often approach. The basic premise
of the approach is to announce your plans **before** you start work, and once
you have started working, craft your changes into a stream of small and easily
reviewable commits.
This approach has several benefits:
- Announcing your plans to work on a feature **before** you begin work avoids
duplicate work
- It permits discussions which can help you achieve your goals in a way that is
consistent with the existing architecture
- It minimizes the chances of you spending time and energy on a change that
might not fit with the consensus of the community or existing architecture and
potentially be rejected as a result
- Incremental development helps ensure you are on the right track with regards
to the rest of the community
- The quicker your changes are merged to master, the less time you will need to
spend rebasing and otherwise trying to keep up with the main code base
<a name="Testing" />
### 4.2 Testing
One of the major design goals of all core btcd packages is to aim for complete
test coverage. This is financial software so bugs and regressions can cost
people real money. For this reason every effort must be taken to ensure the
code is as accurate and bug-free as possible. Thorough testing is a good way to
help achieve that goal.
Unless a new feature you submit is completely trivial, it will probably be
rejected unless it is also accompanied by adequate test coverage for both
positive and negative conditions. That is to say, the tests must ensure your
code works correctly when it is fed correct data as well as incorrect data
(error paths).
Go provides an excellent test framework that makes writing test code and
checking coverage statistics straight forward. For more information about the
test coverage tools, see the [golang cover blog post](http://blog.golang.org/cover).
A quick summary of test practices follows:
- All new code should be accompanied by tests that ensure the code behaves
correctly when given expected values, and, perhaps even more importantly, that
it handles errors gracefully
- When you fix a bug, it should be accompanied by tests which exercise the bug
to both prove it has been resolved and to prevent future regressions
<a name="CodeDocumentation" />
### 4.3 Code Documentation and Commenting
- At a minimum every function must be commented with its intended purpose and
any assumptions that it makes
- Function comments must always begin with the name of the function per
[Effective Go](http://golang.org/doc/effective_go.html)
- Function comments should be complete sentences since they allow a wide
variety of automated presentations such as [godoc.org](https://godoc.org)
- The general rule of thumb is to look at it as if you were completely
unfamiliar with the code and ask yourself, would this give me enough
information to understand what this function does and how I'd probably want
to use it?
- Exported functions should also include detailed information the caller of the
function will likely need to know and/or understand:<br /><br />
**WRONG**
```Go
// convert a compact uint32 to big.Int
func CompactToBig(compact uint32) *big.Int {
```
**RIGHT**
```Go
// CompactToBig converts a compact representation of a whole number N to a
// big integer. The representation is similar to IEEE754 floating point
// numbers.
//
// Like IEEE754 floating point, there are three basic components: the sign,
// the exponent, and the mantissa. They are broken out as follows:
//
// * the most significant 8 bits represent the unsigned base 256 exponent
// * bit 23 (the 24th bit) represents the sign bit
// * the least significant 23 bits represent the mantissa
//
// -------------------------------------------------
// | Exponent | Sign | Mantissa |
// -------------------------------------------------
// | 8 bits [31-24] | 1 bit [23] | 23 bits [22-00] |
// -------------------------------------------------
//
// The formula to calculate N is:
// N = (-1^sign) * mantissa * 256^(exponent-3)
//
// This compact form is only used in bitcoin to encode unsigned 256-bit numbers
// which represent difficulty targets, thus there really is not a need for a
// sign bit, but it is implemented here to stay consistent with bitcoind.
func CompactToBig(compact uint32) *big.Int {
```
- Comments in the body of the code are highly encouraged, but they should
explain the intention of the code as opposed to just calling out the
obvious<br /><br />
**WRONG**
```Go
// return err if amt is less than 5460
if amt < 5460 {
return err
}
```
**RIGHT**
```Go
// Treat transactions with amounts less than the amount which is considered dust
// as non-standard.
if amt < 5460 {
return err
}
```
**NOTE:** The above should really use a constant as opposed to a magic number,
but it was left as a magic number to show how much of a difference a good
comment can make.
<a name="CodeApproval" />
### 5. Code Approval Process
This section describes the code approval process that is used for code
contributions. This is how to get your changes into btcd.
<a name="CodeReview" />
### 5.1 Code Review
All code which is submitted will need to be reviewed before inclusion into the
master branch. This process is performed by the project maintainers and usually
other committers who are interested in the area you are working in as well.
##### Code Review Timeframe
The timeframe for a code review will vary greatly depending on factors such as
the number of other pull requests which need to be reviewed, the size and
complexity of the contribution, how well you followed the guidelines presented
on this page, and how easy it is for the reviewers to digest your commits. For
example, if you make one monolithic commit that makes sweeping changes to things
in multiple subsystems, it will obviously take much longer to review. You will
also likely be asked to split the commit into several smaller, and hence more
manageable, commits.
Keeping the above in mind, most small changes will be reviewed within a few
days, while large or far reaching changes may take weeks. This is a good reason
to stick with the [Share Early, Share Often](#ShareOften) development practice
outlined above.
##### What is the review looking for?
The review is mainly ensuring the code follows the [Development Practices](#DevelopmentPractices)
and [Code Contribution Standards](#Standards). However, there are a few other
checks which are generally performed as follows:
- The code is stable and has no stability or security concerns
- The code is properly using existing APIs and generally fits well into the
overall architecture
- The change is not something which is deemed inappropriate by community
consensus
<a name="CodeRework" />
### 5.2 Rework Code (if needed)
After the code review, the change will be accepted immediately if no issues are
found. If there are any concerns or questions, you will be provided with
feedback along with the next steps needed to get your contribution merged with
master. In certain cases the code reviewer(s) or interested committers may help
you rework the code, but generally you will simply be given feedback for you to
make the necessary changes.
This process will continue until the code is finally accepted.
<a name="CodeAcceptance" />
### 5.3 Acceptance
Once your code is accepted, it will be integrated with the master branch.
Typically it will be rebased and fast-forward merged to master as we prefer to
keep a clean commit history over a tangled weave of merge commits. However,
regardless of the specific merge method used, the code will be integrated with
the master branch and the pull request will be closed.
Rejoice as you will now be listed as a [contributor](https://github.com/btcsuite/btcd/graphs/contributors)!
<a name="Standards" />
### 6. Contribution Standards
<a name="Checklist" />
### 6.1. Contribution Checklist
- [&nbsp;&nbsp;] All changes are Go version 1.3 compliant
- [&nbsp;&nbsp;] The code being submitted is commented according to the
[Code Documentation and Commenting](#CodeDocumentation) section
- [&nbsp;&nbsp;] For new code: Code is accompanied by tests which exercise both
the positive and negative (error paths) conditions (if applicable)
- [&nbsp;&nbsp;] For bug fixes: Code is accompanied by new tests which trigger
the bug being fixed to prevent regressions
- [&nbsp;&nbsp;] Any new logging statements use an appropriate subsystem and
logging level
- [&nbsp;&nbsp;] Code has been formatted with `go fmt`
- [&nbsp;&nbsp;] Running `go test` does not fail any tests
- [&nbsp;&nbsp;] Running `go vet` does not report any issues
- [&nbsp;&nbsp;] Running [golint](https://github.com/golang/lint) does not
report any **new** issues that did not already exist
<a name="Licensing" />
### 6.2. Licensing of Contributions
****
All contributions must be licensed with the
[ISC license](https://github.com/btcsuite/btcd/blob/master/LICENSE). This is
the same license as all of the code in the btcd suite.

35
docs/configure_peer_server_listen_interfaces.md Normal file
View file

@ -0,0 +1,35 @@
btcd allows you to bind to specific interfaces which enables you to setup
configurations with varying levels of complexity. The listen parameter can be
specified on the command line as shown below with the -- prefix or in the
configuration file without the -- prefix (as can all long command line options).
The configuration file takes one entry per line.
**NOTE:** The listen flag can be specified multiple times to listen on multiple
interfaces as a couple of the examples below illustrate.
Command Line Examples:
|Flags|Comment|
|----------|------------|
|--listen=|all interfaces on default port which is changed by `--testnet` and `--regtest` (**default**)|
|--listen=0.0.0.0|all IPv4 interfaces on default port which is changed by `--testnet` and `--regtest`|
|--listen=::|all IPv6 interfaces on default port which is changed by `--testnet` and `--regtest`|
|--listen=:8333|all interfaces on port 8333|
|--listen=0.0.0.0:8333|all IPv4 interfaces on port 8333|
|--listen=[::]:8333|all IPv6 interfaces on port 8333|
|--listen=127.0.0.1:8333|only IPv4 localhost on port 8333|
|--listen=[::1]:8333|only IPv6 localhost on port 8333|
|--listen=:8336|all interfaces on non-standard port 8336|
|--listen=0.0.0.0:8336|all IPv4 interfaces on non-standard port 8336|
|--listen=[::]:8336|all IPv6 interfaces on non-standard port 8336|
|--listen=127.0.0.1:8337 --listen=[::1]:8333|IPv4 localhost on port 8337 and IPv6 localhost on port 8333|
|--listen=:8333 --listen=:8337|all interfaces on ports 8333 and 8337|
The following config file would configure btcd to only listen on localhost for both IPv4 and IPv6:
```text
[Application Options]
listen=127.0.0.1:8333
listen=[::1]:8333
```

46
docs/configure_rpc_server_listen_interfaces.md Normal file
View file

@ -0,0 +1,46 @@
btcd allows you to bind the RPC server to specific interfaces which enables you
to setup configurations with varying levels of complexity. The `rpclisten`
parameter can be specified on the command line as shown below with the -- prefix
or in the configuration file without the -- prefix (as can all long command line
options). The configuration file takes one entry per line.
A few things to note regarding the RPC server:
* The RPC server will **not** be enabled unless the `rpcuser` and `rpcpass`
options are specified.
* When the `rpcuser` and `rpcpass` options are specified, the RPC server will
only listen on localhost IPv4 and IPv6 interfaces by default. You will need
to override the RPC listen interfaces to include external interfaces if you
want to connect from a remote machine.
* The RPC server has TLS enabled by default, even for localhost. You may use
the `--notls` option to disable it, but only when all listeners are on
localhost interfaces.
* The `--rpclisten` flag can be specified multiple times to listen on multiple
interfaces as a couple of the examples below illustrate.
* The RPC server is disabled by default when using the `--regtest` and
`--simnet` networks. You can override this by specifying listen interfaces.
Command Line Examples:
|Flags|Comment|
|----------|------------|
|--rpclisten=|all interfaces on default port which is changed by `--testnet`|
|--rpclisten=0.0.0.0|all IPv4 interfaces on default port which is changed by `--testnet`|
|--rpclisten=::|all IPv6 interfaces on default port which is changed by `--testnet`|
|--rpclisten=:8334|all interfaces on port 8334|
|--rpclisten=0.0.0.0:8334|all IPv4 interfaces on port 8334|
|--rpclisten=[::]:8334|all IPv6 interfaces on port 8334|
|--rpclisten=127.0.0.1:8334|only IPv4 localhost on port 8334|
|--rpclisten=[::1]:8334|only IPv6 localhost on port 8334|
|--rpclisten=:8336|all interfaces on non-standard port 8336|
|--rpclisten=0.0.0.0:8336|all IPv4 interfaces on non-standard port 8336|
|--rpclisten=[::]:8336|all IPv6 interfaces on non-standard port 8336|
|--rpclisten=127.0.0.1:8337 --listen=[::1]:8334|IPv4 localhost on port 8337 and IPv6 localhost on port 8334|
|--rpclisten=:8334 --listen=:8337|all interfaces on ports 8334 and 8337|
The following config file would configure the btcd RPC server to listen to all interfaces on the default port, including external interfaces, for both IPv4 and IPv6:
```text
[Application Options]
rpclisten=
```

156
docs/configuring_tor.md Normal file
View file

@ -0,0 +1,156 @@
### Table of Contents
1. [Overview](#Overview)<br />
2. [Client-Only](#Client)<br />
2.1 [Description](#ClientDescription)<br />
2.2 [Command Line Example](#ClientCLIExample)<br />
2.3 [Config File Example](#ClientConfigFileExample)<br />
3. [Client-Server via Tor Hidden Service](#HiddenService)<br />
3.1 [Description](#HiddenServiceDescription)<br />
3.2 [Command Line Example](#HiddenServiceCLIExample)<br />
3.3 [Config File Example](#HiddenServiceConfigFileExample)<br />
4. [Bridge Mode (Not Anonymous)](#Bridge)<br />
4.1 [Description](#BridgeDescription)<br />
4.2 [Command Line Example](#BridgeCLIExample)<br />
4.3 [Config File Example](#BridgeConfigFileExample)<br />
<a name="Overview" />
### 1. Overview
btcd provides full support for anonymous networking via the
[Tor Project](https://www.torproject.org/), including [client-only](#Client)
and [hidden service](#HiddenService) configurations. In addition, btcd supports
a hybrid, [bridge mode](#Bridge) which is not anonymous, but allows it to
operate as a bridge between regular nodes and hidden service nodes without
routing the regular connections through Tor.
While it is easier to only run as a client, it is more beneficial to the Bitcoin
network to run as both a client and a server so others may connect to you to as
you are connecting to them. We recommend you take the time to setup a Tor
hidden service for this reason.
<a name="Client" />
### 2. Client-Only
<a name="ClientDescription" />
**2.1 Description**<br />
Configuring btcd as a Tor client is straightforward. The first step is
obviously to install Tor and ensure it is working. Once that is done, all that
typically needs to be done is to specify the `--proxy` flag via the btcd command
line or in the btcd configuration file. Typically the Tor proxy address will be
127.0.0.1:9050 (if using standalone Tor) or 127.0.0.1:9150 (if using the Tor
Browser Bundle). If you have Tor configured to require a username and password,
you may specify them with the `--proxyuser` and `--proxypass` flags.
By default, btcd assumes the proxy specified with `--proxy` is a Tor proxy and
hence will send all traffic, including DNS resolution requests, via the
specified proxy.
NOTE: Specifying the `--proxy` flag disables listening by default since you will
not be reachable for inbound connections unless you also configure a Tor
[hidden service](#HiddenService).
<a name="ClientCLIExample" />
**2.2 Command Line Example**<br />
```bash
$ ./btcd --proxy=127.0.0.1:9050
```
<a name="ClientConfigFileExample" />
**2.3 Config File Example**<br />
```text
[Application Options]
proxy=127.0.0.1:9050
```
<a name="HiddenService" />
### 3. Client-Server via Tor Hidden Service
<a name="HiddenServiceDescription" />
**3.1 Description**<br />
The first step is to configure Tor to provide a hidden service. Documentation
for this can be found on the Tor project website
[here](https://www.torproject.org/docs/tor-hidden-service.html.en). However,
there is no need to install a web server locally as the linked instructions
discuss since btcd will act as the server.
In short, the instructions linked above entail modifying your `torrc` file to
add something similar to the following, restarting Tor, and opening the
`hostname` file in the `HiddenServiceDir` to obtain your hidden service .onion
address.
```text
HiddenServiceDir /var/tor/btcd
HiddenServicePort 8333 127.0.0.1:8333
```
Once Tor is configured to provide the hidden service and you have obtained your
generated .onion address, configuring btcd as a Tor hidden service requires
three flags:
* `--proxy` to identify the Tor (SOCKS 5) proxy to use for outgoing traffic.
This is typically 127.0.0.1:9050.
* `--listen` to enable listening for inbound connections since `--proxy`
disables listening by default
* `--externalip` to set the .onion address that is advertised to other peers
<a name="HiddenServiceCLIExample" />
**3.2 Command Line Example**<br />
```bash
$ ./btcd --proxy=127.0.0.1:9050 --listen=127.0.0.1 --externalip=fooanon.onion
```
<a name="HiddenServiceConfigFileExample" />
**3.3 Config File Example**<br />
```text
[Application Options]
proxy=127.0.0.1:9050
listen=127.0.0.1
externalip=fooanon.onion
```
<a name="Bridge" />
### 4. Bridge Mode (Not Anonymous)
<a name="BridgeDescription" />
**4.1 Description**<br />
btcd provides support for operating as a bridge between regular nodes and hidden
service nodes. In particular this means only traffic which is directed to or
from a .onion address is sent through Tor while other traffic is sent normally.
_As a result, this mode is **NOT** anonymous._
This mode works by specifying an onion-specific proxy, which is pointed at Tor,
by using the `--onion` flag via the btcd command line or in the btcd
configuration file. If you have Tor configured to require a username and
password, you may specify them with the `--onionuser` and `--onionpass` flags.
NOTE: This mode will also work in conjunction with a hidden service which means
you could accept inbound connections both via the normal network and to your
hidden service through the Tor network. To enable your hidden service in bridge
mode, you only need to specify your hidden service's .onion address via the
`--externalip` flag since traffic to and from .onion addresses are already
routed via Tor due to the `--onion` flag.
<a name="BridgeCLIExample" />
**4.2 Command Line Example**<br />
```bash
$ ./btcd --onion=127.0.0.1:9050 --externalip=fooanon.onion
```
<a name="BridgeConfigFileExample" />
**4.3 Config File Example**<br />
```text
[Application Options]
onion=127.0.0.1:9050
externalip=fooanon.onion
```

15
docs/default_ports.md Normal file
View file

@ -0,0 +1,15 @@
While btcd is highly configurable when it comes to the network configuration,
the following is intended to be a quick reference for the default ports used so
port forwarding can be configured as required.
btcd provides a `--upnp` flag which can be used to automatically map the bitcoin
peer-to-peer listening port if your router supports UPnP. If your router does
not support UPnP, or you don't wish to use it, please note that only the bitcoin
peer-to-peer port should be forwarded unless you specifically want to allow RPC
access to your btcd from external sources such as in more advanced network
configurations.
|Name|Port|
|----|----|
|Default Bitcoin peer-to-peer port|TCP 8333|
|Default RPC port|TCP 8334|

1121
docs/json_rpc_api.md Normal file
View file

File diff suppressed because it is too large Load diff

74
docs/using_bootrap_dat.md Normal file
View file

@ -0,0 +1,74 @@
### Table of Contents
1. [What is bootstrap.dat?](#What)<br />
2. [What are the pros and cons of using bootstrap.dat?](#ProsCons)
3. [Where do I get bootstrap.dat?](#Obtaining)
4. [How do I know I can trust the bootstrap.dat I downloaded?](#Trust)
5. [How do I use bootstrap.dat with btcd?](#Importing)
<a name="What" />
### 1. What is bootstrap.dat?
It is a flat, binary file containing bitcoin blockchain data starting from the
genesis block and continuing through a relatively recent block height depending
on the last time it was updated.
See [this](https://bitcointalk.org/index.php?topic=145386.0) thread on
bitcointalk for more details.
**NOTE:** Using bootstrap.dat is entirely optional. Btcd will download the
block chain from other peers through the Bitcoin protocol with no extra
configuration needed.
<a name="ProsCons" />
### 2. What are the pros and cons of using bootstrap.dat?
Pros:
- Typically accelerates the initial process of bringing up a new node as it
downloads from public P2P nodes and generally is able to achieve faster
download speeds
- It is particularly beneficial when bringing up multiple nodes as you only need
to download the data once
Cons:
- Requires you to setup and configure a torrent client if you don't already have
one available
- Requires roughly twice as much disk space since you'll need the flat file as
well as the imported database
<a name="Obtaining" />
### 3. Where do I get bootstrap.dat?
The bootstrap.dat file is made available via a torrent. See
[this](https://bitcointalk.org/index.php?topic=145386.0) thread on bitcointalk
for the torrent download details.
<a name="Trust" />
### 4. How do I know I can trust the bootstrap.dat I downloaded?
You don't need to trust the file as the `addblock` utility verifies every block
using the same rules that are used when downloading the block chain normally
through the Bitcoin protocol. Additionally, the chain rules contain hard-coded
checkpoints for the known-good block chain at periodic intervals. This ensures
that not only is it a valid chain, but it is the same chain that everyone else
is using.
<a name="Importing" />
### 5. How do I use bootstrap.dat with btcd?
btcd comes with a separate utility named `addblock` which can be used to import
`bootstrap.dat`. This approach is used since the import is a one-time operation
and we prefer to keep the daemon itself as lightweight as possible.
1. Stop btcd if it is already running. This is required since addblock needs to
access the database used by btcd and it will be locked if btcd is using it.
2. Note the path to the downloaded bootstrap.dat file.
3. Run the addblock utility with the `-i` argument pointing to the location of
boostrap.dat:<br /><br />
**Windows:**
```bat
C:\> "%PROGRAMFILES%\Btcd Suite\Btcd\addblock" -i C:\Path\To\bootstrap.dat
```
**Linux/Unix/BSD/POSIX:**
```bash
$ $GOPATH/bin/addblock -i /path/to/bootstrap.dat
```