bchd

command module
v0.22.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 28, 2026 License: ISC Imports: 78 Imported by: 0

README

bchd

Build Status ISC License GoDoc

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

This project is a port of the btcd codebase to Bitcoin Cash. It provides a high powered and reliable blockchain server which makes it a suitable backend to serve blockchain data to lite clients and block explorers or to power your local wallet.

bchd does not include any wallet functionality by design as it makes the codebase more modular and easy to maintain. The bchwallet is a separate application that provides a secure Bitcoin Cash wallet that communicates with your running bchd instance via the API.

Table of Contents

Requirements

Go 1.26.0 or newer; use 1.26.9 or 1.27.2 or newer for the gRPC server's HTTP/2 security fixes.

Install

Install Pre-built Packages

The easiest way to run the server is to download a pre-built binary. You can find binaries of our latest release for each operating system at the releases page.

Build from Source

If you prefer to install from source do the following:

  • Install Go according to the installation instructions here: http://golang.org/doc/install

  • Run the following commands to obtain bchd, all dependencies, and install it:

go install github.com/gcash/bchd@v0.22.4

This will download the source code into your GOPATH and compile bchd and install it in your path.

For developers if you wish to place the working directory outside your GOPATH you can do so with Go >=1.12.x as follows:

mkdir workspace
cd workspace
git clone https://github.com/gcash/bchd.git
cd bchd
go install (or build or run, etc)

Dependencies will be automatically installed to $GOPATH/pkg/mod.

If you are a bchd contributor and would like to change the default config file (bchd.conf), make any changes to sample-bchd.conf and then run the following commands:

make bindata  # requires github.com/go-bindata/go-bindata/

Getting Started

To start bchd with default options just run:

./bchd

You'll find a large number of runtime options with the help flag. All of them can also be set in a config file. See the sample config file for an example of how to use it.

./bchd --help

You can use the common json RPC interface through the bchctl command:

./bchctl --help

./bchctl --listcommands

Bchd separates the node and the wallet. Commands for the wallet will work when you are also running bchwallet:

./bchctl -u username -P password --wallet getnewaddress

Docker

Building and running bchd in docker is quite painless. To build the image:

docker build . -t bchd

To run the image:

# Use stop-timeout to make sure the container exits cleanly!
docker run --stop-timeout=1200 bchd

To run bchctl and connect to your bchd instance:

# Find the running bchd container.
docker ps

# Exec bchctl.
docker exec <container> bchctl <command>

Documentation

The documentation is a work-in-progress. It is located in the docs folder.

Contributing

Contributions are definitely welcome! Please read the contributing guidelines before starting.

Security Disclosures

To report security issues please contact:

Chris Pacia (ctpacia@gmail.com) - GPG Fingerprint: 0150 2502 DD3A 928D CE52 8CB9 B895 6DBF EE7C 105C

or

Josh Ellithorpe (quest@mac.com) - GPG Fingerprint: B6DE 3514 E07E 30BB 5F40 8D74 E49B 7E00 0022 8DDD

License

bchd is licensed under the copyfree ISC License.

Documentation

Overview

Code generated for package main by go-bindata DO NOT EDIT. (@generated) sources: sample-bchd.conf

bchd is a full-node bitcoin cash implementation written in Go.

The default options are sane for most users. This means bchd will work 'out of the box' for most users. However, there are also a wide variety of flags that can be used to control it.

The following section provides a usage overview which enumerates the flags. An interesting point to note is that the long form of all of these options (except -C) can be specified in a configuration file that is automatically parsed when bchd starts up. By default, the configuration file is located at ~/.bchd/bchd.conf on POSIX-style operating systems and %LOCALAPPDATA%\bchd\bchd.conf on Windows. The -C (--configfile) flag, as shown below, can be used to override this location.

Usage:

bchd [OPTIONS]

Application Options:

-V, --version                  Display version information and exit
-C, --configfile=              Path to configuration file (default:
                               ~/.bchd/bchd.conf)
-b, --datadir=                 Directory to store data (default:
                               ~/.bchd/data)
    --logdir=                  Directory to log output. (default:
                               ~/.bchd/logs)
