Getting Started with MultiChain | MultiChain https://www.multichain.

com/getting-started/

This tutorial requires two server nodes. If you have not done so already, please download and install (/download-
install/) MultiChain on each server. If you are using MultiChain on Windows, please read the Windows notes in the
README.txt file to adapt the instructions below.

1. Creating a blockchain
First we will create a new blockchain named chain1. On the first server, run this command:

multichain‐util create chain1

(If you are using Windows, you need to first open a DOS command line in the directory where you installed the
MultiChain executables. You can do this by navigating to that directory in the Windows Explorer, then typing cmd in
the address bar at the top.)

View the blockchain’s default settings (these can also be modified (/developers/blockchain-parameters/) but we
recommend using the defaults for now):

cat ~/.multichain/chain1/params.dat (on Windows, view %APPDATA%\MultiChain\chain1\params.dat)

Initialize the blockchain, including mining the genesis block:

multichaind chain1 ‐daemon

You should be told that the server has started and then after a few seconds, that the genesis block was found. You
should also be given the node address that others can use to connect to this chain.

Copy and paste the node address here: chain1@[ip-address]:[port]

2. Connecting to a blockchain
Now we’ll connect to this blockchain from elsewhere. On the second server, run the following:

multichaind chain1@[ip‐address]:[port]

You should be told that the blockchain was successfully initialized, but you do not have permission to connect. You

1 of 6 2/16/2018, 7:06 PM
Getting Started with MultiChain | MultiChain https://www.multichain.com/getting-started/

should also be shown a message containing an address in this node’s wallet.

Copy and paste the wallet address here: 1...

Back on the first server, add connection permissions for this address:

multichain‐cli chain1 grant 1... connect

Now try reconnecting again from the second server:

multichaind chain1 ‐daemon

You should be shown a message that the node was started, and it should display this second node’s address.

3. Some commands in interactive mode

Before we proceed, let’s enter interactive mode so we can issue commands without typing multichain‐cli chain1
every time. On both servers:

multichain‐cli chain1

(If you are using Windows, interactive mode is not yet available, so all commands in this guide should be preceded
by multichain‐cli chain1. You will also need to open another DOS command line in the directory where you
installed the MultiChain executables.)

Now that the blockchain is working on two nodes, you can run the commands in this section on either or both. To get
general information:

getinfo

See a list of all available commands:

help

Show all permissions currently assigned:

listpermissions

Create a new address in the wallet:

getnewaddress

List all addresses in the wallet:

getaddresses

Get the parameters of this blockchain (based on params.dat file):

getblockchainparams

For each node, get a list of connected peers:

getpeerinfo

2 of 6 2/16/2018, 7:06 PM
Getting Started with MultiChain | MultiChain https://www.multichain.com/getting-started/

4. Using native assets

If you only interested in blockchains for data storage and retrieval, rather than representing asset transactions, skip
straight to section 6.

Now we are going to create a new asset and send it between nodes. On the first server, get the address that has
the permission to create assets:

listpermissions issue

Copy and paste the displayed address here: 1...

Now we’ll create a new asset on this node with 1000 units, each of which can be subdivided into 100 parts, sending
it to itself:

issue 1... asset1 1000 0.01

On both servers, verify that the asset named asset1 is listed:

listassets

Now check the asset balances on each server. The first should show a balance of 1000, and the second should
show no assets at all:

gettotalbalances

On the first server, now try sending 100 units of the asset to the second server’s wallet:

sendasset 1... asset1 100

You should see an error that the address does not have receive permissions. So it’s time to add receive and send
permissions:

grant 1... receive,send

Now try sending the asset again, and it should go through:

sendasset 1... asset1 100

Now check the asset balances on each server, including transactions with zero confirmations. They should be 900
and 100 respectively:

gettotalbalances 0

You can also view the transaction on each node and see how it affected their balances:

listwallettransactions 1

5. Transaction metadata
In this section we’ll create a transaction that sends 125 units of asset1 along with some metadata. On the first
server, run:

3 of 6 2/16/2018, 7:06 PM
Getting Started with MultiChain | MultiChain https://www.multichain.com/getting-started/

sendwithdata 1... '{"asset1":125}' 48692066726f6d204d756c7469436861696e21

Copy and paste the displayed transaction ID:

a1b2...

Now this transaction can be examined on the second server as below:

getwallettransaction a1b2...

In the output from this command, you should see the balance field showing the incoming 125 units of asset1 and the
data field containing the hexadecimal metadata that was added.

6. Streams
Now let’s create a stream, which can be used for general data storage and retrieval. On the first server:

create stream stream1 false

The false means the stream can only be written to by those with explicit permissions. Let’s see its permissions:

listpermissions stream1.*

So for now, only the first server has the ability to write to the stream, as well as administrate it. Let’s publish
something to it, with key key1:

publish stream1 key1 73747265616d2064617461

The txid of the stream item is returned. Now let’s see that the stream is visible on another node. On the second
server:

liststreams

(The root stream was in the blockchain by default.) Now we want the second server to subscribe to the stream, then
view its contents:

subscribe stream1
liststreamitems stream1

Now we want the second server to be allowed to publish to the stream. On the first server:

grant 1... receive,send
grant 1... stream1.write

Note that the address needs both general send/receive permissions for the blockchain, as well as permission to
write to this specific stream. Now let’s publish a couple of items on the second server:

publish stream1 key1 736f6d65206f746865722064617461
publish stream1 key2 53747265616d732052756c6521

Now let’s query the stream’s contents in many different ways. Back on the first server:

subscribe stream1

4 of 6 2/16/2018, 7:06 PM
Getting Started with MultiChain | MultiChain https://www.multichain.com/getting-started/

liststreamitems stream1 (should show 3 items)

liststreamkeys stream1 (2 keys)
liststreamkeyitems stream1 key1 (2 items with this key)
liststreampublishers stream1 (2 publishers)
liststreampublisheritems stream1 1... (2 items by this publisher)

This is just a taste of the ways in which streams can be queried – for more information, please consult the API
documentation (/developers/json-rpc-api/).

7. Round-robin mining
In this section we’ll start collaborative “mining” (i.e. block creation) between the nodes. Note that mining in the case
of a permissioned MultiChain blockchain is based on block signatures (/developers/mining-block-signatures/) and a
customizable round-robin consensus scheme, rather than proof-of-work as in bitcoin.

On the first server, run:

grant 1... mine

On the second server, check that two permitted miners are listed:

listpermissions mine

Run this on both servers to maximize the degree of miner randomness:

setruntimeparam miningturnover 1

Now wait for a couple of minutes, so that a few blocks are mined. (This assumes you left the block time on the
default of 15 seconds.) On either server, check the miners of the last few blocks:

listblocks ‐10

The address of the miner of each block is in the miner field of each element of the response.

Note that this tutorial uses only two mining nodes and the low default value for the mining‐diversity blockchain
parameter (/developers/blockchain-parameters/). So each block can be mined by either node, and the chain is not
secure. A secure chain would use more mining nodes and/or a higher value for this parameter.

8. Now go explore…
Congratulations – you have finished the first tutorial! Now you try any of the other tutorials (/developers/#tutorials),
create blockchains with different parameters (/developers/blockchain-parameters/) or explore the available API
commands (/developers/json-rpc-api/). You can also install the Explorer (https://github.com/MultiChain/multichain-
explorer) or Web Demo (https://github.com/MultiChain/multichain-web-demo) to see a graphical interface for your
blockchain.

Finally, you may want to subscribe below for updates. And if you have any questions or problems, please ask in the
developer Q&A (/qa/) or contact us (/contact-us/).

5 of 6 2/16/2018, 7:06 PM
Getting Started with MultiChain | MultiChain https://www.multichain.com/getting-started/

9. Get product updates (one email per month max)

Subscribe

About Us (https://www.multichain.com/about-coin-sciences-ltd/)
Terms (https://www.multichain.com/terms-of-service/)
Privacy (https://www.multichain.com/privacy-policy/)
Contact Us (https://www.multichain.com/contact-us/) Follow (http://twitter.com/CoinSciences)

MultiChain © 2018 Coin Sciences Ltd

6 of 6 2/16/2018, 7:06 PM