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

Major rework on documentation to make it compatible to readthedocs.org

Browse source
This commit is contained in:
Christian Lehmann 2019-09-09 17:24:56 +02:00 • committed by Jake Sylvestre
parent 35194e2dac
commit 355472b0f7
24 changed files with 655 additions and 640 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
README.md
View file

@ -26,7 +26,7 @@ transactions based on miner requirements ("standard" transactions).
One key difference between btcd and Bitcoin Core is that btcd does *NOT* include One key difference between btcd and Bitcoin Core is that btcd does *NOT* include
wallet functionality and this was a very intentional design decision. See the wallet functionality and this was a very intentional design decision. See the
blog entry [here](https://blog.conformal.com/btcd-not-your-moms-bitcoin-daemon) blog entry [here](https://web.archive.org/web/20171125143919/https://blog.conformal.com/btcd-not-your-moms-bitcoin-daemon)
for more details. This means you can't actually make or receive payments for more details. This means you can't actually make or receive payments
directly with btcd. That functionality is provided by the directly with btcd. That functionality is provided by the
[btcwallet](https://github.com/btcsuite/btcwallet) and [btcwallet](https://github.com/btcsuite/btcwallet) and

1
docs/.gitignore vendored Normal file
View file

@ -0,0 +1 @@
/_build

20
docs/Makefile Normal file
View file

@ -0,0 +1,20 @@
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = .
BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

305
docs/README.md
View file

@ -1,305 +0,0 @@
### Table of Contents
1. [About](#About)
2. [Getting Started](#GettingStarted)
1. [Installation](#Installation)
1. [Windows](#WindowsInstallation)
2. [Linux/BSD/MacOSX/POSIX](#PosixInstallation)
1. [Gentoo Linux](#GentooInstallation)
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. [The btcsuite Bitcoin-related Go Packages](#GoPackages)
6. [Using Docker](#Docker)
<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 since October 2013.
It properly downloads, validates, and serves the block chain using the exact
rules (including consensus bugs) for block acceptance as Bitcoin Core. We have
taken great care to avoid btcd causing a fork to the block chain. It includes a
full block validation testing framework which contains all of the 'official'
block acceptance tests (and some additional ones) that is run on every pull
request to help ensure it properly follows consensus. Also, it passes all of
the JSON test data in the Bitcoin Core code.
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 by the block chain and also includes more strict checks which filter
transactions based on miner requirements ("standard" transactions).
One key difference between btcd and Bitcoin Core is that btcd does *NOT* include
wallet functionality and this was a very intentional design decision. See the
blog entry [here](https://web.archive.org/web/20171125143919/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
[Paymetheus](https://github.com/btcsuite/Paymetheus) (Windows-only) projects
which are both under active development.
<a name="GettingStarted" />
### 2. Getting Started
<a name="Installation" />
**2.1 Installation**
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**
- Install Go according to the installation instructions here:
http://golang.org/doc/install
- Ensure Go was installed properly and is a supported version:
```bash
$ go version
$ go env GOROOT GOPATH
```
NOTE: The `GOROOT` and `GOPATH` above must not be the same path. It is
recommended that `GOPATH` is set to a directory in your home directory such as
`~/goprojects` to avoid write permission issues. It is also recommended to add
`$GOPATH/bin` to your `PATH` at this point.
- Run the following commands to obtain btcd, all dependencies, and install it:
```bash
$ git clone https://github.com/btcsuite/btcd $GOPATH/src/github.com/btcsuite/btcd
$ cd $GOPATH/src/github.com/btcsuite/btcd
$ GO111MODULE=on go install -v . ./cmd/...
```
- btcd (and utilities) will now be installed in ```$GOPATH/bin```. If you did
not already add the bin directory to your system path during Go installation,
we recommend you do so now.
**Updating**
- Run the following commands to update btcd, all dependencies, and install it:
```bash
$ cd $GOPATH/src/github.com/btcsuite/btcd
$ git pull && GO111MODULE=on go install -v . ./cmd/...
```
<a name="GentooInstallation" />
**2.1.2.1 Gentoo Linux Installation**
* Install Layman and enable the Bitcoin overlay.
* https://gitlab.com/bitcoin/gentoo
* Copy or symlink `/var/lib/layman/bitcoin/Documentation/package.keywords/btcd-live` to `/etc/portage/package.keywords/`
* Install btcd: `$ emerge net-p2p/btcd`
<a name="Configuration" />
**2.2 Configuration**
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**
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 or both an RPC limited username and password:
* btcd.conf configuration file
```
[Application Options]
rpcuser=myuser
rpcpass=SomeDecentp4ssw0rd
rpclimituser=mylimituser
rpclimitpass=Limitedp4ssw0rd
```
* btcctl.conf configuration file
```
[Application Options]
rpcuser=myuser
rpcpass=SomeDecentp4ssw0rd
```
OR
```
[Application Options]
rpclimituser=mylimituser
rpclimitpass=Limitedp4ssw0rd
```
For a list of available options, run: `$ btcctl --help`
<a name="Mining" />
**2.4 Mining**
btcd supports the `getblocktemplate` RPC.
The limited user cannot access this RPC.
**1. Add the payment addresses with the `miningaddr` option.**
```
[Application Options]
rpcuser=myuser
rpcpass=SomeDecentp4ssw0rd
miningaddr=12c6DSiU4Rq3P4ZxziKxzrL5LmMBrzjrJX
miningaddr=1M83ju3EChKYyysmM2FXtLNftbacagd8FR
```
**2. Add btcd's RPC TLS certificate to system Certificate Authority list.**
`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**
1. Copy rpc.cert to /usr/share/ca-certificates: `# cp /home/user/.btcd/rpc.cert /usr/share/ca-certificates/btcd.crt`
2. Add btcd.crt to /etc/ca-certificates.conf: `# echo btcd.crt >> /etc/ca-certificates.conf`
3. Update the CA certificate list: `# update-ca-certificates`
**3. Set your mining software url to use https.**
`$ cgminer -o https://127.0.0.1:8334 -u rpcuser -p rpcpassword`
<a name="Help" />
### 3. Help
<a name="Startup" />
**3.1 Startup**
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**
* [Using bootstrap.dat](https://github.com/btcsuite/btcd/tree/master/docs/using_bootstrap_dat.md)
<a name="NetworkConfig" />
**3.1.2 Network Configuration**
* [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**
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**
* [irc.freenode.net](irc://irc.freenode.net), channel `#btcd`
<a name="MailingLists" />
**4.2 Mailing Lists**
* <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" />
* The btcsuite Bitcoin-related Go Packages:
* [btcrpcclient](https://github.com/btcsuite/btcd/tree/master/rpcclient) - Implements a
robust and easy to use Websocket-enabled Bitcoin JSON-RPC client
* [btcjson](https://github.com/btcsuite/btcd/tree/master/btcjson) - Provides an extensive API
for the underlying JSON-RPC command and return values
* [wire](https://github.com/btcsuite/btcd/tree/master/wire) - Implements the
Bitcoin wire protocol
* [peer](https://github.com/btcsuite/btcd/tree/master/peer) -
Provides a common base for creating and managing Bitcoin network peers.
* [blockchain](https://github.com/btcsuite/btcd/tree/master/blockchain) -
Implements Bitcoin block handling and chain selection rules
* [blockchain/fullblocktests](https://github.com/btcsuite/btcd/tree/master/blockchain/fullblocktests) -
Provides a set of block tests for testing the consensus validation rules
* [txscript](https://github.com/btcsuite/btcd/tree/master/txscript) -
Implements the Bitcoin transaction scripting language
* [btcec](https://github.com/btcsuite/btcd/tree/master/btcec) - Implements
support for the elliptic curve cryptographic functions needed for the
Bitcoin scripts
* [database](https://github.com/btcsuite/btcd/tree/master/database) -
Provides a database interface for the Bitcoin block chain
* [mempool](https://github.com/btcsuite/btcd/tree/master/mempool) -
Package mempool provides a policy-enforced pool of unmined bitcoin
transactions.
* [btcutil](https://github.com/btcsuite/btcutil) - Provides Bitcoin-specific
convenience functions and types
* [chainhash](https://github.com/btcsuite/btcd/tree/master/chaincfg/chainhash) -
Provides a generic hash type and associated functions that allows the
specific hash algorithm to be abstracted.
* [connmgr](https://github.com/btcsuite/btcd/tree/master/connmgr) -
Package connmgr implements a generic Bitcoin network connection manager.
<a name="Docker" />
### 6. Using Docker
You can run btcd in a Docker container, without the need to compile the source by yourself. Visit the [Using Docker](https://github.com/btcsuite/btcd/tree/master/docs/using_docker.md) page for more inrormation and examples.
* [Using Docker](https://github.com/btcsuite/btcd/tree/master/docs/using_docker.md) details page

106
docs/code_contribution_guidelines.md
View file

@ -1,23 +1,4 @@
### Table of Contents # Code contribution guidelines
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 />
4.4. [Model Git Commit Messages](#ModelGitCommitMessages)<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 Developing cryptocurrencies is an exciting endeavor that touches a wide variety
of areas such as wire protocols, peer-to-peer networking, databases, of areas such as wire protocols, peer-to-peer networking, databases,
@ -38,9 +19,7 @@ is outlined on this page.
We highly encourage code contributions, however it is imperative that you adhere We highly encourage code contributions, however it is imperative that you adhere
to the guidelines established on this page. to the guidelines established on this page.
<a name="MinSkillset" /> ## Minimum Recommended Skillset
### 2. Minimum Recommended Skillset
The following list is a set of core competencies that we recommend you possess 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 before you really start attempting to contribute code to the project. These are
@ -64,9 +43,7 @@ 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 understanding of the various aspects involved with cryptography such as the
security and performance implications. security and performance implications.
<a name="ReqReading" /> ## Required Reading
### 3. Required Reading
- [Effective Go](http://golang.org/doc/effective_go.html) - The entire btcd - [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, suite follows the guidelines in this document. For your code to be accepted,
@ -74,17 +51,13 @@ security and performance implications.
- [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 - [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. foundation to build on will make the code much more comprehensible.
<a name="DevelopmentPractices" /> ## Development Practices
### 4. Development Practices
Developers are expected to work in their own trees and submit pull requests when 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 they feel their feature or bug fix is ready for integration into the master
branch. branch.
<a name="ShareEarly" /> ## Share Early, Share Often
### 4.1 Share Early, Share Often
We firmly believe in the share early, share often approach. The basic premise 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 of the approach is to announce your plans **before** you start work, and once
@ -105,9 +78,7 @@ This approach has several benefits:
- The quicker your changes are merged to master, the less time you will need to - 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 spend rebasing and otherwise trying to keep up with the main code base
<a name="Testing" /> ## Testing
### 4.2 Testing
One of the major design goals of all core btcd packages is to aim for complete 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 test coverage. This is financial software so bugs and regressions can cost
@ -126,15 +97,14 @@ checking coverage statistics straight forward. For more information about the
test coverage tools, see the [golang cover blog post](http://blog.golang.org/cover). test coverage tools, see the [golang cover blog post](http://blog.golang.org/cover).
A quick summary of test practices follows: A quick summary of test practices follows:
- All new code should be accompanied by tests that ensure the code behaves - All new code should be accompanied by tests that ensure the code behaves
correctly when given expected values, and, perhaps even more importantly, that correctly when given expected values, and, perhaps even more importantly, that
it handles errors gracefully it handles errors gracefully
- When you fix a bug, it should be accompanied by tests which exercise the bug - 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 to both prove it has been resolved and to prevent future regressions
<a name="CodeDocumentation" /> ## Code Documentation and Commenting
### 4.3 Code Documentation and Commenting
- At a minimum every function must be commented with its intended purpose and - At a minimum every function must be commented with its intended purpose and
any assumptions that it makes any assumptions that it makes
@ -144,16 +114,20 @@ A quick summary of test practices follows:
variety of automated presentations such as [godoc.org](https://godoc.org) 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 - 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 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 information to understand what this function does and how I'd probably want
to use it? to use it?
- Exported functions should also include detailed information the caller of the - Exported functions should also include detailed information the caller of the
function will likely need to know and/or understand:<br /><br /> function will likely need to know and/or understand:
**WRONG** **WRONG**
```Go ```Go
// convert a compact uint32 to big.Int // convert a compact uint32 to big.Int
func CompactToBig(compact uint32) *big.Int { func CompactToBig(compact uint32) *big.Int {
``` ```
**RIGHT** **RIGHT**
```Go ```Go
// CompactToBig converts a compact representation of a whole number N to a // CompactToBig converts a compact representation of a whole number N to a
// big integer. The representation is similar to IEEE754 floating point // big integer. The representation is similar to IEEE754 floating point
@ -180,31 +154,35 @@ func CompactToBig(compact uint32) *big.Int {
// sign bit, but it is implemented here to stay consistent with bitcoind. // sign bit, but it is implemented here to stay consistent with bitcoind.
func CompactToBig(compact uint32) *big.Int { func CompactToBig(compact uint32) *big.Int {
``` ```
- Comments in the body of the code are highly encouraged, but they should - 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 explain the intention of the code as opposed to just calling out the
obvious<br /><br /> obvious
**WRONG** **WRONG**
```Go ```Go
// return err if amt is less than 5460 // return err if amt is less than 5460
if amt < 5460 { if amt < 5460 {
return err return err
} }
``` ```
**RIGHT** **RIGHT**
```Go ```Go
// Treat transactions with amounts less than the amount which is considered dust // Treat transactions with amounts less than the amount which is considered dust
// as non-standard. // as non-standard.
if amt < 5460 { if amt < 5460 {
return err return err
} }
``` ```
**NOTE:** The above should really use a constant as opposed to a magic number, **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 but it was left as a magic number to show how much of a difference a good
comment can make. comment can make.
<a name="ModelGitCommitMessages" /> ## Model Git Commit Messages
### 4.4 Model Git Commit Messages
This project prefers to keep a clean commit history with well-formed commit This project prefers to keep a clean commit history with well-formed commit
messages. This section illustrates a model commit message and provides a bit messages. This section illustrates a model commit message and provides a bit
@ -214,7 +192,7 @@ being provided here.
Here’s a model Git commit message: Here’s a model Git commit message:
``` ```text
Short (50 chars or less) summary of changes Short (50 chars or less) summary of changes
More detailed explanatory text, if necessary. Wrap it to about 72 More detailed explanatory text, if necessary. Wrap it to about 72
@ -255,22 +233,18 @@ a good thing.
wrap our plain text emails such that there’s room for a few levels of nested wrap our plain text emails such that there’s room for a few levels of nested
reply indicators without overflow in an 80 column terminal. reply indicators without overflow in an 80 column terminal.
<a name="CodeApproval" /> ## Code Approval Process
### 5. Code Approval Process
This section describes the code approval process that is used for code This section describes the code approval process that is used for code
contributions. This is how to get your changes into btcd. contributions. This is how to get your changes into btcd.
<a name="CodeReview" /> ## Code Review
### 5.1 Code Review
All code which is submitted will need to be reviewed before inclusion into the 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 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. other committers who are interested in the area you are working in as well.
##### Code Review Timeframe ## Code Review Timeframe
The timeframe for a code review will vary greatly depending on factors such as 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 the number of other pull requests which need to be reviewed, the size and
@ -286,7 +260,7 @@ 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 to stick with the [Share Early, Share Often](#ShareOften) development practice
outlined above. outlined above.
##### What is the review looking for? ## What is the review looking for?
The review is mainly ensuring the code follows the [Development Practices](#DevelopmentPractices) The review is mainly ensuring the code follows the [Development Practices](#DevelopmentPractices)
and [Code Contribution Standards](#Standards). However, there are a few other and [Code Contribution Standards](#Standards). However, there are a few other
@ -298,9 +272,7 @@ checks which are generally performed as follows:
- The change is not something which is deemed inappropriate by community - The change is not something which is deemed inappropriate by community
consensus consensus
<a name="CodeRework" /> ## Rework Code (if needed)
### 5.2 Rework Code (if needed)
After the code review, the change will be accepted immediately if no issues are 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 found. If there are any concerns or questions, you will be provided with
@ -311,9 +283,7 @@ make the necessary changes.
This process will continue until the code is finally accepted. This process will continue until the code is finally accepted.
<a name="CodeAcceptance" /> ## Acceptance
### 5.3 Acceptance
Once your code is accepted, it will be integrated with the master branch. 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 Typically it will be rebased and fast-forward merged to master as we prefer to
@ -323,13 +293,9 @@ 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)! Rejoice as you will now be listed as a [contributor](https://github.com/btcsuite/btcd/graphs/contributors)!
<a name="Standards" /> ## Contribution Standards
### 6. Contribution Standards ## Contribution Checklist
<a name="Checklist" />
### 6.1. Contribution Checklist
- [&nbsp;&nbsp;] All changes are Go version 1.3 compliant - [&nbsp;&nbsp;] All changes are Go version 1.3 compliant
- [&nbsp;&nbsp;] The code being submitted is commented according to the - [&nbsp;&nbsp;] The code being submitted is commented according to the
@ -346,9 +312,7 @@ Rejoice as you will now be listed as a [contributor](https://github.com/btcsuite
- [&nbsp;&nbsp;] Running [golint](https://github.com/golang/lint) does not - [&nbsp;&nbsp;] Running [golint](https://github.com/golang/lint) does not
report any **new** issues that did not already exist report any **new** issues that did not already exist
<a name="Licensing" /> ## Licensing of Contributions
### 6.2. Licensing of Contributions
All contributions must be licensed with the All contributions must be licensed with the
[ISC license](https://github.com/btcsuite/btcd/blob/master/LICENSE). This is [ISC license](https://github.com/btcsuite/btcd/blob/master/LICENSE). This is

77
docs/conf.py Normal file
View file

@ -0,0 +1,77 @@
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
import recommonmark
from recommonmark.transform import AutoStructify
# -- Project information -----------------------------------------------------
project = 'btcd'
copyright = '2020, btcd'
author = 'btcsuite developers'
# The full version, including alpha/beta/rc tags
release = 'beta'
source_suffix = ['.md']
# The master toctree document.
master_doc = 'index'
# -- General configuration ---------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.napoleon',
'sphinx.ext.mathjax',
'sphinx_markdown_tables',
'recommonmark',
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# app setup hook
def setup(app):
app.add_config_value('recommonmark_config', {
#'url_resolver': lambda url: github_doc_root + url,
'auto_toc_tree_section': 'Contents',
'enable_math': False,
'enable_inline_math': False,
'enable_eval_rst': True,
'enable_auto_doc_ref': True,
}, True)
app.add_transform(AutoStructify)

190
docs/configuration.md Normal file
View file

@ -0,0 +1,190 @@
# Configuration
btcd has a number of [configuration](http://godoc.org/github.com/btcsuite/btcd)
options, which can be viewed by running: `$ btcd --help`.
## Peer server listen interface
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
```
In addition, if you are starting btcd with TLS and want to make it
available via a hostname, then you will need to generate the TLS
certificates for that host. For example,
```
gencerts --host=myhostname.example.com --directory=/home/me/.btcd/
```
## RPC server listen interface
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` and/or `rpclimituser` and `rpclimitpass`
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=
```
## Default ports
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|
## Using bootstrap.dat
### 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.
### 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
### 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.
### 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.
### 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:
**Windows:**
```bat
"%PROGRAMFILES%\Btcd Suite\Btcd\addblock" -i C:\Path\To\bootstrap.dat
```
**Linux/Unix/BSD/POSIX:**
```bash
$GOPATH/bin/addblock -i /path/to/bootstrap.dat
```

43
docs/configure_peer_server_listen_interfaces.md
View file

@ -1,43 +0,0 @@
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
```
In addition, if you are starting btcd with TLS and want to make it
available via a hostname, then you will need to generate the TLS
certificates for that host. For example,
```
gencerts --host=myhostname.example.com --directory=/home/me/.btcd/
```

47
docs/configure_rpc_server_listen_interfaces.md
View file

@ -1,47 +0,0 @@
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` and/or `rpclimituser` and `rpclimitpass`
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=
```

96
docs/configuring_tor.md
View file

@ -1,25 +1,4 @@
### Table of Contents # Configuring TOR
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 />
5. [Tor Stream Isolation](#TorStreamIsolation)<br />
5.1 [Description](#TorStreamIsolationDescription)<br />
5.2 [Command Line Example](#TorStreamIsolationCLIExample)<br />
5.3 [Config File Example](#TorStreamIsolationFileExample)<br />
<a name="Overview" />
### 1. Overview
btcd provides full support for anonymous networking via the btcd provides full support for anonymous networking via the
[Tor Project](https://www.torproject.org/), including [client-only](#Client) [Tor Project](https://www.torproject.org/), including [client-only](#Client)
@ -34,13 +13,7 @@ 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 you are connecting to them. We recommend you take the time to setup a Tor
hidden service for this reason. hidden service for this reason.
<a name="Client" /> ## Client-only
### 2. Client-Only
<a name="ClientDescription" />
**2.1 Description**<br />
Configuring btcd as a Tor client is straightforward. The first step is 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 obviously to install Tor and ensure it is working. Once that is done, all that
@ -58,17 +31,13 @@ NOTE: Specifying the `--proxy` flag disables listening by default since you will
not be reachable for inbound connections unless you also configure a Tor not be reachable for inbound connections unless you also configure a Tor
[hidden service](#HiddenService). [hidden service](#HiddenService).
<a name="ClientCLIExample" /> ### Command line example
**2.2 Command Line Example**<br />
```bash ```bash
$ ./btcd --proxy=127.0.0.1:9050 ./btcd --proxy=127.0.0.1:9050
``` ```
<a name="ClientConfigFileExample" /> ### Config file example
**2.3 Config File Example**<br />
```text ```text
[Application Options] [Application Options]
@ -76,13 +45,7 @@ $ ./btcd --proxy=127.0.0.1:9050
proxy=127.0.0.1:9050 proxy=127.0.0.1:9050
``` ```
<a name="HiddenService" /> ## Client-server via Tor hidden service
### 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 The first step is to configure Tor to provide a hidden service. Documentation
for this can be found on the Tor project website for this can be found on the Tor project website
@ -103,23 +66,20 @@ HiddenServicePort 8333 127.0.0.1:8333
Once Tor is configured to provide the hidden service and you have obtained your 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 generated .onion address, configuring btcd as a Tor hidden service requires
three flags: three flags:
* `--proxy` to identify the Tor (SOCKS 5) proxy to use for outgoing traffic. * `--proxy` to identify the Tor (SOCKS 5) proxy to use for outgoing traffic.
This is typically 127.0.0.1:9050. This is typically 127.0.0.1:9050.
* `--listen` to enable listening for inbound connections since `--proxy` * `--listen` to enable listening for inbound connections since `--proxy`
disables listening by default disables listening by default
* `--externalip` to set the .onion address that is advertised to other peers * `--externalip` to set the .onion address that is advertised to other peers
<a name="HiddenServiceCLIExample" /> ### Command line example
**3.2 Command Line Example**<br />
```bash ```bash
$ ./btcd --proxy=127.0.0.1:9050 --listen=127.0.0.1 --externalip=fooanon.onion ./btcd --proxy=127.0.0.1:9050 --listen=127.0.0.1 --externalip=fooanon.onion
``` ```
<a name="HiddenServiceConfigFileExample" /> ### Config file example
**3.3 Config File Example**<br />
```text ```text
[Application Options] [Application Options]
@ -129,13 +89,7 @@ listen=127.0.0.1
externalip=fooanon.onion externalip=fooanon.onion
``` ```
<a name="Bridge" /> ## Bridge mode (not anonymous)
### 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 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 service nodes. In particular this means only traffic which is directed to or
@ -154,17 +108,13 @@ 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 `--externalip` flag since traffic to and from .onion addresses are already
routed via Tor due to the `--onion` flag. routed via Tor due to the `--onion` flag.
<a name="BridgeCLIExample" /> ### Command line example
**4.2 Command Line Example**<br />
```bash ```bash
$ ./btcd --onion=127.0.0.1:9050 --externalip=fooanon.onion ./btcd --onion=127.0.0.1:9050 --externalip=fooanon.onion
``` ```
<a name="BridgeConfigFileExample" /> ### Config file example
**4.3 Config File Example**<br />
```text ```text
[Application Options] [Application Options]
@ -173,13 +123,7 @@ onion=127.0.0.1:9050
externalip=fooanon.onion externalip=fooanon.onion
``` ```
<a name="TorStreamIsolation" /> ## Tor stream isolation
### 5. Tor Stream Isolation
<a name="TorStreamIsolationDescription" />
**5.1 Description**<br />
Tor stream isolation forces Tor to build a new circuit for each connection Tor stream isolation forces Tor to build a new circuit for each connection
making it harder to correlate connections. making it harder to correlate connections.
@ -187,17 +131,13 @@ making it harder to correlate connections.
btcd provides support for Tor stream isolation by using the `--torisolation` btcd provides support for Tor stream isolation by using the `--torisolation`
flag. This option requires --proxy or --onionproxy to be set. flag. This option requires --proxy or --onionproxy to be set.
<a name="TorStreamIsolationCLIExample" /> ### Command line example
**5.2 Command Line Example**<br />
```bash ```bash
$ ./btcd --proxy=127.0.0.1:9050 --torisolation ./btcd --proxy=127.0.0.1:9050 --torisolation
``` ```
<a name="TorStreamIsolationFileExample" /> ### Config file example
**5.3 Config File Example**<br />
```text ```text
[Application Options] [Application Options]

15
docs/contact.md Normal file
View file

@ -0,0 +1,15 @@
# Contact
## IRC
* [irc.freenode.net](irc://irc.freenode.net), channel `#btcd`
## Mailing Lists
* [btcd](mailto:btcd+subscribe@opensource.conformal.com): discussion of btcd and its packages.
* [btcd-commits](mailto:btcd-commits+subscribe@opensource.conformal.com): readonly mail-out of source code changes.
## Issue Tracker
The [integrated github issue tracker](https://github.com/btcsuite/btcd/issues)
is used for this project.

34
docs/controlling.md Normal file
View file

@ -0,0 +1,34 @@
# Controlling and querying btcd via btcctl
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 or both an RPC limited username and password:
* btcd.conf configuration file
```bash
[Application Options]
rpcuser=myuser
rpcpass=SomeDecentp4ssw0rd
rpclimituser=mylimituser
rpclimitpass=Limitedp4ssw0rd
```
* btcctl.conf configuration file
```bash
[Application Options]
rpcuser=myuser
rpcpass=SomeDecentp4ssw0rd
```
OR
```bash
[Application Options]
rpclimituser=mylimituser
rpclimitpass=Limitedp4ssw0rd
```
For a list of available options, run: `$ btcctl --help`

15
docs/default_ports.md
View file

@ -1,15 +0,0 @@
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|

37
docs/developer_resources.md Normal file
View file

@ -0,0 +1,37 @@
# Developer Resources
* [Code Contribution Guidelines](https://github.com/btcsuite/btcd/tree/master/docs/code_contribution_guidelines.md)
* [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)
* The btcsuite Bitcoin-related Go Packages:
* [btcrpcclient](https://github.com/btcsuite/btcd/tree/master/rpcclient) - Implements a
robust and easy to use Websocket-enabled Bitcoin JSON-RPC client
* [btcjson](https://github.com/btcsuite/btcd/tree/master/btcjson) - Provides an extensive API
for the underlying JSON-RPC command and return values
* [wire](https://github.com/btcsuite/btcd/tree/master/wire) - Implements the
Bitcoin wire protocol
* [peer](https://github.com/btcsuite/btcd/tree/master/peer) -
Provides a common base for creating and managing Bitcoin network peers.
* [blockchain](https://github.com/btcsuite/btcd/tree/master/blockchain) -
Implements Bitcoin block handling and chain selection rules
* [blockchain/fullblocktests](https://github.com/btcsuite/btcd/tree/master/blockchain/fullblocktests) -
Provides a set of block tests for testing the consensus validation rules
* [txscript](https://github.com/btcsuite/btcd/tree/master/txscript) -
Implements the Bitcoin transaction scripting language
* [btcec](https://github.com/btcsuite/btcd/tree/master/btcec) - Implements
support for the elliptic curve cryptographic functions needed for the
Bitcoin scripts
* [database](https://github.com/btcsuite/btcd/tree/master/database) -
Provides a database interface for the Bitcoin block chain
* [mempool](https://github.com/btcsuite/btcd/tree/master/mempool) -
Package mempool provides a policy-enforced pool of unmined bitcoin
transactions.
* [btcutil](https://github.com/btcsuite/btcutil) - Provides Bitcoin-specific
convenience functions and types
* [chainhash](https://github.com/btcsuite/btcd/tree/master/chaincfg/chainhash) -
Provides a generic hash type and associated functions that allows the
specific hash algorithm to be abstracted.
* [connmgr](https://github.com/btcsuite/btcd/tree/master/connmgr) -
Package connmgr implements a generic Bitcoin network connection manager.

57
docs/index.md Normal file
View file

@ -0,0 +1,57 @@
# btcd
[![Build Status](https://travis-ci.org/btcsuite/btcd.png?branch=master)](https://travis-ci.org/btcsuite/btcd)
[![ISC License](http://img.shields.io/badge/license-ISC-blue.svg)](http://copyfree.org)
[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)](http://godoc.org/github.com/btcsuite/btcd)
btcd is an alternative full node bitcoin implementation written in Go (golang).
This project is currently under active development and is in a Beta state. It
is extremely stable and has been in production use since October 2013.
It properly downloads, validates, and serves the block chain using the exact
rules (including consensus bugs) for block acceptance as Bitcoin Core. We have
taken great care to avoid btcd causing a fork to the block chain. It includes a
full block validation testing framework which contains all of the 'official'
block acceptance tests (and some additional ones) that is run on every pull
request to help ensure it properly follows consensus. Also, it passes all of
the JSON test data in the Bitcoin Core code.
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 by the block chain and also includes more strict checks which filter
transactions based on miner requirements ("standard" transactions).
One key difference between btcd and Bitcoin Core is that btcd does *NOT* include
wallet functionality and this was a very intentional design decision. See the
blog entry [here](https://web.archive.org/web/20171125143919/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
[Paymetheus](https://github.com/btcsuite/Paymetheus) (Windows-only) projects
which are both under active development.
## Documentation
Documentation is a work-in-progress. It is available at [btcd.readthedocs.io](https://btcd.readthedocs.io/en/docu/).
## Contents
* [Installation](installation.md)
* [Update](update.md)
* [Configuration](configuration.md)
* [Configuring TOR](configuring_tor.md)
* [Docker](using_docker.md)
* [Controlling](controlling.md)
* [Mining](mining.md)
* [Wallet](wallet.md)
* [Developer resources](developer_resources.md)
* [JSON RPC API](json_rpc_api.md)
* [Code contribution guidelines](code_contribution_guidelines.md)
* [Contact](contact.md)
## License
btcd is licensed under the [copyfree](http://copyfree.org) ISC License.

76
docs/installation.md Normal file
View file

@ -0,0 +1,76 @@
# Installation
The first step is to install btcd. See one of the following sections for
details on how to install on the supported operating systems.
## Requirements
[Go](http://golang.org) 1.11 or newer.
## 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 the btcsuite developers. To
verify the signature perform the following:
* Download the Conformal public key:
https://raw.githubusercontent.com/btcsuite/btcd/master/release/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
```
## Windows Installation
* Install the MSI available at: [btcd windows installer](https://github.com/btcsuite/btcd/releases)
* Launch btcd from the Start Menu
## Linux/BSD/MacOSX/POSIX Installation
* Install Go according to the [installation instructions](http://golang.org/doc/install)
* Ensure Go was installed properly and is a supported version:
```bash
go version
go env GOROOT GOPATH
```
NOTE: The `GOROOT` and `GOPATH` above must not be the same path. It is
recommended that `GOPATH` is set to a directory in your home directory such as
`~/goprojects` to avoid write permission issues. It is also recommended to add
`$GOPATH/bin` to your `PATH` at this point.
* Run the following commands to obtain btcd, all dependencies, and install it:
```bash
git clone https://github.com/btcsuite/btcd $GOPATH/src/github.com/btcsuite/btcd
cd $GOPATH/src/github.com/btcsuite/btcd
GO111MODULE=on go install -v . ./cmd/...
```
* btcd (and utilities) will now be installed in ```$GOPATH/bin```. If you did
not already add the bin directory to your system path during Go installation,
we recommend you do so now.
## Gentoo Linux Installation
* [Install Layman](https://gitlab.com/bitcoin/gentoo) and enable the Bitcoin overlay.
* Copy or symlink `/var/lib/layman/bitcoin/Documentation/package.keywords/btcd-live` to `/etc/portage/package.keywords/`
* Install btcd: `$ emerge net-p2p/btcd`
## Startup
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.
* [Using bootstrap.dat](https://github.com/btcsuite/btcd/tree/master/docs/using_bootstrap_dat.md)

3
docs/json_rpc_api.md
View file

@ -1,4 +1,5 @@
### Table of Contents # JSON RPC API
1. [Overview](#Overview)<br /> 1. [Overview](#Overview)<br />
2. [HTTP POST Versus Websockets](#HttpPostVsWebsockets)<br /> 2. [HTTP POST Versus Websockets](#HttpPostVsWebsockets)<br />
3. [Authentication](#Authentication)<br /> 3. [Authentication](#Authentication)<br />

35
docs/make.bat Normal file
View file

@ -0,0 +1,35 @@
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=.
set BUILDDIR=_build
if "%1" == "" goto help
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
exit /b 1
)
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
:end
popd

30
docs/mining.md Normal file
View file

@ -0,0 +1,30 @@
# Mining
btcd supports the `getblocktemplate` RPC.
The limited user cannot access this RPC.
## Add the payment addresses with the `miningaddr` option
```bash
[Application Options]
rpcuser=myuser
rpcpass=SomeDecentp4ssw0rd
miningaddr=12c6DSiU4Rq3P4ZxziKxzrL5LmMBrzjrJX
miningaddr=1M83ju3EChKYyysmM2FXtLNftbacagd8FR
```
## Add btcd's RPC TLS certificate to system Certificate Authority list
`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
1. Copy rpc.cert to /usr/share/ca-certificates: `# cp /home/user/.btcd/rpc.cert /usr/share/ca-certificates/btcd.crt`
2. Add btcd.crt to /etc/ca-certificates.conf: `# echo btcd.crt >> /etc/ca-certificates.conf`
3. Update the CA certificate list: `# update-ca-certificates`
## Set your mining software url to use https
`cgminer -o https://127.0.0.1:8334 -u rpcuser -p rpcpassword`

1
docs/requirements.txt Normal file
View file

@ -0,0 +1 @@
sphinx_markdown_tables

13
docs/table_of_content.md Normal file
View file

@ -0,0 +1,13 @@
# Contents
* [Installation](installation.md)
* [Update](update.md)
* [Configuration](configuration.md)
* [Configuring TOR](configuring_tor.md)
* [Controlling](controlling.md)
* [Mining](mining.md)
* [Wallet](wallet.md)
* [Developer resources](developer_resources.md)
* [JSON RPC API](json_rpc_api.md)
* [Code contribution guidelines](code_contribution_guidelines.md)
* [Contact](contact.md)

8
docs/update.md Normal file
View file

@ -0,0 +1,8 @@
# Update
* Run the following commands to update btcd, all dependencies, and install it:
```bash
cd $GOPATH/src/github.com/btcsuite/btcd
git pull && GO111MODULE=on go install -v . ./cmd/...
```

79
docs/using_bootstrap_dat.md
View file

@ -1,79 +0,0 @@
### 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
```

5
docs/wallet.md Normal file
View file

@ -0,0 +1,5 @@
# Wallet
btcd was intentionally developed without an integrated wallet for security
reasons. Please see [btcwallet](https://github.com/btcsuite/btcwallet) for more
information.