From 355472b0f79a72d2445ed2f0d9e5e472b25814f4 Mon Sep 17 00:00:00 2001 From: Christian Lehmann Date: Mon, 9 Sep 2019 17:24:56 +0200 Subject: [PATCH] Major rework on documentation to make it compatible to readthedocs.org --- README.md | 2 +- docs/.gitignore | 1 + docs/Makefile | 20 ++ docs/README.md | 305 ------------------ docs/code_contribution_guidelines.md | 106 ++---- docs/conf.py | 77 +++++ docs/configuration.md | 190 +++++++++++ ...configure_peer_server_listen_interfaces.md | 43 --- .../configure_rpc_server_listen_interfaces.md | 47 --- docs/configuring_tor.md | 96 ++---- docs/contact.md | 15 + docs/controlling.md | 34 ++ docs/default_ports.md | 15 - docs/developer_resources.md | 37 +++ docs/index.md | 57 ++++ docs/installation.md | 76 +++++ docs/json_rpc_api.md | 3 +- docs/make.bat | 35 ++ docs/mining.md | 30 ++ docs/requirements.txt | 1 + docs/table_of_content.md | 13 + docs/update.md | 8 + docs/using_bootstrap_dat.md | 79 ----- docs/wallet.md | 5 + 24 files changed, 655 insertions(+), 640 deletions(-) create mode 100644 docs/.gitignore create mode 100644 docs/Makefile delete mode 100644 docs/README.md create mode 100644 docs/conf.py create mode 100644 docs/configuration.md delete mode 100644 docs/configure_peer_server_listen_interfaces.md delete mode 100644 docs/configure_rpc_server_listen_interfaces.md create mode 100644 docs/contact.md create mode 100644 docs/controlling.md delete mode 100644 docs/default_ports.md create mode 100644 docs/developer_resources.md create mode 100644 docs/index.md create mode 100644 docs/installation.md create mode 100644 docs/make.bat create mode 100644 docs/mining.md create mode 100644 docs/requirements.txt create mode 100644 docs/table_of_content.md create mode 100644 docs/update.md delete mode 100644 docs/using_bootstrap_dat.md create mode 100644 docs/wallet.md diff --git a/README.md b/README.md index 8c9d252a..352252dd 100644 --- a/README.md +++ b/README.md @@ -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 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 directly with btcd. That functionality is provided by the [btcwallet](https://github.com/btcsuite/btcwallet) and diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 00000000..a485625d --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +/_build diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d4bb2cbb --- /dev/null +++ b/docs/Makefile @@ -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) diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 15d7e739..00000000 --- a/docs/README.md +++ /dev/null @@ -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) - - - -### 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. - - - -### 2. Getting Started - - - -**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. - - - -**2.1.1 Windows Installation**
- -* Install the MSI available at: https://github.com/btcsuite/btcd/releases -* Launch btcd from the Start Menu - - - -**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/... -``` - - - -**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` - - - -**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`. - - - -**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` - - - -**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` - - - -### 3. Help - - - -**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. - - - -**3.1.1 bootstrap.dat** - -* [Using bootstrap.dat](https://github.com/btcsuite/btcd/tree/master/docs/using_bootstrap_dat.md) - - - -**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) - - - -**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. - - - - -### 4. Contact - - - -**4.1 IRC** - -* [irc.freenode.net](irc://irc.freenode.net), channel `#btcd` - - - -**4.2 Mailing Lists** - -* btcd: discussion - of btcd and its packages. -* btcd-commits: - readonly mail-out of source code changes. - - - -### 5. 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. - - - -### 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 diff --git a/docs/code_contribution_guidelines.md b/docs/code_contribution_guidelines.md index b643e911..a135ad93 100644 --- a/docs/code_contribution_guidelines.md +++ b/docs/code_contribution_guidelines.md @@ -1,23 +1,4 @@ -### Table of Contents -1. [Overview](#Overview)
-2. [Minimum Recommended Skillset](#MinSkillset)
-3. [Required Reading](#ReqReading)
-4. [Development Practices](#DevelopmentPractices)
-4.1. [Share Early, Share Often](#ShareEarly)
-4.2. [Testing](#Testing)
-4.3. [Code Documentation and Commenting](#CodeDocumentation)
-4.4. [Model Git Commit Messages](#ModelGitCommitMessages)
-5. [Code Approval Process](#CodeApproval)
-5.1 [Code Review](#CodeReview)
-5.2 [Rework Code (if needed)](#CodeRework)
-5.3 [Acceptance](#CodeAcceptance)
-6. [Contribution Standards](#Standards)
-6.1. [Contribution Checklist](#Checklist)
-6.2. [Licensing of Contributions](#Licensing)
- - - -### 1. Overview +# Code contribution guidelines Developing cryptocurrencies is an exciting endeavor that touches a wide variety 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 to the guidelines established on this page. - - -### 2. Minimum Recommended Skillset +## 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 @@ -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 security and performance implications. - - -### 3. Required Reading +## 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, @@ -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 foundation to build on will make the code much more comprehensible. - - -### 4. Development Practices +## 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. - - -### 4.1 Share Early, Share Often +## 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 @@ -105,9 +78,7 @@ This approach has several benefits: - 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 - - -### 4.2 Testing +## 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 @@ -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). 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 - - -### 4.3 Code Documentation and Commenting +## Code Documentation and Commenting - At a minimum every function must be commented with its intended purpose and 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) - 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? + 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:

+ function will likely need to know and/or understand: + **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 @@ -180,31 +154,35 @@ func CompactToBig(compact uint32) *big.Int { // 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

+ obvious + **WRONG** + ```Go // return err if amt is less than 5460 if amt < 5460 { - return err + return err } ``` + **RIGHT** + ```Go // Treat transactions with amounts less than the amount which is considered dust // as non-standard. if amt < 5460 { - return err + 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. - - -### 4.4 Model Git Commit Messages +## Model Git Commit Messages 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 @@ -214,7 +192,7 @@ being provided here. Here’s a model Git commit message: -``` +```text Short (50 chars or less) summary of changes 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 reply indicators without overflow in an 80 column terminal. - - -### 5. Code Approval Process +## 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. - - -### 5.1 Code Review +## 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 +## 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 @@ -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 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) 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 consensus - - -### 5.2 Rework Code (if needed) +## 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 @@ -311,9 +283,7 @@ make the necessary changes. This process will continue until the code is finally accepted. - - -### 5.3 Acceptance +## 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 @@ -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)! - +## Contribution Standards -### 6. Contribution Standards - - - -### 6.1. Contribution Checklist +## Contribution Checklist - [  ] All changes are Go version 1.3 compliant - [  ] 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 - [  ] Running [golint](https://github.com/golang/lint) does not report any **new** issues that did not already exist - - -### 6.2. Licensing of Contributions +## Licensing of Contributions All contributions must be licensed with the [ISC license](https://github.com/btcsuite/btcd/blob/master/LICENSE). This is diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..3db16305 --- /dev/null +++ b/docs/conf.py @@ -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) diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 00000000..132c07a1 --- /dev/null +++ b/docs/configuration.md @@ -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 +``` diff --git a/docs/configure_peer_server_listen_interfaces.md b/docs/configure_peer_server_listen_interfaces.md deleted file mode 100644 index ac611373..00000000 --- a/docs/configure_peer_server_listen_interfaces.md +++ /dev/null @@ -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/ -``` diff --git a/docs/configure_rpc_server_listen_interfaces.md b/docs/configure_rpc_server_listen_interfaces.md deleted file mode 100644 index 3115d6a1..00000000 --- a/docs/configure_rpc_server_listen_interfaces.md +++ /dev/null @@ -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= -``` diff --git a/docs/configuring_tor.md b/docs/configuring_tor.md index 442930d6..ecb03bfc 100644 --- a/docs/configuring_tor.md +++ b/docs/configuring_tor.md @@ -1,25 +1,4 @@ -### Table of Contents -1. [Overview](#Overview)
-2. [Client-Only](#Client)
-2.1 [Description](#ClientDescription)
-2.2 [Command Line Example](#ClientCLIExample)
-2.3 [Config File Example](#ClientConfigFileExample)
-3. [Client-Server via Tor Hidden Service](#HiddenService)
-3.1 [Description](#HiddenServiceDescription)
-3.2 [Command Line Example](#HiddenServiceCLIExample)
-3.3 [Config File Example](#HiddenServiceConfigFileExample)
-4. [Bridge Mode (Not Anonymous)](#Bridge)
-4.1 [Description](#BridgeDescription)
-4.2 [Command Line Example](#BridgeCLIExample)
-4.3 [Config File Example](#BridgeConfigFileExample)
-5. [Tor Stream Isolation](#TorStreamIsolation)
-5.1 [Description](#TorStreamIsolationDescription)
-5.2 [Command Line Example](#TorStreamIsolationCLIExample)
-5.3 [Config File Example](#TorStreamIsolationFileExample)
- - - -### 1. Overview +# Configuring TOR btcd provides full support for anonymous networking via the [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 hidden service for this reason. - - -### 2. Client-Only - - - -**2.1 Description**
+## Client-only 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 @@ -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 [hidden service](#HiddenService). - - -**2.2 Command Line Example**
+### Command line example ```bash -$ ./btcd --proxy=127.0.0.1:9050 +./btcd --proxy=127.0.0.1:9050 ``` - - -**2.3 Config File Example**
+### Config file example ```text [Application Options] @@ -76,13 +45,7 @@ $ ./btcd --proxy=127.0.0.1:9050 proxy=127.0.0.1:9050 ``` - - -### 3. Client-Server via Tor Hidden Service - - - -**3.1 Description**
+## Client-server via Tor hidden service The first step is to configure Tor to provide a hidden service. Documentation 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 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 - - -**3.2 Command Line Example**
+### Command line example ```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 ``` - - -**3.3 Config File Example**
+### Config file example ```text [Application Options] @@ -129,13 +89,7 @@ listen=127.0.0.1 externalip=fooanon.onion ``` - - -### 4. Bridge Mode (Not Anonymous) - - - -**4.1 Description**
+## Bridge mode (not anonymous) 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 @@ -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 routed via Tor due to the `--onion` flag. - - -**4.2 Command Line Example**
+### Command line example ```bash -$ ./btcd --onion=127.0.0.1:9050 --externalip=fooanon.onion +./btcd --onion=127.0.0.1:9050 --externalip=fooanon.onion ``` - - -**4.3 Config File Example**
+### Config file example ```text [Application Options] @@ -173,13 +123,7 @@ onion=127.0.0.1:9050 externalip=fooanon.onion ``` - - -### 5. Tor Stream Isolation - - - -**5.1 Description**
+## Tor stream isolation Tor stream isolation forces Tor to build a new circuit for each connection 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` flag. This option requires --proxy or --onionproxy to be set. - - -**5.2 Command Line Example**
+### Command line example ```bash -$ ./btcd --proxy=127.0.0.1:9050 --torisolation +./btcd --proxy=127.0.0.1:9050 --torisolation ``` - - -**5.3 Config File Example**
+### Config file example ```text [Application Options] diff --git a/docs/contact.md b/docs/contact.md new file mode 100644 index 00000000..88b425e8 --- /dev/null +++ b/docs/contact.md @@ -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. diff --git a/docs/controlling.md b/docs/controlling.md new file mode 100644 index 00000000..93ab403b --- /dev/null +++ b/docs/controlling.md @@ -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` diff --git a/docs/default_ports.md b/docs/default_ports.md deleted file mode 100644 index 14e4eea2..00000000 --- a/docs/default_ports.md +++ /dev/null @@ -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| diff --git a/docs/developer_resources.md b/docs/developer_resources.md new file mode 100644 index 00000000..cec8ce99 --- /dev/null +++ b/docs/developer_resources.md @@ -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. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..5dc0dfcf --- /dev/null +++ b/docs/index.md @@ -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. + diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 00000000..3eea886e --- /dev/null +++ b/docs/installation.md @@ -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) diff --git a/docs/json_rpc_api.md b/docs/json_rpc_api.md index 61884df0..db292d2b 100644 --- a/docs/json_rpc_api.md +++ b/docs/json_rpc_api.md @@ -1,4 +1,5 @@ -### Table of Contents +# JSON RPC API + 1. [Overview](#Overview)
2. [HTTP POST Versus Websockets](#HttpPostVsWebsockets)
3. [Authentication](#Authentication)
diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..922152e9 --- /dev/null +++ b/docs/make.bat @@ -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 diff --git a/docs/mining.md b/docs/mining.md new file mode 100644 index 00000000..29a3e898 --- /dev/null +++ b/docs/mining.md @@ -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` diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..e16dd4b3 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +sphinx_markdown_tables diff --git a/docs/table_of_content.md b/docs/table_of_content.md new file mode 100644 index 00000000..85f08a97 --- /dev/null +++ b/docs/table_of_content.md @@ -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) diff --git a/docs/update.md b/docs/update.md new file mode 100644 index 00000000..1fb847cf --- /dev/null +++ b/docs/update.md @@ -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/... +``` diff --git a/docs/using_bootstrap_dat.md b/docs/using_bootstrap_dat.md deleted file mode 100644 index de7e08c0..00000000 --- a/docs/using_bootstrap_dat.md +++ /dev/null @@ -1,79 +0,0 @@ -### Table of Contents -1. [What is bootstrap.dat?](#What)
-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) - - - -### 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. - - - -### 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 - - - -### 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. - - - -### 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. - - - -### 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:

-**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 -``` diff --git a/docs/wallet.md b/docs/wallet.md new file mode 100644 index 00000000..cc123aa7 --- /dev/null +++ b/docs/wallet.md @@ -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.