MultiChain runtime parameters

Parameters that affect the behavior of individual MultiChain nodes

MultiChain’s runtime parameters only affect individual nodes in a network, by modifying the behavior of a specific multichaind process. This makes them different from blockchain parameters which are global to a blockchain, and most of which are critical to that blockchain’s consensus.

Runtime parameters can be specified in one of five ways (in descending order of priority):

  • A selected subset of parameters can be changed while MultiChain is running using the setruntimeparam API call.
  • On the command line, e.g. multichaind chain1 -hideknownopdrops=1
  • In the per-blockchain set runtime params file, e.g. ~/.multichain/chain1/setruntimeparam.conf (see storeruntimeparams below).
  • In the per-blockchain configuration file, e.g. ~/.multichain/chain1/multichain.conf
  • In the global configuration file, e.g. ~/.multichain/multichain.conf

For the last three possibilities, these lines take the format param=value in the file, e.g. hideknownopdrops=1.

Note that you can change this ~/.multichain/ path using the -datadir= option, and %APPDATA%\MultiChain\ is the equivalent on Windows.

List of parameters

MultiChain supports all runtime parameters in Bitcoin Core 0.10, with many additions. The full list can be seen by running multichaind with no parameters, and the most important parameters are listed below. Parameters and values which require MultiChain Enterprise are highlighted like this.

