MultiChain lets you control every aspect of your blockchain

Configuring a blockchain

The parameters of a blockchain are configured after creating the chain by running multichain-util create [chain-name], and before starting the chain by running multichaind [chain-name].

Parameters are set in the params.dat file for each blockchain, which can be modified in any text editor. Once the blockchain is initialized, these parameters cannot be changed. To prevent accidental modification, a hash of the parameters is added to params.dat when the chain starts running.

When new nodes attempt to connect to an existing blockchain, they first download a minimal set of blockchain parameters from the existing node, and write them to the params.dat file in the appropriate directory. Once they are granted permission to connect, they are able to download the full set of blockchain parameters.

The parameters for a blockchain can be retrieved using the getblockchainparams API call.

Full list of blockchain parameters

Below is a full list of parameters in the params.dat file, grouped by section.

Basic chain parameters
Parameter Description Example
chain-protocol Use multichain for a MultiChain blockchain or bitcoin for a bitcoin-style blockchain with no permissions, native assets or streams. multichain
chain-description Textual description of the blockchain for display to users. Internal chain
root-stream-name Name of the root stream for general data storage (leave blank for none). root
root-stream-open Allow anyone with send permissions to write to the root stream. true
chain-is-testnet Whether to set testnet to true in the output of various JSON-RPC API calls. This is for compatibility with Bitcoin Core and does not affect any other testnet-like behavior. false
target-block-time Target average number of seconds between blocks, i.e. delay for confirming transactions. If this is below 10 seconds, it is recommended to set mining-turnover low, to minimize the number of forks. 60 (one minute)
maximum-block-size Maximum number of bytes in each block, to prevent network flooding by a rogue miner. 1000000 (1MB)
Global permissions
Parameter Description Example
anyone-can-connect Apply no restriction to connecting to the network, i.e. nodes do not require connect permissions. false
anyone-can-send Apply no restriction to sending transactions, i.e. signing transaction inputs. false
anyone-can-receive Apply no restriction to receiving transactions, i.e. appearing in transaction outputs. false
anyone-can-receive-empty Apply no restriction to addresses which appear in transaction outputs containing no native currency, assets or other metadata. Only relevant if anyone-can-receive=false. This allows addresses without receive permission to include a change output in non-asset transactions, e.g. to publish to streams. true
anyone-can-create Apply no restriction to creating new streams. false
anyone-can-issue Apply no restriction to issuing (creating) new native assets. false
anyone-can-mine Apply no restriction to mining blocks for the chain, i.e. confirming transactions. false
anyone-can-activate Apply no restriction to changing connect, send and receive permissions of other users. false
anyone-can-admin Apply no restriction to changing all permissions of other users. false
support-miner-precheck Support advanced miner permission checks by caching the inputs spent by an administrator when setting admin or mine permissions – see permissions management for more information. true
allow-p2sh-outputs Allow pay to scripthash outputs, where the redeem script is only revealed when an output is spent. See permissions management for more information about permissions and P2SH addresses. true
allow-multisig-outputs Allow multisignature outputs, where more than one address is explicitly listed in a transaction output, and a given number of these addresses are required to sign in order to spend that output. See permissions management for more information about permissions and multisig outputs. true
Consensus requirements
Parameter Description Example
setup-first-blocks Length of initial setup phase in blocks. During the setup phase, the constraints specified by the other parameters in this section are not applied. 1440
mining-diversity Minimum proportion of permitted miners required to participate in round-robin mining to render a valid blockchain, between 0.0 (no constraint) and 1.0 (every permitter miner must participate). Unlike mining-turnover, this is a hard rule which determines whether a blockchain is valid or not. 0.5
admin-consensus-admin Proportion of permitted administrators who must agree to modify the admin privileges for an address, between 0 (no consensus required) and 1 (every admin must agree). 0.5
admin-consensus-activate Proportion of permitted administrators who must agree to modify the activate privileges for an address, between 0 and 1. 0.5
admin-consensus-mine Proportion of permitted administrators who must agree to modify mining privileges for an address, between 0 and 1. 0.5
admin-consensus-create Proportion of permitted administrators who must agree to modify stream creation privileges for an address, between 0 and 1. 0.0
admin-consensus-issue Proportion of permitted administrators who must agree to modify asset issuing privileges for an address, between 0 and 1. 0.0
Defaults for mining runtime parameters
lock-admin-mine-rounds Ignore forks that reverse changes in admin or mine permissions after this many (integer) mining rounds have passed. A mining round is defined as mining-diversity multiplied by the number of permitted miners, rounded up. This prevents changes in the blockchain’s governance model from being reversed and can be overridden by each node using the lockadminminerounds runtime parameter. 10
mining-requires-peers A node will only mine if it is connected to at least one other node. This is ignored during the setup phase or if only one address has mine permissions, and can be overridden by each node using the miningrequirespeers runtime parameter. true
mine-empty-rounds If there are no new transactions, stop mining after this many rounds of empty blocks. A mining round is defined as mining-diversity multiplied by the number of permitted miners, rounded up. This reduces disk usage in blockchains with periods of low activity. If negative, continue mining indefinitely. This is ignored during the setup phase or if target-adjust-freq>0, and can be overridden by each node using the mineemptyrounds runtime parameter. 2.5
mining-turnover A value of 0.0 prefers pure round robin mining between an automatically-discovered subset of the permitted miners, with others stepping in only if a miner fails. In this case the number of active miners will be mining-diversity multiplied by the number of permitted miners, rounded up. A value of 1.0 prefers pure random mining between all permitted miners. Intermediate values set the balance between these two behaviors. Lower values reduce the number of forks, making the blockchain more efficient, but increase the level of mining concentration. Unlike mining-diversity, this is a recommendation rather than a consensus rule, and can be overridden by each node using the miningturnover runtime parameter. 0.5
Native blockchain currency

