btcd

https://travis-ci.org/btcsuite/btcd.png?branch=masterBuild Status http://img.shields.io/badge/license-ISC-blue.svgISC License https://img.shields.io/badge/godoc-reference-blue.svgGoDoc

btcd is an alternative full node bitcoin implementation written in Go (golang).

This project is currently under active development and is in a Beta state. It is extremely stable and has been in production use since October 2013.

It properly downloads, validates, and serves the block chain using the exact rules (including consensus bugs) for block acceptance as Bitcoin Core. We have taken great care to avoid btcd causing a fork to the block chain. It includes a full block validation testing framework which contains all of the ‘official’ block acceptance tests (and some additional ones) that is run on every pull request to help ensure it properly follows consensus. Also, it passes all of the JSON test data in the Bitcoin Core code.

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

One key difference between btcd and Bitcoin Core is that btcd does NOT include wallet functionality and this was a very intentional design decision. See the blog entry here for more details. This means you can’t actually make or receive payments directly with btcd. That functionality is provided by the btcwallet and Paymetheus (Windows-only) projects which are both under active development.

Documentation

Documentation is a work-in-progress. It is available at btcd.readthedocs.io.

Contents

Installation

The first step is to install btcd. See one of the following sections for details on how to install on the supported operating systems.

Requirements

Go 1.11 or newer.

GPG Verification Key

All official release tags are signed by Conformal so users can ensure the code has not been tampered with and is coming from the btcsuite developers. To verify the signature perform the following:

  • Download the Conformal public key: https://raw.githubusercontent.com/btcsuite/btcd/master/release/GIT-GPG-KEY-conformal.txt

  • Import the public key into your GPG keyring:

    gpg --import GIT-GPG-KEY-conformal.txt

  • Verify the release tag with the following command where TAG_NAME is a placeholder for the specific tag:

    git tag -v TAG_NAME

Windows Installation

Linux/BSD/MacOSX/POSIX Installation

go version
go env GOROOT GOPATH

NOTE: The GOROOT and GOPATH above must not be the same path. It is recommended that GOPATH is set to a directory in your home directory such as ~/goprojects to avoid write permission issues. It is also recommended to add $GOPATH/bin to your PATH at this point.

  • Run the following commands to obtain btcd, all dependencies, and install it:
git clone https://github.com/btcsuite/btcd $GOPATH/src/github.com/btcsuite/btcd
cd $GOPATH/src/github.com/btcsuite/btcd
GO111MODULE=on go install -v . ./cmd/...
  • btcd (and utilities) will now be installed in $GOPATH/bin. If you did not already add the bin directory to your system path during Go installation, we recommend you do so now.

Gentoo Linux Installation

  • Install Layman and enable the Bitcoin overlay.
  • Copy or symlink /var/lib/layman/bitcoin/Documentation/package.keywords/btcd-live to /etc/portage/package.keywords/
  • Install btcd: $ emerge net-p2p/btcd

Startup

Typically btcd will run and start downloading the block chain with no extra configuration necessary, however, there is an optional method to use a bootstrap.dat file that may speed up the initial block chain download process.

Update

  • Run the following commands to update btcd, all dependencies, and install it:
cd $GOPATH/src/github.com/btcsuite/btcd
git pull && GO111MODULE=on go install -v . ./cmd/...

Configuration

btcd has a number of configuration options, which can be viewed by running: $ btcd --help.

Peer server listen interface

btcd allows you to bind to specific interfaces which enables you to setup configurations with varying levels of complexity. The listen parameter can be specified on the command line as shown below with the – prefix or in the configuration file without the – prefix (as can all long command line options). The configuration file takes one entry per line.

NOTE: The listen flag can be specified multiple times to listen on multiple interfaces as a couple of the examples below illustrate.

Command Line Examples:

Flags Comment
--listen= all interfaces on default port which is changed by --testnet and --regtest (default)
--listen=0.0.0.0 all IPv4 interfaces on default port which is changed by --testnet and --regtest
--listen=:: all IPv6 interfaces on default port which is changed by --testnet and --regtest
--listen=:8333 all interfaces on port 8333
--listen=0.0.0.0:8333 all IPv4 interfaces on port 8333
--listen=[::]:8333 all IPv6 interfaces on port 8333
--listen=127.0.0.1:8333 only IPv4 localhost on port 8333
--listen=[::1]:8333 only IPv6 localhost on port 8333
--listen=:8336 all interfaces on non-standard port 8336
--listen=0.0.0.0:8336 all IPv4 interfaces on non-standard port 8336
--listen=[::]:8336 all IPv6 interfaces on non-standard port 8336
--listen=127.0.0.1:8337 --listen=[::1]:8333 IPv4 localhost on port 8337 and IPv6 localhost on port 8333
--listen=:8333 --listen=:8337 all interfaces on ports 8333 and 8337

The following config file would configure btcd to only listen on localhost for both IPv4 and IPv6:

[Application Options]

listen=127.0.0.1:8333
listen=[::1]:8333

In addition, if you are starting btcd with TLS and want to make it available via a hostname, then you will need to generate the TLS certificates for that host. For example,

gencerts --host=myhostname.example.com --directory=/home/me/.btcd/

RPC server listen interface

btcd allows you to bind the RPC server to specific interfaces which enables you to setup configurations with varying levels of complexity. The rpclisten parameter can be specified on the command line as shown below with the – prefix or in the configuration file without the – prefix (as can all long command line options). The configuration file takes one entry per line.

A few things to note regarding the RPC server:

  • The RPC server will not be enabled unless the rpcuser and rpcpass options are specified.
  • When the rpcuser and rpcpass and/or rpclimituser and rpclimitpass options are specified, the RPC server will only listen on localhost IPv4 and IPv6 interfaces by default. You will need to override the RPC listen interfaces to include external interfaces if you want to connect from a remote machine.
  • The RPC server has TLS enabled by default, even for localhost. You may use the --notls option to disable it, but only when all listeners are on localhost interfaces.
  • The --rpclisten flag can be specified multiple times to listen on multiple interfaces as a couple of the examples below illustrate.
  • The RPC server is disabled by default when using the --regtest and --simnet networks. You can override this by specifying listen interfaces.

Command Line Examples:

Flags Comment
--rpclisten= all interfaces on default port which is changed by --testnet
--rpclisten=0.0.0.0 all IPv4 interfaces on default port which is changed by --testnet
--rpclisten=:: all IPv6 interfaces on default port which is changed by --testnet
--rpclisten=:8334 all interfaces on port 8334
--rpclisten=0.0.0.0:8334 all IPv4 interfaces on port 8334
--rpclisten=[::]:8334 all IPv6 interfaces on port 8334
--rpclisten=127.0.0.1:8334 only IPv4 localhost on port 8334
--rpclisten=[::1]:8334 only IPv6 localhost on port 8334
--rpclisten=:8336 all interfaces on non-standard port 8336
--rpclisten=0.0.0.0:8336 all IPv4 interfaces on non-standard port 8336
--rpclisten=[::]:8336 all IPv6 interfaces on non-standard port 8336
--rpclisten=127.0.0.1:8337 --listen=[::1]:8334 IPv4 localhost on port 8337 and IPv6 localhost on port 8334
--rpclisten=:8334 --listen=:8337 all interfaces on ports 8334 and 8337

The following config file would configure the btcd RPC server to listen to all interfaces on the default port, including external interfaces, for both IPv4 and IPv6:

[Application Options]

rpclisten=

Default ports

While btcd is highly configurable when it comes to the network configuration, the following is intended to be a quick reference for the default ports used so port forwarding can be configured as required.

btcd provides a --upnp flag which can be used to automatically map the bitcoin peer-to-peer listening port if your router supports UPnP. If your router does not support UPnP, or you don’t wish to use it, please note that only the bitcoin peer-to-peer port should be forwarded unless you specifically want to allow RPC access to your btcd from external sources such as in more advanced network configurations.

Name Port
Default Bitcoin peer-to-peer port TCP 8333
Default RPC port TCP 8334

Using bootstrap.dat

What is bootstrap.dat?

It is a flat, binary file containing bitcoin blockchain data starting from the genesis block and continuing through a relatively recent block height depending on the last time it was updated.

See this thread on bitcointalk for more details.

NOTE: Using bootstrap.dat is entirely optional. Btcd will download the block chain from other peers through the Bitcoin protocol with no extra configuration needed.

What are the pros and cons of using bootstrap.dat?

Pros:

  • Typically accelerates the initial process of bringing up a new node as it downloads from public P2P nodes and generally is able to achieve faster download speeds
  • It is particularly beneficial when bringing up multiple nodes as you only need to download the data once

Cons:

  • Requires you to setup and configure a torrent client if you don’t already have one available
  • Requires roughly twice as much disk space since you’ll need the flat file as well as the imported database
Where do I get bootstrap.dat?

The bootstrap.dat file is made available via a torrent. See this thread on bitcointalk for the torrent download details.

How do I know I can trust the bootstrap.dat I downloaded?

You don’t need to trust the file as the addblock utility verifies every block using the same rules that are used when downloading the block chain normally through the Bitcoin protocol. Additionally, the chain rules contain hard-coded checkpoints for the known-good block chain at periodic intervals. This ensures that not only is it a valid chain, but it is the same chain that everyone else is using.

How do I use bootstrap.dat with btcd?

btcd comes with a separate utility named addblock which can be used to import bootstrap.dat. This approach is used since the import is a one-time operation and we prefer to keep the daemon itself as lightweight as possible.

  1. Stop btcd if it is already running. This is required since addblock needs to access the database used by btcd and it will be locked if btcd is using it.
  2. Note the path to the downloaded bootstrap.dat file.
  3. Run the addblock utility with the -i argument pointing to the location of boostrap.dat:

Windows:

"%PROGRAMFILES%\Btcd Suite\Btcd\addblock" -i C:\Path\To\bootstrap.dat

Linux/Unix/BSD/POSIX:

$GOPATH/bin/addblock -i /path/to/bootstrap.dat

Configuring TOR

btcd provides full support for anonymous networking via the Tor Project, including client-only and hidden service configurations along with stream isolation. In addition, btcd supports a hybrid, bridge mode 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.

Client-only

Configuring btcd as a Tor client is straightforward. The first step is obviously to install Tor and ensure it is working. Once that is done, all that 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.

Command line example
./btcd --proxy=127.0.0.1:9050
Config file example
[Application Options]

proxy=127.0.0.1:9050

Client-server via Tor hidden service

The first step is to configure Tor to provide a hidden service. Documentation for this can be found on the Tor project website here. 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.

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
Command line example
./btcd --proxy=127.0.0.1:9050 --listen=127.0.0.1 --externalip=fooanon.onion
Config file example
[Application Options]

proxy=127.0.0.1:9050
listen=127.0.0.1
externalip=fooanon.onion

Bridge mode (not anonymous)

btcd provides support for operating as a bridge between regular nodes and hidden service nodes. In particular this means only traffic which is directed to or 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.

Command line example
./btcd --onion=127.0.0.1:9050 --externalip=fooanon.onion
Config file example
[Application Options]

onion=127.0.0.1:9050
externalip=fooanon.onion

Tor stream isolation

Tor stream isolation forces Tor to build a new circuit for each connection making it harder to correlate connections.

btcd provides support for Tor stream isolation by using the --torisolation flag. This option requires –proxy or –onionproxy to be set.

Command line example
./btcd --proxy=127.0.0.1:9050 --torisolation
Config file example
[Application Options]

proxy=127.0.0.1:9050
torisolation=1

Using Docker

Introduction

With Docker you can easily set up btcd to run your Bitcoin full node. You can find the official btcd Docker images on Docker Hub btcsuite/btcd. The Docker source file of this image is located at Dockerfile.

This documentation focuses on running Docker container with docker-compose.yml files. These files are better to read and you can use them as a template for your own use. For more information about Docker and Docker compose visit the official Docker documentation.

Docker volumes

Special diskspace hint: The following examples are using a Docker managed volume. The volume is named btcd-data This will use a lot of disk space, because it contains the full Bitcoin blockchain. Please make yourself familiar with Docker volumes.

The btcd-data volume will be reused, if you upgrade your docker-compose.yml file. Keep in mind, that it is not automatically removed by Docker, if you delete the btcd container. If you don’t need the volume anymore, please delete it manually with the command:

docker volume ls
docker volume rm btcd-data

For binding a local folder to your btcd container please read the Docker documentation. The preferred way is to use a Docker managed volume.

Known error messages when starting the btcd container

We pass all needed arguments to btcd as command line parameters in our docker-compose.yml file. It doesn’t make sense to create a btcd.conf file. This would make things too complicated. Anyhow btcd will complain with following log messages when starting. These messages can be ignored:

Error creating a default config file: open /sample-btcd.conf: no such file or directory
...
[WRN] BTCD: open /root/.btcd/btcd.conf: no such file or directory

Examples

Preamble

All following examples uses some defaults:

  • container_name: btcd Name of the docker container that is be shown by e.g. docker ps -a
  • hostname: btcd (very important to set a fixed name before first start) The internal hostname in the docker container. By default, docker is recreating the hostname every time you change the docker-compose.yml file. The default hostnames look like ef00548d4fa5. This is a problem when using the btcd RPC port. The RPC port is using a certificate to validate the hostname. If the hostname changes you need to recreate the certificate. To avoid this, you should set a fixed hostname before the first start. This ensures, that the docker volume is created with a certificate with this hostname.
  • restart: unless-stopped Starts the btcd container when Docker starts, except that when the container is stopped (manually or otherwise), it is not restarted even after Docker restarts.

To use the following examples create an empty directory. In this directory create a file named docker-compose.yml, copy and paste the example into the docker-compose.yml file and run it.

mkdir ~/btcd-docker
cd ~/btcd-docker
touch docker-compose.yaml
nano docker-compose.yaml (use your favourite editor to edit the compose file)
docker-compose up (creates and starts a new btcd container)

With the following commands you can control docker-compose:

docker-compose up -d (creates and starts the container in background)

docker-compose down (stops and delete the container. The docker volume btcd-data will not be deleted)

docker-compose stop (stops the container)

docker-compose start (starts the container)

docker ps -a (list all running and stopped container)

docker volume ls (lists all docker volumes)

docker logs btcd (shows the log )

docker-compose help (brings up some helpful information)

Full node without RPC port

Let’s start with an easy example. If you just want to create a full node without the need of using the RPC port, you can use the following example. This example will launch btcd and exposes only the default p2p port 8333 to the outside world:

version: "2"

services:
  btcd:
    container_name: btcd
    hostname: btcd
    image: btcsuite/btcd:latest
    restart: unless-stopped
    volumes:
      - btcd-data:/root/.btcd
    ports:
      - 8333:8333

volumes:
  btcd-data:
Full node with RPC port

To use the RPC port of btcd you need to specify a username and a very strong password. If you want to connect to the RPC port from the internet, you need to expose port 8334(RPC) as well.

version: "2"

services:
  btcd:
    container_name: btcd
    hostname: btcd
    image: btcsuite/btcd:latest
    restart: unless-stopped
    volumes:
      - btcd-data:/root/.btcd
    ports:
      - 8333:8333
      - 8334:8334
    command: [
        "--rpcuser=[CHOOSE_A_USERNAME]",
        "--rpcpass=[CREATE_A_VERY_HARD_PASSWORD]"
    ]

volumes:
  btcd-data:
Full node with RPC port running on TESTNET

To run a node on testnet, you need to provide the –testnet argument. The ports for testnet are 18333 (p2p) and 18334 (RPC):

version: "2"

services:
  btcd:
    container_name: btcd
    hostname: btcd
    image: btcsuite/btcd:latest
    restart: unless-stopped
    volumes:
      - btcd-data:/root/.btcd
    ports:
      - 18333:18333
      - 18334:18334
    command: [
        "--testnet",
        "--rpcuser=[CHOOSE_A_USERNAME]",
        "--rpcpass=[CREATE_A_VERY_HARD_PASSWORD]"
    ]

volumes:
  btcd-data:

Controlling and querying btcd via btcctl

btcctl is a command line utility that can be used to both control and query btcd via RPC. btcd does not enable its RPC server by default; You must configure at minimum both an RPC username and password or both an RPC limited username and password:

  • btcd.conf configuration file
[Application Options]
rpcuser=myuser
rpcpass=SomeDecentp4ssw0rd
rpclimituser=mylimituser
rpclimitpass=Limitedp4ssw0rd
  • btcctl.conf configuration file
[Application Options]
rpcuser=myuser
rpcpass=SomeDecentp4ssw0rd

OR

[Application Options]
rpclimituser=mylimituser
rpclimitpass=Limitedp4ssw0rd

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

Mining

btcd supports the getblocktemplate RPC. The limited user cannot access this RPC.

Add the payment addresses with the miningaddr option

[Application Options]
rpcuser=myuser
rpcpass=SomeDecentp4ssw0rd
miningaddr=12c6DSiU4Rq3P4ZxziKxzrL5LmMBrzjrJX
miningaddr=1M83ju3EChKYyysmM2FXtLNftbacagd8FR

Add btcd’s RPC TLS certificate to system Certificate Authority list

cgminer uses curl to fetch data from the RPC server. Since curl validates the certificate by default, we must install the btcd RPC certificate into the default system Certificate Authority list.

Ubuntu

  1. Copy rpc.cert to /usr/share/ca-certificates: # cp /home/user/.btcd/rpc.cert /usr/share/ca-certificates/btcd.crt
  2. Add btcd.crt to /etc/ca-certificates.conf: # echo btcd.crt >> /etc/ca-certificates.conf
  3. Update the CA certificate list: # update-ca-certificates

Set your mining software url to use https

cgminer -o https://127.0.0.1:8334 -u rpcuser -p rpcpassword

Wallet

btcd was intentionally developed without an integrated wallet for security reasons. Please see btcwallet for more information.

Developer Resources

  • Code Contribution Guidelines
  • JSON-RPC Reference
  • The btcsuite Bitcoin-related Go Packages:
    • btcrpcclient - Implements a robust and easy to use Websocket-enabled Bitcoin JSON-RPC client
    • btcjson - Provides an extensive API for the underlying JSON-RPC command and return values
    • wire - Implements the Bitcoin wire protocol
    • peer - Provides a common base for creating and managing Bitcoin network peers.
    • blockchain - Implements Bitcoin block handling and chain selection rules
    • blockchain/fullblocktests - Provides a set of block tests for testing the consensus validation rules
    • txscript - Implements the Bitcoin transaction scripting language
    • btcec - Implements support for the elliptic curve cryptographic functions needed for the Bitcoin scripts
    • database - Provides a database interface for the Bitcoin block chain
    • mempool - Package mempool provides a policy-enforced pool of unmined bitcoin transactions.
    • btcutil - Provides Bitcoin-specific convenience functions and types
    • chainhash - Provides a generic hash type and associated functions that allows the specific hash algorithm to be abstracted.
    • connmgr - Package connmgr implements a generic Bitcoin network connection manager.

JSON RPC API

  1. Overview
  2. HTTP POST Versus Websockets
  3. Authentication
    3.1. Overview
    3.2. HTTP Basic Access Authentication
    3.3. JSON-RPC Authenticate Command (Websocket-specific)
  4. Command-line Utility
  5. Standard Methods
    5.1. Method Overview
    5.2. Method Details
  6. Extension Methods
    6.1. Method Overview
    6.2. Method Details
  7. Websocket Extension Methods (Websocket-specific)
    7.1. Method Overview
    7.2. Method Details
  8. Notifications (Websocket-specific)
    8.1. Notification Overview
    8.2. Notification Details
  9. Example Code
    9.1. Go
    9.2. node.js

1. Overview

