MultiChain 1.0 runtime parameters

Parameters that affect the behavior of individual MultiChain 1.0 nodes

Note: This page has been kept for MultiChain 1.0 – documentation for the MultiChain 2 runtime parameters is now available.

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 three ways (in descending order of priority):

  • On the command line, e.g. multichaind chain1 -hideknownopdrops=1
  • As extra lines in the local node’s blockchain configuration file, e.g. hideknownopdrops=1 in ~/.multichain/chain1/multichain.conf
  • As extra lines in the global blockchain configuration file, e.g. hideknownopdrops=1 in ~/.multichain/multichain.conf

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

A selection of runtime parameters can be retrieved using the getruntimeparams API call, and a small number of parameters can be changed while MultiChain is running using setruntimeparam.

Selected Bitcoin Core parameters

MultiChain supports the full set of runtime parameters of Bitcoin Core (as of version 0.10), with many additions. The full list can be seen by running multichaind with no parameters, but some of the most useful parameters are listed below:

Parameter Description Default
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
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 the MultiChain’s data is located. ~/.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
port Listen for incoming peer-to-peer connections on this port. default-network-port in blockchain parameters
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
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 network/CIDR (e.g. 1.2.3.4/24). Use multiple times to allow multiple IPs or ranges. 127.0.0.1
rpcport Listen for incoming JSON-RPC API commands on this port. default-rpc-port in blockchain parameters
shrinkdebugfile Shrink the debug.log file if it gets too large, both when the node starts up and after each block is processed. From MultiChain 1.0.2, this is applied to other log files as well. See also shrinkdebugfilesize. 1 unless debug is used.
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
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

New MultiChain parameters

MultiChain adds several new runtime parameters to access its additional functionality. These new parameters are listed below:

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
Other MultiChain parameters
Parameter Description Default
autosubscribe Set this parameter to assets, streams or assets,streams to automatically subscribe to every new asset and/or stream created on the blockchain, without requiring use of the subscribe command. 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
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
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. Both ends of the initial connection must be running MultiChain 1.0 beta 2 or later. 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
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
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
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
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. (Requires MultiChain 1.0.3 or later.) n/a
shrinkdebugfilesize If shrinkdebugfile is 1, this controls the maximum size of the debug files affected. When one of these files reaches over 5 times this number of bytes, it is reduced back down to this size. 200000
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
walletdbversion This controls which wallet database is used, where 1 means the original version inherited from Bitcoin Core, and 2 means the new fully scalable MultiChain wallet – more explanation here. To change wallet versions, the rescan parameter must also be used. 2
walletnotifynew This works like walletnotify but is only executed when a transaction is first seen. (Requires MultiChain 1.0.3 or later.) n/a