Skip to content
twostacktwostacktwostack

Overview

Sooner or later every application we build has to put a Transaction on the network and wait for it to be mined. We don’t want to do that for the first time on mainnet, with real coins, and the public test networks are slow and shared with everyone else. What we want is a network of our own, on our own machine, where we can mine a block whenever we like.

That is what Regression Test Mode (REGTEST) gives us. A regtest node runs the full Bitcoin SV rules, but it never connects to any other network, not even the public testnet. In regtest mode we are able to:

  • mine blocks on demand, and so create as many test coins as we want,
  • broadcast Transactions and follow them until they are mined,
  • get back the merkle proof of every Transaction we broadcast,
  • test every step of a payment, without anyone else’s Transactions getting in the way.

In 2020 this tutorial walked through installing the SV Node client, writing a bitcoind.conf and driving the node’s own wallet with bitcoin-cli. The network has since moved to Teranode, and Transactions now reach it through a broadcast service rather than a node’s RPC. Teranode has no wallet, and no bitcoin-cli. Those pages are retired, and the setup below replaces them.

What is inside

Section titled “What is inside”

We use localnet-teranode, which brings up a complete regtest network in Docker with a single command. It is the same stack the libspiffy and libtokensv tests run against.

Component Version What it does for us
Teranode v0.16.0 The regtest node itself
Arcade v0.16.0 The ARC-compatible broadcast API: we submit Transactions, follow their status and fetch their merkle proofs
Merkle Service v0.6.2 Follows the node’s gossip, and gives Arcade what it needs to build the merkle proofs
Autominer Mines a block every 10 minutes, as the real network would
Faucet A small Go program that holds the mined coins and sends them to our test Addresses

Figure 1 shows how the pieces fit together.

Our application broadcasts through Arcade, and reads headers and chain data from Teranode directly. Arcade passes Transactions to Teranode. Merkle Service follows Teranode’s gossip and sends Arcade the proofs. The faucet and autominer mine and spend through Teranode.Our applicationArcadeMerkle ServiceFaucet, autominerTeranode (regtest)broadcast, status, proofsheaders,chain dataTransactionsgossipproofsmine, spendDataHub 18090 · RPC 19292 · wire protocol 18444 · libp2p 19905
Figure 1: The parts of localnet-teranode, and what our application talks to

Referring to Figure 1, we notice a few interesting things:

  1. Our application broadcasts through Arcade, never through the node. This is the same arrangement we have on mainnet, which is the point: code that works against the local network works against a public broadcaster with a change of address.
  2. The merkle proof doesn’t come from the node either. Merkle Service watches the blocks and subtrees that Teranode gossips, and hands Arcade the pieces from which it builds each proof.
  3. For block headers and other chain data we go to Teranode directly, through its DataHub or the Bitcoin wire protocol.
  4. Since Teranode has no wallet, the faucet does the job that bitcoin-cli sendtoaddress used to do.

Do note that Arcade has since been renamed BSV Broadcaster (from v0.19.0). The local network still runs Arcade v0.16.0, so these pages use the name the containers and logs use. The API is the same. See Broadcasting and merkle proofs for the public broadcasters.

The tutorial

Section titled “The tutorial”