btcd provides a JSON-RPC 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 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.
  • 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 requests and Websockets

Websockets are the preferred transport for btcd RPC and are used by applications such as 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, an extension API 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 is stable, the Websocket extension API 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

2. HTTP POST Versus Websockets

The btcd RPC server supports both HTTP POST requests and the preferred Websockets. All of the standard and extension methods described in this documentation can be accessed through both. As the name indicates, the Websocket-specific extension methods can only be accessed when connected via Websockets.

As mentioned in the 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 full-access username configured for the btcd RPC server
  • rpcpass is the full-access password configured for the btcd RPC server
  • rpclimituser is the limited username configured for the btcd RPC server
  • rpclimitpass is the limited password configured for the btcd RPC server
  • 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/or a rpclimituser and rpclimitpass, and uses TLS authentication for all connections.

Depending on which connection transaction you are using, you can choose one of two, mutually exclusive, methods.

3.2 HTTP Basic Access Authentication

The btcd RPC server uses HTTP 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 JSON-RPC method.

The 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 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 Safe for limited user? Description
1 addnode N Attempts to add or remove a persistent peer.
2 createrawtransaction Y Returns a new transaction spending the provided inputs and sending to the provided addresses.
3 decoderawtransaction Y Returns a JSON object representing the provided serialized, hex-encoded transaction.
4 decodescript Y Returns a JSON object with information about the provided hex-encoded script.
5 getaddednodeinfo N Returns information about manually added (persistent) peers.
6 getbestblockhash Y Returns the hash of the of the best (most recent) block in the longest block chain.
7 getblock Y Returns information about a block given its hash.
8 getblockcount Y Returns the number of blocks in the longest block chain.
9 getblockhash Y Returns hash of the block in best block chain at the given height.
10 getblockheader Y Returns the block header of the block.
11 getconnectioncount N Returns the number of active connections to other peers.
12 getdifficulty Y Returns the proof-of-work difficulty as a multiple of the minimum difficulty.
13 getgenerate N Return if the server is set to generate coins (mine) or not.
14 gethashespersec N Returns a recent hashes per second performance measurement while generating coins (mining).
15 getinfo Y Returns a JSON object containing various state info.
16 getmempoolinfo N Returns a JSON object containing mempool-related information.
17 getmininginfo N Returns a JSON object containing mining-related information.
18 getnettotals Y Returns a JSON object containing network traffic statistics.
19 getnetworkhashps Y Returns the estimated network hashes per second for the block heights provided by the parameters.
20 getpeerinfo N Returns information about each connected network peer as an array of json objects.
21 getrawmempool Y Returns an array of hashes for all of the transactions currently in the memory pool.
22 getrawtransaction Y Returns information about a transaction given its hash.
23 help Y Returns a list of all commands or help for a specified command.
24 ping N Queues a ping to be sent to each connected peer.
25 sendrawtransaction Y 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
26 setgenerate N 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.
27 stop N Shutdown btcd.
28 submitblock Y Attempts to submit a new serialized, hex-encoded block to the network.
29 validateaddress Y 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.
30 verifychain N Verifies the block chain database.

5.2 Method Details
Method addnode
Parameters 1. peer (string, required) - ip address and port of the peer to operate 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
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
  , ...
}
3. locktime (int64, optional, default=0) - specifies the transaction locktime. If non-zero, the inputs will also have their locktimes activated.
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}
3. locktime 0
Example Return 010000000118c057d3bfd3024628e9a6b18c105e4bb035053d1a378fce08856b7ade89dae6010000
0000ffffffff0199efee02000000001976a9141cb013db35ecccc156fdfd81d03a11c51998f99388
ac00000000
Newlines added for display purposes. The actual return does not contain newlines.
Return to Overview
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-encoded 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
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
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
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
Method getblock
Parameters 1. block hash (string, required) - the hash of the block
2. verbosity (int, optional, default=1) - Specifies whether the block data should be returned as a hex-encoded string (0), as parsed data with a slice of TXIDs (1), or as parsed data with parsed transaction data (2).
Description Returns information about a block given its hash.
Returns (verbosity=0) "data" (string) hex-encoded bytes of the serialized block
Returns (verbosity=1) { (json object)
  "hash": "blockhash", (string) the hash of the block (same as provided)
  "confirmations": n, (numeric) the number of confirmations
  "strippedsize", n (numeric) the size of the block without witness data
  "size": n, (numeric) the size of the block
  "weight": n, (numeric) value of the weight metric
  "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 (only if there is one)
}
Returns (verbosity=2) { (json object)
  "hash": "blockhash", (string) the hash of the block (same as provided)
  "confirmations": n, (numeric) the number of confirmations
  "strippedsize", n (numeric) the size of the block without witness data
  "size": n, (numeric) the size of the block
  "weight": n, (numeric) value of the weight metric
  "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 (verbosity=0) "010000000000000000000000000000000000000000000000000000000000000000000000
3ba3edfd7a7b12b27ac72c3e67768f617fc81bc3888a51323a9fb8aa4b1e5e4a29ab5f49
ffff001d1dac2b7c01010000000100000000000000000000000000000000000000000000
00000000000000000000ffffffff4d04ffff001d0104455468652054696d65732030332f
4a616e2f32303039204368616e63656c6c6f72206f6e206272696e6b206f66207365636f
6e64206261696c6f757420666f722062616e6b73ffffffff0100f2052a01000000434104
678afdb0fe5548271967f1a67130b7105cd6a828e03909a67962e0ea1f61deb649f6bc3f
4cef38c4f35504e51ec112de5c384df7ba0b8d578a4c702b6bf11d5fac00000000"
Newlines added for display purposes. The actual return does not contain newlines.
Example Return (verbosity=1) {
  "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
Method getblockcount
Parameters None
Description Returns the number of blocks in the longest block chain.
Returns numeric
Example Return 276820
Return to Overview
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
Method getblockheader
Parameters 1. block hash (string, required) - the hash of the block
2. verbose (boolean, optional, default=true) - specifies the block header is returned as a JSON object instead of a hex-encoded string
Description Returns hex-encoded bytes of the serialized block header.
Returns (verbose=false) "data" (string) hex-encoded bytes of the serialized block
Returns (verbose=true) { (json object)
  "hash": "blockhash", (string) the hash of the block (same as provided)
  "confirmations": n, (numeric) the number of confirmations
  "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
  "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 (only if there is one)
}
Example Return (verbose=false) "0200000035ab154183570282ce9afc0b494c9fc6a3cfea05aa8c1add2ecc564900000000
38ba3d78e4500a5a7570dbe61960398add4410d278b21cd9708e6d9743f374d544fc0552
27f1001c29c1ea3b"
Newlines added for display purposes. The actual return does not contain newlines.
Example Return (verbose=true) {
  "hash": "00000000009e2958c15ff9290d571bf9459e93b19765c6801ddeccadbb160a1e",
  "confirmations": 392076,
  "height": 100000,
  "version": 2,
  "merkleroot": "d574f343976d8e70d91cb278d21044dd8a396019e6db70755a0a50e4783dba38",
  "time": 1376123972,
  "nonce": 1005240617,
  "bits": "1c00f127",
  "difficulty": 271.75767393,
  "previousblockhash": "000000004956cc2edd1a8caa05eacfa3c69f4c490bfc9ace820257834115ab35",
  "nextblockhash": "0000000000629d100db387f37d0f37c51118f250fb0946310a8c37316cbc4028"
}
Return to Overview
Method getconnectioncount
Parameters None
Description Returns the number of active connections to other peers
Returns numeric
Example Return 8
Return to Overview
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
Method getgenerate
Parameters None
Description Return if the server is set to generate coins (mine) or not.
Returns false (boolean)
Return to Overview
Method gethashespersec
Parameters None
Description Returns a recent hashes per second performance measurement while generating coins (mining).
Returns 0 (numeric)
Return to Overview
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
Method getmempoolinfo
Parameters None
Description Returns a JSON object containing mempool-related information.
Returns { (json object)
  "bytes": n, (numeric) size in bytes of the mempool
  "size": n, (numeric) number of transactions in the mempool
}
Example Return {
  "bytes": 310768,
  "size": 157,
}
Return to Overview
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
  "currentblockweight": n, (numeric) weight 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,
  "currentblockweight": 740,
  "currentblocktx": 1,
  "difficulty": 256,
  "errors": "",
  "generate": false,
  "genproclimit": -1,
  "hashespersec": 0,
  "networkhashps": 33081554756,
  "pooledtx": 8,
  "testnet": true,
}
Return to Overview
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
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
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
    "currentheight": n, (numeric) the latest block height the peer is known to have relayed since connected
    "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,
    "currentheight": 276955,
    "syncnode": true,
  }
]
Return to Overview
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-encoded bytes of the signature script
      "sequence": n, (numeric) the script sequence number
    "txinwitness": “data", (string) the witness stack for the input
    }
  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
    "txinwitness": “data", (string) the witness stack for the input
    }, ...
  ]
  "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
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
Method ping
Parameters None
Description Queues a ping to be sent to each connected peer.
Ping times are provided by getpeerinfo via the pingtime and pingwait fields.
Returns Nothing
Return to Overview
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
    "vsize": n, (numeric) transaction virtual size
    "weight": n, (numeric) The transaction's weight (between vsize*4-3 and vsize*4)
    "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
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
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
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
Method stop
Parameters None
Description Shutdown btcd.
Returns "btcd stopping." (string)
Return to Overview
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
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

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 Safe for limited user? Description
1 debuglevel N Dynamically changes the debug logging level.
2 getbestblock Y Get block height and hash of best block in the main chain.
3 getcurrentnet Y Get bitcoin network btcd is running on.
4 searchrawtransactions Y Query for transactions related to a particular address.
5 node N Attempts to add or remove a peer.
6 generate N When in simnet or regtest mode, generate a set number of blocks.
7 version Y Returns the JSON-RPC API version.
8 getheaders Y Returns block headers starting with the first known block hash from the request.

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 <subsystem>=<level>,<subsystem2>=<level2>,...
The valid debug levels are trace, debug, info, warn, error, and critical.
The valid subsystems are AMGR, ADXR, 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 ADXR BCDB BMGR BTCD CHAN DISC PEER RPCS SCRP SRVR TXMP]
Return to Overview
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
Method getcurrentnet
Parameters None
Description Get bitcoin network btcd is running on.
Returns numeric
Example Return 3652501241 (mainnet)
118034699 (testnet3)
Return to Overview
Method searchrawtransactions
Parameters 1. address (string, required) - bitcoin address
2. verbose (int, optional, default=true) - specifies the transaction is returned as a JSON object instead of hex-encoded string
3. skip (int, optional, default=0) - the number of leading transactions to leave out of the final response
4. count (int, optional, default=100) - the maximum number of transactions to return
5. vinextra (int, optional, default=0) - Specify that extra data from previous output will be returned in vin
6. reverse (boolean, optional, default=false) - Specifies that the transactions should be returned in reverse chronological order
Description Returns raw data for transactions involving the passed address. Returned transactions are pulled from both the database, and transactions currently in the mempool. Transactions pulled from the mempool will have the "confirmations" field set to 0. Usage of this RPC requires the optional --addrindex flag to be activated, otherwise all responses will simply return with an error stating the address index has not yet been built up. Similarly, until the address index has caught up with the current best height, all requests will return an error response in order to avoid serving stale data.
Returns (verbose=0) [ (json array of strings)
   "serializedtx", ... hex-encoded bytes of the serialized transaction
]
Returns (verbose=1) [ (array of json objects)
   { (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-encoded bytes of the signature script
      "txinwitness": “data", (string) the witness stack for the input
    "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
      }
      "prevOut": { (json object) Data from the origin transaction output with index vout.
        "addresses": ["value",...], (array of string) previous output addresses
        "value": n.nnn, (numeric) previous output value
      }
      "txinwitness": “data", (string) the witness stack for the input
    "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
          "address", (string) the bitcoin address
          ...
        ]
      }
    }, ...
   ]
   "blockhash":"hash" Hash of the block the transaction is part of.
   "confirmations":n, Number of numeric confirmations of block.
   "time":t, Transaction time in seconds since the epoch.
   "blocktime":t, Block time in seconds since the epoch.
},...
]
Return to Overview
Method node
Parameters 1. command (string, required) - connect to add a peer (defaults to temporary), remove to remove a persistent peer, or disconnect to remove all matching non-persistent peers
2. peer (string, required) - ip address and port, or ID of the peer to operate on
3. connection type (string, optional) - perm indicates the peer should be added as a permanent peer, temp indicates a connection should only be attempted once.
Description Attempts to add or remove a peer.
Returns Nothing
Return to Overview
Method generate
Parameters 1. numblocks (int, required) - The number of blocks to generate
Description When in simnet or regtest mode, generates numblocks blocks. If blocks arrive from elsewhere, they are built upon but don't count toward the number of blocks to generate. Only generated blocks are returned. This RPC call will exit with an error if the server is already CPU mining, and will prevent the server from CPU mining for another command while it runs.
Returns [ (json array of strings)
   "blockhash", ... hash of the generated block
]
Return to Overview
Method version
Parameters None
Description Returns the version of the JSON-RPC API built into this release of btcd.
Returns { (json object)
  "btcdjsonrpcapi": {
    "versionstring": "x.y.z", (string) the version of the JSON-RPC API
    "major": x, (numeric) the major version of the JSON-RPC API
    "minor": y, (numeric) the minor version of the JSON-RPC API
    "patch": z, (numeric) the patch version of the JSON-RPC API
    "prerelease": "", (string) prerelease info for the JSON-RPC API
    "buildmetadata": "" (string) metadata about the server build
  }
}
Example Return {
  "btcdjsonrpcapi": {
    "versionstring": "1.0.0",
    "major": 1,
    "minor": 0,
    "patch": 0,
    "prerelease": "",
    "buildmetadata": ""
  }
}
Return to Overview
Method getheaders
Parameters 1. Block Locators (JSON array, required)
 [ (json array of strings)
  "blocklocator", (string) the known block hash
  ...
 ]
2. hashstop (string) - last desired block's hash
Description Returns block headers starting with the first known block hash from the request.
Returns [ (json array of strings)
  "blockheader",
  ...
]
Example Return [
  "0000002099417930b2ae09feda10e38b58c0f6bb44b4d60fa33f0e000000000000000000d53...",
  "000000203ba25a173bfd24d09e0c76002a910b685ca297bd09a17b020000000000000000702..."
]
Return to Overview

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. All of these RPC methods are available to the limited user. Click the method name for further details such as parameter and return information.

# Method Description Notifications
1 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 Send notifications when a block is connected or disconnected from the best chain. blockconnected, blockdisconnected, filteredblockconnected, and filteredblockdisconnected
3 stopnotifyblocks Cancel registered notifications for whenever a block is connected or disconnected from the main (best) chain. None
4 notifyreceived DEPRECATED, for similar functionality see loadtxfilter
Send notifications when a txout spends to an address.		 recvtx and redeemingtx
5 stopnotifyreceived DEPRECATED, for similar functionality see loadtxfilter
Cancel registered notifications for when a txout spends to any of the passed addresses.		 None
6 notifyspent DEPRECATED, for similar functionality see loadtxfilter
Send notification when a txout is spent.		 redeemingtx
7 stopnotifyspent DEPRECATED, for similar functionality see loadtxfilter
Cancel registered spending notifications for each passed outpoint.		 None
8 rescan DEPRECATED, for similar functionality see rescanblocks
Rescan block chain for transactions to addresses and spent transaction outpoints.		 recvtx, redeemingtx, rescanprogress, and rescanfinished
9 notifynewtransactions Send notifications for all new transactions as they are accepted into the mempool. txaccepted or txacceptedverbose
10 stopnotifynewtransactions Stop sending either a txaccepted or a txacceptedverbose notification when a new transaction is accepted into the mempool. None
11 session Return details regarding a websocket client's current connection. None
12 loadtxfilter Load, add to, or reload a websocket client's transaction filter for mempool transactions, new blocks and rescanblocks. relevanttxaccepted
13 rescanblocks Rescan blocks for transactions matching the loaded transaction filter. None

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
Method notifyblocks
Notifications blockconnected, blockdisconnected, filteredblockconnected, and filteredblockdisconnected
Parameters None
Description Request notifications for whenever a block is connected or disconnected from the main (best) chain.
NOTE: If a client subscribes to both block and transaction (recvtx and redeemingtx) notifications, the blockconnected notification will be sent after all transaction notifications have been sent. This allows clients to know when all relevant transactions for a block have been received.
Returns Nothing
Return to Overview
Method stopnotifyblocks
Notifications None
Parameters None
Description Cancel sending notifications for whenever a block is connected or disconnected from the main (best) chain.
Returns Nothing
Return to Overview
Method notifyreceived
Notifications recvtx and redeemingtx
Parameters 1. Addresses (JSON array, required)
 [ (json array of strings)
  "bitcoinaddress", (string) the bitcoin address
  ...
 ]
Description DEPRECATED, for similar functionality see loadtxfilter
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
Method stopnotifyreceived
Notifications None
Parameters 1. Addresses (JSON array, required)
 [ (json array of strings)
  "bitcoinaddress", (string) the bitcoin address
  ...
 ]
Description DEPRECATED, for similar functionality see loadtxfilter
Cancel registered receive notifications for each passed address.
Returns Nothing
Return to Overview
Method notifyspent
Notifications 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 DEPRECATED, for similar functionality see loadtxfilter
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
Method stopnotifyspent
Notifications None
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 DEPRECATED, for similar functionality see loadtxfilter
Cancel registered spending notifications for each passed outpoint.
Returns Nothing
Return to Overview
Method rescan
Notifications recvtx, redeemingtx, rescanprogress, and 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 DEPRECATED, for similar functionality see rescanblocks
Rescan block chain for transactions to addresses, starting at block BeginBlock and ending at EndBlock. The current known UTXO set for all passed addresses at height BeginBlock should included in the Outpoints argument. If EndBlock is omitted, the rescan continues through the best block in the main chain. Additionally, if no EndBlock is provided, the client is automatically registered for transaction notifications for all rescanned addresses and the final UTXO set. Rescan results are sent as recvtx and redeemingtx notifications. This call returns once the rescan completes.
Returns Nothing
Return to Overview
Method notifynewtransactions
Notifications txaccepted or txacceptedverbose
Parameters 1. verbose (boolean, optional, default=false) - specifies which type of notification to receive. If verbose is true, then the caller receives txacceptedverbose, otherwise the caller receives txaccepted
Description Send either a txaccepted or a txacceptedverbose notification when a new transaction is accepted into the mempool.
Returns Nothing
Return to Overview
Method stopnotifynewtransactions
Notifications None
Parameters None
Description Stop sending either a txaccepted or a txacceptedverbose notification when a new transaction is accepted into the mempool.
Returns Nothing
Return to Overview
Method session
Notifications None
Parameters None
Description Return a JSON object with details regarding a websocket client's current connection to the RPC server. This currently only includes the session ID, a random unsigned 64-bit integer that is created for each newly connected client. Session IDs may be used to verify that the current connection was not lost and subsequently reestablished.
Returns { (json object)
  "sessionid": n (numeric) the session ID
}
Example Return {
  "sessionid": 67089679842
}
Return to Overview
Method loadtxfilter
Notifications relevanttxaccepted
Parameters 1. Reload (boolean, required) - Load a new filter instead of adding data to an existing one
2. Addresses (JSON array, required) - Array of addresses to add to the transaction filter
3. Outpoints (JSON array, required) - Array of outpoints to add to the transaction filter
Description Load, add to, or reload a websocket client's transaction filter for mempool transactions, new blocks and rescanblocks.
Returns Nothing
Return to Overview
Method rescanblocks
Notifications None
Parameters 1. Blockhashes (JSON array, required) - List of hashes to rescan. Each next block must be a child of the previous.
Description Rescan blocks for transactions matching the loaded transaction filter.
Returns [ (JSON array)
  { (JSON object)
    "hash": "data", (string) Hash of the matching block.
    "transactions": [ (JSON array) List of matching transactions, serialized and hex-encoded.
      "serializedtx" (string) Serialized and hex-encoded transaction.
    ]
  }
]
Example Return [
  {
    "hash": "0000002099417930b2ae09feda10e38b58c0f6bb44b4d60fa33f0e000000000000000000d53...",
    "transactions": [
      "493046022100cb42f8df44eca83dd0a727988dcde9384953e830b1f8004d57485e2ede1b9c8..."
    ]
  }
]

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 DEPRECATED, for similar functionality see filteredblockconnected
Block connected to the main chain.		 notifyblocks
2 blockdisconnected DEPRECATED, for similar functionality see filteredblockdisconnected
Block disconnected from the main chain.		 notifyblocks
3 recvtx DEPRECATED, for similar functionality see relevanttxaccepted and filteredblockconnected
Processed a transaction output spending to a wallet address.		 notifyreceived and rescan
4 redeemingtx DEPRECATED, for similar functionality see relevanttxaccepted and filteredblockconnected
Processed a transaction that spends a registered outpoint.		 notifyspent and rescan
5 txaccepted Received a new transaction after requesting simple notifications of all new transactions accepted into the mempool. notifynewtransactions
6 txacceptedverbose Received a new transaction after requesting verbose notifications of all new transactions accepted into the mempool. notifynewtransactions
7 rescanprogress DEPRECATED, notifications not used by rescanblocks
A rescan operation that is underway has made progress.		 rescan
8 rescanfinished DEPRECATED, notifications not used by rescanblocks
A rescan operation has completed.		 rescan
9 relevanttxaccepted A transaction matching the tx filter has been accepted into the mempool. loadtxfilter
10 filteredblockconnected Block connected to the main chain; contains any transactions that match the client's tx filter. notifyblocks, loadtxfilter
11 filteredblockdisconnected Block disconnected from the main chain. notifyblocks, loadtxfilter

8.2 Notification Details
Method blockconnected
Request notifyblocks
Parameters 1. BlockHash (string) hex-encoded bytes of the attached block hash
2. BlockHeight (numeric) height of the attached block
3. BlockTime (numeric) unix time of the attached block
Description DEPRECATED, for similar functionality see filteredblockconnected
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,
   1389636265
  ],
 "id": null
}
Return to Overview
Method blockdisconnected
Request notifyblocks
Parameters 1. BlockHash (string) hex-encoded bytes of the disconnected block hash
2. BlockHeight (numeric) height of the disconnected block
3. BlockTime (numeric) unix time of the disconnected block
Description DEPRECATED, for similar functionality see filteredblockdisconnected
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,
   1389636265
  ],
 "id": null
}
Return to Overview
Method recvtx
Request rescan or 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 DEPRECATED, for similar functionality see relevanttxaccepted and filteredblockconnected
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
Method redeemingtx
Requests notifyspent and 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 DEPRECATED, for similar functionality see relevanttxaccepted and filteredblockconnected
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
Method txaccepted
Request notifynewtransactions
Parameters 1. TxHash (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
Method txacceptedverbose
Request 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
Method rescanprogress
Request 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 DEPRECATED, notifications not used by rescanblocks
Notifies a client with the current progress at periodic intervals when a long-running rescan is underway.
Example {
 "jsonrpc": "1.0",
 "method": "rescanprogress",
 "params":
  [
   "0000000000000ea86b49e11843b2ad937ac89ae74a963c7edd36e0147079b89d",
   127213,
   1306533807
  ],
 "id": null
}
Return to Overview
Method rescanfinished
Request 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 DEPRECATED, notifications not used by rescanblocks
Notifies a client that the 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
Method relevanttxaccepted
Request loadtxfilter
Parameters 1. Transaction (string) hex-encoded serialized transaction matching the client's filter loaded ith loadtxfilter
Description Notifies a client that a transaction matching the client's tx filter has been accepted into he mempool.
Example Example relevanttxaccepted notification (newlines added for readability):
{
 "jsonrpc": "1.0",
 "method": "relevanttxaccepted",
 "params": [
  "01000000014221abdcca25c8a3b0c044034875dece048c77d567a806f0c2e7e0f5e25a8f100..."
 ],
 "id": null
}
Method filteredblockconnected
Request notifyblocks, loadtxfilter
Parameters 1. BlockHeight (numeric) height of the attached block
2. Header (string) hex-encoded serialized header of the attached block
3. Transactions (JSON array) hex-encoded serialized transactions matching the filter for the client connection loaded with loadtxfilter
Description Notifies when a block has been added to the main chain. Notification is sent to all connected clients.
Example Example filteredblockconnected notification for mainnet block 280330 (newlines added for readability):
{
 "jsonrpc": "1.0",
 "method": "filteredblockconnected",
 "params":
  [
   280330,
   "0200000052d1e8813f697293e41942aa230e7e4fcc44832d78a1372202000000000000006aa...",
   [
    "01000000014221abdcca25c8a3b0c044034875dece048c77d567a806f0c2e7e0f5e25a8f100..."
   ]
  ],
 "id": null
}
Return to Overview
Method filteredblockdisconnected
Request notifyblocks, loadtxfilter
Parameters 1. BlockHeight (numeric) height of the disconnected block
2. Header (string) hex-encoded serialized header 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":
  [
   280330,
   "0200000052d1e8813f697293e41942aa230e7e4fcc44832d78a1372202000000000000006aa..."
  ],
 "id": null
}
Return to Overview

9. Example Code

This section provides example code for interacting with the JSON-RPC API in various languages.

9.1 Go

This section provides examples of using the RPC interface using Go and the rpcclient package.

9.1.1 Using getblockcount to Retrieve the Current Block Height

The following is an example Go application which uses the rpcclient package to connect with a btcd instance via Websockets, issues getblockcount to retrieve the current block height, and displays it.

package main

import (
	"io/ioutil"
	"log"
	"path/filepath"

	"github.com/btcsuite/btcd/rpcclient"
	"github.com/btcsuite/btcutil"
)

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 := &rpcclient.ConnConfig{
		Host:         "localhost:8334",
		Endpoint:     "ws",
		User:         "yourrpcuser",
		Pass:         "yourrpcpass",
		Certificates: certs,
	}
	client, err := rpcclient.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:

2018/08/27 11:17:27 Block count: 536027

9.1.2 Using getblock to Retrieve the Genesis Block

The following is an example Go application which uses the rpcclient package to connect with a btcd instance via Websockets, issues getblock to retrieve information about the Genesis block, and display a few details about it.

package main

import (
	"io/ioutil"
	"log"
	"path/filepath"
	"time"

	"github.com/btcsuite/btcd/chaincfg/chainhash"
	"github.com/btcsuite/btcd/rpcclient"
	"github.com/btcsuite/btcutil"
)

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 := &rpcclient.ConnConfig{
		Host:         "localhost:18334",
		Endpoint:     "ws",
		User:         "yourrpcuser",
		Pass:         "yourrpcpass",
		Certificates: certs,
	}
	client, err := rpcclient.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 := chainhash.NewHashFromStr(genesisHashStr)
	if err != nil {
		log.Fatal(err)
	}
	block, err := client.GetBlockVerbose(blockHash)
	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:

Hash: 000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f
Previous Block: 0000000000000000000000000000000000000000000000000000000000000000
Next Block: 00000000839a8e6886ab5951d76f411475428afc90947ee320161bbf18eb6048
Merkle root: 4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b
Timestamp: 2009-01-03 18:15:05 +0000 UTC
Confirmations: 534323
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 rpcclient package to connect with a btcd instance via Websockets and registers for blockconnected and blockdisconnected notifications with notifyblocks. It also sets up handlers for the notifications.

package main

import (
	"io/ioutil"
	"log"
	"path/filepath"
	"time"

	"github.com/btcsuite/btcd/chaincfg/chainhash"
	"github.com/btcsuite/btcd/rpcclient"
	"github.com/btcsuite/btcutil"
)

func main() {
	// Setup handlers for blockconnected and blockdisconnected
	// notifications.
	ntfnHandlers := rpcclient.NotificationHandlers{
		OnBlockConnected: func(hash *chainhash.Hash, height int32, t time.Time) {
			log.Printf("Block connected: %v (%d) %s", hash, height, t)
		},
		OnBlockDisconnected: func(hash *chainhash.Hash, height int32, t time.Time) {
			log.Printf("Block disconnected: %v (%d) %s", hash, height, t)
		},
	}

	// 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 := &rpcclient.ConnConfig{
		Host:         "localhost:8334",
		Endpoint:     "ws",
		User:         "yourrpcuser",
		Pass:         "yourrpcpass",
		Certificates: certs,
	}
	client, err := rpcclient.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:

2018/08/27 10:35:43 Client shutdown in 10 seconds...
2018/08/27 10:35:44 Block connected: 00000000000000000003321723557df58914658dc6fd963d547292a0a4797454 (534747) 2018-08-02 06:37:52 +0800 CST
2018/08/27 10:35:47 Block connected: 0000000000000000002e12773b798fc61dffe00ed5c3e89d3c306f8058c51e13 (534748) 2018-08-02 06:39:54 +0800 CST
2018/08/27 10:35:49 Block connected: 0000000000000000001bb311cd849839ce88499b91a201922f55a1cfafabe267 (534749) 2018-08-02 06:44:22 +0800 CST
2018/08/27 10:35:50 Block connected: 00000000000000000019d7296c9b5c175369ad337ec44b76bd4728021a09b864 (534750) 2018-08-02 06:55:44 +0800 CST
2018/08/27 10:35:53 Block connected: 00000000000000000022db98cf47e944ed58ca450c819e8fef8f8c71ca5d9901 (534751) 2018-08-02 06:57:39 +0800 CST
2018/08/27 10:35:53 Client shutting down...
2018/08/27 10:35:53 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 (can be installed with npm install ws) to connect with a btcd instance, issues notifyblocks to register for blockconnected and blockdisconnected notifications, and displays all incoming messages.

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');
})

Code contribution guidelines

Developing cryptocurrencies is an exciting endeavor that touches a wide variety of areas such as wire protocols, peer-to-peer networking, databases, 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.

Required Reading

  • Effective Go - The entire btcd suite follows the guidelines in this document. For your code to be accepted, it must follow the guidelines therein.
  • Original Satoshi Whitepaper - This is the white paper that started it all. Having a solid foundation to build on will make the code much more comprehensible.

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.

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

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.

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

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
    • Function comments should be complete sentences since they allow a wide variety of automated presentations such as 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

// convert a compact uint32 to big.Int
func CompactToBig(compact uint32) *big.Int {

RIGHT

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

// return err if amt is less than 5460
if amt < 5460 {
  return err
}

RIGHT

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

Model Git Commit Messages

This project prefers to keep a clean commit history with well-formed commit messages. This section illustrates a model commit message and provides a bit of background for it. This content was originally created by Tim Pope and made available on his website, however that website is no longer active, so it is being provided here.

Here’s a model Git commit message:

Short (50 chars or less) summary of changes

More detailed explanatory text, if necessary.  Wrap it to about 72
characters or so.  In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body.  The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.

Write your commit message in the present tense: "Fix bug" and not "Fixed
bug."  This convention matches up with commit messages generated by
commands like git merge and git revert.

Further paragraphs come after blank lines.

- Bullet points are okay, too
- Typically a hyphen or asterisk is used for the bullet, preceded by a
  single space, with blank lines in between, but conventions vary here
- Use a hanging indent

Prefix the summary with the subsystem/package when possible. Many other projects make use of the code and this makes it easier for them to tell when something they’re using has changed. Have a look at past commits for examples of commit messages.

Here are some of the reasons why wrapping your commit messages to 72 columns is a good thing.

  • git log doesn’t do any special special wrapping of the commit messages. With the default pager of less -S, this means your paragraphs flow far off the edge of the screen, making them difficult to read. On an 80 column terminal, if we subtract 4 columns for the indent on the left and 4 more for symmetry on the right, we’re left with 72 columns.
  • git format-patch –stdout converts a series of commits to a series of emails, using the messages for the message body. Good email netiquette dictates we wrap our plain text emails such that there’s room for a few levels of nested reply indicators without overflow in an 80 column terminal.

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.

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 development practice outlined above.

What is the review looking for?

The review is mainly ensuring the code follows the Development Practices and Code Contribution 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

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.

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!

Contribution Standards

Contribution Checklist

  • [  ] All changes are Go version 1.3 compliant
  • [  ] The code being submitted is commented according to the Code Documentation and Commenting 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 does not report any new issues that did not already exist

Licensing of Contributions

All contributions must be licensed with the ISC license. This is the same license as all of the code in the btcd suite.

Contact

IRC

Mailing Lists

  • btcd: discussion of btcd and its packages.
  • btcd-commits: readonly mail-out of source code changes.

Issue Tracker

The integrated github issue tracker is used for this project.

License

btcd is licensed under the copyfree ISC License.