Parameter Description Default
acceptfiltertimeout Maximum running time in milliseconds when (a) using a transaction filter to validate an unconfirmed transaction received over the network, and (b) using a stream filter to validate a stream item being retrieved. To prevent breaks in consensus, no timeout is applied when using a transaction filter to validate the transactions in a block – see Smart Filters for more details. 100
allowunencrypted Available in MultiChain Enterprise only. If the onlyencrypted runtime parameter is used, this still allows unencrypted peer-to-peer connections to these specific IP addresses. Values can be a single IP (e.g. 1.2.3.4), a network/netmask (e.g. 1.2.3.4/255.255.255.0) or a CIDR (e.g. 1.2.3.4/24). Use multiple times to allow multiple IPs or ranges. n/a
autosubscribe Set this parameter to automatically subscribe to new streams and/or assets, without requiring use of the subscribe command. Pass as a comma-delimited list containing assets and/or streams. In MultiChain Enterprise, use one or more of streams-items,streams-items-local,streams-keys,streams-keys-local,streams-publishers,streams-publishers-local,streams-retrieve instead of streams to control which indexes to build and whether to retrieve off-chain items automatically. n/a
bantx A comma-delimited list of txids for transactions that should not be accepted by the node. Any new incoming block containing one of these transactions will also be considered invalid, but previously accepted and verified blocks will not be affected. n/a
blocknotify Execute this command when a new block is added at the end of the current chain. A %s in the command parameters will be substituted with the block hash. n/a
chunkquerytimeout Wait this number of seconds before assuming that a chunk query (to the network as a whole) has failed, returning the chunk back to the queue for later retrying. 25
chunkrequesttimeout Wait this number of seconds before assuming that a chunk retrieval request (to a specific source node) has failed, returning the chunk to the queue for later retrying from a different source. 10
daemon Run multichaind in the background as a daemon to accept JSON-RPC API commands. You should generally use this option every time. Use -daemon as a command line option. 0
datadir The directory in which MultiChain’s data is stored. The data for each blockchain is stored within a subdirectory of this directory, which shares the blockchain’s name. ~/.multichain/ (Linux), %APPDATA%\MultiChain\ (Windows)
debug Output additional debug information to the debug.log log file. Pass mchn to log general MultiChain-specific events, mcapi for all API requests and responses, mccoin for changes to the UTXO set, mcatxo for coin selection, mcminer for locally created blocks and mcblock for details of all new blocks. All Bitcoin Core values are also supported. Use this parameter multiple times to specify multiple types of debug information. n/a
flushsourcechunks Ensure that data for offchain items published by this node is flushed to disk before the transaction referencing them is broadcast. This is important for durability but can incur a performance penalty. 1
handshakelocal Manually override the wallet address which is used for handshaking with other peers in a MultiChain blockchain. This is helpful if the address previously used for handshaking has lost connect permissions, and the node does not yet know which of its other addresses to use, because it has been disconnected from the chain. n/a
healthcheckport Available in MultiChain Enterprise only. If this is set, the node opens an additional port for health checking that will respond even if all main API threads are busy. To retrieve a health check, send this port a simple HTTP GET / request or a gethealthcheck JSON-RPC API command, authenticated in either case like a regular API request. n/a
hideknownopdrops Remove recognized MultiChain OP_DROP metadata from the responses to calls like decoderawtransaction, decodescript, getrawtransaction, gettxout and listunspent which show the content of transaction output scripts, whether in raw hexadecimal or decoded form. This option is provided to help with backwards compatibility for tools built on Bitcoin Core, which get confused by this metadata. 0
initprivkey Initialize the node’s wallet with a specific private key (formatted as per the output of dumpprivkey) instead of a random self-generated key. This can be helpful in reducing the number of steps required during a network deployment but has security implications, e.g. command-line parameters may be visible to other users. n/a
lockadminminerounds
miningrequirespeers
mineemptyrounds
miningturnover		 These override the recommendations provided by the lock-admin-mine-rounds, mining-requires-peers, mine-empty-rounds and mining-turnover blockchain parameters, and should be used with caution. Their meaning is documented here. blockchain parameters
lockblock Blocks on branches without this block (passed as a block hash) will be rejected. This allows a particular branch of a chain to be manually selected. n/a
lockinlinemetadata Skip outputs containing inline metadata when performing automatic coin selection. (These outputs can still be spent directly using createrawtransaction and appendrawtransaction.) 1
logdir The directory in which MultiChain’s log data is stored. The log data for each blockchain is stored within a subdirectory of this directory, which shares the blockchain’s name. same as datadir
maxqueryscanitems The maximum number of transactions to decode for a querying request (currently liststreamqueryitems). 5000
maxshowndata The maximum number of bytes to show in the data field of API responses. Pieces of data larger than this will be returned as an object with txid, vout and size fields, for use with the gettxoutdata command. 16384
offline Start MultiChain in offline mode, so that it does not accept incoming (or create outgoing) peer-to-peer connections. For stronger security, use multichaind-cold, whose peer-to-peer networking code is disabled at compile time – see cold nodes and wallets for more information. 0
onlyencrypted Available in MultiChain Enterprise only. Only allow encrypted peer-to-peer connections to other nodes. (These must also be using MultiChain Enterprise.) 0
port Listen for incoming peer-to-peer connections on this port. default-network-port in blockchain parameters
purgemethod Available in MultiChain Enterprise only. Controls the method used for wiping data from disk when purging information from the node. Allowed values include unlink (no wiping), zero (all zeroes), one (all ones), zeroone (zeroes then ones) and random1–random4 (one to four random passes). The following values from the srm Unix command are also supported: simple, dod, doe, rcmp, gutmann. zero
reindex Rebuild the blockchain and reindex transactions on startup. 0
rescan Rebuild the set of transactions in the node’s wallet on startup, including those relating to addresses in the wallet and subscribed assets and streams. 0
retryinittime When attempting to connect to a new blockchain for the first time, set this above 0 to keep retrying for the specified number of seconds. During this retrying period, two API commands are available: getinitstatus to check on progress and stop to stop the node. Note that before a node has successfully retrieved the blockchain parameters, its API will respond on port 8570 since it does not yet know the chain’s default-rpc-port. This behavior can be overridden using the rpcport runtime parameter. 0
rpcallowip Allow incoming JSON-RPC API connections from these IP addresses. Values can be a single IP (e.g. 1.2.3.4), a network/netmask (e.g. 1.2.3.4/255.255.255.0) or a CIDR (e.g. 1.2.3.4/24). Use multiple times to allow multiple IPs or ranges. 127.0.0.1
rpcallowmethod Only allow certain methods, provided as a comma-delimited list, to be accessed in the JSON-RPC API. This can be used multiple times. If omitted, all methods are allowed. n/a
rpcport Listen for incoming JSON-RPC API commands on this port. default-rpc-port in blockchain parameters
sendfiltertimeout Maximum running time in milliseconds when using a transaction or stream filter to validate a new transaction (possibly containing stream items) being sent. If any filter runs longer than this time, its execution will be aborted and the transaction will be rejected – see Smart Filters for more details. 20
shortoutput When running multichaind, only show the node address (if connecting was successful) or an address in the wallet (if connect permissions must be granted by another node). This is useful for building automated deployment scripts. 0
shrinkdebugfile Shrink the debug.log file and other log files if they get too large, both when the node starts up and after each block is processed. See also shrinkdebugfilesize. 1 unless debug is used.
shrinkdebugfilesize If shrinkdebugfile is 1, this controls the maximum size of the debug and log files affected. When one of these files reaches over 5 times this number of bytes, it is reduced back down to this size. 200000
storeruntimeparams Persistently store any changes made to the runtime parameters using the setruntimeparam API command in the setruntimeparam.conf file, which will be read by MultiChain on future launches. (Requires MultiChain 2.0.2 or later.) 0
txindex Keep a full index of all transactions, rather than just those relevant to this wallet. This allows getrawtransaction to be used for any transaction. Use -txindex as a command line option. Until reindex is implemented, this must be set before multichaind runs for the first time. 1
v1apicompatible Include all fields that appeared in MultiChain 1.0.x API responses, even if they have been superceded. 0
walletdbversion This controls which wallet database format is used, where 2 means a MultiChain 1.0-compatible wallet that uses Berkeley DB and 3 (added in 2.0 beta 2) means the newer proprietary wallet format. Wallets can be upgraded but not downgraded. 2
walletnotify Execute this command when a transaction is first seen or confirmed, if it relates to an address in the wallet or a subscribed asset or stream. The substitutions below can be used in the command parameters to pass more information (only %s is supported if walletdbversion=1). See also walletnotifynew below.

  • %m – name of blockchain
  • %s – hexadecimal transaction ID
  • %h – hexadecimal raw transaction
  • %j – JSON transaction description (as output by decoderawtransaction)
  • %c – 1 if this is the first time the transaction has been seen, 0 otherwise
  • %n – height of the block in which the transaction appears (-1 if unconfirmed)
  • %b – hash of the block in which the transaction appears (all 0s if unconfirmed)
  • %a – comma-delimited list of wallet addresses used in the transaction
  • %e – comma-delimited list of subscribed assets or streams affected by the transaction, passed as the asset or stream issuance/creation txids
 n/a
walletnotifynew This works like walletnotify but is only executed when a transaction is first seen. n/a
Autocombine parameters

The parameters below control MultiChain’s automatic combining of large groups of unspent outputs (UTXOs) belonging to the same address into a single unspent output. This can improve wallet performance, especially for block creators in a chain with short block times and non-zero rewards. See also the combineunspent call in the JSON-RPC API which enables this process to be triggered manually.

Parameter Description Default
autocombineminconf Only automatically combine outputs with at least this number of confirmations. 1
autocombinemininputs Require at least this number of inputs in an automatic combine transaction. 50
autocombinemaxinputs Use no more than this number of inputs in an automatic combine transaction. 100
autocombinedelay Minimum delay between automatic combine transactions, in seconds. 1
autocombinesuspend Suspend automatic combine transactions for this number of seconds after a call to listunspent. This avoids changing the unspent output list while external code might be dependent on that list. 15