BSV blockchainBSV blockchain

Configure SV Node

Configure SV Node for the network you run and the workload you expect. By the end you have a bitcoin.conf with the three required parameters and the options for your network, ready to start the node with. Every option works as a command-line argument (-key=value) or as a line in bitcoin.conf (key=value). Point to a different file with -conf=CONFIG_FILE. Run bitcoind -help for the full list of the version you installed, 1.2.3 at the time of writing.

Set the required parameters

SV Node 1.2.3 does not start until three parameters are set. Without them it exits with “Mandatory consensus parameter is not set” or “Mandatory policy parameter is not set”.

ParameterWhat it sets
excessiveblocksizeThe largest block you accept from any source, in bytes or with a unit (B, kB, MB, GB). 0 means unlimited.
maxstackmemoryusageconsensusThe most stack memory a script may use during verification after GenesisThe 2020 BSV blockchain protocol upgrade that removed most limit-based consensus rules, at consensus level. 0 means unlimited.
minminingtxfeeThe lowest fee rate, in BSV/kB, for a transaction to go into a block you create. 0.00000001 is 1 satoshi per kB.

Use this starting point. It runs on testnet, because testnet=1 selects the network. For regtest, replace that line with regtest=1:

bitcoin.conf
testnet=1
excessiveblocksize=10GB
maxstackmemoryusageconsensus=100MB
minminingtxfee=0.00000001

The first two are consensus settings, so choose them for your use case rather than copying the values above. The startup error points to the Genesis settings guidance.

Choose the network

Mainnet is the default. Add one of these options to run another network, each with its own P2PPeer-to-peer: the connections between nodes and RPCRemote procedure call: the interface that lets you control a running node with commands port:

OptionNetworkP2P portRPC port
testnet=1testnet1833318332
regtest=1regtest, blocks solved instantly1844418332
stn=1Scaling Test Network93339332
noneMainnet83338332

Override the defaults with port=PORT and rpcport=PORT.

Set the main options

The options below are grouped by what they control. Each one works in bitcoin.conf or on the command line.

Configure the RPC server

Set server=1 and credentials to call the node with bitcoin-cli or over HTTP. Replace RPC_USERNAME and RPC_PASSWORD with your own values. For the methods themselves, see SV Node RPC methods.

RPC gives full control of the node and its wallet. Keep rpcbind and rpcallowip on 127.0.0.1 or a private network, and never leave rpcpassword at a default. The bitcoinsv/bitcoin-sv Docker image generates a bitcoin.conf with rpcuser=bitcoin, rpcpassword=password and rpcallowip=::/0, so replace all three before you publish the port.

bitcoin.conf
server=1
rpcuser=RPC_USERNAME
rpcpassword=RPC_PASSWORD
rpcbind=127.0.0.1
rpcallowip=127.0.0.1

These options control how the RPC server authenticates callers and where it listens:

OptionUse
rpcauthA salted hash of the password in place of rpcuser and rpcpassword. The format is USERNAME:SALT$HASH.
rpcbindThe address to listen on. The default is all interfaces. Repeat it for more than one.
rpcallowipWho may connect, as an IP, a network and netmask or a CIDR. Repeat it for more than one.
rpcthreadsThreads serving RPC calls. The default is 4.
rest=1Accept public REST requests. The default is off.

Tune connections and peers

These options control which peers your node connects to and who can connect to it:

OptionUse
listenAccept inbound connections. The default is 1 unless you use -proxy or -connect.
maxconnectionsMaximum peer connections. The default is 125.
maxconnectionsfromaddrMaximum inbound connections from one address. 0 is unlimited and the default.
addnode=IP_ADDRESSA peer to connect to and keep. Repeat it for more than one.
connect=IP_ADDRESSConnect only to these peers. Repeat it for more than one.
whitelist=IP_OR_NETWORKPeers that cannot be banned for misbehavior and whose transactions are always relayed.
whitebind=ADDRESSBind to an address and whitelist the peers that connect to it.
banscoreMisbehavior threshold before a peer is disconnected. The default is 100.

Set limits and storage

These options cap the memory, database cache and transaction size, and choose how much of the chain the node keeps:

prune deletes old blocks from your node for good. Undoing it means downloading the chain again.

OptionUse
maxmempool=SIZE_MBMemory for the mempool, in megabytes or with a unit. The default is 1,000 and the minimum 300.
dbcache=SIZE_MBCache for the databases except the coins database, in megabytes. The default is 512, from 4 to 16,384.
blockmaxsize=SIZEThe largest block you will mine. It never exceeds excessiveblocksize.
maxtxsizepolicy=SIZEThe largest transaction you relay and mine. The default is 10 MB.
maxstackmemoryusagepolicy=SIZEStack memory per transaction you relay and mine. The default is 100 MB and it must not exceed the consensus value.
prune=MIB_TO_KEEPDelete old blocks. 1 allows pruning by RPC, a value above 550 prunes automatically to that many MiB. The help text marks it as incompatible with txindex, and 1.2.3 prints no error when both are set, so do not combine them.
txindex=1Keep a full transaction index, used by getrawtransaction. The default is off.

Run getsettings on a running node to see the policy limits it applies, and dumpparameters to see the options it was started with.

Send notifications

SV Node can publish block and transaction events over ZeroMQA messaging library the node uses to publish events to other programs. Set zmqpubhashblock, zmqpubhashtx, zmqpubrawblock or zmqpubrawtx to an address, for example zmqpubhashblock=tcp://127.0.0.1:28332. Consume everything you enable, because unread notifications use memory. The repository documents all notification options in doc/zmq.md.

Debug

Set debug=CATEGORY for one category, for example debug=rpc, or debug=1 for all. printtoconsole=1 sends the log to the console instead of bitcoind.log, which suits a container.

Next steps

With the node configured, look up the calls you can make on it.