From 8a50187bf1f58e70968333c3200abfc2ce896bd4 Mon Sep 17 00:00:00 2001 From: Dave Collins Date: Sun, 18 Jan 2015 11:16:43 -0600 Subject: [PATCH] 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. --- README.md | 2 +- docs/README.md | 209 +++ docs/code_contribution_guidelines.md | 287 +++++ ...configure_peer_server_listen_interfaces.md | 35 + .../configure_rpc_server_listen_interfaces.md | 46 + docs/configuring_tor.md | 156 +++ docs/default_ports.md | 15 + docs/json_rpc_api.md | 1121 +++++++++++++++++ docs/using_bootrap_dat.md | 74 ++ 9 files changed, 1944 insertions(+), 1 deletion(-) create mode 100644 docs/README.md create mode 100644 docs/code_contribution_guidelines.md create mode 100644 docs/configure_peer_server_listen_interfaces.md create mode 100644 docs/configure_rpc_server_listen_interfaces.md create mode 100644 docs/configuring_tor.md create mode 100644 docs/default_ports.md create mode 100644 docs/json_rpc_api.md create mode 100644 docs/using_bootrap_dat.md diff --git a/README.md b/README.md index c3e46399..0b4ab025 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..56d85ac9 --- /dev/null +++ b/docs/README.md @@ -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) + + +### 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. + + +### 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](http://godoc.org/github.com/btcsuite/btcd) +options, which can be viewed by running: `$ btcd --help`. + + +**2.3 Controlling and Querying btcd via btcctl**
+ +btcctl is a command line utility that can be used to both control and query btcd +via [RPC](http://www.wikipedia.org/wiki/Remote_procedure_call). btcd does +**not** enable its RPC server by default; You must configure at minimum both an +RPC username and password: + +* 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` + + +**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.
+ +**1. Add the payment addresses with the `miningaddr` option.**
+ +``` +[Application Options] +rpcuser=myuser +rpcpass=SomeDecentp4ssw0rd +miningaddr=12c6DSiU4Rq3P4ZxziKxzrL5LmMBrzjrJX +miningaddr=1M83ju3EChKYyysmM2FXtLNftbacagd8FR +``` + +**2. Add btcd's RPC TLS certificate to system Certificate Authority list.**
+ +`cgminer` uses [curl](http://curl.haxx.se/) to fetch data from the RPC server. +Since curl validates the certificate by default, we must install the `btcd` RPC +certificate into the default system Certificate Authority list. + +**Ubuntu**
+ +1. Copy rpc.cert to /usr/share/ca-certificates: `# cp /home/user/.btcd/rpc.cert /usr/share/ca-certificates/btcd.crt`
+2. Add btcd.crt to /etc/ca-certificates.conf: `# echo btcd.crt >> /etc/ca-certificates.conf`
+3. Update the CA certificate list: `# update-ca-certificates`
+ +**3. Set your mining software url to use https.**
+ +`$ cgminer -o https://127.0.0.1:8334 -u rpcuser -p rpcpassword` + + +### 3. Help + + +**3.1 Startup**
+ +Typically btcd will run and start downloading the block chain with no extra +configuration necessary, however, there is an optional method to use a +`bootstrap.dat` file that may speed up the initial block chain download process. + + +**3.1.1 bootstrap.dat**
+* [Using bootstrap.dat](https://github.com/btcsuite/btcd/tree/master/docs/using_bootstrap_dat.md) + + +**3.1.2 Network Configuration**
+* [What Ports Are Used by Default?](https://github.com/btcsuite/btcd/tree/master/docs/default_ports.md) +* [How To Listen on Specific Interfaces](https://github.com/btcsuite/btcd/tree/master/docs/configure_peer_server_listen_interfaces.md) +* [How To Configure RPC Server to Listen on Specific Interfaces](https://github.com/btcsuite/btcd/tree/master/docs/configure_rpc_server_listen_interfaces.md) +* [Configuring btcd with Tor](https://github.com/btcsuite/btcd/tree/master/docs/configuring_tor.md) + + +**3.1 Wallet**
+ +btcd was intentionally developed without an integrated wallet for security +reasons. Please see [btcwallet](https://github.com/btcsuite/btcwallet) for more +information. + + +### 4. Contact + + +**4.1 IRC**
+* [irc.conformal.com](irc://irc.conformal.com:+6697), port 6697, tls, channel #btcd + + +**4.2 Mailing Lists**
+* btcd: discussion + of btcd and its packages. +* btcd-commits: + readonly mail-out of source code changes. + + +### 5. Developer Resources + + +* [Code Contribution Guidelines](https://github.com/btcsuite/btcd/tree/master/docs/code_contribution_guidelines.md) + +* [JSON-RPC Reference](https://github.com/btcsuite/btcd/tree/master/docs/json_rpc_api.md) + * [RPC Examples](https://github.com/btcsuite/btcd/tree/master/docs/json_rpc_api.md#ExampleCode) + +* 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 \ No newline at end of file diff --git a/docs/code_contribution_guidelines.md b/docs/code_contribution_guidelines.md new file mode 100644 index 00000000..0de7c317 --- /dev/null +++ b/docs/code_contribution_guidelines.md @@ -0,0 +1,287 @@ +### Table of Contents +1. [Overview](#Overview)
+2. [Minimum Recommended Skillset](#MinSkillset)
+3. [Required Reading](#ReqReading)
+4. [Development Practices](#DevelopmentPractices)
+4.1. [Share Early, Share Often](#ShareEarly)
+4.2. [Testing](#Testing)
+4.3. [Code Documentation and Commenting](#CodeDocumentation)
+5. [Code Approval Process](#CodeApproval)
+5.1 [Code Review](#CodeReview)
+5.2 [Rework Code (if needed)](#CodeRework)
+5.3 [Acceptance](#CodeAcceptance)
+6. [Contribution Standards](#Standards)
+6.1. [Contribution Checklist](#Checklist)
+6.2. [Licensing of Contributions](#Licensing)
+ + +### 1. Overview + +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. + + +### 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. + + +### 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. + + +### 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. + + +### 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 + + +### 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 + + +### 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:

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

+**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. + + +### 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. + + +### 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 + + +### 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. + + +### 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)! + + +### 6. Contribution Standards + + +### 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 + + +### 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. diff --git a/docs/configure_peer_server_listen_interfaces.md b/docs/configure_peer_server_listen_interfaces.md new file mode 100644 index 00000000..26f5ec72 --- /dev/null +++ b/docs/configure_peer_server_listen_interfaces.md @@ -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 +``` diff --git a/docs/configure_rpc_server_listen_interfaces.md b/docs/configure_rpc_server_listen_interfaces.md new file mode 100644 index 00000000..13bd584b --- /dev/null +++ b/docs/configure_rpc_server_listen_interfaces.md @@ -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= +``` diff --git a/docs/configuring_tor.md b/docs/configuring_tor.md new file mode 100644 index 00000000..daffeaa6 --- /dev/null +++ b/docs/configuring_tor.md @@ -0,0 +1,156 @@ +### Table of Contents +1. [Overview](#Overview)
+2. [Client-Only](#Client)
+2.1 [Description](#ClientDescription)
+2.2 [Command Line Example](#ClientCLIExample)
+2.3 [Config File Example](#ClientConfigFileExample)
+3. [Client-Server via Tor Hidden Service](#HiddenService)
+3.1 [Description](#HiddenServiceDescription)
+3.2 [Command Line Example](#HiddenServiceCLIExample)
+3.3 [Config File Example](#HiddenServiceConfigFileExample)
+4. [Bridge Mode (Not Anonymous)](#Bridge)
+4.1 [Description](#BridgeDescription)
+4.2 [Command Line Example](#BridgeCLIExample)
+4.3 [Config File Example](#BridgeConfigFileExample)
+ + +### 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. + + +### 2. Client-Only + + +**2.1 Description**
+ +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). + + +**2.2 Command Line Example**
+ +```bash +$ ./btcd --proxy=127.0.0.1:9050 +``` + + +**2.3 Config File Example**
+ +```text +[Application Options] + +proxy=127.0.0.1:9050 +``` + + +### 3. Client-Server via Tor Hidden Service + + +**3.1 Description**
+ +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 + + +**3.2 Command Line Example**
+ +```bash +$ ./btcd --proxy=127.0.0.1:9050 --listen=127.0.0.1 --externalip=fooanon.onion +``` + + +**3.3 Config File Example**
+ +```text +[Application Options] + +proxy=127.0.0.1:9050 +listen=127.0.0.1 +externalip=fooanon.onion +``` + + +### 4. Bridge Mode (Not Anonymous) + + +**4.1 Description**
+ +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. + + +**4.2 Command Line Example**
+ +```bash +$ ./btcd --onion=127.0.0.1:9050 --externalip=fooanon.onion +``` + + +**4.3 Config File Example**
+ +```text +[Application Options] + +onion=127.0.0.1:9050 +externalip=fooanon.onion +``` \ No newline at end of file diff --git a/docs/default_ports.md b/docs/default_ports.md new file mode 100644 index 00000000..14e4eea2 --- /dev/null +++ b/docs/default_ports.md @@ -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| diff --git a/docs/json_rpc_api.md b/docs/json_rpc_api.md new file mode 100644 index 00000000..bb267a88 --- /dev/null +++ b/docs/json_rpc_api.md @@ -0,0 +1,1121 @@ +### Table of Contents +1. [Overview](#Overview)
+2. [HTTP POST Versus Websockets](#HttpPostVsWebsockets)
+3. [Authentication](#Authentication)
+3.1. [Overview](#AuthenticationOverview)
+3.2. [HTTP Basic Access Authentication](#HTTPAuth)
+3.3. [JSON-RPC Authenticate Command (Websocket-specific)](#JSONAuth)
+4. [Command-line Utility](#CLIUtil)
+5. [Standard Methods](#Methods)
+5.1. [Method Overview](#MethodOverview)
+5.2. [Method Details](#MethodDetails)
+6. [Extension Methods](#ExtensionMethods)
+6.1. [Method Overview](#ExtMethodOverview)
+6.2. [Method Details](#ExtMethodDetails)
+7. [Websocket Extension Methods (Websocket-specific)](#WSExtMethods)
+7.1. [Method Overview](#WSExtMethodOverview)
+7.2. [Method Details](#WSExtMethodDetails)
+8. [Notifications (Websocket-specific)](#Notifications)
+8.1. [Notification Overview](#NotificationOverview)
+8.2. [Notification Details](#NotificationDetails)
+9. [Example Code](#ExampleCode)
+9.1. [Go](#ExampleGoApp)
+9.2. [node.js](#ExampleNodeJsCode)
+ + +### 1. Overview + +btcd provides a [JSON-RPC](http://json-rpc.org/wiki/specification) API that is +fully compatible with the original bitcoind/bitcoin-qt. There are a few key +differences between btcd and bitcoind as far as how RPCs are serviced: +* Unlike bitcoind that has the wallet and chain intermingled in the same process + which leads to several issues, btcd intentionally splits the wallet and chain + services into independent processes. See the blog post + [here](https://blog.conformal.com/btcd-not-your-moms-bitcoin-daemon/) for + further details on why they were separated. This means that if you are + talking directly to btcd, only chain-related RPCs are available. However both + chain-related and wallet-related RPCs are available via + [btcwallet](https://github.com/btcsuite/btcwallet). +* btcd is secure by default which means that the RPC connection is TLS-enabled + by default +* btcd provides access to the API through both + [HTTP POST](http://en.wikipedia.org/wiki/POST_%28HTTP%29) requests and + [Websockets](http://en.wikipedia.org/wiki/WebSocket) + +Websockets are the preferred transport for btcd RPC and are used by applications +such as [btcwallet](https://github.com/btcsuite/btcwallet) for inter-process +communication with btcd. The websocket connection endpoint for btcd is +`wss://your_ip_or_domain:8334/ws`. + +In addition to the [standard API](#Methods), an [extension API](#WSExtMethods) +has been developed that is exclusive to clients using Websockets. In its current +state, this API attempts to cover features found missing in the standard API +during the development of btcwallet. + +While the [standard API](#Methods) is stable, the +[Websocket extension API](#WSExtMethods) should be considered a work in +progress, incomplete, and susceptible to changes (both additions and removals). + +The original bitcoind/bitcoin-qt JSON-RPC API documentation is available at [https://en.bitcoin.it/wiki/Original_Bitcoin_client/API_Calls_list](https://en.bitcoin.it/wiki/Original_Bitcoin_client/API_Calls_list) + + +### 2. HTTP POST Versus Websockets + +The btcd RPC server supports both [HTTP POST](http://en.wikipedia.org/wiki/POST_%28HTTP%29) +requests and the preferred [Websockets](http://en.wikipedia.org/wiki/WebSocket). +All of the [standard](#Methods) and [extension](#ExtensionMethods) methods +described in this documentation can be accessed through both. As the name +indicates, the [Websocket-specific extension](#WSExtMethods) methods can only be +accessed when connected via Websockets. + +As mentioned in the [overview](#Overview), the websocket connection endpoint for +btcd is `wss://your_ip_or_domain:8334/ws`. + +The most important differences between the two transports as it pertains to the +JSON-RPC API are: + +| |HTTP POST Requests|Websockets| +|---|------------------|----------| +|Allows multiple requests across a single connection|No|Yes| +|Supports asynchronous notifications|No|Yes| +|Scales well with large numbers of requests|No|Yes| + + +### 3. Authentication + + +**3.1 Authentication Overview**
+ +The following authentication details are needed before establishing a connection +to a btcd RPC server: + +* **rpcuser** is the username that the btcd RPC server is configured with +* **rpcpass** is the password that the btcd RPC server is configured with +* **rpccert** is the PEM-encoded X.509 certificate (public key) that the btcd + server is configured with. It is automatically generated by btcd and placed + in the btcd home directory (which is typically `%LOCALAPPDATA%\Btcd` on + Windows and `~/.btcd` on POSIX-like OSes) + +**NOTE:** As mentioned above, btcd is secure by default which means the RPC +server is not running unless configured with a **rpcuser** and **rpcpass** and +uses TLS authentication for all connections. + +Depending on which connection transaction you are using, you can choose one of +two, mutually exclusive, methods. +- [Use HTTP Authorization Header](#HTTPAuth) - HTTP POST requests and Websockets +- [Use the JSON-RPC "authenticate" command](#JSONAuth) - Websockets only + + +**3.2 HTTP Basic Access Authentication**
+ +The btcd RPC server uses HTTP [basic access authentication](http://en.wikipedia.org/wiki/Basic_access_authentication) with the **rpcuser** +and **rpcpass** detailed above. If the supplied credentials are invalid, you +will be disconnected immediately upon making the connection. + + +**3.3 JSON-RPC Authenticate Command (Websocket-specific)**
+ +While the HTTP basic access authentication method is the preferred method, the +ability to set HTTP headers from websockets is not always available. In that +case, you will need to use the [authenticate](#authenticate) JSON-RPC method. + +The [authenticate](#authenticate) command must be the first command sent after +connecting to the websocket. Sending any other commands before authenticating, +supplying invalid credentials, or attempting to authenticate again when already +authenticated will cause the websocket to be closed immediately. + + + +### 4. Command-line Utility + +btcd comes with a separate utility named `btcctl` which can be used to issue +these RPC commands via HTTP POST requests to btcd after configuring it with the +information in the [Authentication](#Authentication) section above. It can also +be used to communicate with any server/daemon/service which provides a JSON-RPC +API compatible with the original bitcoind/bitcoin-qt client. + + +### 5. Standard Methods + + +**5.1 Method Overview**
+ +The following is an overview of the RPC methods and their current status. Click +the method name for further details such as parameter and return information. + +|#|Method|Description| +|---|------|-----------| +|1|[addnode](#addnode)|Attempts to add or remove a persistent peer.| +|2|[createrawtransaction](#createrawtransaction)|Returns a new transaction spending the provided inputs and sending to the provided addresses.| +|3|[decoderawtransaction](#decoderawtransaction)|Returns a JSON object representing the provided serialized, hex-encoded transaction.| +|4|[decodescript](#decodescript)|Returns a JSON object with information about the provided hex-encoded script.| +|5|[getaddednodeinfo](#getaddednodeinfo)|Returns information about manually added (persistent) peers.| +|6|[getbestblockhash](#getbestblockhash)|Returns the hash of the of the best (most recent) block in the longest block chain.| +|7|[getblock](#getblock)|Returns information about a block given its hash.| +|8|[getblockcount](#getblockcount)|Returns the number of blocks in the longest block chain.| +|9|[getblockhash](#getblockhash)|Returns hash of the block in best block chain at the given height.| +|10|[getconnectioncount](#getconnectioncount)|Returns the number of active connections to other peers.| +|11|[getdifficulty](#getdifficulty)|Returns the proof-of-work difficulty as a multiple of the minimum difficulty.| +|12|[getgenerate](#getgenerate)|Return if the server is set to generate coins (mine) or not.| +|13|[gethashespersec](#gethashespersec)|Returns a recent hashes per second performance measurement while generating coins (mining).| +|14|[getinfo](#getinfo)|Returns a JSON object containing various state info.| +|15|[getmininginfo](#getmininginfo)|Returns a JSON object containing mining-related information.| +|16|[getnettotals](#getnettotals)|Returns a JSON object containing network traffic statistics.| +|17|[getnetworkhashps](#getnetworkhashps)|Returns the estimated network hashes per second for the block heights provided by the parameters.| +|18|[getpeerinfo](#getpeerinfo)|Returns information about each connected network peer as an array of json objects.| +|19|[getrawmempool](#getrawmempool)|Returns an array of hashes for all of the transactions currently in the memory pool.| +|20|[getrawtransaction](#getrawtransaction)|Returns information about a transaction given its hash.| +|21|[getwork](#getwork)|Returns formatted hash data to work on or checks and submits solved data.
NOTE: Since btcd does not have the wallet integrated to provide payment addresses, btcd must be configured via the `--miningaddr` option to provide which payment addresses to pay created blocks to for this RPC to function.| +|22|[help](#help)|Returns a list of all commands or help for a specified command.| +|23|[ping](#ping)|Queues a ping to be sent to each connected peer.| +|24|[sendrawtransaction](#sendrawtransaction)|Submits the serialized, hex-encoded transaction to the local peer and relays it to the network.
btcd does not yet implement the `allowhighfees` parameter, so it has no effect| +|25|[setgenerate](#setgenerate) |Set the server to generate coins (mine) or not.
NOTE: Since btcd does not have the wallet integrated to provide payment addresses, btcd must be configured via the `--miningaddr` option to provide which payment addresses to pay created blocks to for this RPC to function.| +|26|[stop](#stop)|Shutdown btcd.| +|27|[submitblock](#submitblock)|Attempts to submit a new serialized, hex-encoded block to the network.| +|28|[validateaddress](#validateaddress)|Verifies the given address is valid. NOTE: Since btcd does not have a wallet integrated, btcd will only return whether the address is valid or not.| +|29|[verifychain](#verifychain)|Verifies the block chain database.| + + +**5.2 Method Details**
+ + + +| | | +|---|---| +|Method|addnode| +|Parameters|1. peer (string, required) - ip address and port of the peer tooperate on
2. command (string, required) - `add` to add a persistent peer, `remove` to remove a persistent peer, or `onetry` to try a single connection to a peer| +|Description|Attempts to add or remove a persistent peer.| +|Returns|Nothing| +[Return to Overview](#MethodOverview)
+ +*** + + +| | | +|---|---| +|Method|createrawtransaction| +|Parameters|1. transaction inputs (JSON array, required) - json array of json objects
`[`
  `{`
    `"txid": "hash", (string, required) the hash of the input transaction`
    `"vout": n (numeric, required) the specific output of the input transaction to redeem`
  `}, ...`
`]`
2. addresses and amounts (JSON object, required) - json object with addresses as keys and amounts as values
`{`
  `"address": n.nnn (numeric, required) the address to send to as the key and the amount in BTC as the value`
  `, ...`
`}`| +|Description|Returns a new transaction spending the provided inputs and sending to the provided addresses.
The transaction inputs are not signed in the created transaction.
The `signrawtransaction` RPC command provided by wallet must be used to sign the resulting transaction.| +|Returns|`"transaction" (string) hex-encoded bytes of the serialized transaction`| +|Example Parameters|1. transaction inputs `[{"txid":"e6da89de7a6b8508ce8f371a3d0535b04b5e108cb1a6e9284602d3bfd357c018","vout":1}]`
2. addresses and amounts `{"13cgrTP7wgbZYWrY9BZ22BV6p82QXQT3nY": 0.49213337}`| +|Example Return|`010000000118c057d3bfd3024628e9a6b18c105e4bb035053d1a378fce08856b7ade89dae6010000`
`0000ffffffff0199efee02000000001976a9141cb013db35ecccc156fdfd81d03a11c51998f99388`
`ac00000000`
**Newlines added for display purposes. The actual return does not contain newlines.**| +[Return to Overview](#MethodOverview)
+ +*** + + +| | | +|---|---| +|Method|decoderawtransaction| +|Parameters|1. data (string, required) - serialized, hex-encoded transaction| +|Description|Returns a JSON object representing the provided serialized, hex-encoded transaction.| +|Returns|`{ (json object)`
  `"txid": "hash", (string) the hash of the transaction`
  `"version": n, (numeric) the transaction version`
  `"locktime": n, (numeric) the transaction lock time`
  `"vin": [ (array of json objects) the transaction inputs as json objects`
  For coinbase transactions:
    `{ (json object)`
      `"coinbase": "data", (string) the hex-dencoded bytes of the signature script`
      `"sequence": n, (numeric) the script sequence number`
    `}`
  For non-coinbase transactions:
    `{ (json object)`
      `"txid": "hash", (string) the hash of the origin transaction`
      `"vout": n, (numeric) the index of the output being redeemed from the origin transaction`
      `"scriptSig": { (json object) the signature script used to redeem the origin transaction`
        `"asm": "asm", (string) disassembly of the script`
        `"hex": "data", (string) hex-encoded bytes of the script`
      `}`
      `"sequence": n, (numeric) the script sequence number`
    `}, ...`
  `]`
  `"vout": [ (array of json objects) the transaction outputs as json objects`
    `{ (json object)`
      `"value": n, (numeric) the value in BTC`
      `"n": n, (numeric) the index of this transaction output`
      `"scriptPubKey": { (json object) the public key script used to pay coins`
        `"asm": "asm", (string) disassembly of the script`
        `"hex": "data", (string) hex-encoded bytes of the script`
        `"reqSigs": n, (numeric) the number of required signatures`
        `"type": "scripttype" (string) the type of the script (e.g. 'pubkeyhash')`
        `"addresses": [ (json array of string) the bitcoin addresses associated with this output`
          `"bitcoinaddress", (string) the bitcoin address`
          `...`
        `]`
      `}`
    `}, ...`
  `]`
`}`| +|Example Return|`{`
  `"txid": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b",`
  `"version": 1,`
  `"locktime": 0,`
  `"vin": [`
  For coinbase transactions:
    `{ (json object)`
      `"coinbase": "04ffff001d0104455468652054696d65732030332f4a616e2f32303039204368616e63656c6c6...",`
      `"sequence": 4294967295,`
    `}`
  For non-coinbase transactions:
    `{`
      `"txid": "60ac4b057247b3d0b9a8173de56b5e1be8c1d1da970511c626ef53706c66be04",`
      `"vout": 0,`
      `"scriptSig": {`
        `"asm": "3046022100cb42f8df44eca83dd0a727988dcde9384953e830b1f8004d57485e2ede1b9c8f0...",`
        `"hex": "493046022100cb42f8df44eca83dd0a727988dcde9384953e830b1f8004d57485e2ede1b9c8...",`
      `}`
      `"sequence": 4294967295,`
    `}`
  `]`
  `"vout": [`
    `{`
      `"value": 50,`
      `"n": 0,`
      `"scriptPubKey": {`
        `"asm": "04678afdb0fe5548271967f1a67130b7105cd6a828e03909a67962e0ea1f61deb649f6bc3f4ce...",`
        `"hex": "4104678afdb0fe5548271967f1a67130b7105cd6a828e03909a67962e0ea1f61deb649f6bc3f4...",`
        `"reqSigs": 1,`
        `"type": "pubkey"`
        `"addresses": [`
          `"1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",`
        `]`
      `}`
    `}`
  `]`
`}`| +[Return to Overview](#MethodOverview)
+ +*** + + +| | | +|---|---| +|Method|decodescript| +|Parameters|1. script (string, required) - hex-encoded script| +|Description|Returns a JSON object with information about the provided hex-encoded script.| +|Returns|`{ (json object)`
  `"asm": "asm", (string) disassembly of the script`
  `"reqSigs": n, (numeric) the number of required signatures`
  `"type": "scripttype", (string) the type of the script (e.g. 'pubkeyhash')`
  `"addresses": [ (json array of string) the bitcoin addresses associated with this script`
    `"bitcoinaddress", (string) the bitcoin address`
    `...`
  `]`
  `"p2sh": "scripthash", (string) the script hash for use in pay-to-script-hash transactions`
`}`| +|Example Return|`{`
  `"asm": "OP_DUP OP_HASH160 b0a4d8a91981106e4ed85165a66748b19f7b7ad4 OP_EQUALVERIFY OP_CHECKSIG",`
  `"reqSigs": 1,`
  `"type": "pubkeyhash",`
  `"addresses": [`
    `"1H71QVBpzuLTNUh5pewaH3UTLTo2vWgcRJ"`
  `]`
  `"p2sh": "359b84ff799f48231990ff0298206f54117b08b6"`
`}`| +[Return to Overview](#MethodOverview)
+ +*** + + +| | | +|---|---| +|Method|getaddednodeinfo| +|Parameters|1. dns (boolean, required) - specifies whether the returned data is a JSON object including DNS and connection information, or just a list of added peers
2. node (string, optional) - only return information about this specific peer instead of all added peers.| +|Description|Returns information about manually added (persistent) peers.| +|Returns (dns=false)|`["ip:port", ...]`| +|Returns (dns=true)|`[ (json array of objects)`
  `{ (json object)`
    `"addednode": "ip_or_domain", (string) the ip address or domain of the added peer`
    `"connected": true or false, (boolean) whether or not the peer is currently connected`
    `"addresses": [ (json array or objects) DNS lookup and connection information about the peer`
      `{ (json object)`
        `"address": "ip", (string) the ip address for this DNS entry`
        `"connected": "inbound/outbound/false" (string) the connection 'direction' (if connected)`
      `}, ...`
    `]`
  `}, ...`
`]`| +|Example Return (dns=false)|`["192.168.0.10:8333", "mydomain.org:8333"]`| +|Example Return (dns=true)|`[`
  `{`
    `"addednode": "mydomain.org:8333",`
    `"connected": true,`
    `"addresses": [`
      `{`
        `"address": "1.2.3.4",`
        `"connected": "outbound"`
      `},`
      `{`
        `"address": "5.6.7.8",`
        `"connected": "false"`
      `}`
    `]`
  `}`
`]`| +[Return to Overview](#MethodOverview)
+ +*** + + +| | | +|---|---| +|Method|getbestblockhash| +|Parameters|None| +|Description|Returns the hash of the of the best (most recent) block in the longest block chain.| +|Returns|string| +|Example Return|`0000000000000001f356adc6b29ab42b59f913a396e170f80190dba615bd1e60`| +[Return to Overview](#MethodOverview)
+ +*** + + +| | | +|---|---| +|Method|getblock| +|Parameters|1. block hash (string, required) - the hash of the block
2. verbose (boolean, optional, default=true) - specifies the block is returned as a JSON object instead of hex-encoded string
3. verbosetx (boolean, optional, default=false) - specifies that each transaction is returned as a JSON object and only applies if the `verbose` flag is true.**This parameter is a btcd extension**| +|Description|Returns information about a block given its hash.| +|Returns (verbose=false)|`"data" (string) hex-encoded bytes of the serialized block`| +|Returns (verbose=true, verbosetx=false)|`{ (json object)`
  `"hash": "blockhash", (string) the hash of the block (same as provided)`
  `"confirmations": n, (numeric) the number of confirmations`
  `"size": n, (numeric) the size of the block`
  `"height": n, (numeric) the height of the block in the block chain`
  `"version": n, (numeric) the block version`
  `"merkleroot": "hash", (string) root hash of the merkle tree`
  `"tx": [ (json array of string) the transaction hashes`
    `"transactionhash", (string) hash of the parent transaction`
    `...`
  `]`
  `"time": n, (numeric) the block time in seconds since 1 Jan 1970 GMT`
  `"nonce": n, (numeric) the block nonce`
  `"bits", n, (numeric) the bits which represent the block difficulty`
  `difficulty: n.nn, (numeric) the proof-of-work difficulty as a multiple of the minimum difficulty`
  `"previousblockhash": "hash", (string) the hash of the previous block`
  `"nextblockhash": "hash", (string) the hash of the next block`
`}`| +|Returns (verbose=true, verbosetx=true)|`{ (json object)`
  `"hash": "blockhash", (string) the hash of the block (same as provided)`
  `"confirmations": n, (numeric) the number of confirmations`
  `"size": n, (numeric) the size of the block`
  `"height": n, (numeric) the height of the block in the block chain`
  `"version": n, (numeric) the block version`
  `"merkleroot": "hash", (string) root hash of the merkle tree`
  `"rawtx": [ (array of json objects) the transactions as json objects`
    `(see getrawtransaction json object details)`
  `]`
  `"time": n, (numeric) the block time in seconds since 1 Jan 1970 GMT`
  `"nonce": n, (numeric) the block nonce`
  `"bits", n, (numeric) the bits which represent the block difficulty`
  `difficulty: n.nn, (numeric) the proof-of-work difficulty as a multiple of the minimum difficulty`
  `"previousblockhash": "hash", (string) the hash of the previous block`
  `"nextblockhash": "hash", (string) the hash of the next block`
`}`| +|Example Return (verbose=false)|`"010000000000000000000000000000000000000000000000000000000000000000000000`
`3ba3edfd7a7b12b27ac72c3e67768f617fc81bc3888a51323a9fb8aa4b1e5e4a29ab5f49`
`ffff001d1dac2b7c01010000000100000000000000000000000000000000000000000000`
`00000000000000000000ffffffff4d04ffff001d0104455468652054696d65732030332f`
`4a616e2f32303039204368616e63656c6c6f72206f6e206272696e6b206f66207365636f`
`6e64206261696c6f757420666f722062616e6b73ffffffff0100f2052a01000000434104`
`678afdb0fe5548271967f1a67130b7105cd6a828e03909a67962e0ea1f61deb649f6bc3f`
`4cef38c4f35504e51ec112de5c384df7ba0b8d578a4c702b6bf11d5fac00000000"`
**Newlines added for display purposes. The actual return does not contain newlines.**| +|Example Return (verbose=true, verbosetx=false)|`{`
  `"hash": "000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f",`
  `"confirmations": 277113,`
  `"size": 285,`
  `"height": 0,`
  `"version": 1,`
  `"merkleroot": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b",`
  `"tx": [`
    `"4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b"`
  `],`
  `"time": 1231006505,`
  `"nonce": 2083236893,`
  `"bits": "1d00ffff",`
  `"difficulty": 1,`
  `"previousblockhash": "0000000000000000000000000000000000000000000000000000000000000000",`
  `"nextblockhash": "00000000839a8e6886ab5951d76f411475428afc90947ee320161bbf18eb6048"`
`}`| +[Return to Overview](#MethodOverview)
+ +*** + + +| | | +|---|---| +|Method|getblockcount| +|Parameters|None| +|Description|Returns the number of blocks in the longest block chain.| +|Returns|numeric| +|Example Return|`276820`| +[Return to Overview](#MethodOverview)
+ +*** + + +| | | +|---|---| +|Method|getblockhash| +|Parameters|1. block height (numeric, required)| +|Description|Returns hash of the block in best block chain at the given height.| +|Returns|string| +|Example Return|`000000000000000096579458d1c0f1531fcfc58d57b4fce51eb177d8d10e784d`| +[Return to Overview](#MethodOverview)
+ +*** + + +| | | +|---|---| +|Method|getconnectioncount| +|Parameters|None| +|Description|Returns the number of active connections to other peers| +|Returns|numeric| +|Example Return|`8`| +[Return to Overview](#MethodOverview)
+ +*** + + +| | | +|---|---| +|Method|getdifficulty| +|Parameters|None| +|Description|Returns the proof-of-work difficulty as a multiple of the minimum difficulty.| +|Returns|numeric| +|Example Return|`1180923195.260000`| +[Return to Overview](#MethodOverview)
+ +*** + + +| | | +|---|---| +|Method|getgenerate| +|Parameters|None| +|Description|Return if the server is set to generate coins (mine) or not.| +|Returns|`false` (boolean)| +[Return to Overview](#MethodOverview)
+ +*** + + +| | | +|---|---| +|Method|gethashespersec| +|Parameters|None| +|Description|Returns a recent hashes per second performance measurement while generating coins (mining).| +|Returns|`0` (numeric)| +[Return to Overview](#MethodOverview)
+ +*** + + +| | | +|---|---| +|Method|getinfo| +|Parameters|None| +|Description|Returns a JSON object containing various state info.| +|Notes|NOTE: Since btcd does NOT contain wallet functionality, wallet-related fields are not returned. See getinfo in btcwallet for a version which includes that information.| +|Returns|`{ (json object)`
  `"version": n, (numeric) the version of the server`
  `"protocolversion": n, (numeric) the latest supported protocol version`
  `"blocks": n, (numeric) the number of blocks processed`
  `"timeoffset": n, (numeric) the time offset`
  `"connections": n, (numeric) the number of connected peers`
  `"proxy": "host:port", (string) the proxy used by the server`
  `"difficulty": n.nn, (numeric) the current target difficulty`
  `"testnet": true or false, (boolean) whether or not server is using testnet`
  `"relayfee": n.nn, (numeric) the minimum relay fee for non-free transactions in BTC/KB`
`}`| +|Example Return|`{`
  `"version": 70000`
  `"protocolversion": 70001, `
  `"blocks": 298963,`
  `"timeoffset": 0,`
  `"connections": 17,`
  `"proxy": "",`
  `"difficulty": 8000872135.97,`
  `"testnet": false,`
  `"relayfee": 0.00001,`
`}`| +[Return to Overview](#MethodOverview)
+ +*** + + +| | | +|---|---| +|Method|getmininginfo| +|Parameters|None| +|Description|Returns a JSON object containing mining-related information.| +|Returns|`{ (json object)`
  `"blocks": n, (numeric) latest best block`
  `"currentblocksize": n, (numeric) size of the latest best block`
  `"currentblocktx": n, (numeric) number of transactions in the latest best block`
  `"difficulty": n.nn, (numeric) current target difficulty`
  `"errors": "errors", (string) any current errors`
  `"generate": true or false, (boolean) whether or not server is set to generate coins`
  `"genproclimit": n, (numeric) number of processors to use for coin generation (-1 when disabled)`
  `"hashespersec": n, (numeric) recent hashes per second performance measurement while generating coins`
  `"networkhashps": n, (numeric) estimated network hashes per second for the most recent blocks`
  `"pooledtx": n, (numeric) number of transactions in the memory pool`
  `"testnet": true or false, (boolean) whether or not server is using testnet`
`}`| +|Example Return|`{`
  `"blocks": 236526,`
  `"currentblocksize": 185,`
  `"currentblocktx": 1,`
  `"difficulty": 256,`
  `"errors": "",`
  `"generate": false,`
  `"genproclimit": -1,`
  `"hashespersec": 0,`
  `"networkhashps": 33081554756,`
  `"pooledtx": 8,`
  `"testnet": true,`
`}`| +[Return to Overview](#MethodOverview)
+ +*** + + +| | | +|---|---| +|Method|getnettotals| +|Parameters|None| +|Description|Returns a JSON object containing network traffic statistics.| +|Returns|`{`
  `"totalbytesrecv": n, (numeric) total bytes received`
  `"totalbytessent": n, (numeric) total bytes sent`
  `"timemillis": n (numeric) number of milliseconds since 1 Jan 1970 GMT`
`}`| +|Example Return|`{`
  `"totalbytesrecv": 1150990,`
  `"totalbytessent": 206739,`
  `"timemillis": 1391626433845`
`}`| +[Return to Overview](#MethodOverview)
+ +*** + + +| | | +|---|---| +|Method|getnetworkhashps| +|Parameters|1. blocks (numeric, optional, default=120) - The number of blocks, or -1 for blocks since last difficulty change
2. height (numeric, optional, default=-1) - Perform estimate ending with this height or -1 for current best chain block height| +|Description|Returns the estimated network hashes per second for the block heights provided by the parameters.| +|Returns|numeric| +|Example Return|`6573971939`| +[Return to Overview](#MethodOverview)
+ +*** + + +| | | +|---|---| +|Method|getpeerinfo| +|Parameters|None| +|Description|Returns data about each connected network peer as an array of json objects.| +|Returns|`[`
  `{`
    `"addr": "host:port", (string) the ip address and port of the peer`
    `"services": "00000001", (string) the services supported by the peer`
    `"lastrecv": n, (numeric) time the last message was received in seconds since 1 Jan 1970 GMT`
    `"lastsend": n, (numeric) time the last message was sent in seconds since 1 Jan 1970 GMT`
    `"bytessent": n, (numeric) total bytes sent`
    `"bytesrecv": n, (numeric) total bytes received`
    `"conntime": n, (numeric) time the connection was made in seconds since 1 Jan 1970 GMT`
    `"pingtime": n, (numeric) number of microseconds the last ping took`
    `"pingwait": n, (numeric) number of microseconds a queued ping has been waiting for a response`
    `"version": n, (numeric) the protocol version of the peer`
    `"subver": "useragent", (string) the user agent of the peer`
    `"inbound": true_or_false, (boolean) whether or not the peer is an inbound connection`
    `"startingheight": n, (numeric) the latest block height the peer knew about when the connection was established`
    `"syncnode": true_or_false, (boolean) whether or not the peer is the sync peer`
  `}, ...`
`]`| +|Example Return|`[`
  `{`
    `"addr": "178.172.xxx.xxx:8333",`
    `"services": "00000001",`
    `"lastrecv": 1388183523,`
    `"lastsend": 1388185470,`
    `"bytessent": 287592965,`
    `"bytesrecv": 780340,`
    `"conntime": 1388182973,`
    `"pingtime": 405551,`
    `"pingwait": 183023,`
    `"version": 70001,`
    `"subver": "/btcd:0.4.0/",`
    `"inbound": false,`
    `"startingheight": 276921,`
    `"syncnode": true,`
  `}`
`]`| +[Return to Overview](#MethodOverview)
+ +*** + + +| | | +|---|---| +|Method|getrawtransaction| +|Parameters|1. transaction hash (string, required) - the hash of the transaction
2. verbose (int, optional, default=0) - specifies the transaction is returned as a JSON object instead of hex-encoded string| +|Description|Returns information about a transaction given its hash.| +|Returns (verbose=0)|`"data" (string) hex-encoded bytes of the serialized transaction`| +|Returns (verbose=1)|`{ (json object)`
  `"hex": "data", (string) hex-encoded transaction`
  `"txid": "hash", (string) the hash of the transaction`
  `"version": n, (numeric) the transaction version`
  `"locktime": n, (numeric) the transaction lock time`
  `"vin": [ (array of json objects) the transaction inputs as json objects`
  For coinbase transactions:
    `{ (json object)`
      `"coinbase": "data", (string) the hex-dencoded bytes of the signature script`
      `"sequence": n, (numeric) the script sequence number`
    `}`
  For non-coinbase transactions:
    `{ (json object)`
      `"txid": "hash", (string) the hash of the origin transaction`
      `"vout": n, (numeric) the index of the output being redeemed from the origin transaction`
      `"scriptSig": { (json object) the signature script used to redeem the origin transaction`
        `"asm": "asm", (string) disassembly of the script`
        `"hex": "data", (string) hex-encoded bytes of the script`
      `}`
      `"sequence": n, (numeric) the script sequence number`
    `}, ...`
  `]`
  `"vout": [ (array of json objects) the transaction outputs as json objects`
    `{ (json object)`
      `"value": n, (numeric) the value in BTC`
      `"n": n, (numeric) the index of this transaction output`
      `"scriptPubKey": { (json object) the public key script used to pay coins`
        `"asm": "asm", (string) disassembly of the script`
        `"hex": "data", (string) hex-encoded bytes of the script`
        `"reqSigs": n, (numeric) the number of required signatures`
        `"type": "scripttype" (string) the type of the script (e.g. 'pubkeyhash')`
        `"addresses": [ (json array of string) the bitcoin addresses associated with this output`
          `"bitcoinaddress", (string) the bitcoin address`
          `...`
        `]`
      `}`
    `}, ...`
  `]`
`}`| +|Example Return (verbose=0)|`"010000000104be666c7053ef26c6110597dad1c1e81b5e6be53d17a8b9d0b34772054bac60000000`
`008c493046022100cb42f8df44eca83dd0a727988dcde9384953e830b1f8004d57485e2ede1b9c8f`
`022100fbce8d84fcf2839127605818ac6c3e7a1531ebc69277c504599289fb1e9058df0141045a33`
`76eeb85e494330b03c1791619d53327441002832f4bd618fd9efa9e644d242d5e1145cb9c2f71965`
`656e276633d4ff1a6db5e7153a0a9042745178ebe0f5ffffffff0280841e00000000001976a91406`
`f1b6703d3f56427bfcfd372f952d50d04b64bd88ac4dd52700000000001976a9146b63f291c295ee`
`abd9aee6be193ab2d019e7ea7088ac00000000`
**Newlines added for display purposes. The actual return does not contain newlines.**| +|Example Return (verbose=1)|`{`
  `"hex": "01000000010000000000000000000000000000000000000000000000000000000000000000f...",`
  `"txid": "90743aad855880e517270550d2a881627d84db5265142fd1e7fb7add38b08be9",`
  `"version": 1,`
  `"locktime": 0,`
  `"vin": [`
  For coinbase transactions:
    `{ (json object)`
      `"coinbase": "03708203062f503253482f04066d605108f800080100000ea2122f6f7a636f696e4065757374726174756d2f",`
      `"sequence": 0,`
    `}`
  For non-coinbase transactions:
    `{`
      `"txid": "60ac4b057247b3d0b9a8173de56b5e1be8c1d1da970511c626ef53706c66be04",`
      `"vout": 0,`
      `"scriptSig": {`
        `"asm": "3046022100cb42f8df44eca83dd0a727988dcde9384953e830b1f8004d57485e2ede1b9c8f0...",`
        `"hex": "493046022100cb42f8df44eca83dd0a727988dcde9384953e830b1f8004d57485e2ede1b9c8...",`
      `}`
      `"sequence": 4294967295,`
    `}`
  `]`
  `"vout": [`
    `{`
      `"value": 25.1394,`
      `"n": 0,`
      `"scriptPubKey": {`
        `"asm": "OP_DUP OP_HASH160 ea132286328cfc819457b9dec386c4b5c84faa5c OP_EQUALVERIFY OP_CHECKSIG",`
        `"hex": "76a914ea132286328cfc819457b9dec386c4b5c84faa5c88ac",`
        `"reqSigs": 1,`
        `"type": "pubkeyhash"`
        `"addresses": [`
          `"1NLg3QJMsMQGM5KEUaEu5ADDmKQSLHwmyh",`
        `]`
      `}`
    `}`
  `]`
`}`| +[Return to Overview](#MethodOverview)
+ +*** + + +| | | +|---|---| +|Method|getwork| +|Parameters|1. data (string, optional) - The hex| +|Description|Returns information about a transaction given its hash.| +|Notes|NOTE: Since btcd does not have the wallet integrated to provide payment addresses, btcd must be configured via the `--miningaddr` option to provide which payment addresses to pay created blocks to for this RPC to function. +|Returns (data not specified)|`{ (json object)`
  `"data": "hex", (string) hex-encoded block data`
  `"hash1": "hex", (string) (DEPRECATED) hex-encoded formatted hash buffer`
  `"midstate": "hex", (string) (DEPRECATED) hex-encoded precomputed hash state after hashing first half of the data`
  `"target": "hex", (string) the hex-encoded little-endian hash target`
`}`| +|Returns (data specified)|`true` or `false` (boolean)| +|Example Return (data not specified)|`{`
  `"data": "00000002c39b5d2b7a1e8f7356a1efce26b24bd15d7d906e85341ef9cec99b6a000000006474f...",`
  `"hash1": "00000000000000000000000000000000000000000000000000000000000000000000008000000...",`
  `"midstate": "ae4a80fc51476e452de855b4e20d5f33418c50fc7cae3b1ecd5badb819b8a584",`
  `"target": "0000000000000000000000000000000000000000000000008c96010000000000",`
`}`| +|Example Return (data specified)|`true`| +[Return to Overview](#MethodOverview)
+ +*** + + +| | | +|---|---| +|Method|help| +|Parameters|1. command (string, optional) - the command to get help for| +|Description|Returns a list of all commands or help for a specified command.
When no `command` parameter is specified, a list of avaialable commands is returned
When `command` is a valid method, the help text for that method is returned.| +|Returns|string| +|Example Return|getblockcount
Returns a numeric for the number of blocks in the longest block chain.| +[Return to Overview](#MethodOverview)
+ +*** + + +| | | +|---|---| +|Method|ping| +|Parameters|None| +|Description|Queues a ping to be sent to each connected peer.
Ping times are provided by [getpeerinfo](#getpeerinfo) via the `pingtime` and `pingwait` fields.| +|Returns|Nothing| +[Return to Overview](#MethodOverview)
+ +*** + + +| | | +|---|---| +|Method|getrawmempool| +|Parameters|1. verbose (boolean, optional, default=false)| +|Description|Returns an array of hashes for all of the transactions currently in the memory pool.
The `verbose` flag specifies that each transaction is returned as a JSON object.| +|Notes|Since btcd does not perform any mining, the priority related fields `startingpriority` and `currentpriority` that are available when the `verbose` flag is set are always 0.| +|Returns (verbose=false)|`[ (json array of string)`
  `"transactionhash", (string) hash of the transaction`
  `...`
`]`| +|Returns (verbose=true)|`{ (json object)`
  `"transactionhash": { (json object)`
    `"size": n, (numeric) transaction size in bytes`
    `"fee" : n, (numeric) transaction fee in bitcoins`
    `"time": n, (numeric) local time transaction entered pool in seconds since 1 Jan 1970 GMT`
    `"height": n, (numeric) block height when transaction entered the pool`
    `"startingpriority": n, (numeric) priority when transaction entered the pool`
    `"currentpriority": n, (numeric) current priority`
    `"depends": [ (json array) unconfirmed transactions used as inputs for this transaction`
      `"transactionhash", (string) hash of the parent transaction`
      `...`
    `]`
  `}, ...`
`}`| +|Example Return (verbose=false)|`[`
  `"3480058a397b6ffcc60f7e3345a61370fded1ca6bef4b58156ed17987f20d4e7",`
  `"cbfe7c056a358c3a1dbced5a22b06d74b8650055d5195c1c2469e6b63a41514a"`
`]`| +|Example Return (verbose=true)|`{`
  `"1697a19cede08694278f19584e8dcc87945f40c6b59a942dd8906f133ad3f9cc": {`
    `"size": 226,`
    `"fee" : 0.0001,`
    `"time": 1387992789,`
    `"height": 276836,`
    `"startingpriority": 0,`
    `"currentpriority": 0,`
    `"depends": [`
      `"aa96f672fcc5a1ec6a08a94aa46d6b789799c87bd6542967da25a96b2dee0afb",`
    `]`
`}`| +[Return to Overview](#MethodOverview)
+ +*** + + +| | | +|---|---| +|Method|setgenerate| +|Parameters|1. generate (boolean, required) - `true` to enable generation, `false` to disable it
2. genproclimit (numeric, optional) - the number of processors (cores) to limit generation to or `-1` for default| +|Description|Set the server to generate coins (mine) or not.| +|Notes|NOTE: Since btcd does not have the wallet integrated to provide payment addresses, btcd must be configured via the `--miningaddr` option to provide which payment addresses to pay created blocks to for this RPC to function.| +|Returns|Nothing| +[Return to Overview](#MethodOverview)
+ +*** + + +| | | +|---|---| +|Method|sendrawtransaction| +|Parameters|1. signedhex (string, required) serialized, hex-encoded signed transaction
2. allowhighfees (boolean, optional, default=false) whether or not to allow insanely high fees| +|Description|Submits the serialized, hex-encoded transaction to the local peer and relays it to the network.| +|Notes|btcd does not yet implement the `allowhighfees` parameter, so it has no effect| +|Returns|`"hash" (string) the hash of the transaction`| +|Example Return|`"1697a19cede08694278f19584e8dcc87945f40c6b59a942dd8906f133ad3f9cc"`| +[Return to Overview](#MethodOverview)
+ +*** + + +| | | +|---|---| +|Method|submitblock| +|Parameters|1. data (string, required) serialized, hex-encoded block
2. params (json object, optional, default=nil) this parameter is currently ignored| +|Description|Attempts to submit a new serialized, hex-encoded block to the network.| +|Returns (success)|Success: Nothing
Failure: `"rejected: reason"` (string)| +[Return to Overview](#MethodOverview)
+ +*** + + +| | | +|---|---| +|Method|stop| +|Parameters|None| +|Description|Shutdown btcd.| +|Returns|`"btcd stopping."` (string)| +[Return to Overview](#MethodOverview)
+ +*** + + +| | | +|---|---| +|Method|validateaddress| +|Parameters|1. address (string, required) - bitcoin address| +|Description|Verify an address is valid.| +|Returns|`{ (json object)`
  `"isvalid": true or false, (bool) whether or not the address is valid.`
  `"address": "bitcoinaddress", (string) the bitcoin address validated.`
}| +[Return to Overview](#MethodOverview)
+ +*** + + +| | | +|---|---| +|Method|verifychain| +|Parameters|1. checklevel (numeric, optional, default=3) - how in-depth the verification is (0=least amount of checks, higher levels are clamped to the highest supported level)
2. numblocks (numeric, optional, default=288) - the number of blocks starting from the end of the chain to verify| +|Description|Verifies the block chain database.
The actual checks performed by the `checklevel` parameter is implementation specific. For btcd this is:
`checklevel=0` - Look up each block and ensure it can be loaded from the database.
`checklevel=1` - Perform basic context-free sanity checks on each block.| +|Notes|Btcd currently only supports `checklevel` 0 and 1, but the default is still 3 for compatibility. Per the information in the Parameters section above, higher levels are automatically clamped to the highest supported level, so this means the default is effectively 1 for btcd.| +|Returns|`true` or `false` (boolean)| +|Example Return|`true`| +[Return to Overview](#MethodOverview)
+ + + +### 6. Extension Methods + + +**6.1 Method Overview**
+ +The following is an overview of the RPC methods which are implemented by btcd, but not the original bitcoind client. Click the method name for further details such as parameter and return information. + +|#|Method|Description| +|---|------|-----------| +|1|[debuglevel](#debuglevel)|Dynamically changes the debug logging level.| +|2|[getbestblock](#getbestblock)|Get block height and hash of best block in the main chain.|None| +|3|[getcurrentnet](#getcurrentnet)|Get bitcoin network btcd is running on.|None| + + +**6.2 Method Details**
+ + + +| | | +|---|---| +|Method|debuglevel| +|Parameters|1. _levelspec_ (string)| +|Description|Dynamically changes the debug logging level.
The levelspec can either a debug level or of the form `=,=,...`
The valid debug levels are `trace`, `debug`, `info`, `warn`, `error`, and `critical`.
The valid subsystems are `AMGR`, `BCDB`, `BMGR`, `BTCD`, `CHAN`, `DISC`, `PEER`, `RPCS`, `SCRP`, `SRVR`, and `TXMP`.
Additionally, the special keyword `show` can be used to get a list of the available subsystems.| +|Returns|string| +|Example Return|`Done.`| +|Example `show` Return|`Supported subsystems [AMGR BCDB BMGR BTCD CHAN DISC PEER RPCS SCRP SRVR TXMP]`| +[Return to Overview](#ExtMethodOverview)
+ +*** + + + +| | | +|---|---| +|Method|getbestblock| +|Parameters|None| +|Description|Get block height and hash of best block in the main chain.| +|Returns|`{ (json object)`
 `"hash": "data", (string) the hex-encoded bytes of the best block hash`
 `"height": n (numeric) the block height of the best block`
`}`| +[Return to Overview](#ExtMethodOverview)
+ +*** + + + +| | | +|---|---| +|Method|getcurrentnet| +|Parameters|None| +|Description|Get bitcoin network btcd is running on.| +|Returns|numeric| +|Example Return|`3652501241` (mainnet)
`118034699` (testnet3)| +[Return to Overview](#ExtMethodOverview)
+ +*** + + +### 7. Websocket Extension Methods (Websocket-specific) + + +**7.1 Method Overview**
+ +The following is an overview of the RPC method requests available exclusively to Websocket clients. Click the method name for further details such as parameter and return information. + +|#|Method|Description|Notifications| +|---|------|-----------|-------------| +|1|[authenticate](#authenticate)|Authenticate the connection against the username and passphrase configured for the RPC server.
NOTE: This is only required if an HTTP Authorization header is not being used.|None| +|2|[notifyblocks](#notifyblocks)|Send notifications when a block is connected or disconnected from the best chain.|[blockconnected](#blockconnected) and [blockdisconnected](#blockdisconnected)| +|3|[notifyreceived](#notifyreceived)|Send notifications when a txout spends to an address.|[recvtx](#recvtx) and [redeemingtx](#redeemingtx)| +|4|[notifyspent](#notifyspent)|Send notification when a txout is spent.|[redeemingtx](#redeemingtx)| +|5|[rescan](#rescan)|Rescan block chain for transactions to addresses and spent transaction outpoints.|[recvtx](#recvtx), [redeemingtx](#redeemingtx), [rescanprogress](#rescanprogress), and [rescanfinished](#rescanfinished) | +|6|[notifynewtransactions](#notifynewtransactions)|Send notifications for all new transactions as they are accepted into the mempool.|[txaccepted](#txaccepted) or [txacceptedverbose](#txacceptedverbose)| + + +**7.2 Method Details**
+ + + +| | | +|---|---| +|Method|authenticate| +|Parameters|1. username (string, required)
2. passphrase (string, required)| +|Description|Authenticate the connection against the username and password configured for the RPC server.
Invoking any other method before authenticating with this command will close the connection.
NOTE: This is only required if an HTTP Authorization header is not being used.| +|Returns|Success: Nothing
Failure: Nothing (websocket disconnected)| +[Return to Overview](#ExtensionRequestOverview)
+ + + +| | | +|---|---| +|Method|notifyblocks| +|Notifications|[blockconnected](#blockconnected) and [blockdisconnected](#blockdisconnected)| +|Parameters|None| +|Description|Request notifications for whenever a block is connected or disconnected from the main (best) chain.| +|Returns|Nothing| +[Return to Overview](#ExtensionRequestOverview)
+ +*** + + + +| | | +|---|---| +|Method|notifyreceived| +|Notifications|[recvtx](#recvtx) and [redeemingtx](#redeemingtx)| +|Parameters|1. Addresses (JSON array, required)
 `[ (json array of strings)`
  `"bitcoinaddress", (string) the bitcoin address`
  `...`
 `]`| +|Description|Send a recvtx notification when a transaction added to mempool or appears in a newly-attached block contains a txout pkScript sending to any of the passed addresses. Matching outpoints are automatically registered for redeemingtx notifications.| +|Returns|Nothing| +[Return to Overview](#ExtensionRequestOverview)
+ +*** + + + +| | | +|---|---| +|Method|notifyspent| +|Notifications|[redeemingtx](#redeemingtx)| +|Parameters|1. Outpoints (JSON array, required)
 `[ (JSON array)`
  `{ (JSON object)`
   `"hash":"data", (string) the hex-encoded bytes of the outpoint hash`
   `"index":n (numeric) the txout index of the outpoint`
  `},`
  `...`
 `]`| +|Description|Send a redeemingtx notification when a transaction spending an outpoint appears in mempool (if relayed to this btcd instance) and when such a transaction first appears in a newly-attached block.| +|Returns|Nothing| +[Return to Overview](#ExtensionRequestOverview)
+ +*** + + + +| | | +|---|---| +|Method|rescan| +|Notifications|[recvtx](#recvtx), [redeemingtx](#redeemingtx), [rescanprogress](#rescanprogress), and [rescanfinished](#rescanfinished)| +|Parameters|1. BeginBlock (string, required) block hash to begin rescanning from
2. Addresses (JSON array, required)
 `[ (json array of strings)`
  `"bitcoinaddress", (string) the bitcoin address`
  `...`
 `]`
3. Outpoints (JSON array, required)
 `[ (JSON array)`
  `{ (JSON object)`
   `"hash":"data", (string) the hex-encoded bytes of the outpoint hash`
   `"index":n (numeric) the txout index of the outpoint`
  `},`
  `...`
 `]`
4. EndBlock (string, optional) hash of final block to rescan| +|Description|Rescan block chain for transactions to addresses, starting at block BeginBlock and ending at EndBlock. If EndBlock is omitted, the rescan continues through the best block in the main chain. The current known UTXO set for all passed addresses at height BeginBlock should included in the Outpoints argument. Rescan results are sent as recvtx and redeemingtx notifications. This call returns once the rescan completes.| +|Returns|Nothing| +[Return to Overview](#ExtensionRequestOverview)
+ +*** + + + +| | | +|---|---| +|Method|notifynewtransactions| +|Notifications|[txaccepted](#txaccepted) or [txacceptedverbose](#txacceptedverbose)| +|Parameters|1. verbose (boolean, optional, default=false) - specifies which type of notification to receive. If verbose is true, then the caller receives [txacceptedverbose](#txacceptedverbose), otherwise the caller receives [txaccepted](#txaccepted)| +|Description|Send either a [txaccepted](#txaccepted) or a [txacceptedverbose](#txacceptedverbose) notification when a new transaction is accepted into the mempool.| +|Returns|Nothing| +[Return to Overview](#ExtensionRequestOverview)
+ + + +### 8. Notifications (Websocket-specific) + +btcd uses standard JSON-RPC notifications to notify clients of changes, rather than requiring clients to poll btcd for updates. JSON-RPC notifications are a subset of requests, but do not contain an ID. The notification type is categorized by the `method` field and additional details are sent as a JSON array in the `params` field. + + +**8.1 Notification Overview**
+ +The following is an overview of the JSON-RPC notifications used for Websocket connections. Click the method name for further details of the context(s) in which they are sent and their parameters. + +|#|Method|Description|Request| +|---|------|-----------|-------| +|1|[blockconnected](#blockconnected)|Block connected to the main chain.|[notifyblocks](#notifyblocks)| +|2|[blockdisconnected](#blockdisconnected)|Block disconnected from the main chain.|[notifyblocks](#notifyblocks)| +|3|[recvtx](#recvtx)|Processed a transaction output spending to a wallet address.|[notifyreceived](#notifyreceived) and [rescan](#rescan)| +|4|[redeemingtx](#redeemingtx)|Processed a transaction that spends a registered outpoint.|[notifyspent](#notifyspent) and [rescan](#rescan)| +|5|[txaccepted](#txaccepted)|Received a new transaction after requesting simple notifications of all new transactions accepted into the mempool.|[notifynewtransactions](#notifynewtransactions)| +|6|[txacceptedverbose](#txacceptedverbose)|Received a new transaction after requesting verbose notifications of all new transactions accepted into the mempool.|[notifynewtransactions](#notifynewtransactions)| +|7|[rescanprogress](#rescanprogress)|A rescan operation that is underway has made progress.|[rescan](#rescan)| +|8|[rescanfinished](#rescanfinished)|A rescan operation has completed.|[rescan](#rescan)| + + +**8.2 Notification Details**
+ + + +| | | +|---|---| +|Method|blockconnected| +|Request|[notifyblocks](#notifyblocks)| +|Parameters|1. BlockHash (string) hex-encoded bytes of the attached block hash
2. BlockHeight (numeric) height of the attached block| +|Description|Notifies when a block has been added to the main chain. Notification is sent to all connected clients.| +|Example|Example blockconnected notification for mainnet block 280330 (newlines added for readability):
`{`
 `"jsonrpc": "1.0",`
 `"method": "blockconnected",`
 `"params":`
  `[`
   `"000000000000000004cbdfe387f4df44b914e464ca79838a8ab777b3214dbffd",`
   `280330`
  `],`
 `"id": null`
`}`| +[Return to Overview](#NotificationOverview)
+ +*** + + + +| | | +|---|---| +|Method|blockdisconnected| +|Request|[notifyblocks](#notifyblocks)| +|Parameters|1. BlockHash (string) hex-encoded bytes of the disconnected block hash
2. BlockHeight (numeric) height of the disconnected block| +|Description|Notifies when a block has been removed from the main chain. Notification is sent to all connected clients.| +|Example|Example blockdisconnected notification for mainnet block 280330 (newlines added for readability):
`{`
 `"jsonrpc": "1.0",`
 `"method": "blockdisconnected",`
 `"params":`
  `[`
   `"000000000000000004cbdfe387f4df44b914e464ca79838a8ab777b3214dbffd",`
   `280330`
  `],`
 `"id": null`
`}`| +[Return to Overview](#NotificationOverview)
+ +*** + + + +| | | +|---|---| +|Method|recvtx| +|Request|[rescan](#rescan) or [notifyreceived](#notifyreceived)| +|Parameters|1. Transaction (string) full transaction encoded as a hex string
2. Block details (object, optional) details about a block and the index of the transaction within a block, if the transaction is mined| +|Description|Notifies a client when a transaction is processed that contains at least a single output with a pkScript sending to a requested address. If multiple outputs send to requested addresses, a single notification is sent. If a mempool (unmined) transaction is processed, the block details object (second parameter) is excluded.| +|Example|Example recvtx notification for mainnet transaction 61d3696de4c888730cbe06b0ad8ecb6d72d6108e893895aa9bc067bd7eba3fad when processed by mempool (newlines added for readability):
`{`
 `"jsonrpc": "1.0",`
 `"method": "recvtx",`
 `"params":`
  `[`
   `"010000000114d9ff358894c486b4ae11c2a8cf7851b1df64c53d2e511278eff17c22fb737300000000..."`
  `],`
 `"id": null`
`}`
The recvtx notification for the same txout, after the transaction was mined into block 276425:
`{`
 `"jsonrpc": "1.0",`
 `"method": "recvtx",`
 `"params":`
  `[`
   `"010000000114d9ff358894c486b4ae11c2a8cf7851b1df64c53d2e511278eff17c22fb737300000000...",`
   `{`
    `"height": 276425,`
    `"hash": "000000000000000325474bb799b9e591f965ca4461b72cb7012b808db92bb2fc",`
    `"index": 684,`
    `"time": 1387737310`
   `}`
  `],`
 `"id": null`
`}`| +[Return to Overview](#NotificationOverview)
+ +*** + + + +| | | +|---|---| +|Method|redeemingtx| +|Requests|[notifyspent](#notifyspent) and [rescan](#rescan)| +|Parameters|1. Transaction (string) full transaction encoded as a hex string
2. Block details (object, optional) details about a block and the index of the transaction within a block, if the transaction is mined| +|Description|Notifies a client when an registered outpoint is spent by a transaction accepted to mempool and/or mined into a block.| +|Example|Example redeemingtx notification for mainnet outpoint 61d3696de4c888730cbe06b0ad8ecb6d72d6108e893895aa9bc067bd7eba3fad:0 after being spent by transaction 4ad0c16ac973ff675dec1f3e5f1273f1c45be2a63554343f21b70240a1e43ece (newlines added for readability):
`{`
 `"jsonrpc": "1.0",`
 `"method": "redeemingtx",`
 `"params":`
  `[`
   `"0100000003ad3fba7ebd67c09baa9538898e10d6726dcb8eadb006be0c7388c8e46d69d3610000000..."`
  `],`
 `"id": null`
`}`
The redeemingtx notification for the same txout, after the spending transaction was mined into block 279143:
`{`
 `"jsonrpc": "1.0",`
 `"method": "recvtx",`
 `"params":`
  `[`
   `"0100000003ad3fba7ebd67c09baa9538898e10d6726dcb8eadb006be0c7388c8e46d69d3610000000...",`
   `{`
    `"height": 279143,`
    `"hash": "00000000000000017188b968a371bab95aa43522665353b646e41865abae02a4",`
    `"index": 6,`
    `"time": 1389115004`
   `}`
  `],`
 `"id": null`
`}`| +[Return to Overview](#NotificationOverview)
+ +*** + + + +| | | +|---|---| +|Method|txaccepted| +|Request|[notifynewtransactions](#notifynewtransactions)| +|Parameters|1. TxSha (string) hex-encoded bytes of the transaction hash
2. Amount (numeric) sum of the value of all the transaction outpoints| +|Description|Notifies when a new transaction has been accepted and the client has requested standard transaction details.| +|Example|Example txaccepted notification for mainnet transaction id "16c54c9d02fe570b9d41b518c0daefae81cc05c69bbe842058e84c6ed5826261" (newlines added for readability):
`{`
 `"jsonrpc": "1.0",`
 `"method": "txaccepted",`
 `"params":`
  `[`
   `"16c54c9d02fe570b9d41b518c0daefae81cc05c69bbe842058e84c6ed5826261",`
   `55838384`
  `],`
 `"id": null`
`}`| +[Return to Overview](#NotificationOverview)
+ +*** + + + +| | | +|---|---| +|Method|txacceptedverbose| +|Request|[notifynewtransactions](#notifynewtransactions)| +|Parameters|1. RawTx (json object) the transaction as a json object (see getrawtransaction json object details)| +|Description|Notifies when a new transaction has been accepted and the client has requested verbose transaction details.| +|Example|Example txacceptedverbose notification (newlines added for readability):
`{`
 `"jsonrpc": "1.0",`
 `"method": "txacceptedverbose",`
 `"params":`
  `[`
   `{`
    `"hex": "01000000010000000000000000000000000000000000000000000000000000000000000000f...",`
    `"txid": "90743aad855880e517270550d2a881627d84db5265142fd1e7fb7add38b08be9",`
    `"version": 1,`
    `"locktime": 0,`
    `"vin": [`
    For coinbase transactions:
      `{ (json object)`
        `"coinbase": "03708203062f503253482f04066d605108f800080100000ea2122f6f7a636f696e4065757374726174756d2f",`
        `"sequence": 0,`
      `}`
    For non-coinbase transactions:
      `{`
        `"txid": "60ac4b057247b3d0b9a8173de56b5e1be8c1d1da970511c626ef53706c66be04",`
        `"vout": 0,`
        `"scriptSig": {`
          `"asm": "3046022100cb42f8df44eca83dd0a727988dcde9384953e830b1f8004d57485e2ede1b9c8f0...",`
          `"hex": "493046022100cb42f8df44eca83dd0a727988dcde9384953e830b1f8004d57485e2ede1b9c8...",`
        `}`
        `"sequence": 4294967295,`
      `}`
    `],`
    `"vout": [`
     `{`
      `"value": 25.1394,`
      `"n": 0,`
      `"scriptPubKey": {`
       `"asm": "OP_DUP OP_HASH160 ea132286328cfc819457b9dec386c4b5c84faa5c OP_EQUALVERIFY OP_CHECKSIG",`
       `"hex": "76a914ea132286328cfc819457b9dec386c4b5c84faa5c88ac",`
       `"reqSigs": 1,`
       `"type": "pubkeyhash"`
       `"addresses": [`
        `"1NLg3QJMsMQGM5KEUaEu5ADDmKQSLHwmyh",`
       `]`
     `}`
    `]`
   `}`
  `],`
 `"id": null`
`}`| +[Return to Overview](#NotificationOverview)
+ +*** + + + +| | | +|---|---| +|Method|rescanprogress| +|Request|[rescan](#rescan)| +|Parameters|1. Hash (string) hash of the last processed block
2. Height (numeric) height of the last processed block
3. Time (numeric) UNIX time of the last processed block| +|Description|Notifies a client with the current progress at periodic intervals when a long-running [rescan](#rescan) is underway.| +|Example|`{`
 `"jsonrpc": "1.0",`
 `"method": "rescanprogress",`
 `"params":`
  `[`
   `"0000000000000ea86b49e11843b2ad937ac89ae74a963c7edd36e0147079b89d",`
   `127213,`
   `1306533807`
  `],`
 `"id": null`
`}`| +[Return to Overview](#NotificationOverview)
+ +*** + + + +| | | +|---|---| +|Method|rescanfinished| +|Request|[rescan](#rescan)| +|Parameters|1. Hash (string) hash of the last rescanned block
2. Height (numeric) height of the last rescanned block
3. Time (numeric) UNIX time of the last rescanned block | +|Description|Notifies a client that the [rescan](#rescan) has completed and no further notifications will be sent.| +|Example|`{`
 `"jsonrpc": "1.0",`
 `"method": "rescanfinished",`
 `"params":`
  `[`
   `"0000000000000ea86b49e11843b2ad937ac89ae74a963c7edd36e0147079b89d",`
   `127213,`
   `1306533807`
  `],`
 `"id": null`
`}`| +[Return to Overview](#NotificationOverview)
+ + + +### 9. Example Code + +This section provides example code for interacting with the JSON-RPC API in +various languages. + +* [Go](#ExampleGoApp) +* [node.js](#ExampleNodeJsCode) + + +**9.1 Go** + +This section provides examples of using the RPC interface using Go and the +[btcrpcclient](https://github.com/btcsuite/btcrpcclient) package. + +* [Using getblockcount to Retrieve the Current Block Height](#ExampleGetBlockCount) +* [Using getblock to Retrieve the Genesis Block](#ExampleGetBlock) +* [Using notifyblocks to Receive blockconnected and blockdisconnected Notifications (Websocket-specific)](#ExampleNotifyBlocks) + + + +**9.1.1 Using getblockcount to Retrieve the Current Block Height**
+ +The following is an example Go application which uses the +[btcrpcclient](https://github.com/btcsuite/btcrpcclient) package to connect with +a btcd instance via Websockets, issues [getblockcount](#getblockcount) to +retrieve the current block height, and displays it. + +```Go +package main + +import ( + "github.com/btcsuite/btcrpcclient" + "github.com/btcsuite/btcutil" + "io/ioutil" + "log" + "path/filepath" +) + +func main() { + // Load the certificate for the TLS connection which is automatically + // generated by btcd when it starts the RPC server and doesn't already + // have one. + btcdHomeDir := btcutil.AppDataDir("btcd", false) + certs, err := ioutil.ReadFile(filepath.Join(btcdHomeDir, "rpc.cert")) + if err != nil { + log.Fatal(err) + } + + // Create a new RPC client using websockets. Since this example is + // not long-lived, the connection will be closed as soon as the program + // exits. + connCfg := &btcrpcclient.ConnConfig{ + Host: "localhost:8334", + Endpoint: "ws", + User: "yourrpcuser", + Pass: "yourrpcpass", + Certificates: certs, + } + client, err := btcrpcclient.New(connCfg, nil) + if err != nil { + log.Fatal(err) + } + defer client.Shutdown() + + // Query the RPC server for the current block count and display it. + blockCount, err := client.GetBlockCount() + if err != nil { + log.Fatal(err) + } + log.Printf("Block count: %d", blockCount) +} +``` + +Which results in: + +```bash +Block count: 276978 +``` + + +**9.1.2 Using getblock to Retrieve the Genesis Block**
+ +The following is an example Go application which uses the +[btcrpcclient](https://github.com/btcsuite/btcrpcclient) package to connect with +a btcd instance via Websockets, issues [getblock](#getblock) to retrieve +information about the Genesis block, and display a few details about it. + +```Go +package main + +import ( + "github.com/btcsuite/btcrpcclient" + "github.com/btcsuite/btcutil" + "github.com/btcsuite/btcwire" + "io/ioutil" + "log" + "path/filepath" + "time" +) + +func main() { + // Load the certificate for the TLS connection which is automatically + // generated by btcd when it starts the RPC server and doesn't already + // have one. + btcdHomeDir := btcutil.AppDataDir("btcd", false) + certs, err := ioutil.ReadFile(filepath.Join(btcdHomeDir, "rpc.cert")) + if err != nil { + log.Fatal(err) + } + + // Create a new RPC client using websockets. Since this example is + // not long-lived, the connection will be closed as soon as the program + // exits. + connCfg := &btcrpcclient.ConnConfig{ + Host: "localhost:18334", + Endpoint: "ws", + User: "yourrpcuser", + Pass: "yourrpcpass", + Certificates: certs, + } + client, err := btcrpcclient.New(connCfg, nil) + if err != nil { + log.Fatal(err) + } + defer client.Shutdown() + + // Query the RPC server for the genesis block using the "getblock" + // command with the verbose flag set to true and the verboseTx flag + // set to false. + genesisHashStr := "000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f" + blockHash, err := btcwire.NewShaHashFromStr(genesisHashStr) + if err != nil { + log.Fatal(err) + } + block, err := client.GetBlockVerbose(blockHash, false) + if err != nil { + log.Fatal(err) + } + + // Display some details about the returned block. + log.Printf("Hash: %v\n", block.Hash) + log.Printf("Previous Block: %v\n", block.PreviousHash) + log.Printf("Next Block: %v\n", block.NextHash) + log.Printf("Merkle root: %v\n", block.MerkleRoot) + log.Printf("Timestamp: %v\n", time.Unix(block.Time, 0).UTC()) + log.Printf("Confirmations: %v\n", block.Confirmations) + log.Printf("Difficulty: %f\n", block.Difficulty) + log.Printf("Size (in bytes): %v\n", block.Size) + log.Printf("Num transactions: %v\n", len(block.Tx)) +} +``` + +Which results in: + +```bash +Hash: 000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f +Previous Block: 0000000000000000000000000000000000000000000000000000000000000000 +Next Block: 00000000839a8e6886ab5951d76f411475428afc90947ee320161bbf18eb6048 +Merkle root: 4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b +Timestamp: 2009-01-03 18:15:05 +0000 UTC +Confirmations: 277290 +Difficulty: 1.000000 +Size (in bytes): 285 +Num transactions: 1 +``` + + +**9.1.3 Using notifyblocks to Receive blockconnected and blockdisconnected +Notifications (Websocket-specific)**
+ +The following is an example Go application which uses the +[btcrpcclient](https://github.com/btcsuite/btcrpcclient) package to connect with +a btcd instance via Websockets and registers for +[blockconnected](#blockconnected) and [blockdisconnected](#blockdisconnected) +notifications with [notifyblocks](#notifyblocks). It also sets up handlers for +the notifications. + +```Go +package main + +import ( + "github.com/btcsuite/btcrpcclient" + "github.com/btcsuite/btcutil" + "github.com/btcsuite/btcwire" + "io/ioutil" + "log" + "path/filepath" + "time" +) + +func main() { + // Setup handlers for blockconnected and blockdisconnected + // notifications. + ntfnHandlers := btcrpcclient.NotificationHandlers{ + OnBlockConnected: func(hash *btcwire.ShaHash, height int32) { + log.Printf("Block connected: %v (%d)", hash, height) + }, + OnBlockDisconnected: func(hash *btcwire.ShaHash, height int32) { + log.Printf("Block disconnected: %v", hash, height) + }, + } + + // Load the certificate for the TLS connection which is automatically + // generated by btcd when it starts the RPC server and doesn't already + // have one. + btcdHomeDir := btcutil.AppDataDir("btcd", false) + certs, err := ioutil.ReadFile(filepath.Join(btcdHomeDir, "rpc.cert")) + if err != nil { + log.Fatal(err) + } + + // Create a new RPC client using websockets. + connCfg := &btcrpcclient.ConnConfig{ + Host: "localhost:8334", + Endpoint: "ws", + User: "yourrpcuser", + Pass: "yourrpcpass", + Certificates: certs, + } + client, err := btcrpcclient.New(connCfg, &ntfnHandlers) + if err != nil { + log.Fatal(err) + } + + // Register for blockconnected and blockdisconneted notifications. + if err := client.NotifyBlocks(); err != nil { + client.Shutdown() + log.Fatal(err) + } + + // For this example, gracefully shutdown the client after 10 seconds. + // Ordinarily when to shutdown the client is highly application + // specific. + log.Println("Client shutdown in 10 seconds...") + time.AfterFunc(time.Second*10, func() { + log.Println("Client shutting down...") + client.Shutdown() + log.Println("Client shutdown complete.") + }) + + // Wait until the client either shuts down gracefully (or the user + // terminates the process with Ctrl+C). + client.WaitForShutdown() +} +``` + +Example output: + +``` +2014/05/12 20:33:17 Client shutdown in 10 seconds... +2014/05/12 20:33:19 Block connected: 000000000000000007dff1f95f7b3f5eac2892a4123069517caf34e2c417650d (300461) +2014/05/12 20:33:27 Client shutting down... +2014/05/12 20:31:27 Client shutdown complete. +``` + + +### 9.2. Example node.js Code + + +**9.2.1 Using notifyblocks to be Notified of Block Connects and Disconnects**
+ +The following is example node.js code which uses [ws](https://github.com/einaros/ws) +(can be installed with `npm install ws`) to connect with a btcd instance, +issues [notifyblocks](#notifyblocks) to register for +[blockconnected](#blockconnected) and [blockdisconnected](#blockdisconnected) +notifications, and displays all incoming messages. + +```javascript +var fs = require('fs'); +var WebSocket = require('ws'); + +// Load the certificate for the TLS connection which is automatically +// generated by btcd when it starts the RPC server and doesn't already +// have one. +var cert = fs.readFileSync('/path/to/btcd/appdata/rpc.cert'); +var user = "yourusername"; +var password = "yourpassword"; + + +// Initiate the websocket connection. The btcd generated certificate acts as +// its own certificate authority, so it needs to be specified in the 'ca' array +// for the certificate to properly validate. +var ws = new WebSocket('wss://127.0.0.1:8334/ws', { + headers: { + 'Authorization': 'Basic '+new Buffer(user+':'+password).toString('base64') + }, + cert: cert, + ca: [cert] +}); +ws.on('open', function() { + console.log('CONNECTED'); + // Send a JSON-RPC command to be notified when blocks are connected and + // disconnected from the chain. + ws.send('{"jsonrpc":"1.0","id":"0","method":"notifyblocks","params":[]}'); +}); +ws.on('message', function(data, flags) { + console.log(data); +}); +ws.on('error', function(derp) { + console.log('ERROR:' + derp); +}) +ws.on('close', function(data) { + console.log('DISCONNECTED'); +}) +``` \ No newline at end of file diff --git a/docs/using_bootrap_dat.md b/docs/using_bootrap_dat.md new file mode 100644 index 00000000..d508831d --- /dev/null +++ b/docs/using_bootrap_dat.md @@ -0,0 +1,74 @@ +### Table of Contents +1. [What is bootstrap.dat?](#What)
+2. [What are the pros and cons of using bootstrap.dat?](#ProsCons) +3. [Where do I get bootstrap.dat?](#Obtaining) +4. [How do I know I can trust the bootstrap.dat I downloaded?](#Trust) +5. [How do I use bootstrap.dat with btcd?](#Importing) + + +### 1. What is bootstrap.dat? + +It is a flat, binary file containing bitcoin blockchain data starting from the +genesis block and continuing through a relatively recent block height depending +on the last time it was updated. + +See [this](https://bitcointalk.org/index.php?topic=145386.0) thread on +bitcointalk for more details. + +**NOTE:** Using bootstrap.dat is entirely optional. Btcd will download the +block chain from other peers through the Bitcoin protocol with no extra +configuration needed. + + +### 2. What are the pros and cons of using bootstrap.dat? + +Pros: +- Typically accelerates the initial process of bringing up a new node as it + downloads from public P2P nodes and generally is able to achieve faster + download speeds +- It is particularly beneficial when bringing up multiple nodes as you only need + to download the data once + +Cons: +- Requires you to setup and configure a torrent client if you don't already have + one available +- Requires roughly twice as much disk space since you'll need the flat file as + well as the imported database + + +### 3. Where do I get bootstrap.dat? + +The bootstrap.dat file is made available via a torrent. See +[this](https://bitcointalk.org/index.php?topic=145386.0) thread on bitcointalk +for the torrent download details. + + +### 4. How do I know I can trust the bootstrap.dat I downloaded? + +You don't need to trust the file as the `addblock` utility verifies every block +using the same rules that are used when downloading the block chain normally +through the Bitcoin protocol. Additionally, the chain rules contain hard-coded +checkpoints for the known-good block chain at periodic intervals. This ensures +that not only is it a valid chain, but it is the same chain that everyone else +is using. + + +### 5. How do I use bootstrap.dat with btcd? + +btcd comes with a separate utility named `addblock` which can be used to import +`bootstrap.dat`. This approach is used since the import is a one-time operation +and we prefer to keep the daemon itself as lightweight as possible. + +1. Stop btcd if it is already running. This is required since addblock needs to + access the database used by btcd and it will be locked if btcd is using it. +2. Note the path to the downloaded bootstrap.dat file. +3. Run the addblock utility with the `-i` argument pointing to the location of + boostrap.dat:

+**Windows:** +```bat +C:\> "%PROGRAMFILES%\Btcd Suite\Btcd\addblock" -i C:\Path\To\bootstrap.dat +``` +**Linux/Unix/BSD/POSIX:** +```bash +$ $GOPATH/bin/addblock -i /path/to/bootstrap.dat +```