Mirroristas/kaspad
2
0
Fork 0
mirror of https://github.com/kaspanet/kaspad.git synced 2025-03-30 15:08:33 +00:00
Code Issues Packages Projects Releases Wiki Activity

[NOD-618] Removed outdated docs folder (#570)

Browse Source
This commit is contained in:
Svarog 2020-01-06 10:48:41 +02:00 committed by Dan Aharoni
parent 733d06af5a
commit 784d3de4ca
8 changed files with 0 additions and 2400 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

299
docs/README.md
View File

@ -1,299 +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)
<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://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/kaspanet/kaspad/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
$ go get -u github.com/Masterminds/glide
$ git clone https://github.com/kaspanet/kaspad $GOPATH/src/github.com/kaspanet/kaspad
$ cd $GOPATH/src/github.com/kaspanet/kaspad
$ glide install
$ go install . ./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/kaspanet/kaspad
$ git pull && glide install
$ go install . ./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/kaspanet/kaspad)
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:16110 -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/kaspanet/kaspad/tree/master/docs/using_bootstrap_dat.md)
<a name="NetworkConfig" />
**3.1.2 Network Configuration**
* [What Ports Are Used by Default?](https://github.com/kaspanet/kaspad/tree/master/docs/default_ports.md)
* [How To Listen on Specific Interfaces](https://github.com/kaspanet/kaspad/tree/master/docs/configure_peer_server_listen_interfaces.md)
* [How To Configure RPC Server to Listen on Specific Interfaces](https://github.com/kaspanet/kaspad/tree/master/docs/configure_rpc_server_listen_interfaces.md)
* [Configuring btcd with Tor](https://github.com/kaspanet/kaspad/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/kaspanet/kaspad/tree/master/docs/code_contribution_guidelines.md)
<a name="JSONRPCReference" />
* [JSON-RPC Reference](https://github.com/kaspanet/kaspad/tree/master/docs/json_rpc_api.md)
* [RPC Examples](https://github.com/kaspanet/kaspad/tree/master/docs/json_rpc_api.md#ExampleCode)
<a name="GoPackages" />
* The btcsuite Bitcoin-related Go Packages:
* [btcrpcclient](https://github.com/kaspanet/kaspad/tree/master/rpcclient) - Implements a
robust and easy to use Websocket-enabled Bitcoin JSON-RPC client
* [btcjson](https://github.com/kaspanet/kaspad/tree/master/btcjson) - Provides an extensive API
for the underlying JSON-RPC command and return values
* [wire](https://github.com/kaspanet/kaspad/tree/master/wire) - Implements the
Bitcoin wire protocol
* [peer](https://github.com/kaspanet/kaspad/tree/master/peer) -
Provides a common base for creating and managing Bitcoin network peers.
* [blockchain](https://github.com/kaspanet/kaspad/tree/master/blockchain) -
Implements Bitcoin block handling and chain selection rules
* [blockchain/fullblocktests](https://github.com/kaspanet/kaspad/tree/master/blockchain/fullblocktests) -
Provides a set of block tests for testing the consensus validation rules
* [txscript](https://github.com/kaspanet/kaspad/tree/master/txscript) -
Implements the Bitcoin transaction scripting language
* [btcec](https://github.com/kaspanet/kaspad/tree/master/btcec) - Implements
support for the elliptic curve cryptographic functions needed for the
Bitcoin scripts
* [database](https://github.com/kaspanet/kaspad/tree/master/database) -
Provides a database interface for the Bitcoin block chain
* [mempool](https://github.com/kaspanet/kaspad/tree/master/mempool) -
Package mempool provides a policy-enforced pool of unmined bitcoin
transactions.
* [btcutil](https://github.com/daglabs/btcutil) - Provides Bitcoin-specific
convenience functions and types
* [chainhash](https://github.com/kaspanet/kaspad/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/kaspanet/kaspad/tree/master/connmgr) -
Package connmgr implements a generic Bitcoin network connection manager.

355
docs/code_contribution_guidelines.md
View File

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

35
docs/configure_peer_server_listen_interfaces.md
View File

@ -1,35 +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=:16111|all interfaces on port 16111|
|--listen=0.0.0.0:16111|all IPv4 interfaces on port 16111|
|--listen=[::]:16111|all IPv6 interfaces on port 16111|
|--listen=127.0.0.1:16111|only IPv4 localhost on port 16111|
|--listen=[::1]:16111|only IPv6 localhost on port 16111|
|--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]:16111|IPv4 localhost on port 8337 and IPv6 localhost on port 16111|
|--listen=:16111 --listen=:8337|all interfaces on ports 16111 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:16111
listen=[::1]:16111
```

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=:16110|all interfaces on port 16110|
|--rpclisten=0.0.0.0:16110|all IPv4 interfaces on port 16110|
|--rpclisten=[::]:16110|all IPv6 interfaces on port 16110|
|--rpclisten=127.0.0.1:16110|only IPv4 localhost on port 16110|
|--rpclisten=[::1]:16110|only IPv6 localhost on port 16110|
|--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]:16110|IPv4 localhost on port 8337 and IPv6 localhost on port 16110|
|--rpclisten=:16110 --listen=:8337|all interfaces on ports 16110 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=
```

207
docs/configuring_tor.md
View File

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

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 16111|
|Default RPC port|TCP 16110|

1363
docs/json_rpc_api.md
View File

File diff suppressed because it is too large Load Diff

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