Skip to content
libspiffy

Local network (localnet)

localnet-teranode runs a complete regtest network on your machine. libspiffy talks to it exactly as it talks to mainnet: headers over the wire protocol, broadcasts and proofs through an ARC-compatible API. It’s the network the tutorial uses and the one libspiffy’s own integration tests run against.

The stack runs in Docker:

  • Teranode v0.16.0, a single regtest node.
  • Arcade v0.16.0, an ARC-compatible API for broadcast, transaction status and merkle paths.
  • Merkle Service v0.6.2, which builds the proofs Arcade serves.
  • An autominer, which mines a block every 10 minutes.
  • A faucet that holds the coinbase coins.

Start it

Section titled “Start it”
Terminal window
git clone https://github.com/twostack/localnet-teranode
cd localnet-teranode
./scripts/start.sh      # .env, containers, FSM to RUNNING, mine to 101, wait for Arcade
./scripts/status.sh     # containers, tip, faucet balance

You need Docker with about 4 GB free and Go 1.27 or later (for the faucet).

Point libspiffy at it

Section titled “Point libspiffy at it”
await libspiffy.initialize(
  isar: isar,
  secureStorage: secureStorage,
  networkType: 'regtest',
  peerAddresses: ['127.0.0.1:18444'],                         // headers
  arcConfig: ArcServiceConfig(baseUrl: 'http://127.0.0.1:23011'), // Arcade, no /v1
);

Arcade serves the ARC API at its root. Don’t add /v1 to its URL.

Get coins

Section titled “Get coins”
Terminal window
./scripts/faucet.sh send <address> <satoshis> --arcade
./scripts/mine.sh 1

Always pass --arcade. It sends the payment through Arcade, which then follows it to its merkle proof. Without it, the payment is mined but nobody can give you its proof. To import the coins into a wallet with their proof, follow tutorial step 4. Arcade’s GET /tx/{txid} returns the merklePath once the transaction is mined. Wrap it and the raw transaction in a BEEF and send ImportTransactionCommand.

Useful scripts

Section titled “Useful scripts”
Script What it does
./scripts/mine.sh [count] [address] Mine now (to the faucet unless an address is given)
./scripts/faucet.sh balance What the faucet can spend
./scripts/stop.sh Stop, keeping the chain
./scripts/reset.sh Stop and wipe the chain (the faucet key and .env are kept)

Things that differ from mainnet

Section titled “Things that differ from mainnet”
  • Fork heights. Genesis activates at height 100 and Chronicle at 200.
  • Fee floor. Arcade enforces 100 sat/kB, although Teranode here accepts any fee. libspiffy pays the policy rate ARC publishes.
  • Peer bans. Teranode’s wire-protocol service bans a peer whose user agent lacks BSV or Bitcoin SV for 24 hours, and every client on your machine shares one Docker gateway IP. libspiffy’s default /LibSpiffy-BSV:1.0/ passes. If another tool gets you banned, run docker restart tnl-legacy.
  • Testing from a phone. Set HOST_IP=0.0.0.0 in .env, rerun start.sh, and use your machine’s LAN address.

For running libspiffy’s own test suite against the stack, see Testing against localnet.