Getting Started

Running a Test Node

There are many different ways of interacting with the Bitcoin network. The main choices tend to be :

  • Run your own node
  • Connect to a third-party API
  • Run a self-hosted, light-weight edge-router e.g. a Planaria Eventchain Node

For the purposes of subsequent tutorials and code samples, there exists a special mode for running a Bitcoin node locally called Regression Test Mode or REGTEST. This is a very safe way to get started and the bitcoin client software remains fully functional. In regression test mode you are able to :

  • generate as many bitcoin tokens as your want (local use only)
  • transmit and receive transactions (locally only)
  • query for transactions
  • and pretty much all the other features of a public node

In Regression Test Mode the local node software does not connect to the larger bitcoin network (not even the public TestNet). This gives the developer absolute control over their playground, without having lots of external network events/transactions being broadcast into the local environment.

For the impatient, interested in different ways of interacting with the Bitcoin network, you can have a read through the Application Architecture section.

The different modes of running a local node are :

  • MAINNET- Connects your node to the live bitcoin network
  • TESTNET- Connects your node to the public test network
  • STN - Connects your node to the scaling test network. CAREFULL! The Scaling Test Network generates HUGE blocks. Expect block sizes in excess of 1 (one) gigabyte.
  • REGTEST- Regresstion Test Mode. Runs a node in local-only test mode with no connections to the public bitcoin networks. Great for local development. All the examples in this guide will assume a running local instance, configured in REGTEST mode.

Downloading Client Node Software

The Bitcoin Client Node software we will be using is the implementation known as BitcoinSV. You can obtain a copy of the software from the bitcoinsv download page. At the time of writing the latest version of the software is 1.0.3; you might want to download a newer version if available.

Regression Test Mode Configuration

The bitcoin node is configured via a file called bitcoind.conf. This file is expected to reside in the data folder of your bitcoin node installation. This folder is located at $BITCOIN_HOME/data; and the config file should be located at $BITCOIN_HOME/data/bitcoind.conf. This configuration file should be created if it does not exists.

For our Regression Test Node setup, we will configure the following parameters :

Setting Description value
daemon Set to (1) if we want to run in daemon mode (background) 0
regtest Set to (1) to run a regression test node 1
txindex Maintain a full transaction index,used by the getrawtransaction rpc call 1
rpcbind IP address for JSON-RPC Server to bind to 1
rpcport TCP port where JSON-RPC Server will listen for requests 1
whitelist Do not require local clients to authenticate to the JSON-RPC Server
debug More verbose logging. Useful. 1
excessiveblocksize Maximum block size that the node will accept 2000000000
maxstackmemoryusageconsensus Maximum amount of memory that a Script can consume during evaluation. 200000000

NOTE: BitcoinSV Node software has moved a consensus model wherein the block sizes are completed uncapped, and the maximum sizes are determined through miner-consensus. These settings are documented at the Choosing Consensus Settings page of the Bitcoin SV client node website.

Our bitcoind.conf will look as follows:

# Use the regtest network, because we can generate blocks as needed.

# The use of bitcoin cash address format is deprecated. Disable.
# In this example, we will keep bitcoind running in one terminal window.
# So we don't need it to run as a daemon.

# Have our local node generate a transaction index to allow for faster queries

# RPC settings (inbound RPC connections)


# Enable the JSON-RPC Server. This is required by bitcoin-cli.

# In this example we are only interested in receiving raw transactions.
# The address here is the URL where bitcoind will listen for new ZeroMQ connection requests.

# 2Gb execessive block size
# 200Mb max stack memory

Set the environment variable $BITCOIN_HOME to the directory where you installed the bitcoin client node.

export BITCOIN_HOME=~/bin/bitcoin-sv-1.0.3

We can now start our node by running the following command:

$BITCOIN_HOME/bin/bitcoind -datadir=$BITCOIN_HOME/data

You can monitor the log for the Regression Test Mode as follows :

tail -f $BITCOIN_HOME/data/regtest/bitcoind.log

Simulated Block Discovery (mining)

We can simulate the block discovery function of a bitcoin mining node in Regression Test Mode. Doing so also implicitly rewards a local test wallet with the block rewards.

Note that the Bitcoin network consensus rules require that Transaction Processors (mining nodes) can’t spend their block reward until at least 100 subsequent blocks have been discovered. This means that when we first start our bitcoind in regression test mode, we need to generate at least 101 blocks to get the reward of 1 block spendable from our local wallet.

Let’s generate our first coins

bitcoin-cli -datadir=$BITCOIN_HOME/data generate 101

You will see something like this in the end of your $BITCOIN_HOME/bitcoind.log file :

2020-06-02 16:01:16 AddToWallet abd8743a82a7fe4cf24766de165ad398b2992fbb6140b11479095495d253c226  new

You will now have some spendable coins in your local bitcoin wallet. This wallet is managed directly by the bitcoin client node.

Wallet Operations

There are several ways to interact with the default wallet created inside your local test node.

Show Wallet Balance

bitcoin-cli -datadir=$BITCOIN_HOME/data getbalance

Create new Receiving Address

bitcoin-cli -datadir=$BITCOIN_HOME/data getnewaddress

Send coins to different Address

Send 10 bitcoins to a address defined by the environment variable $RECIPIENT_ADDRESS

export RECIPIENT_ADDRESS=<paste some address here>
bitcoin-cli -datadir=$BITCOIN_HOME/data sendtoaddress $NEW_ADDRESS 10.00

Install the TwoStack SDK

This guide will use The TwoStack Wallet SDK in all code samples. Dart is a cross-platform language which allows one to build natively-compiled server-side and mobile (Android and iOS) applications. For mobile and web development we will use the Flutter framework. For building server-side applications we will, as much as possible attempt to minimise framework useage. That being said, the reader should consider the Aqueduct framework for server-side Dart applications.

Last modified June 15, 2021: Bitcoin4J Release Docs (1b1846b)