BSV blockchainBSV blockchain

How BSV blockchain networks differ

Choose the right network for each stage of your app, and keep the wallet and your code on the same one. The BSV blockchain has a live network, Mainnet, and test networks whose coins have no value. Each network keeps its own coins and history, and nothing moves from one to another.

What each network is for

An app developer works with three networks:

  • Mainnet

    The live BSV blockchain

    • Coins are real BSV with a market value
    • A payment cannot be undone
    • Use it when your app is ready for real users
  • Testnet

    A public test network

    • Test coins are free and have no value
    • The examples in these docs use it
    • Use it to build and test your app
  • Teratestnet

    The test network for Teranode

    • Test coins of its own, separate from testnet
    • Runs on Teranode, the new BSV blockchain node software
    • Use it only to test against Teranode on purpose

Testnet and teratestnet each have their own faucetA site that sends free test coins to an address. The wallet toolbox also accepts stn and tstn, scaling test networks that need endpoints you configure yourself, and mock for test utilities. App examples do not use them.

Why the wallet and the code must agree

A transaction exists only on the network that accepted it. When the wallet, your code and the services it calls point at different networks, the error rarely names the network:

  • Coins from a testnet faucet do not show in BSV Desktop while it is on TeraTestNet, since the wallet keeps a separate balance on each network.
  • A proof check against the wrong network fails. new WhatsOnChain() with no argument checks the Merkle pathThe proof that a transaction is in a block against Mainnet, so a testnet transaction throws Invalid merkle path, as in Try the BSV blockchain in your browser.
  • An explorer for one network does not find a transaction from another. A testnet transaction shows on the testnet explorer of WhatsOnChain, not on its Mainnet explorer.

Where each package names the network

Several packages default to Mainnet, so code meant for testnet that leaves out the network runs on Mainnet.

Code that runs on Mainnet by mistake spends real BSV. Pass the network in every call that takes one.

Each package and BSV Desktop name the same network in their own way:

WhereMainnetTestnetTeratestnetDefault
BSV Desktop, network buttonMainnetTestnetTeraTestNetMainnet for a new wallet
getNetwork in @bsv/sdkmainnettestnetNone of its ownReads the wallet
ServerWallet.create in @bsv/simple'main''testnet'Not accepted'main'
chain in @bsv/wallet-toolbox'main''test''ttn'None, you pass it
WhatsOnChain in @bsv/sdk'main''test'Not accepted'main'
networkPreset of overlay lookups in @bsv/sdk'mainnet''testnet''teratestnet''mainnet'

An app that uses WalletClient does not set the network. It follows the wallet, and getNetwork reads which network that is. getNetwork returns only mainnet or testnet, so it cannot tell teratestnet apart from them. For a server wallet on teratestnet, use @bsv/wallet-toolbox with the chain 'ttn', since ServerWallet does not accept it. This page was written against @bsv/sdk 4.0.1, @bsv/simple 0.7.2, @bsv/wallet-toolbox 2.15.1 and BSV Desktop 3.3.1.

How to tell which network you are on

Keys are not tied to a network. BSV Desktop keeps the same identity keyThe public key that identifies a wallet to an app on every network. The same key gives a Mainnet address that starts with 1 and a testnet address that starts with m or n.

The address format only shows how the address was encoded. toAddress() in @bsv/sdk uses the Mainnet format unless you pass 'testnet', so code can print a Mainnet-format address for a key it uses on testnet. To know the network, ask the wallet with getNetwork and stop when the answer differs from the network you intend, as in Check the network from your app.

To learn more about building on the BSV blockchain testnet, review these articles: