hotmoka/tendermint-node repository overview

⁠Mokamint and Hotmoka

This image provides a Hotmoka node of a blockchain based on a proof of stake consensus built over the Tendermint engine, now Ignite (https://tendermint.com/core/⁠). Consensus is achieved through a round-robin selection of a validator among a modifiable set of validator nodes. The selected validator mines the next block. New validators can be elected by selling (and buying) validation power. Misbehaving validators get punished.

Hotmoka⁠ is the abstract definition of a device that can store objects (data structures) in its persistent memory (its state) and can execute, on those objects, code written in a subset of Java called Takamaka. Such a device is called a Hotmoka node and such programs are known as smart contracts. It is well true that Hotmoka nodes can be different from the nodes of a blockchain (for instance, they can be an Internet of Things device); however, the most prominent application of Hotmoka nodes is, at the moment, the construction of blockchains whose nodes are Hotmoka nodes.

Every Hotmoka node has its own persistent state, that contains code and objects. Since Hotmoka nodes are made for running Java code, the code inside their state is kept in the standard jar format used by Java, while objects are just a collection of values for their fields, with a class tag that identifies whose class they belong to and a reference (the classpath) to the jar where that class is defined. While a device of an Internet of Thing network is the sole responsible for its own state, things are different if a Hotmoka node is part of a blockchain. There, the state is synchronized and identical across all nodes of the blockchain.

The following instructions provide information on how to create Hotmoka nodes of a blockchain whose consensus is based on the Tendermint byzantine consensus engine.

⁠Join an existing blockchain, by spawning a new node that clones an existing node

This is the most typical situation. Namely, you want to join an existing blockchain, with a node that mines new blocks and receives blocks created by the other peers. This docker image provides a script for this situation. It creates a key pair that identifies the node and that is kept inside the container.

The process is consequently split in two:

• configure the node (config-clone)
• run the node (go)

Each phase is the execution of a script inside this docker image. The script config-clone is meant to be run only once, while go can be run, stopped and run again, whenever you want to start or stop a node. You can also pause it and unpause it. The reason for splitting the process in two scripts is that it allows one to manually edit the configuration created by config-clone before running the node, although we won't show this here. Moreover, having distinct scripts allows go to be stopped and run again, repeatedly, whenever you want to stop and restart a node.

The following instructions assume that you have a reliable internet connection. If the connection is too slow, or flickering, or if it disconnects for some time, the synchronization of the node will likely fail.

⁠Configure the node: config-clone

This script creates the configuration directory of a node that joins an existing Hotmoka blockchain based on the Tendermint byzantine consensus engine. For that, you must specify the URI of a node of this blockchain, from where the configuration information will be fetched, such as ws://panarea.hotmoka.io:8002: this node is maintained by Hotmoka. You must also specify the average block creation rate of the blockchain, that in the case of ws://panarea.hotmoka.io:8002 is 10,000 milliseconds. We will use two volumes: chain will contain the actual blockchain data and hotmoka_tendermint will contain the configuration information created for the node. By using volumes, we can share that information across successive invocations of docker:

docker run -it --rm -e HOTMOKA_PUBLIC_SERVICE_URI=ws://panarea.hotmoka.io:8002 -e TARGET_BLOCK_CREATION_TIME=10000 -v chain:/home/hotmoka/chain -v hotmoka_tendermint:/home/hotmoka/hotmoka_tendermint hotmoka/tendermint-node:1.12.4 config-clone

Note that the script above will create a key pair with empty password, that will be kept inside the container. This key pair identifies the node and will be used to sign the blocks that the node will create, if it will ever become a validator of the network. It must remain inside the container, although you may want to extract a copy from the container to your local host.

⁠Run the node: go

After configuring the node, you can run it with the go script:

docker run -it --log-driver local --rm --name hotmoka -p 8001:8001 -p 26656:26656 -v chain:/home/hotmoka/chain -v hotmoka_tendermint:/home/hotmoka/hotmoka_tendermint hotmoka/tendermint-node:1.12.4 go

The command above allows connections to the ports:

• 8001: this is the port where the Hotmoka node is published by default; it can be used to contact the node, install and run smart contracts;
• 26656: this is the port where the Tendermint engine communicates with its peers.

After the command above, you should see that the node will start up and begin synchronizing from ws://panarea.hotmoka.io:8002. This will take some time (hours, days, weeks...) depending on the age of the cloned blockchain and on the speed of your internet connection. You can leave the container in the backrground by entering ctrl+p, ctrl+q, as always in docker.

You can then enter the running container and check the manifest of the node, that is identical to that of any other node of the joined blockchain:

docker exec -it hotmoka /bin/bash

and then

hotmoka@e41eda9afd3b:~$ moka nodes manifest show

Note that the resulting node will not be a validator. For that, you need to buy some validation power from a validator who is willing to sell it to you. Check the moka nodes tendermint validators commands.

⁠Update a node

If you want to update the version of a running node, you must first stop it and then restart the new version:

docker stop hotmoka
docker rm hotmoka

then run the new version of the node as explained above for the go command.

⁠Start a brand new blockchain, by spawning its first node

This situation is much rarer. It occurs when you want to start a brand new blockchain from scratch, by minting its genesis block and initializing its store. Later, other nodes can join the new blockchain with the technique described above.

This docker image provides a script for starting a brand new blockchain. The process is split in three:

• configure the node (config-new)
• initialize the node (init)
• run the node (go)

Each phase is the execution of a script inside this docker image. The scripts config-new and init are meant to be run only once, while go can be run, stopped and run again, whenever you want to start or stop a node. You can also pause it and unpause it. The reason for splitting the process in three scripts is that it allows one to manually edit the configuration created by config-new before initializing and running the node, although we won't show this here. Moreover, having distinct scripts allows go to be stopped and run again, repeatedly, whenever you want to stop and restart a node.

⁠Configure the node: config-new

The first thing to do is to create a key pair for the gamete account. This is an account of Hotmoka that holds all cryptocurrency minted at start-up. It can also be used for providing cryptocurrency for free, if your node allows a free faucet. In any case, you can create a key pair for the gamete account by running the container and the moka command inside it:

docker run -it --rm --name hotmoka hotmoka/tendermint-node:1.12.4 /bin/bash

and inside the container:

hotmoka@afbef35bce14:~$ moka keys create --name gamete.pem --password

When prompted, enter the password that you prefer or just leave it blank. The output will be something like:

Enter value for --password (the password that will be needed later to use the key pair): 
The new key pair has been written into "gamete.pem":
* public key: CBSW5keMkZ5wuupC4S4c1KbtbWzdsAzbeNseY3E9v5o4 (ed25519, base58)
* public key: ph0y5d0xREYKFZOYMC+AROXf/0+h9He6clCt9rbIcec= (ed25519, base64)
* Tendermint-like address: 21476455E6E2277C88090F063A9DC05E3190E4A3

This will create a key pair gamete.pem inside the running container. In another shell, you can transfer the key pair to your local machine:

docker cp hotmoka:/home/hotmoka/gamete.pem .

At this point, delete the key pair from the container and exit the container:

hotmoka@afbef35bce14:~$ rm gamete.pem
hotmoka@afbef35bce14:~$ exit

You can now configure the node, specifying the public key of the gamete:

docker run -it --rm -e PUBLIC_KEY_GAMETE_BASE64="ph0y5d0xREYKFZOYMC+AROXf/0+h9He6clCt9rbIcec=" -e CHAIN_ID=whale -e TARGET_BLOCK_CREATION_TIME=10000 -v chain:/home/hotmoka/chain -v hotmoka_tendermint:/home/hotmoka/hotmoka_tendermint hotmoka/tendermint-node:1.12.4 config-new

Note that the public key of the gamete is reported in base64 format, currently. The target block creation time, in milliseconds, is the average time between the creation of two successive blocks. The chain identifier identifies the new network and must be used, for instance, in the transaction requests sent to the Hotmoka nodes of the network.

⁠Initialize the node: init

The initialization of the node consists in the execution of a few initial transactions that create the genesis block, the manifest and the gas station of the node. You can do this with:

docker run -it --rm -v chain:/home/hotmoka/chain -v hotmoka_tendermint:/home/hotmoka/hotmoka_tendermint hotmoka/tendermint-node:1.12.4 init

This should take a few seconds. You should see the logs of the executed transactions, until the script terminates.

⁠Run the node: go

Once the node has been configured and initialized, you can run it. Follow for this the instructions reported above for the go script. The resulting node will be the (currently) unique validator of the new blockchain.

⁠Source Code

Mokamint and Hotmoka are open-source projects whose code is maintained on Github: https://github.com/Hotmoka/hotmoka⁠ and https://github.com/Mokamint-chain/mokamint⁠.

⁠License

Mokamint and Hotmoka are licensed under the Apache-2.0 open-source license⁠.

⁠Further Information

You can see all options of the scripts in this image by executing:

docker run -it --rm hotmoka/tendermint-node:1.12.4 info

⁠Tutorial

The above Github page of Hotmoka contains a detailed tutorial about Hotmoka, its use, the creation of smart contracts in Takamaka and their execution. The tutorial is also available in PDF version under the releases section⁠ of the Github project and can also be read online⁠.