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 throwsInvalid 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:
| Where | Mainnet | Testnet | Teratestnet | Default |
|---|---|---|---|---|
| BSV Desktop, network button | Mainnet | Testnet | TeraTestNet | Mainnet for a new wallet |
getNetwork in @bsv/sdk | mainnet | testnet | None of its own | Reads 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.
Related articles
To learn more about building on the BSV blockchain testnet, review these articles: