Reading the chain

A wallet that checks its own merkle proofs needs the block headers to check them against. On the local network, Arcade doesn’t serve headers, so we take them from Teranode. There are three ways to do this.

Over the wire protocol

Teranode speaks the Bitcoin wire protocol on 127.0.0.1:18444: version and verack, getheaders and headers, and block announcements. A client that syncs headers from an SV Node already speaks it.

Do note that Teranode only accepts a peer whose user agent contains BSV or Bitcoin SV, with that exact capitalisation. It bans any other peer’s IP address for 24 hours. Every connection from our machine arrives from the same Docker gateway address, so one misconfigured client locks out every client on the machine. libspiffy’s default /LibSpiffy:1.0/ doesn’t pass, and a user agent such as /LibSpiffy-BSV:1.0/ does.

To lift a ban, we restart the service that holds it:

docker restart tnl-legacy

rpc.sh clearbanned does not help here, as the RPC never reaches that service.

Through the DataHub

The DataHub is Teranode’s HTTP interface, at http://127.0.0.1:18090/api/v1. It is also the most convenient way to look around, and there is a block explorer at http://127.0.0.1:18090/.

Path	What it gives us
/bestblockheader/json	the tip: its hash, height and header fields
/headers/<hash>?n=<count>	count headers back from a block, 80 bytes each (with /hex and /json variants)
/header/<hash>/json	one header
/block/height/<h>/json, /block/<hash>/json	a block: its header, coinbase_tx, subtrees and Transaction count
/tx/<txid>/hex	any Transaction the node holds, as raw hex
/txmeta/<txid>/json	the blocks a Transaction is in, its fee, size and parents
/utxos/<txid>/json	every Output of a Transaction, with its Locking Script, amount and whether it is unspent (OK)

/tx/<txid>/hex is handy when we need to put a Transaction into Extended Format: it gives us the Output an Input spends.

Through gossip

For a push when a block is mined, we can subscribe to Teranode’s libp2p topic teranode/bitcoin/1.0.0/regtest-block at /ip4/127.0.0.1/tcp/19905/p2p/<TERANODE_PEER_ID>, where the peer ID is in .env. Each message carries the block’s hash, height and 80-byte header.

The RPC

Teranode’s JSON-RPC listens on 127.0.0.1:19292. The stack’s rpc.sh fills in the credentials for us:

./scripts/rpc.sh getblockchaininfo
./scripts/rpc.sh getrawtransaction <txid>

Those who are used to bitcoin-cli should be warned that much of what it offered is missing. These work:

• generate, generatetoaddress
• getblockchaininfo, getbestblockhash, getblock, getblockbyheight, getblockhash, getblockheader, getchaintips
• getrawtransaction, sendrawtransaction
• getmininginfo, getpeerinfo, invalidateblock, reconsiderblock

These are listed, but not implemented: getblockcount, gettxout, gettxoutproof, verifytxoutproof, decoderawtransaction, decodescript, getblocktemplate, submitblock, getmempoolinfo and validateaddress, among others. The wallet methods are not there at all.

getblockchaininfo can lag a freshly mined block by a few seconds. The DataHub’s /bestblockheader/json does not, so that is the one to read the tip from.