Using the Michelson Programming Language to Write Smart Contracts on Tezos [A How-To Guide] - Part 2

We’re going to write a new smart contract in Michelson using a string passed in the parameter by the user that we'll concatenate to the string already present in the storage before saving the new string into the storage. (Part 1 is available here .) After introducing the basics of Michelson in the previous article, we’re going to continue our exploration of this programming language. In this new installment, we’re introducing an amazing tool that’ll help us write, debug, and examine our Michelson code: the developed by the . Jupyter notebook with the Michelson kernel Baking Bad team We’re going to write a new smart contract in Michelson using a string passed in the parameter by the user that we'll concatenate to the string already present in the storage before saving the new string into the storage. It’s highly recommended to read first, as it introduces concepts about smart contracts in Michelson we’re going to use here. Part 1 But first, let’s have a look at what’s probably the best tool around to code: Michelson! Baking Bad’s Jupyter Notebook Baking Bad developed an online Michelson compiler that goes beyond compiling your Michelson code. It offers syntax highlighting, debugging, and a step-by-step visualization of the stack. You can open the notebook we’re going to use for this lesson using (bear in mind the kernel needs a minute or two to load) before selecting the file. this link MichelsonTutorial-Demo3.ipynb The file is divided into two parts: The inline code In the first part, the whole smart contract is dropped into a single cell. You can compile and run it by writing in the following cell. RUN %default parameter storage After running the smart contract, there’s a detailed description of each step and what each instruction did to modify the stack (in on the picture). At the end of the runtime (in on the picture), you’re left with your new storage. In [10] Out [10] The step-by-step code Where this compiler shines is you can enter the instructions to modify the stack one by one and examine their effect after each step. As in every Michelson smart contract, you start by specifying the parameter and the storage. Then, you type to start the execution. BEGIN parameter storage After this configuration step, you can enter the instructions one by one and run them by hitting to see how they modify the stack. In the cell, you’re presented with the current value at the top of the stack. CMD/CTRL + SHIFT Out [...] you can see a instruction in the step-by-step code. This is Michelson — this is just an instruction used in the Jupyter notebooks to print the current state of the stack. Note: DUMP not When you want to end the execution of the smart contract, you enter , and it’ll return the new storage, provided there’s no error in your code. If there’s one at any step of the execution, you’ll see a message and be able to fix it right away without having to review your code line by line. COMMIT Handling Parameters in a Michelson Smart Contract In the last lesson, we introduced a few instructions that manipulated data either already in the stack or that we pushed ourselves. But what about handling users’ input? This is actually pretty easy! We’re going to work with the contract present in the Jupyter notebook introduced above. You’re welcome to follow along in the notebook and run the instructions one by one to get a better understanding of how the stack looks like after each instruction. Here’s the full smart contract: If you remember, a pair containing the parameter and the storage is automatically pushed at the top of the stack when the contract is called. We can then get the left part of the pair (the parameter) and use it. Here’s how it works. First, let’s initialize our stack: In this step, we get a fresh stack with a pair containing a parameter of type ( ) and the storage of type , too ( ). Our final goal is to concatenate these two strings and return them. string world string Hello In the next step, we duplicate the top element of the stack because we need the parameter and the storage in two separate elements of the stack to be able to put them together in one single string. Michelson doesn’t have variables and is immutable by nature. New elements of the stack can be created with different methods — for example, by pushing them (with the instruction) or by duplicating them (with the instruction). Remember at every step of the execution, you’re dealing with the top element of the stack. It’s the only one you can work with. PUSH DUP Let’s start with the first element of the stack, and let’s get the parameter out of the pair. We use the instruction, whose purpose is to break an element of type and to return the left side of the pair (in this case, the parameter passed to the smart contract). After running , we’re left with the string on top of the stack. CAR pair CAR world Now you may be wondering: How can I work with the second element of the stack if Michelson only deals with the first one? It’s very easy! Bring the second element to the top with the instruction, and keep the other one for later. SWAP When using the instruction, you tell Michelson: “I don’t need the first element for now, but I’d like to work on the second one.” Michelson will bring down the first element to the second position and the second element up to the first position. SWAP Now that the second pair we duplicated at the beginning is at the top, we can use a reverse to get the right part of the pair with the instruction. CAR CDR The instruction works like the instruction, but you’ll keep the right side of the pair you’re manipulating (a pair always contains only two elements, so and are the only possible operations). After that, you can see our stack is made of two elements: in the first position, the string and in the second position, the string . CDR CAR CDR CAR Hello world Now let’s put them together! In computer programming, the operation of putting two strings together is called It’s only logical that the instruction to put two strings together in Michelson is called . The operation takes the two strings currently at the top of the stack and returns a single string. For the operation to be successful, two conditions must be true: concatenation . CONCAT You do have two elements on top of the stack (it’ll generate an error if there’s only one element left). If more elements are present, it’ll only deal with the two elements at the top. The two elements on top of the stack are strings (Michelson is strictly typed — it knows what kind of values it has in its stack, so don’t even try to fool it) Now if you remember what we talked about in Part 1, you know what’s going to happen. We must create a pair with a list and the new storage to end the execution of the smart contract (it’s like saying goodbye in Michelson). First, let’s push an empty list on the top of the stack: Once the empty list is there, we can create a pair with the empty list and the string: Once again, be very wary of the order of your elements and their type: Michelson will take the first element to put it on the left side of the pair and the second element to put it on the right side of the pair. Returning a pair of type (Pair string list (operation)) will generate an error. Now our stack is clean and contains a pair with a list of operations and a string, the execution of the smart contract comes to an end. You can see the full execution and the transformations of the stack in the video below: Conclusion In this new part of the Michelson tutorial for beginners, we had a look at a Jupyter notebook with a Michelson kernel that we’ll use heavily in the following parts of this tutorial to write, debug, and execute code. New operation codes in Michelson were introduced: , which extracts the left part of a pair; , which duplicates the top element of the stack; , which extracts the right part of a pair; , which swaps the positions of the two elements on the top of the stack; and , which takes two strings and returns a single string made of the two previous strings put together. CAR DUP CDR SWAP CONCAT Animations that represent the operations in the stack were also added to help you better visualize and follow what happens at every step. This will become even more useful when the operations in the stack become more complicated and intricate. Stay tuned! (Previously published behind a paywall here: https://medium.com/better-programming/an-introduction-to-michelson-the-scripting-language-of-tezos-part-2-4cc972c8237c )