Programming Hotmoka
A tutorial on Hotmoka and smart contracts in Takamaka

Chapter 2 Getting started with Hotmoka

2.1 Hotmoka in a nutshell

Hotmoka is the abstract definition of a device that can store objects (data structures) in its persistent memory (its state or storage) 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, taking that terminology from programs that run inside a blockchain. 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 that is part of a blockchain. There, the state is synchronized and identical across all nodes of the blockchain.

In object-oriented programming, the units of code that can be run on an object are called methods. When a method must be run on an object, that object is identified as the receiver of the execution of the method. The same happens in Hotmoka. That is, when one wants to run a method on an object, that object must have been already allocated in the state of the node and must be marked as the receiver of the execution of the method. Assume for instance that one wants to run a method on the object in Fig. 2.1, identified as receiver. The code of the method is contained in a jar, previously installed in the state of the node, and referred to as classpath. This is the jar where the class of the receiver is defined.

The main difference with standard object-oriented programming is that Hotmoka requires one to specify a further object, called payer. This is because a Hotmoka node is a public service, that can be used by everyone has an internet connection that can reach the node. Therefore, that service must be paid with the internal cryptocurrency of the node, by providing a measure of execution effort known as gas. The payer is therefore a sort of bank account, whose balance gets decreased in order to pay for the gas needed for the execution of the method. The payer is accessible inside the method as its caller.

Receiver and payer have different roles but same treatment in Hotmoka: they are objects in state, stored at their respective state locations or storage references. For instance, the payer might be allocated at 3fcbb8889b77be34…#0 (Fig. 2.1). A storage reference has two parts, separated by a # sign. The first part are 64 hexadecimal digits (i.e., 32 bytes) that identify the transaction that created the object; the second part is a progressive number that identifies an object created during that transaction: the first object created during the transaction has progressive zero, the second has progressive one, and so on. When a method is called on a Hotmoka node, what is actually specified in the call request are the storage references of the receiver and of the payer (plus the actual arguments to the method, if any).

Each object in the state of a Hotmoka node knows its classpath, that is, it holds a reference to the jar, already installed in the node, that contains the compiled bytecode of the class of the object. For instance, in Fig. 2.1, the payer account is a Java object whose class io.takamaka.code.lang.ExternallyOwnedAccountED25519 is defined in a jar referenced by the transaction reference 68e90e2868751a3f…. Namely, in Hotmoka, a transaction is either:

• 1. the installation of a jar, that modifies the state of the node, and is paid by a payer account, or

• 2. the execution of a constructor, that yields the storage reference of a new object, or

• 3. the execution of a method on a receiver, that yields a returned value and/or has side-effects that modify the state of the node, and is paid by a payer account.

A Hotmoka node keeps track of the transactions that it has executed, so that it is possible, for instance, to recreate its state by running all the transactions executed in the past, starting from the empty state.

It is very important to discuss at this moment a significant difference with what happens in Bitcoin, Ethereum and most other blockchains. There, an account is not an object, nor a contract, but just a key in the key/value store of the blockchain, whose value is its balance. The key used for an account is typically computed by hashing the public key derived from the private key of the account. In some sense, accounts, in those blockchains, exist independently from the state of the blockchain and can be computed offline: just create a random private key, compute the associated public key and hence its hash. Hotmoka is radically different: an account is an object that must be allocated in state by an explicit construction transaction (that must be paid, as every transaction). The public key is explicitly stored inside the constructed object (base64-encoded in its publicKey field, see Fig. 2.1). That public key was passed as a parameter at the creation of the payer object and can be passed again for creating more accounts. That is, it is well possible, in Hotmoka, to have more accounts in the state of a node, all distinct, but controlled by the same key. It is also possible to rotate the key of an account (that is, replace it with another key), since the publicKey field is not final.

This has a major consequence. In Bitcoin and Ethereum, an account is identified by twelve words and a password, by using the BIP39 encoding (see Fig. 5 and 6 of [1]). These twelve words are just a mnemonic representation of 132 bits: 128 bits for the random entropy used to derive the private key of the account and four bits of checksum. In Hotmoka, these 128 bits are not enough, since they identify the key of the account but not the 32 bytes of its storage reference (in this representation, the progressive is assumed to be zero). As a consequence, accounts in Hotmoka are identified by 128+256 bits, plus 12 bits of checksum (and a password), which give rise to 36 words in BIP39 encoding. By specifying those 36 words across different clients, one can control the same account with all such clients. As usual, those 36 words must be stored in paper and kept in a secure place, since their lost amounts to losing access to the account.

As shown in Fig. 2.1, the code of the objects (contracts) installed in the state of a Hotmoka node consists in jars (Java archives) written in a subset of Java known as Takamaka. This is done in a way completely different from other blockchains:

• 1. In Hotmoka, programmers code the contracts that want to install in the node and nothing more; they do not program the encoding of data into the key/value store of the node (its keeper, as it is called in other blockchains); they do not program the gas metering; they do not program the authentication of the accounts and the verification of their credentials. Everything is automatic in Hotmoka, exactly as in Ethereum, and differently from other blockchains that use general purpose languages such as Java for their smart contracts: there, programmers must take care of all these details, which is difficult, boring and error-prone. If this is done incorrectly, those blockchains will hang.

• 2. In Hotmoka, the code installed in the node passes a preliminary verification, that checks the correct use of some primitives, that we will introduce in the subsequent chapters, and guarantees that the code is deterministic. This excludes an array of errors in Hotmoka, while other blockchains will hang if, for instance, the code is non-deterministic.