-a, --addpeer=                 Add a peer to connect with at startup
    --connect=                 Connect only to the specified peers at startup
    --nolisten                 Disable listening for incoming connections --
                               NOTE: Listening is automatically disabled if
                               the --connect or --proxy options are used
                               without also specifying listen interfaces via
                               --listen
    --listen=                  Add an interface/port to listen for
                               connections (default all interfaces port:
                               8333, testnet: 18333)
    --maxpeers=                Max number of inbound and outbound peers,
                               keeping --targetoutboundpeers of them for
                               outbound peers -- Persistent peers, from
                               --addpeer, --connect or addnode, are not
                               counted (default: 125)
    --maxpeersperip=           Max number of inbound and outbound peers per
                               IP -- Local addresses, such as a Tor daemon's,
                               are not limited (default: 5)
    --minsyncpeernetworkspeed= Disconnect sync peers slower than this
                               threshold in bytes/sec (default: 51200)
    --nobanning                Disable banning of misbehaving peers
    --banduration=             How long to ban misbehaving peers.  Valid time
                               units are {s, m, h}.  Minimum 1 second
                               (default: 24h0m0s)
    --banthreshold=            Maximum allowed ban score before disconnecting
                               and banning misbehaving peers. (default: 100)
    --whitelist=               Add an IP network or IP that will not be
                               banned. (eg. 192.168.1.0/24 or ::1)
    --agentblacklist=          A comma separated list of user-agent
                               substrings which will cause bchd to reject any
                               peers whose user-agent contains any of the
                               blacklisted substrings.
    --agentwhitelist=          A comma separated list of user-agent
                               substrings which will cause bchd to require
                               all peers' user-agents to contain one of the
                               whitelisted substrings. The blacklist is
                               applied before the whitelist, and an empty
                               whitelist will allow all agents that do not
                               fail the blacklist.
-u, --rpcuser=                 Username for RPC connections
-P, --rpcpass=                 Password for RPC connections
    --rpclimituser=            Username for limited RPC connections
    --rpclimitpass=            Password for limited RPC connections
    --rpclisten=               Add an interface/port to listen for RPC
                               connections (default port: 8334, testnet:
                               18334)
    --rpccert=                 File containing the certificate file (default:
                               ~/.bchd/rpc.cert)
    --rpckey=                  File containing the certificate key (default:
                               ~/.bchd/rpc.key)
    --rpcmaxclients=           Max number of RPC clients for standard
                               connections (default: 10)
    --rpcmaxwebsockets=        Max number of authenticated RPC websocket
                               clients, and of those yet to authenticate
                               (default: 25)
    --rpcmaxconcurrentreqs=    Max number of concurrent RPC requests that may
                               be processed concurrently (default: 20)
    --rpcquirks                Mirror some JSON-RPC quirks of Bitcoin Core --
                               NOTE: Discouraged unless interoperability
                               issues need to be worked around
    --rpcauthtimeout=          The number of seconds a connection to the RPC
                               server is allowed to stay open without
                               authenticating. To disable the timeout use 0.
                               (default: 10)
    --norpc                    Disable built-in RPC server -- NOTE: The RPC
                               server is disabled by default if no
                               rpcuser/rpcpass or rpclimituser/rpclimitpass
                               is specified
    --notls                    Disable TLS for the RPC server -- NOTE: This
                               is only allowed if the RPC server is bound to
                               localhost
    --nodnsseed                Disable DNS seeding for peers
    --externalip=              Add an ip or Tor v3 onion address to the list
                               of local addresses we claim to listen on to
                               peers
    --proxy=                   Connect via SOCKS5 proxy (eg. 127.0.0.1:9050)
    --proxyuser=               Username for proxy server
    --proxypass=               Password for proxy server
    --onion=                   Connect to tor hidden services via SOCKS5
                               proxy (eg. 127.0.0.1:9050)
    --onionuser=               Username for onion proxy server
    --onionpass=               Password for onion proxy server
    --noonion                  Disable connecting to tor hidden services
    --torisolation             Enable Tor stream isolation by randomizing
                               user credentials for each connection.
    --testnet                  Use the test network
    --testnet4                 Use the test 4 network
    --chipnet                  Use the chip network
    --regtest                  Use the regression test network
    --regtestanyhost           In regression test mode, allow connections
                               from any host, not just localhost
    --regtestnoreset           In regression test mode, don't reset the
                               network db on node restart
    --simnet                   Use the simulation test network
    --addcheckpoint=           Add a custom checkpoint.  Format:
                               '<height>:<hash>'
    --nocheckpoints            Disable built-in checkpoints.  Don't do this
                               unless you know what you're doing.
    --maxreorgdepth=           Depth at which main chain blocks are
                               finalized, so that blocks forking the chain
                               below them are rejected (-1 to disable)
                               (default: 10)
    --finalizationdelay=       Time in seconds a block must have been known,
                               and the node running, before the block can be
                               finalized (default: 7200)
    --dbtype=                  Database backend to use for the Block Chain
                               (default: ffldb)
    --profile=                 Enable HTTP profiling on the given port on
                               localhost, or on IP:port -- NOTE port must be
                               between 1024 and 65535
    --cpuprofile=              Write CPU profile to the specified file
