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 :
|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||127.0.0.1|
|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. regtest=1 # The use of bitcoin cash address format is deprecated. Disable. usecashaddr=0 # In this example, we will keep bitcoind running in one terminal window. # So we don't need it to run as a daemon. daemon=1 # Have our local node generate a transaction index to allow for faster queries txindex=1 # RPC settings (inbound RPC connections) rpcbind=127.0.0.1 rpcport=18332 whitelist=127.0.0.1 debug=1 rpcworkqueue=128 rpcthreads=128 rpctimeout=220 # Enable the JSON-RPC Server. This is required by bitcoin-cli. server=1 # 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. #zmqpubrawtx=tcp://127.0.0.1:28332 #zmqpubrawblock=tcp://127.0.0.1:28332 zmqpubhashtx=tcp://127.0.0.1:28332 zmqpubhashblock=tcp://127.0.0.1:28332 #See https://bitcoinsv.io/choosing-consensus-settings/ # 2Gb execessive block size # 200Mb max stack memory excessiveblocksize=2000000000 maxstackmemoryusageconsensus=200000000
Set the environment variable $BITCOIN_HOME to the directory where you installed the bitcoin client node.
We can now start our node by running the following command:
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.
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.