How to set up a blockchain and connect multiple nodes

Creating a new blockchain

To create a new blockchain called [chain-name] based on MultiChain’s default blockchain parameters, run:

multichain-util create [chain-name]

Alternatively, to create a new blockchain based on the parameters of an existing chain [old-name], run:

multichain-util clone [old-name] [chain-name]

Any parameter can be set on the command line using a flag with the same name, for example: (requires alpha 26)

multichain-util create [chain-name] -maximum-block-size=16777216

Finally, to create a blockchain using a previous version of the MultiChain protocol, run the command below. This will enable older versions of MultiChain to connect to the chain, but disable any features which require the new protocol:

multichain-util create [chain-name] 10002  (for compatibility with 1.0 alpha 13 or earlier)

In all cases, a new directory ~/.multichain/[chain-name]/ will be created, with a params.dat file inside. (Note that you can change this ~/.multichain/ path using the -datadir= option, and %APPDATA%\MultiChain\ is the equivalent on Windows.) The params.dat file contains many settings and can be edited using any text editor – see blockchain parameters for a comprehensive list.

Once the settings are finalized, start the blockchain running in the background by issuing the following command:

multichaind [chain-name] -daemon

This will lock the contents of params.dat, initialize the blockchain, and cause the first (genesis) block to be mined. A node address such as chain1@12.34.56.78:8571 will be output, to allow other nodes to easily connect. (This can also be obtained via the getinfo call.)

To begin with, the MultiChain node that created the chain has a single address which is granted all permissions, including administration and mining. Mining can proceed using this node only until the end of the setup phase, as defined by the setup-first-blocks parameter in params.dat. At the end of the setup phase, mining will proceed according to the mining-diversity and mining-requires-peers settings.

Connecting to a blockchain

To connect to an existing blockchain for the first time, first obtain the node address from any node which is already connected. The node address is shown whenever multichaind starts up or can be obtained using the getinfo API call. Connect using the node address as follows:

multichaind chain1@12.34.56.78:8571 -daemon

If the blockchain is private, you will not be able to connect immediately, because you have not yet been granted permission by an administrator. In this case, a message will be output on the screen containing your address, which you should send to one of the chain’s administrators. After permission has been granted, you can immediately reconnect to chain1 using the shorter form:

multichaind chain1 -daemon

Once you are successfully connected to a blockchain, all of its params.dat parameters are automatically downloaded and verified. Your node will begin downloading and verifying the blockchain, and discovering and connecting to other peers within that blockchain’s network.

Reconnecting to a blockchain

You may need to restart multichaind if a server is rebooted or the stop command was issued through the API. In this case it can be relaunched just with the chain name, e.g.:

multichaind chain1 -daemon

Next steps

Once you have a blockchain node up and running, you can start issuing commands to your node using multichain-cli, or by sending JSON-RPC requests. See the JSON-RPC API documentation for more details or getting started for some ideas.

Connecting to the bitcoin network

MultiChain can also act as a node on the regular bitcoin network. To make this work, create a new directory ~/.multichain/bitcoin/ and then save this bitcoin network params file as params.dat inside that directory. You can then launch MultiChain as a bitcoin node by running:

multichaind bitcoin@seed.bitcoin.sipa.be -daemon

(The address seed.bitcoin.sipa.be is a DNS seed for the bitcoin network.)

In this way, MultiChain can be used as a replacement for Bitcoin Core, while enjoying some of its extra APIs such as sendfromaddress.

Creating a bitcoin-style blockchain

Apart from connecting to the bitcoin network, MultiChain can also be used to create a separate bitcoin-style blockchain between multiple MultiChain nodes. To do this, create a new directory ~/.multichain/mybitcoin/ and then save this bitcoin protocol params file as params.dat inside that directory. You can then modify the blockchain parameters in the file to suit your needs. At a minimum, you should change the default-network-port to something other than 8333. Note the setting chain-protocol=bitcoin at the top of this file, which defines the chain as a bitcoin-style blockchain, with no native assets or permissions. To start the blockchain running:

multichaind mybitcoin -daemon

To add other MultiChain nodes to a bitcoin-style blockchain, you should first copy the ~/.multichain/mybitcoin/params.dat file manually to the server for each new node. This step is required because the parameters file cannot be transferred automatically as part of the peer-to-peer handshaking protocol. After doing this, you can make the connection in the usual way:

multichaind mybitcoin@[node-ip-address]:[default-network-port] -daemon

If you wish to run multiple bitcoin-style blockchains in parallel, you should change mybitcoin to something different for each chain. This must be done in the three places: (a) the chain-name parameter in the params.dat file, (b) the directory name and (c) the parameter passed to multichaind.

See also these instructions on allowing bitcoin wallets to connect to a MultiChain network. This enables a blockchain supporting native assets and permissions to be used with a regular bitcoin wallet.