-d, --debuglevel=              Logging level for all subsystems {trace,
                               debug, info, warn, error, critical} -- You may
                               also specify
                               <subsystem>=<level>,<subsystem2>=<level>,...
                               to set the log level for individual subsystems
                               -- Use show to list available subsystems
                               (default: info)
    --upnp                     Use UPnP to map our listening port outside of
                               NAT
    --excessiveblocksize=      The block size (in bytes) that P2P and RPC
                               message limits are sized for, and on regtest
                               and simnet the floor of the block size limit
                               -- 0 uses the network's default, which is also
                               the minimum: 2000000 on testnet4 and chipnet,
                               otherwise 32000000
    --minrelaytxfee=           The minimum fee rate in BCH/kB a transaction
                               must pay to be relayed, accepted into the
                               mempool and mined -- Must be above 0 and at
                               most 21000000 (default: 1e-05)
    --maxtxfee=                The maximum total fee in BCH of a transaction
                               sent with sendrawtransaction or checked with
                               testmempoolaccept, unless allowhighfees is set
                               (default: 0.1)
    --limitfreerelay=          Deprecated, has no effect: free transactions
                               are no longer relayed
    --norelaypriority          Deprecated, has no effect: transaction
                               priority is no longer used
    --trickleinterval=         Minimum time between attempts to send new
                               inventory to a connected peer (default: 50ms)
    --maxorphantx=             Max number of orphan transactions to keep in
                               memory (default: 100)
    --generate                 Generate (mine) bitcoins using the CPU
    --miningaddr=              Add the specified payment address to the list
                               of addresses to use for generated blocks -- At
                               least one address is required if the generate
                               option is set
    --blockminsize=            Deprecated, has no effect: blocks no longer
                               include transactions below the minimum relay
                               fee
    --blockmaxsize=            Maximum block size in bytes to be used when
                               creating a block -- 0 follows the consensus
                               limit less 1000 bytes
    --blockprioritysize=       Deprecated, has no effect: blocks no longer
                               have a high-priority area
    --cbflags=                 Comment to append to the coinbase input when
                               generating a block template. (default: /bchd/)
    --uacomment=               Comment to add to the user agent -- See BIP 14
                               for more information.
    --nopeerbloomfilters       Disable bloom filtering support
    --nocfilters               Disable committed filtering (CF) support
    --dropcfindex              Deletes the index used for committed filtering
                               (CF) support from the database on start up and
                               then exits.
    --sigcachemaxsize=         The maximum number of entries in the signature
                               verification cache, and in the cache of
                               transaction signature hashes (default: 100000)
    --utxocachemaxsize=        The maximum size in MiB of the UTXO cache
                               (default: 450)
    --gcpercent=               Garbage collection target percentage -- Higher
                               values use more memory and less CPU; a
                               negative value disables the collector (use
                               with GOMEMLIMIT). Ignored if GOGC is set
                               (default: 50)
    --blocksonly               Do not accept transactions from remote peers.
    --nodoublespendproof       Do not create, relay or answer queries for
                               double spend proofs
    --txindex                  Maintain a full hash-based transaction index
                               which makes all transactions available via the
                               getrawtransaction RPC
    --droptxindex              Deletes the hash-based transaction index from
                               the database on start up and then exits.
    --addrindex                Maintain a full address-based transaction
                               index which makes the searchrawtransactions
                               RPC available
    --dropaddrindex            Deletes the address-based transaction index
                               from the database on start up and then exits.
    --slpindex                 Maintain an index which makes slp transaction
                               validity and token metadata available via
                               various gRPC methods
    --slpcachemaxsize=         The maximum number of entries in the slp
                               indexer cache (default: 100000)
    --dropslpindex             Deletes the slp index from the database on
                               start up and then exits.
    --slpgraphsearch           Enables gRPC calls related to slp graph search.
    --relaynonstd              Relay non-standard transactions regardless of
                               the default settings for the active network.
    --rejectnonstd             Reject non-standard transactions regardless of
                               the default settings for the active network.
    --prune                    Delete historical blocks from the chain. A
                               buffer of blocks will be retained in case of a
                               reorg.
    --prunedepth=              The number of blocks to retain when running in
                               pruned mode. Cannot be less than 288.
                               (default: 4320)
    --targetoutboundpeers=     Number of outbound connections to maintain
                               (default: 8)
    --reindexchainstate        Rebuild the UTXO database from currently
                               indexed blocks on disk.
    --fastsync                 Download the UTXO set of the last checkpoint
                               that has one and sync full blocks from there
                               to the tip rather than from genesis.
    --grpclisten=              Add an interface/port to listen for
                               experimental gRPC connections (default port:
                               8335, testnet: 18335)
    --grpcauthtoken=           An authentication token for the gRPC API to
                               authenticate clients
    --grpcmaxsubscriptions=    Max number of gRPC subscriptions clients may
                               hold at once (default: 100)
    --grpcmaxfilterentries=    Max number of entries a gRPC subscription's
                               transaction filter may hold; an address,
                               outpoint or token ID counts once, a data
                               element once per 20 bytes (default: 100000)
    --grpcmaxconcurrentcalls=  Max number of gRPC calls other than
                               subscriptions in progress at once; up to 4
                               times as many more wait, and later ones are
                               refused (default: 16)
    --dbcachesize=             The maximum size in MiB of the database cache
                               (default: 500)
    --dbflushinterval=         The number of seconds between database flushes
                               (default: 1800)
    --prometheus=              Specify an (addr):port to serve prometheus
                               metrics (for example :9000 or
                               my-interface:9000, default disabled)

