Move all wiki docs into docs folder of the repo.
This allows the docs to be updated via pull requests and makes it easier to keep it in sync as a part of normal code updates.
This commit is contained in:
parent
f9f4d37976
commit
8a50187bf1
9 changed files with 1944 additions and 1 deletions
|
@ -103,7 +103,7 @@ is used for this project.
|
|||
|
||||
## Documentation
|
||||
|
||||
The documentation is a work-in-progress. It uses the [github wiki](https://github.com/btcsuite/btcd/wiki) facility.
|
||||
The documentation is a work-in-progress. It is located in the [docs](https://github.com/btcsuite/btcd/tree/master/docs) folder.
|
||||
|
||||
## GPG Verification Key
|
||||
|
||||
|
|
209
docs/README.md
Normal file
209
docs/README.md
Normal file
|
@ -0,0 +1,209 @@
|
|||
### Table of Contents
|
||||
1. [About](#About)
|
||||
2. [Getting Started](#GettingStarted)
|
||||
1. [Installation](#Installation)
|
||||
1. [Windows](#WindowsInstallation)
|
||||
2. [Linux/BSD/MacOSX/POSIX](#PosixInstallation)
|
||||
2. [Configuration](#Configuration)
|
||||
3. [Controlling and Querying btcd via btcctl](#BtcctlConfig)
|
||||
4. [Mining](#Mining)
|
||||
3. [Help](#Help)
|
||||
1. [Startup](#Startup)
|
||||
1. [Using bootstrap.dat](#BootstrapDat)
|
||||
2. [Network Configuration](#NetworkConfig)
|
||||
3. [Wallet](#Wallet)
|
||||
4. [Contact](#Contact)
|
||||
1. [IRC](#ContactIRC)
|
||||
2. [Mailing Lists](#MailingLists)
|
||||
5. [Developer Resources](#DeveloperResources)
|
||||
1. [Code Contribution Guidelines](#ContributionGuidelines)
|
||||
2. [JSON-RPC Reference](#JSONRPCReference)
|
||||
3. [Conformal Bitcoin-related Go Packages](#GoPackages)
|
||||
|
||||
<a name="About" />
|
||||
### 1. About
|
||||
btcd is a full node bitcoin implementation written in [Go](http://golang.org),
|
||||
licensed under the [copyfree](http://www.copyfree.org) ISC License.
|
||||
|
||||
This project is currently under active development and is in a Beta state. It is
|
||||
extremely stable and has been in production use for over 6 months as of May
|
||||
2014, however there are still a couple of major features we want to add before
|
||||
we come out of beta.
|
||||
|
||||
It currently properly downloads, validates, and serves the block chain using the
|
||||
exact rules (including bugs) for block acceptance as the reference
|
||||
implementation, [bitcoind](https://github.com/bitcoin/bitcoin). We have taken
|
||||
great care to avoid btcd causing a fork to the block chain. It passes all of
|
||||
the '[official](https://github.com/TheBlueMatt/test-scripts/)' block acceptance
|
||||
tests.
|
||||
|
||||
It also properly relays newly mined blocks, maintains a transaction pool, and
|
||||
relays individual transactions that have not yet made it into a block. It
|
||||
ensures all individual transactions admitted to the pool follow the rules
|
||||
required into the block chain and also includes the vast majority of the more
|
||||
strict checks which filter transactions based on miner requirements ("standard"
|
||||
transactions).
|
||||
|
||||
One key difference between btcd and bitcoind is that btcd does NOT include
|
||||
wallet functionality and this was a very intentional design decision. See the
|
||||
[blog entry](https://blog.conformal.com/btcd-not-your-moms-bitcoin-daemon) for
|
||||
more details. This means you can't actually make or receive payments directly
|
||||
with btcd. That functionality is provided by the
|
||||
[btcwallet](https://github.com/btcsuite/btcwallet) and
|
||||
[btcgui](https://github.com/btcsuite/btcgui) projects which are both under
|
||||
active development.
|
||||
|
||||
<a name="GettingStarted" />
|
||||
### 2. Getting Started
|
||||
|
||||
<a name="Installation" />
|
||||
**2.1 Installation**<br />
|
||||
|
||||
The first step is to install btcd. See one of the following sections for
|
||||
details on how to install on the supported operating systems.
|
||||
|
||||
<a name="WindowsInstallation" />
|
||||
**2.1.1 Windows Installation**<br />
|
||||
|
||||
* Install the MSI available at: https://github.com/btcsuite/btcd/releases
|
||||
* Launch btcd from the Start Menu
|
||||
|
||||
<a name="PosixInstallation" />
|
||||
**2.1.2 Linux/BSD/MacOSX/POSIX Installation**<br />
|
||||
|
||||
* Install Go according to the installation instructions here: http://golang.org/doc/install
|
||||
* Run the following command to ensure your Go version is at least version 1.2: `$ go version`
|
||||
* Run the following command to obtain btcd, its dependencies, and install it: `$ go get github.com/btcsuite/btcd/...`<br />
|
||||
* To upgrade, run the following command: `$ go get -u github.com/btcsuite/btcd/...`
|
||||
* Run btcd: `$ btcd`
|
||||
|
||||
<a name="Configuration" />
|
||||
**2.2 Configuration**<br />
|
||||
|
||||
btcd has a number of [configuration](http://godoc.org/github.com/btcsuite/btcd)
|
||||
options, which can be viewed by running: `$ btcd --help`.
|
||||
|
||||
<a name="BtcctlConfig" />
|
||||
**2.3 Controlling and Querying btcd via btcctl**<br />
|
||||
|
||||
btcctl is a command line utility that can be used to both control and query btcd
|
||||
via [RPC](http://www.wikipedia.org/wiki/Remote_procedure_call). btcd does
|
||||
**not** enable its RPC server by default; You must configure at minimum both an
|
||||
RPC username and password:
|
||||
|
||||
* btcd.conf configuration file
|
||||
```
|
||||
[Application Options]
|
||||
rpcuser=myuser
|
||||
rpcpass=SomeDecentp4ssw0rd
|
||||
```
|
||||
* btcctl.conf configuration file
|
||||
```
|
||||
[Application Options]
|
||||
rpcuser=myuser
|
||||
rpcpass=SomeDecentp4ssw0rd
|
||||
```
|
||||
For a list of available options, run: `$ btcctl --help`
|
||||
|
||||
<a name="Mining" />
|
||||
**2.4 Mining**<br />
|
||||
btcd supports both the `getwork` and `getblocktemplate` RPCs although the
|
||||
`getwork` RPC is deprecated and will likely be removed in a future release.<br />
|
||||
|
||||
**1. Add the payment addresses with the `miningaddr` option.**<br />
|
||||
|
||||
```
|
||||
[Application Options]
|
||||
rpcuser=myuser
|
||||
rpcpass=SomeDecentp4ssw0rd
|
||||
miningaddr=12c6DSiU4Rq3P4ZxziKxzrL5LmMBrzjrJX
|
||||
miningaddr=1M83ju3EChKYyysmM2FXtLNftbacagd8FR
|
||||
```
|
||||
|
||||
**2. Add btcd's RPC TLS certificate to system Certificate Authority list.**<br />
|
||||
|
||||
`cgminer` uses [curl](http://curl.haxx.se/) to fetch data from the RPC server.
|
||||
Since curl validates the certificate by default, we must install the `btcd` RPC
|
||||
certificate into the default system Certificate Authority list.
|
||||
|
||||
**Ubuntu**<br />
|
||||
|
||||
1. Copy rpc.cert to /usr/share/ca-certificates: `# cp /home/user/.btcd/rpc.cert /usr/share/ca-certificates/btcd.crt`<br />
|
||||
2. Add btcd.crt to /etc/ca-certificates.conf: `# echo btcd.crt >> /etc/ca-certificates.conf`<br />
|
||||
3. Update the CA certificate list: `# update-ca-certificates`<br />
|
||||
|
||||
**3. Set your mining software url to use https.**<br />
|
||||
|
||||
`$ cgminer -o https://127.0.0.1:8334 -u rpcuser -p rpcpassword`
|
||||
|
||||
<a name="Help" />
|
||||
### 3. Help
|
||||
|
||||
<a name="Startup" />
|
||||
**3.1 Startup**<br />
|
||||
|
||||
Typically btcd will run and start downloading the block chain with no extra
|
||||
configuration necessary, however, there is an optional method to use a
|
||||
`bootstrap.dat` file that may speed up the initial block chain download process.
|
||||
|
||||
<a name="BootstrapDat" />
|
||||
**3.1.1 bootstrap.dat**<br />
|
||||
* [Using bootstrap.dat](https://github.com/btcsuite/btcd/tree/master/docs/using_bootstrap_dat.md)
|
||||
|
||||
<a name="NetworkConfig" />
|
||||
**3.1.2 Network Configuration**<br />
|
||||
* [What Ports Are Used by Default?](https://github.com/btcsuite/btcd/tree/master/docs/default_ports.md)
|
||||
* [How To Listen on Specific Interfaces](https://github.com/btcsuite/btcd/tree/master/docs/configure_peer_server_listen_interfaces.md)
|
||||
* [How To Configure RPC Server to Listen on Specific Interfaces](https://github.com/btcsuite/btcd/tree/master/docs/configure_rpc_server_listen_interfaces.md)
|
||||
* [Configuring btcd with Tor](https://github.com/btcsuite/btcd/tree/master/docs/configuring_tor.md)
|
||||
|
||||
<a name="Wallet" />
|
||||
**3.1 Wallet**<br />
|
||||
|
||||
btcd was intentionally developed without an integrated wallet for security
|
||||
reasons. Please see [btcwallet](https://github.com/btcsuite/btcwallet) for more
|
||||
information.
|
||||
|
||||
<a name="Contact" />
|
||||
### 4. Contact
|
||||
|
||||
<a name="ContactIRC" />
|
||||
**4.1 IRC**<br />
|
||||
* [irc.conformal.com](irc://irc.conformal.com:+6697), port 6697, tls, channel #btcd
|
||||
|
||||
<a name="MailingLists" />
|
||||
**4.2 Mailing Lists**<br />
|
||||
* <a href="mailto:btcd+subscribe@opensource.conformal.com">btcd</a>: discussion
|
||||
of btcd and its packages.
|
||||
* <a href="mailto:btcd-commits+subscribe@opensource.conformal.com">btcd-commits</a>:
|
||||
readonly mail-out of source code changes.
|
||||
|
||||
<a name="DeveloperResources" />
|
||||
### 5. Developer Resources
|
||||
|
||||
<a name="ContributionGuidelines" />
|
||||
* [Code Contribution Guidelines](https://github.com/btcsuite/btcd/tree/master/docs/code_contribution_guidelines.md)
|
||||
<a name="JSONRPCReference" />
|
||||
* [JSON-RPC Reference](https://github.com/btcsuite/btcd/tree/master/docs/json_rpc_api.md)
|
||||
* [RPC Examples](https://github.com/btcsuite/btcd/tree/master/docs/json_rpc_api.md#ExampleCode)
|
||||
<a name="GoPackages" />
|
||||
* Conformal Bitcoin-related Go Packages:
|
||||
* [btcrpcclient](https://github.com/btcsuite/btcrpcclient) - Implements a
|
||||
robust and easy to use Websocket-enabled Bitcoin JSON-RPC client
|
||||
* [btcjson](https://github.com/btcsuite/btcjson) - Provides an extensive API
|
||||
for the underlying JSON-RPC command and return values
|
||||
* [btcws](https://github.com/btcsuite/btcws) - Custom types for btcd
|
||||
websocket extension commands (registers the extension commands with
|
||||
[btcjson](https://github.com/btcsuite/btcjson))
|
||||
* [btcwire](https://github.com/btcsuite/btcwire) - Implements the Bitcoin
|
||||
wire protocol
|
||||
* [btcchain](https://github.com/btcsuite/btcchain) - Implements Bitcoin
|
||||
block handling and chain selection rules
|
||||
* [btcscript](https://github.com/btcsuite/btcscript) - Implements the
|
||||
Bitcoin transaction scripting language
|
||||
* [btcec](https://github.com/btcsuite/btcec) - Implements support for the
|
||||
elliptic curve cryptographic functions needed for the Bitcoin scripts
|
||||
* [btcdb](https://github.com/btcsuite/btcdb) - Provides a database interface
|
||||
for the Bitcoin block chain
|
||||
* [btcutil](https://github.com/btcsuite/btcutil) - Provides Bitcoin-specific
|
||||
convenience functions and types
|
287
docs/code_contribution_guidelines.md
Normal file
287
docs/code_contribution_guidelines.md
Normal file
|
@ -0,0 +1,287 @@
|
|||
### Table of Contents
|
||||
1. [Overview](#Overview)<br />
|
||||
2. [Minimum Recommended Skillset](#MinSkillset)<br />
|
||||
3. [Required Reading](#ReqReading)<br />
|
||||
4. [Development Practices](#DevelopmentPractices)<br />
|
||||
4.1. [Share Early, Share Often](#ShareEarly)<br />
|
||||
4.2. [Testing](#Testing)<br />
|
||||
4.3. [Code Documentation and Commenting](#CodeDocumentation)<br />
|
||||
5. [Code Approval Process](#CodeApproval)<br />
|
||||
5.1 [Code Review](#CodeReview)<br />
|
||||
5.2 [Rework Code (if needed)](#CodeRework)<br />
|
||||
5.3 [Acceptance](#CodeAcceptance)<br />
|
||||
6. [Contribution Standards](#Standards)<br />
|
||||
6.1. [Contribution Checklist](#Checklist)<br />
|
||||
6.2. [Licensing of Contributions](#Licensing)<br />
|
||||
|
||||
<a name="Overview" />
|
||||
### 1. Overview
|
||||
|
||||
Developing cryptocurrencies is an exciting endeavor that touches a wide variety
|
||||
of areas such as wire protocols, peer-to-peer networking, databases,
|
||||
cryptography, language interpretation (transaction scripts), RPC, and
|
||||
websockets. They also represent a radical shift to the current fiscal system
|
||||
and as a result provide an opportunity to help reshape the entire financial
|
||||
system. There are few projects that offer this level of diversity and impact
|
||||
all in one code base.
|
||||
|
||||
However, as exciting as it is, one must keep in mind that cryptocurrencies
|
||||
represent real money and introducing bugs and security vulnerabilities can have
|
||||
far more dire consequences than in typical projects where having a small bug is
|
||||
minimal by comparison. In the world of cryptocurrencies, even the smallest bug
|
||||
in the wrong area can cost people a significant amount of money. For this
|
||||
reason, the btcd suite has a formalized and rigorous development process which
|
||||
is outlined on this page.
|
||||
|
||||
We highly encourage code contributions, however it is imperative that you adhere
|
||||
to the guidelines established on this page.
|
||||
|
||||
<a name="MinSkillset" />
|
||||
### 2. Minimum Recommended Skillset
|
||||
|
||||
The following list is a set of core competencies that we recommend you possess
|
||||
before you really start attempting to contribute code to the project. These are
|
||||
not hard requirements as we will gladly accept code contributions as long as
|
||||
they follow the guidelines set forth on this page. That said, if you don't have
|
||||
the following basic qualifications you will likely find it quite difficult to
|
||||
contribute.
|
||||
|
||||
- A reasonable understanding of bitcoin at a high level (see the
|
||||
[Required Reading](#ReqReading) section for the original white paper)
|
||||
- Experience in some type of C-like language
|
||||
- An understanding of data structures and their performance implications
|
||||
- Familiarity with unit testing
|
||||
- Debugging experience
|
||||
- Ability to understand not only the area you are making a change in, but also
|
||||
the code your change relies on, and the code which relies on your changed code
|
||||
|
||||
Building on top of those core competencies, the recommended skill set largely
|
||||
depends on the specific areas you are looking to contribute to. For example,
|
||||
if you wish to contribute to the cryptography code, you should have a good
|
||||
understanding of the various aspects involved with cryptography such as the
|
||||
security and performance implications.
|
||||
|
||||
<a name="ReqReading" />
|
||||
### 3. Required Reading
|
||||
|
||||
- [Effective Go](http://golang.org/doc/effective_go.html) - The entire btcd
|
||||
suite follows the guidelines in this document. For your code to be accepted,
|
||||
it must follow the guidelinestherein.
|
||||
- [Original Satoshi Whitepaper](http://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=1&cad=rja&ved=0CCkQFjAA&url=http%3A%2F%2Fbitcoin.org%2Fbitcoin.pdf&ei=os3VUuH8G4SlsASV74GoAg&usg=AFQjCNEipPLigou_1MfB7DQjXCNdlylrBg&sig2=FaHDuT5z36GMWDEnybDJLg&bvm=bv.59378465,d.b2I) - This is the white paper that started it all. Having a solid
|
||||
foundation to build on will make the code much more comprehensible.
|
||||
|
||||
<a name="DevelopmentPractices" />
|
||||
### 4. Development Practices
|
||||
|
||||
Developers are expected to work in their own trees and submit pull requests when
|
||||
they feel their feature or bug fix is ready for integration into the master
|
||||
branch.
|
||||
|
||||
<a name="ShareEarly" />
|
||||
### 4.1 Share Early, Share Often
|
||||
|
||||
We firmly believe in the share early, share often approach. The basic premise
|
||||
of the approach is to announce your plans **before** you start work, and once
|
||||
you have started working, craft your changes into a stream of small and easily
|
||||
reviewable commits.
|
||||
|
||||
This approach has several benefits:
|
||||
|
||||
- Announcing your plans to work on a feature **before** you begin work avoids
|
||||
duplicate work
|
||||
- It permits discussions which can help you achieve your goals in a way that is
|
||||
consistent with the existing architecture
|
||||
- It minimizes the chances of you spending time and energy on a change that
|
||||
might not fit with the consensus of the community or existing architecture and
|
||||
potentially be rejected as a result
|
||||
- Incremental development helps ensure you are on the right track with regards
|
||||
to the rest of the community
|
||||
- The quicker your changes are merged to master, the less time you will need to
|
||||
spend rebasing and otherwise trying to keep up with the main code base
|
||||
|
||||
<a name="Testing" />
|
||||
### 4.2 Testing
|
||||
|
||||
One of the major design goals of all core btcd packages is to aim for complete
|
||||
test coverage. This is financial software so bugs and regressions can cost
|
||||
people real money. For this reason every effort must be taken to ensure the
|
||||
code is as accurate and bug-free as possible. Thorough testing is a good way to
|
||||
help achieve that goal.
|
||||
|
||||
Unless a new feature you submit is completely trivial, it will probably be
|
||||
rejected unless it is also accompanied by adequate test coverage for both
|
||||
positive and negative conditions. That is to say, the tests must ensure your
|
||||
code works correctly when it is fed correct data as well as incorrect data
|
||||
(error paths).
|
||||
|
||||
Go provides an excellent test framework that makes writing test code and
|
||||
checking coverage statistics straight forward. For more information about the
|
||||
test coverage tools, see the [golang cover blog post](http://blog.golang.org/cover).
|
||||
|
||||
A quick summary of test practices follows:
|
||||
- All new code should be accompanied by tests that ensure the code behaves
|
||||
correctly when given expected values, and, perhaps even more importantly, that
|
||||
it handles errors gracefully
|
||||
- When you fix a bug, it should be accompanied by tests which exercise the bug
|
||||
to both prove it has been resolved and to prevent future regressions
|
||||
|
||||
<a name="CodeDocumentation" />
|
||||
### 4.3 Code Documentation and Commenting
|
||||
|
||||
- At a minimum every function must be commented with its intended purpose and
|
||||
any assumptions that it makes
|
||||
- Function comments must always begin with the name of the function per
|
||||
[Effective Go](http://golang.org/doc/effective_go.html)
|
||||
- Function comments should be complete sentences since they allow a wide
|
||||
variety of automated presentations such as [godoc.org](https://godoc.org)
|
||||
- The general rule of thumb is to look at it as if you were completely
|
||||
unfamiliar with the code and ask yourself, would this give me enough
|
||||
information to understand what this function does and how I'd probably want
|
||||
to use it?
|
||||
- Exported functions should also include detailed information the caller of the
|
||||
function will likely need to know and/or understand:<br /><br />
|
||||
**WRONG**
|
||||
```Go
|
||||
// convert a compact uint32 to big.Int
|
||||
func CompactToBig(compact uint32) *big.Int {
|
||||
```
|
||||
**RIGHT**
|
||||
```Go
|
||||
// CompactToBig converts a compact representation of a whole number N to a
|
||||
// big integer. The representation is similar to IEEE754 floating point
|
||||
// numbers.
|
||||
//
|
||||
// Like IEEE754 floating point, there are three basic components: the sign,
|
||||
// the exponent, and the mantissa. They are broken out as follows:
|
||||
//
|
||||
// * the most significant 8 bits represent the unsigned base 256 exponent
|
||||
// * bit 23 (the 24th bit) represents the sign bit
|
||||
// * the least significant 23 bits represent the mantissa
|
||||
//
|
||||
// -------------------------------------------------
|
||||
// | Exponent | Sign | Mantissa |
|
||||
// -------------------------------------------------
|
||||
// | 8 bits [31-24] | 1 bit [23] | 23 bits [22-00] |
|
||||
// -------------------------------------------------
|
||||
//
|
||||
// The formula to calculate N is:
|
||||
// N = (-1^sign) * mantissa * 256^(exponent-3)
|
||||
//
|
||||
// This compact form is only used in bitcoin to encode unsigned 256-bit numbers
|
||||
// which represent difficulty targets, thus there really is not a need for a
|
||||
// sign bit, but it is implemented here to stay consistent with bitcoind.
|
||||
func CompactToBig(compact uint32) *big.Int {
|
||||
```
|
||||
- Comments in the body of the code are highly encouraged, but they should
|
||||
explain the intention of the code as opposed to just calling out the
|
||||
obvious<br /><br />
|
||||
**WRONG**
|
||||
```Go
|
||||
// return err if amt is less than 5460
|
||||
if amt < 5460 {
|
||||
return err
|
||||
}
|
||||
```
|
||||
**RIGHT**
|
||||
```Go
|
||||
// Treat transactions with amounts less than the amount which is considered dust
|
||||
// as non-standard.
|
||||
if amt < 5460 {
|
||||
return err
|
||||
}
|
||||
```
|
||||
**NOTE:** The above should really use a constant as opposed to a magic number,
|
||||
but it was left as a magic number to show how much of a difference a good
|
||||
comment can make.
|
||||
|
||||
<a name="CodeApproval" />
|
||||
### 5. Code Approval Process
|
||||
|
||||
This section describes the code approval process that is used for code
|
||||
contributions. This is how to get your changes into btcd.
|
||||
|
||||
<a name="CodeReview" />
|
||||
### 5.1 Code Review
|
||||
|
||||
All code which is submitted will need to be reviewed before inclusion into the
|
||||
master branch. This process is performed by the project maintainers and usually
|
||||
other committers who are interested in the area you are working in as well.
|
||||
|
||||
##### Code Review Timeframe
|
||||
|
||||
The timeframe for a code review will vary greatly depending on factors such as
|
||||
the number of other pull requests which need to be reviewed, the size and
|
||||
complexity of the contribution, how well you followed the guidelines presented
|
||||
on this page, and how easy it is for the reviewers to digest your commits. For
|
||||
example, if you make one monolithic commit that makes sweeping changes to things
|
||||
in multiple subsystems, it will obviously take much longer to review. You will
|
||||
also likely be asked to split the commit into several smaller, and hence more
|
||||
manageable, commits.
|
||||
|
||||
Keeping the above in mind, most small changes will be reviewed within a few
|
||||
days, while large or far reaching changes may take weeks. This is a good reason
|
||||
to stick with the [Share Early, Share Often](#ShareOften) development practice
|
||||
outlined above.
|
||||
|
||||
##### What is the review looking for?
|
||||
|
||||
The review is mainly ensuring the code follows the [Development Practices](#DevelopmentPractices)
|
||||
and [Code Contribution Standards](#Standards). However, there are a few other
|
||||
checks which are generally performed as follows:
|
||||
|
||||
- The code is stable and has no stability or security concerns
|
||||
- The code is properly using existing APIs and generally fits well into the
|
||||
overall architecture
|
||||
- The change is not something which is deemed inappropriate by community
|
||||
consensus
|
||||
|
||||
<a name="CodeRework" />
|
||||
### 5.2 Rework Code (if needed)
|
||||
|
||||
After the code review, the change will be accepted immediately if no issues are
|
||||
found. If there are any concerns or questions, you will be provided with
|
||||
feedback along with the next steps needed to get your contribution merged with
|
||||
master. In certain cases the code reviewer(s) or interested committers may help
|
||||
you rework the code, but generally you will simply be given feedback for you to
|
||||
make the necessary changes.
|
||||
|
||||
This process will continue until the code is finally accepted.
|
||||
|
||||
<a name="CodeAcceptance" />
|
||||
### 5.3 Acceptance
|
||||
|
||||
Once your code is accepted, it will be integrated with the master branch.
|
||||
Typically it will be rebased and fast-forward merged to master as we prefer to
|
||||
keep a clean commit history over a tangled weave of merge commits. However,
|
||||
regardless of the specific merge method used, the code will be integrated with
|
||||
the master branch and the pull request will be closed.
|
||||
|
||||
Rejoice as you will now be listed as a [contributor](https://github.com/btcsuite/btcd/graphs/contributors)!
|
||||
|
||||
<a name="Standards" />
|
||||
### 6. Contribution Standards
|
||||
|
||||
<a name="Checklist" />
|
||||
### 6.1. Contribution Checklist
|
||||
|
||||
- [ ] All changes are Go version 1.3 compliant
|
||||
- [ ] The code being submitted is commented according to the
|
||||
[Code Documentation and Commenting](#CodeDocumentation) section
|
||||
- [ ] For new code: Code is accompanied by tests which exercise both
|
||||
the positive and negative (error paths) conditions (if applicable)
|
||||
- [ ] For bug fixes: Code is accompanied by new tests which trigger
|
||||
the bug being fixed to prevent regressions
|
||||
- [ ] Any new logging statements use an appropriate subsystem and
|
||||
logging level
|
||||
- [ ] Code has been formatted with `go fmt`
|
||||
- [ ] Running `go test` does not fail any tests
|
||||
- [ ] Running `go vet` does not report any issues
|
||||
- [ ] Running [golint](https://github.com/golang/lint) does not
|
||||
report any **new** issues that did not already exist
|
||||
|
||||
<a name="Licensing" />
|
||||
### 6.2. Licensing of Contributions
|
||||
****
|
||||
All contributions must be licensed with the
|
||||
[ISC license](https://github.com/btcsuite/btcd/blob/master/LICENSE). This is
|
||||
the same license as all of the code in the btcd suite.
|
35
docs/configure_peer_server_listen_interfaces.md
Normal file
35
docs/configure_peer_server_listen_interfaces.md
Normal file
|
@ -0,0 +1,35 @@
|
|||
btcd allows you to bind to specific interfaces which enables you to setup
|
||||
configurations with varying levels of complexity. The listen parameter can be
|
||||
specified on the command line as shown below with the -- prefix or in the
|
||||
configuration file without the -- prefix (as can all long command line options).
|
||||
The configuration file takes one entry per line.
|
||||
|
||||
**NOTE:** The listen flag can be specified multiple times to listen on multiple
|
||||
interfaces as a couple of the examples below illustrate.
|
||||
|
||||
Command Line Examples:
|
||||
|
||||
|Flags|Comment|
|
||||
|----------|------------|
|
||||
|--listen=|all interfaces on default port which is changed by `--testnet` and `--regtest` (**default**)|
|
||||
|--listen=0.0.0.0|all IPv4 interfaces on default port which is changed by `--testnet` and `--regtest`|
|
||||
|--listen=::|all IPv6 interfaces on default port which is changed by `--testnet` and `--regtest`|
|
||||
|--listen=:8333|all interfaces on port 8333|
|
||||
|--listen=0.0.0.0:8333|all IPv4 interfaces on port 8333|
|
||||
|--listen=[::]:8333|all IPv6 interfaces on port 8333|
|
||||
|--listen=127.0.0.1:8333|only IPv4 localhost on port 8333|
|
||||
|--listen=[::1]:8333|only IPv6 localhost on port 8333|
|
||||
|--listen=:8336|all interfaces on non-standard port 8336|
|
||||
|--listen=0.0.0.0:8336|all IPv4 interfaces on non-standard port 8336|
|
||||
|--listen=[::]:8336|all IPv6 interfaces on non-standard port 8336|
|
||||
|--listen=127.0.0.1:8337 --listen=[::1]:8333|IPv4 localhost on port 8337 and IPv6 localhost on port 8333|
|
||||
|--listen=:8333 --listen=:8337|all interfaces on ports 8333 and 8337|
|
||||
|
||||
The following config file would configure btcd to only listen on localhost for both IPv4 and IPv6:
|
||||
|
||||
```text
|
||||
[Application Options]
|
||||
|
||||
listen=127.0.0.1:8333
|
||||
listen=[::1]:8333
|
||||
```
|
46
docs/configure_rpc_server_listen_interfaces.md
Normal file
46
docs/configure_rpc_server_listen_interfaces.md
Normal file
|
@ -0,0 +1,46 @@
|
|||
btcd allows you to bind the RPC server to specific interfaces which enables you
|
||||
to setup configurations with varying levels of complexity. The `rpclisten`
|
||||
parameter can be specified on the command line as shown below with the -- prefix
|
||||
or in the configuration file without the -- prefix (as can all long command line
|
||||
options). The configuration file takes one entry per line.
|
||||
|
||||
A few things to note regarding the RPC server:
|
||||
* The RPC server will **not** be enabled unless the `rpcuser` and `rpcpass`
|
||||
options are specified.
|
||||
* When the `rpcuser` and `rpcpass` options are specified, the RPC server will
|
||||
only listen on localhost IPv4 and IPv6 interfaces by default. You will need
|
||||
to override the RPC listen interfaces to include external interfaces if you
|
||||
want to connect from a remote machine.
|
||||
* The RPC server has TLS enabled by default, even for localhost. You may use
|
||||
the `--notls` option to disable it, but only when all listeners are on
|
||||
localhost interfaces.
|
||||
* The `--rpclisten` flag can be specified multiple times to listen on multiple
|
||||
interfaces as a couple of the examples below illustrate.
|
||||
* The RPC server is disabled by default when using the `--regtest` and
|
||||
`--simnet` networks. You can override this by specifying listen interfaces.
|
||||
|
||||
Command Line Examples:
|
||||
|
||||
|Flags|Comment|
|
||||
|----------|------------|
|
||||
|--rpclisten=|all interfaces on default port which is changed by `--testnet`|
|
||||
|--rpclisten=0.0.0.0|all IPv4 interfaces on default port which is changed by `--testnet`|
|
||||
|--rpclisten=::|all IPv6 interfaces on default port which is changed by `--testnet`|
|
||||
|--rpclisten=:8334|all interfaces on port 8334|
|
||||
|--rpclisten=0.0.0.0:8334|all IPv4 interfaces on port 8334|
|
||||
|--rpclisten=[::]:8334|all IPv6 interfaces on port 8334|
|
||||
|--rpclisten=127.0.0.1:8334|only IPv4 localhost on port 8334|
|
||||
|--rpclisten=[::1]:8334|only IPv6 localhost on port 8334|
|
||||
|--rpclisten=:8336|all interfaces on non-standard port 8336|
|
||||
|--rpclisten=0.0.0.0:8336|all IPv4 interfaces on non-standard port 8336|
|
||||
|--rpclisten=[::]:8336|all IPv6 interfaces on non-standard port 8336|
|
||||
|--rpclisten=127.0.0.1:8337 --listen=[::1]:8334|IPv4 localhost on port 8337 and IPv6 localhost on port 8334|
|
||||
|--rpclisten=:8334 --listen=:8337|all interfaces on ports 8334 and 8337|
|
||||
|
||||
The following config file would configure the btcd RPC server to listen to all interfaces on the default port, including external interfaces, for both IPv4 and IPv6:
|
||||
|
||||
```text
|
||||
[Application Options]
|
||||
|
||||
rpclisten=
|
||||
```
|
156
docs/configuring_tor.md
Normal file
156
docs/configuring_tor.md
Normal file
|
@ -0,0 +1,156 @@
|
|||
### Table of Contents
|
||||
1. [Overview](#Overview)<br />
|
||||
2. [Client-Only](#Client)<br />
|
||||
2.1 [Description](#ClientDescription)<br />
|
||||
2.2 [Command Line Example](#ClientCLIExample)<br />
|
||||
2.3 [Config File Example](#ClientConfigFileExample)<br />
|
||||
3. [Client-Server via Tor Hidden Service](#HiddenService)<br />
|
||||
3.1 [Description](#HiddenServiceDescription)<br />
|
||||
3.2 [Command Line Example](#HiddenServiceCLIExample)<br />
|
||||
3.3 [Config File Example](#HiddenServiceConfigFileExample)<br />
|
||||
4. [Bridge Mode (Not Anonymous)](#Bridge)<br />
|
||||
4.1 [Description](#BridgeDescription)<br />
|
||||
4.2 [Command Line Example](#BridgeCLIExample)<br />
|
||||
4.3 [Config File Example](#BridgeConfigFileExample)<br />
|
||||
|
||||
<a name="Overview" />
|
||||
### 1. Overview
|
||||
|
||||
btcd provides full support for anonymous networking via the
|
||||
[Tor Project](https://www.torproject.org/), including [client-only](#Client)
|
||||
and [hidden service](#HiddenService) configurations. In addition, btcd supports
|
||||
a hybrid, [bridge mode](#Bridge) which is not anonymous, but allows it to
|
||||
operate as a bridge between regular nodes and hidden service nodes without
|
||||
routing the regular connections through Tor.
|
||||
|
||||
While it is easier to only run as a client, it is more beneficial to the Bitcoin
|
||||
network to run as both a client and a server so others may connect to you to as
|
||||
you are connecting to them. We recommend you take the time to setup a Tor
|
||||
hidden service for this reason.
|
||||
|
||||
<a name="Client" />
|
||||
### 2. Client-Only
|
||||
|
||||
<a name="ClientDescription" />
|
||||
**2.1 Description**<br />
|
||||
|
||||
Configuring btcd as a Tor client is straightforward. The first step is
|
||||
obviously to install Tor and ensure it is working. Once that is done, all that
|
||||
typically needs to be done is to specify the `--proxy` flag via the btcd command
|
||||
line or in the btcd configuration file. Typically the Tor proxy address will be
|
||||
127.0.0.1:9050 (if using standalone Tor) or 127.0.0.1:9150 (if using the Tor
|
||||
Browser Bundle). If you have Tor configured to require a username and password,
|
||||
you may specify them with the `--proxyuser` and `--proxypass` flags.
|
||||
|
||||
By default, btcd assumes the proxy specified with `--proxy` is a Tor proxy and
|
||||
hence will send all traffic, including DNS resolution requests, via the
|
||||
specified proxy.
|
||||
|
||||
NOTE: Specifying the `--proxy` flag disables listening by default since you will
|
||||
not be reachable for inbound connections unless you also configure a Tor
|
||||
[hidden service](#HiddenService).
|
||||
|
||||
<a name="ClientCLIExample" />
|
||||
**2.2 Command Line Example**<br />
|
||||
|
||||
```bash
|
||||
$ ./btcd --proxy=127.0.0.1:9050
|
||||
```
|
||||
|
||||
<a name="ClientConfigFileExample" />
|
||||
**2.3 Config File Example**<br />
|
||||
|
||||
```text
|
||||
[Application Options]
|
||||
|
||||
proxy=127.0.0.1:9050
|
||||
```
|
||||
|
||||
<a name="HiddenService" />
|
||||
### 3. Client-Server via Tor Hidden Service
|
||||
|
||||
<a name="HiddenServiceDescription" />
|
||||
**3.1 Description**<br />
|
||||
|
||||
The first step is to configure Tor to provide a hidden service. Documentation
|
||||
for this can be found on the Tor project website
|
||||
[here](https://www.torproject.org/docs/tor-hidden-service.html.en). However,
|
||||
there is no need to install a web server locally as the linked instructions
|
||||
discuss since btcd will act as the server.
|
||||
|
||||
In short, the instructions linked above entail modifying your `torrc` file to
|
||||
add something similar to the following, restarting Tor, and opening the
|
||||
`hostname` file in the `HiddenServiceDir` to obtain your hidden service .onion
|
||||
address.
|
||||
|
||||
```text
|
||||
HiddenServiceDir /var/tor/btcd
|
||||
HiddenServicePort 8333 127.0.0.1:8333
|
||||
```
|
||||
|
||||
Once Tor is configured to provide the hidden service and you have obtained your
|
||||
generated .onion address, configuring btcd as a Tor hidden service requires
|
||||
three flags:
|
||||
* `--proxy` to identify the Tor (SOCKS 5) proxy to use for outgoing traffic.
|
||||
This is typically 127.0.0.1:9050.
|
||||
* `--listen` to enable listening for inbound connections since `--proxy`
|
||||
disables listening by default
|
||||
* `--externalip` to set the .onion address that is advertised to other peers
|
||||
|
||||
<a name="HiddenServiceCLIExample" />
|
||||
**3.2 Command Line Example**<br />
|
||||
|
||||
```bash
|
||||
$ ./btcd --proxy=127.0.0.1:9050 --listen=127.0.0.1 --externalip=fooanon.onion
|
||||
```
|
||||
|
||||
<a name="HiddenServiceConfigFileExample" />
|
||||
**3.3 Config File Example**<br />
|
||||
|
||||
```text
|
||||
[Application Options]
|
||||
|
||||
proxy=127.0.0.1:9050
|
||||
listen=127.0.0.1
|
||||
externalip=fooanon.onion
|
||||
```
|
||||
|
||||
<a name="Bridge" />
|
||||
### 4. Bridge Mode (Not Anonymous)
|
||||
|
||||
<a name="BridgeDescription" />
|
||||
**4.1 Description**<br />
|
||||
|
||||
btcd provides support for operating as a bridge between regular nodes and hidden
|
||||
service nodes. In particular this means only traffic which is directed to or
|
||||
from a .onion address is sent through Tor while other traffic is sent normally.
|
||||
_As a result, this mode is **NOT** anonymous._
|
||||
|
||||
This mode works by specifying an onion-specific proxy, which is pointed at Tor,
|
||||
by using the `--onion` flag via the btcd command line or in the btcd
|
||||
configuration file. If you have Tor configured to require a username and
|
||||
password, you may specify them with the `--onionuser` and `--onionpass` flags.
|
||||
|
||||
NOTE: This mode will also work in conjunction with a hidden service which means
|
||||
you could accept inbound connections both via the normal network and to your
|
||||
hidden service through the Tor network. To enable your hidden service in bridge
|
||||
mode, you only need to specify your hidden service's .onion address via the
|
||||
`--externalip` flag since traffic to and from .onion addresses are already
|
||||
routed via Tor due to the `--onion` flag.
|
||||
|
||||
<a name="BridgeCLIExample" />
|
||||
**4.2 Command Line Example**<br />
|
||||
|
||||
```bash
|
||||
$ ./btcd --onion=127.0.0.1:9050 --externalip=fooanon.onion
|
||||
```
|
||||
|
||||
<a name="BridgeConfigFileExample" />
|
||||
**4.3 Config File Example**<br />
|
||||
|
||||
```text
|
||||
[Application Options]
|
||||
|
||||
onion=127.0.0.1:9050
|
||||
externalip=fooanon.onion
|
||||
```
|
15
docs/default_ports.md
Normal file
15
docs/default_ports.md
Normal file
|
@ -0,0 +1,15 @@
|
|||
While btcd is highly configurable when it comes to the network configuration,
|
||||
the following is intended to be a quick reference for the default ports used so
|
||||
port forwarding can be configured as required.
|
||||
|
||||
btcd provides a `--upnp` flag which can be used to automatically map the bitcoin
|
||||
peer-to-peer listening port if your router supports UPnP. If your router does
|
||||
not support UPnP, or you don't wish to use it, please note that only the bitcoin
|
||||
peer-to-peer port should be forwarded unless you specifically want to allow RPC
|
||||
access to your btcd from external sources such as in more advanced network
|
||||
configurations.
|
||||
|
||||
|Name|Port|
|
||||
|----|----|
|
||||
|Default Bitcoin peer-to-peer port|TCP 8333|
|
||||
|Default RPC port|TCP 8334|
|
1121
docs/json_rpc_api.md
Normal file
1121
docs/json_rpc_api.md
Normal file
File diff suppressed because it is too large
Load diff
74
docs/using_bootrap_dat.md
Normal file
74
docs/using_bootrap_dat.md
Normal file
|
@ -0,0 +1,74 @@
|
|||
### Table of Contents
|
||||
1. [What is bootstrap.dat?](#What)<br />
|
||||
2. [What are the pros and cons of using bootstrap.dat?](#ProsCons)
|
||||
3. [Where do I get bootstrap.dat?](#Obtaining)
|
||||
4. [How do I know I can trust the bootstrap.dat I downloaded?](#Trust)
|
||||
5. [How do I use bootstrap.dat with btcd?](#Importing)
|
||||
|
||||
<a name="What" />
|
||||
### 1. What is bootstrap.dat?
|
||||
|
||||
It is a flat, binary file containing bitcoin blockchain data starting from the
|
||||
genesis block and continuing through a relatively recent block height depending
|
||||
on the last time it was updated.
|
||||
|
||||
See [this](https://bitcointalk.org/index.php?topic=145386.0) thread on
|
||||
bitcointalk for more details.
|
||||
|
||||
**NOTE:** Using bootstrap.dat is entirely optional. Btcd will download the
|
||||
block chain from other peers through the Bitcoin protocol with no extra
|
||||
configuration needed.
|
||||
|
||||
<a name="ProsCons" />
|
||||
### 2. What are the pros and cons of using bootstrap.dat?
|
||||
|
||||
Pros:
|
||||
- Typically accelerates the initial process of bringing up a new node as it
|
||||
downloads from public P2P nodes and generally is able to achieve faster
|
||||
download speeds
|
||||
- It is particularly beneficial when bringing up multiple nodes as you only need
|
||||
to download the data once
|
||||
|
||||
Cons:
|
||||
- Requires you to setup and configure a torrent client if you don't already have
|
||||
one available
|
||||
- Requires roughly twice as much disk space since you'll need the flat file as
|
||||
well as the imported database
|
||||
|
||||
<a name="Obtaining" />
|
||||
### 3. Where do I get bootstrap.dat?
|
||||
|
||||
The bootstrap.dat file is made available via a torrent. See
|
||||
[this](https://bitcointalk.org/index.php?topic=145386.0) thread on bitcointalk
|
||||
for the torrent download details.
|
||||
|
||||
<a name="Trust" />
|
||||
### 4. How do I know I can trust the bootstrap.dat I downloaded?
|
||||
|
||||
You don't need to trust the file as the `addblock` utility verifies every block
|
||||
using the same rules that are used when downloading the block chain normally
|
||||
through the Bitcoin protocol. Additionally, the chain rules contain hard-coded
|
||||
checkpoints for the known-good block chain at periodic intervals. This ensures
|
||||
that not only is it a valid chain, but it is the same chain that everyone else
|
||||
is using.
|
||||
|
||||
<a name="Importing" />
|
||||
### 5. How do I use bootstrap.dat with btcd?
|
||||
|
||||
btcd comes with a separate utility named `addblock` which can be used to import
|
||||
`bootstrap.dat`. This approach is used since the import is a one-time operation
|
||||
and we prefer to keep the daemon itself as lightweight as possible.
|
||||
|
||||
1. Stop btcd if it is already running. This is required since addblock needs to
|
||||
access the database used by btcd and it will be locked if btcd is using it.
|
||||
2. Note the path to the downloaded bootstrap.dat file.
|
||||
3. Run the addblock utility with the `-i` argument pointing to the location of
|
||||
boostrap.dat:<br /><br />
|
||||
**Windows:**
|
||||
```bat
|
||||
C:\> "%PROGRAMFILES%\Btcd Suite\Btcd\addblock" -i C:\Path\To\bootstrap.dat
|
||||
```
|
||||
**Linux/Unix/BSD/POSIX:**
|
||||
```bash
|
||||
$ $GOPATH/bin/addblock -i /path/to/bootstrap.dat
|
||||
```
|
Loading…
Reference in a new issue