When creating a blockchain, a fundamental question is whether it should use a native currency (the equivalent of bitcoin as an asset). By default, MultiChain blockchains do not use a native currency. However you may wish to change this to create a market for transactions, whereby transactions bid for inclusion in a block by attaching transaction fees in the native currency, and miners are rewarded with these fees along with block rewards.

Parameter Description Example
initial-block-reward Initial number of native currency units to award the miner of each block, in raw integer units. 0
first-block-reward Use a different mining reward for the first block only, in raw integer units. Ignored if negative. -1
reward-halving-interval Each time this many blocks has passed, halve the per-block miner reward. 52560000
reward-spendable-delay After a block reward is granted to a miner, the number of blocks until that reward can be spent. 1
minimum-per-output Minimum quantity of native currency in every transaction output, in raw integer units. 0
maximum-per-output Maximum quantity of native currency in every transaction output, in raw integer units. 0
minimum-relay-fee Minimum native currency fee required in order to relay a transaction, in raw integer units. This can be overridden by the minrelaytxfee runtime parameter. 0
native-currency-multiple How many raw integer units per display unit of the native currency, as used in the JSON-RPC API. For example in the bitcoin network this would be the number of satoshis per bitcoin. 100000000
Advanced mining parameters
Parameter Description Example
skip-pow-check Skip checking whether block hashes demonstrate sufficient proof-of-work. false
pow-minimum-bits Minimum/initial proof-of-work difficulty, i.e. the number of leading zero bits in the block hash. 20
target-adjust-freq Frequency of recalculating proof-of-work difficulty level, measured in seconds. For blockchains which don’t require proof-of-work, use a negative value to prevent recalculation. 86400 (1 day)
allow-min-difficulty-blocks Ignore the current target difficulty level if blocks are taking too long to appear. false
Transaction limits
Parameter Description Example
only-accept-std-txs Only accept and relay transactions which qualify as ‘standard’, according to the criteria below. true
max-std-tx-size Maximum size of a standard transaction in bytes. 100000 (100k)
max-std-op-returns-count Maximum number of OP_RETURN outputs (for general data) in standard transactions. 10
max-std-op-return-size Maximum size of an OP_RETURN metadata output in a standard transaction, in bytes. 4096 (4K)
max-std-op-drops-count Maximum number of inline OP_DROP metadata elements in a single output in standard transactions. 5
max-std-element-size Maximum size of data elements in standard transactions, in bytes. 600
Advanced parameters
default-network-port Default IP port to use for peer-to-peer communications between nodes (can be overridden by each node using the port runtime parameter). 8571
default-rpc-port Default IP port to use for JSON-RPC calls to multichaind (can be overridden by each node using the rpcport runtime parameter). 8570
chain-name Blockchain name, which is generally set by a call to multichain-util. chain1
protocol-version The version of the chain-protocol protocol used. This can be used to provide backwards compatibility with older versions of MultiChain – see creating a new blockchain. 10007
network-message-start The four-byte “magic value” sent at the start of each peer-to-peer protocol message. fddcc6f1
address-pubkeyhash-version
address-scripthash-version
private-key-version
address-checksum-value
These control the formatting of regular addresses, pay-to-scripthash (multisig) addresses and exported private keys. For more information, see address and key format.

Production recommendations

Below is a list of parameters whose values are crucial for long-term production deployments of MultiChain 1.0. (We expect MultiChain 2.0, now in development, to enable many parameters to be changed by administrator consensus in a running blockchain.)

target-block-time Consider where your validator nodes will be deployed geographically and the latency between those locations. Ensure this value is long enough to enable consensus to be maintained between those nodes at your peak expected throughput. Use pre-production testing to determine a safe value and then add a 50-100% margin of error. This parameter should be tested together with maximum-block-size since larger blocks take longer to propagate.
maximum-block-size Ensure this is large enough for expected future growth. Use pre-production testing to determine the block sizes for a given workload. Note also that for any given transaction throughput, an increase in target-block-time requires a corresponding proportional increase in maximum-block-size.
anyone-can-mine Set to false unless you are certain you want to use proof-of-work mining, in which case ensure that target-adjust-freq is a positive number.
anyone-can-admin Set to false unless you are certain you want any user connected to the blockchain to be able to perform administrative actions, which is a highly unusual case.
support-miner-precheck Set to true if your blockchain is open to the public, or any participant might be motivated to conduct a denial-of-service attack against the network. (Miner prechecks are performed by MultiChain 1.0 beta 2 or later.)
mining-diversity Ensure this is above 0.5 to prevent a long-running network split leading to two blockchain forks that can both continue growing in the long term.
admin-consensus-admin
admin-consensus-mine
To prevent any possibility of a future conflict between administrators leading to a fork, set these above 0.5. This means there will always be a single clear majority for any governance changes to the chain.
target-adjust-freq Set to -1 unless you want to use proof-of-work mining in your blockchain, otherwise block creation could become difficult and CPU intensive over time. There is no reason to use proof-of-work in a chain which has permissioned miners who are governed by mining diversity.
max-std-op-return-size Ensure these are large enough to accommodate the largest piece of data you will ever embed in the blockchain (but note the hard limit of 64 MB). The max-std-tx-size and maximum-block-size should both be at least a few hundred bytes larger than this value.
protocol-version Set to 10008 or later (assuming your chain-protocol is multichain) so that your blockchain will support upgrading to new protocols in future versions of MultiChain.