lbcd/docs at cbbe3a8bbe7bcabe7f31883428b619487dfdecdd - LBRYCommunity/lbcd

History

Javed Khan 00bddf7540 peer: Refactor peer code into its own package. This commit introduces package peer which contains peer related features refactored from peer.go. The following is an overview of the features the package provides: - Provides a basic concurrent safe bitcoin peer for handling bitcoin communications via the peer-to-peer protocol - Full duplex reading and writing of bitcoin protocol messages - Automatic handling of the initial handshake process including protocol version negotiation - Automatic periodic keep-alive pinging and pong responses - Asynchronous message queueing of outbound messages with optional channel for notification when the message is actually sent - Inventory message batching and send trickling with known inventory detection and avoidance - Ability to wait for shutdown/disconnect - Flexible peer configuration - Caller is responsible for creating outgoing connections and listening for incoming connections so they have flexibility to establish connections as they see fit (proxies, etc.) - User agent name and version - Bitcoin network - Service support signalling (full nodes, bloom filters, etc.) - Maximum supported protocol version - Ability to register callbacks for handling bitcoin protocol messages - Proper handling of bloom filter related commands when the caller does not specify the related flag to signal support - Disconnects the peer when the protocol version is high enough - Does not invoke the related callbacks for older protocol versions - Snapshottable peer statistics such as the total number of bytes read and written, the remote address, user agent, and negotiated protocol version - Helper functions for pushing addresses, getblocks, getheaders, and reject messages - These could all be sent manually via the standard message output function, but the helpers provide additional nice functionality such as duplicate filtering and address randomization - Full documentation with example usage - Test coverage In addition to the addition of the new package, btcd has been refactored to make use of the new package by extending the basic peer it provides to work with the blockmanager and server to act as a full node. The following is a broad overview of the changes to integrate the package: - The server is responsible for all connection management including persistent peers and banning - Callbacks for all messages that are required to implement a full node are registered - Logic necessary to serve data and behave as a full node is now in the callback registered with the peer Finally, the following peer-related things have been improved as a part of this refactor: - Don't log or send reject message due to peer disconnects - Remove trace logs that aren't particularly helpful - Finish an old TODO to switch the queue WaitGroup over to a channel - Improve various comments and fix some code consistency cases - Improve a few logging bits - Implement a most-recently-used nonce tracking for detecting self connections and generate a unique nonce for each peer		2015-10-23 06:17:29 +05:30
..
code_contribution_guidelines.md	docs: Add info describing model commit messages.	2015-07-30 13:14:42 -05:00
configure_peer_server_listen_interfaces.md	Move all wiki docs into docs folder of the repo.	2015-01-18 12:19:23 -06:00
configure_rpc_server_listen_interfaces.md	Create limited RPC user.	2015-04-13 14:14:52 -04:00
configuring_tor.md	Add new option --torisolation	2015-05-13 18:30:48 -04:00
default_ports.md	Move all wiki docs into docs folder of the repo.	2015-01-18 12:19:23 -06:00
json_rpc_api.md	Add reverse order option to searchrawtransactions rpc	2015-10-08 16:31:39 +02:00
README.md	peer: Refactor peer code into its own package.	2015-10-23 06:17:29 +05:30
using_bootstrap_dat.md	typo:using_bootrap_dat.md -> using_bootstrap_dat.md	2015-01-29 16:14:27 -05:00

### 1. About btcd is a full node bitcoin implementation written in [Go](http://golang.org), licensed under the [copyfree](http://www.copyfree.org) ISC License.

This project is currently under active development and is in a Beta state. It is extremely stable and has been in production use for over 6 months as of May 2014, however there are still a couple of major features we want to add before we come out of beta.

It currently properly downloads, validates, and serves the block chain using the exact rules (including bugs) for block acceptance as the reference implementation, bitcoind. We have taken great care to avoid btcd causing a fork to the block chain. It passes all of the 'official' block acceptance tests.

It also properly relays newly mined blocks, maintains a transaction pool, and relays individual transactions that have not yet made it into a block. It ensures all individual transactions admitted to the pool follow the rules required into the block chain and also includes the vast majority of the more strict checks which filter transactions based on miner requirements ("standard" transactions).

One key difference between btcd and bitcoind is that btcd does NOT include wallet functionality and this was a very intentional design decision. See the blog entry for more details. This means you can't actually make or receive payments directly with btcd. That functionality is provided by the btcwallet and btcgui 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
Run the following command to ensure your Go version is at least version 1.2: $ go version
Run the following command to obtain btcd, its dependencies, and install it: $ go get github.com/btcsuite/btcd/...
- To upgrade, run the following command: $ go get -u github.com/btcsuite/btcd/...
Run btcd: $ btcd

**2.2 Configuration**

btcd has a number of configuration 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. 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

[Application Options]
rpclimituser=mylimituser
rpclimitpass=Limitedp4ssw0rd

For a list of available options, run: $ btcctl --help

**2.4 Mining**
btcd supports both the `getwork` and `getblocktemplate` RPCs although the `getwork` RPC is deprecated and will likely be removed in a future release. The limited user cannot access these RPCs.

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 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

Copy rpc.cert to /usr/share/ca-certificates: # cp /home/user/.btcd/rpc.cert /usr/share/ca-certificates/btcd.crt
Add btcd.crt to /etc/ca-certificates.conf: # echo btcd.crt >> /etc/ca-certificates.conf
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 for more information.

README.md

Table of Contents