Help Options:

-h, --help                     Show this help message

Directories

Path Synopsis
Package addrmgr implements concurrency safe Bitcoin Cash address manager.
Package addrmgr implements concurrency safe Bitcoin Cash address manager.
Package bchec implements support for the elliptic curves needed for bitcoin.
Package bchec implements support for the elliptic curves needed for bitcoin.
pb
Package pb is a reverse proxy.
Package pb is a reverse proxy.
proxy command
Package blockchain implements bitcoin block handling and chain selection rules.
Package blockchain implements bitcoin block handling and chain selection rules.
fullblocktests
Package fullblocktests provides a set of block consensus validation tests.
Package fullblocktests provides a set of block consensus validation tests.
indexers
Package indexers implements optional block chain indexes.
Package indexers implements optional block chain indexes.
Package btcjson provides primitives for working with the bitcoin JSON-RPC API.
Package btcjson provides primitives for working with the bitcoin JSON-RPC API.
Package chaincfg defines chain configuration parameters.
Package chaincfg defines chain configuration parameters.
chainhash
Package chainhash provides abstracted hash functionality.
Package chainhash provides abstracted hash functionality.
cmd
addblock command
bchctl command
findcheckpoint command
gencerts command
utxotool command
Package connmgr implements a generic Bitcoin network connection manager.
Package connmgr implements a generic Bitcoin network connection manager.
Package database provides a block and metadata storage database.
Package database provides a block and metadata storage database.
cmd/dbtool command
ffldb
Package ffldb implements a driver for the database package that uses leveldb for the backing metadata and flat files for block storage.
Package ffldb implements a driver for the database package that uses leveldb for the backing metadata and flat files for block storage.
internal/treap
Package treap implements a treap data structure that is used to hold ordered key/value pairs using a combination of binary search tree and heap semantics.
Package treap implements a treap data structure that is used to hold ordered key/value pairs using a combination of binary search tree and heap semantics.
rpctest
Package rpctest provides a btcd-specific RPC testing harness crafting and executing integration tests by driving a `bchd` instance via the `RPC` interface.
Package rpctest provides a btcd-specific RPC testing harness crafting and executing integration tests by driving a `bchd` instance via the `RPC` interface.
internal
socks
Package socks dials connections through a SOCKS5 proxy such as Tor.
Package socks dials connections through a SOCKS5 proxy such as Tor.
Package mempool provides a policy-enforced pool of unmined bitcoin cash transactions.
Package mempool provides a policy-enforced pool of unmined bitcoin cash transactions.
Package netsync implements a concurrency safe block syncing protocol.
Package netsync implements a concurrency safe block syncing protocol.
Package peer provides a common base for creating and managing Bitcoin cash network peers.
Package peer provides a common base for creating and managing Bitcoin cash network peers.
Package rpcclient implements a websocket-enabled Bitcoin JSON-RPC client.
Package rpcclient implements a websocket-enabled Bitcoin JSON-RPC client.
Package txscript implements the bitcoin transaction script language.
Package txscript implements the bitcoin transaction script language.
Package wire implements the bitcoin wire protocol.
Package wire implements the bitcoin wire protocol.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL