Skip to content
libspiffy

1 · Run a local network

Your wallets need a network to talk to. localnet-teranode runs a single regtest Teranode in Docker. Alongside it run Arcade for ARC-compatible broadcast and merkle proofs, Merkle Service, an autominer and a faucet. You mine blocks when you want them.

Start the stack

Section titled “Start the stack”
Terminal window
git clone https://github.com/twostack/localnet-teranode
cd localnet-teranode
./scripts/start.sh

start.sh does the following:

  • writes .env
  • starts the containers
  • switches Teranode to RUNNING
  • mines to height 101 so the faucet has mature coins
  • waits for Arcade

It’s safe to run again.

Check it:

Terminal window
./scripts/status.sh                       # containers, tip height, faucet balance
curl http://127.0.0.1:23012/health        # Arcade: {"status":"ok"}

The two ports libspiffy uses

Section titled “The two ports libspiffy uses”
Port Service libspiffy setting
23011 Arcade: broadcast, transaction status, merkle paths. It serves the ARC API at its root, with no /v1. arcConfig: ArcServiceConfig(baseUrl: 'http://127.0.0.1:23011')
18444 Teranode’s Bitcoin wire protocol, where block headers come from peerAddresses: ['127.0.0.1:18444']

The stack serves other ports too (DataHub, RPC, propagation). You won’t need them here. The localnet-teranode README lists them all.

Chain facts worth knowing

Section titled “Chain facts worth knowing”
  • Regtest addresses use testnet prefixes (m… or n…).
  • Coinbase outputs mature after 100 blocks.
  • The autominer mines a block every 10 minutes. ./scripts/mine.sh 1 mines one now.
  • Arcade enforces a fee floor of 100 sat/kB and advertises it at GET /policy. libspiffy pays the policy rate ARC publishes.

If something goes wrong

Section titled “If something goes wrong”

Header sync can’t connect on 18444. Teranode’s wire-protocol service bans a peer whose user agent lacks BSV or Bitcoin SV for 24 hours. The ban is per IP, and every connection from your machine arrives from the same Docker gateway address. libspiffy’s default user agent, LibSpiffyActorSystem.defaultUserAgent, is /LibSpiffy-BSV:1.0/, which passes, but an older client or another tool can get your machine banned. Lift the ban with:

Terminal window
docker restart tnl-legacy

You want a fresh chain. Run ./scripts/reset.sh && ./scripts/start.sh. The faucet key and .env are kept.

You’re testing from a phone. Set HOST_IP=0.0.0.0 in .env and run start.sh again. Then use your machine’s LAN address instead of 127.0.0.1.

Next: install and initialize libspiffy →