6 Fast-Track Application Tutorial
Whenever new technology comes along, especially for us developers, the first thing we want to learn is how to use the language to invoke its functionality and manipulate its data types. We want to know how to develop, validate, and deploy the application. The blockchain is no different. At the current time, the Bitcoin blockchain does not provide the comprehensive functionality required by lots of applications where blockchain can be applied and helpful. Ethereum, however, does provide a comprehensive functionality via its smart contracts capability using Solidity. In this chapter, we will introduce Solidity the language, a browser-based integrated development environment (IDE) to write and deploy Ethereum contracts. At the writing of this book mid-2017, Ethereum IDEs are not matured. That has been typical for new technologies and development, such as Java. When Java development started in the late 1980s, developers used tools like Notepad text editors to write Java programs and deploy them to application servers. It was a tough time for development. Ten or so years later, IDEs like Eclipse facilitate the development, testing, and deployment of Java applications. This evolution will no doubt take place with blockchain Ethereum and Solidity. It is merely a matter of time.
Introducing Solidity
Solidity the word means the quality or state of being firm or strong in structure. Solidity the language is a contract-oriented, high-level language whose syntax is similar to that of JavaScript. It is designed to target the Ethereum Virtual Machine (EVM). Solidity is statically typed and supports inheritance, libraries, and complex user-defined types among other features. This chapter provides a basic introduction to Solidity and assumes some knowledge of programming in general. You can start using Solidity in your browser, with no need to download or compile anything. This application only supports compilation—if you want to run the code or inject it into the blockchain, you have to use a client or blockchain gateway service such as INFURA.
Solidity Basics
As mentioned, Solidity is an object-oriented programming language for writing smart contracts. Developers ask the question, “Is Solidity Turing complete?” An imperative language is Turing complete if it has conditional branching (such as if, while, for), conditional looping statements, and the ability to change an arbitrary amount of memory, such as the ability to maintain an arbitrary number of variables. Since this is almost always the case, most if not all imperative languages are Turing complete if the limitations of finite memory are ignored. The commonly used development languages C, C++, C#, Java, Lua, and Python are all Turing complete, as is Solidity. That said, most of the control structures from C/JavaScript are available in Solidity except for switch.
Let’s start with some basic code examples. The first question to ask is what is the current release of Solidity. When starting, one should always go to the GitHub site (https://github.com/ethereum/solidity/releases), which lists the releases and new functionality for Solidity. Once you know that, then the second statement in the contract would be the release. If you look at the sample code below, you’ll notice the specification of the current release of Solidity at the time of this writing.
As mentioned, the first line indicates that the source code is written for Solidity version 0.4.16. The keyword or directive pragma (from “pragmatic”) is a language construct that specifies how a compiler or translator should process its input.
A contract in Solidity is code that includes the functionality and data that execute and record the state of the contract. The contract resides at a specific address on the Ethereum blockchain. This contract, StorageState, if it were written in Java would be a bean. Java beans declare some variables and include a getter and a setter for each of the variables used to modify or retrieve the value of the variable. The bean is usually a data structure that is passed around class to class containing data we wish to share. The line uint stateData; declares a state variable called stateData of type uint which is an unsigned integer of length 32 bytes. This contract, as mentioned, is a bean allowing anyone to store a single number that is accessible by anyone publishing this number. Just as in Java, by declaring the variable private we pose access restrictions such that only the internal contract code can modify the variable. As you would expect, single-line comments (//) and multi-line comments (/*...*/) are specified as depicted here.
Solidity Control and Flow Statements
As with most of the current computer languages, there are the familiar constructs: the Aristotelian conditional if-then-else, the loop functionality of while and for with the break, continue, return. See Table 6-1 for descriptions and examples.
TABLE 6-1 Functionality and Control of Execution
Data Types
Solidity is a statically typed language, which means that the data type of each variable (state and local) needs to be specified at compile time. The following data types are also known as value types because they will always be passed by value as opposed to reference, i.e., they are always copied when they are used as function arguments or in assignments. See Table 6-2 for descriptions and examples.
TABLE 6-2 Solidity Data Types and Related Functions
Visibility Specifiers
Functions and storage variables can be specified as being public, internal, or private, where the default for functions is public and for storage variables is internal. In addition, functions can also be specified as external. See Table 6-3 for descriptions and examples.
TABLE 6-3 Visibility of Constants and Variables
Block and Transaction Properties
There are special variables and functions that exist in the global namespace. They provide information about the blockchain. See Table 6-4 for syntax and descriptions.
TABLE 6-4 Block and Transaction Properties
Order of Operations
The evaluation order of expressions is not specified (more formally, the order in which the children of one node in the expression tree are evaluated is not specified, but they are of course evaluated before the node itself). It is only guaranteed that statements are executed in order and short-circuiting for boolean expressions is done. See Table 6-5 for descriptions and operators.
TABLE 6-5 Order of Operations
Solidity Functions and Parameters
A function is defined with the function keyword, followed by a name, followed by parentheses (). Function names can contain letters, digits, underscores, and dollar signs (same rules as variables). The parentheses may include parameter names separated by commas (parameter1, parameter2, ...). The code to be executed by the function is placed inside curly brackets {}. When the function reaches a return statement, the function will stop executing.
If the function was invoked from a statement, the contract will “return” to execute the code after the invoking statement. Functions often compute a return value. The return value is “returned” back to the “caller”. See Table 6-6 for descriptions and examples.
TABLE 6-6 Functions and Parameters
Cryptographic Functions
A cryptographic hash function is a special class of hash function with properties that make it suitable for use in cryptography. It is a mathematical algorithm that maps data of arbitrary size to a bit string of a fixed size (a hash function), which is designed to also be a one-way function—that is, a function which is infeasible to invert. The only way to recreate the input data from an ideal cryptographic hash function’s output is to attempt a brute-force search of possible inputs to see if they produce a match, or to use a rainbow table of matched hashes.
The secure hash algorithms are a family of cryptographic hash functions published by the National Institute of Standards and Technology (NIST) as a US Federal Information Processing Standard (FIPS). See Table 6-7 for syntax and descriptions.
TABLE 6-7 Cryptographic Functions
Contract-Related Functions
All functions of the current contract are callable directly, including the current function. See Table 6-8 for syntax and descriptions.
TABLE 6-8 Contract-Related Functions
Functions on Addresses
It is possible to query the balance of an address using the property balance and to send ether (in units of wei) to an address using the send function. See Table 6-9 for syntax and descriptions.
TABLE 6-9 Functions on Addresses
Constructor Arguments
A Solidity contract expects constructor arguments after the end of the contract data itself. This means that you pass the arguments to a contract by putting them after the compiled bytes as returned by the compiler in the usual application binary interface (ABI) format. The ABI is how you call functions in a contract and get data returned. An ABI is like an application program interface (API). It dictates how functions are called and in which binary format parameters are passed. An Ethereum smart contract is bytecode on the Ethereum blockchain. There are usually many functions in a contract. An ABI provides the specification regarding how functions in the contract are invoked, and a guarantee that the function will return data in the expected format.
From Ethereum’s ABI specification, an example:
If we wanted to call abc with the parameters 77 and true, we would pass 68 bytes total, which can be broken down into the following:
• The method ID: This is derived as the first 4 bytes of the Keccak-256 hash of the ASCII form of the signature abc(uint32,bool).
• 0x000000000000000000000000000000000000000000000000000000000000004D: The first parameter, a uint32 value 77 padded to 32 bytes.
• 0x0000000000000000000000000000000000000000000000000000000000000001: The second parameter, boolean true, padded to 32 bytes.
Using a higher-level library such as web3.js abstracts most of these details, but the ABI in JSON format still needs to be provided to web3.js.
ABI is an abstraction and not part of the core Ethereum protocol. Anyone can define their own ABI for their contracts. That said, it is simpler for all developers to use Solidity, Serpent, and web3.js, which all comply with the ABI above.
Accessor Functions
The compiler automatically creates accessor functions for all public state variables. The contract given below will have a function called data that does not take any arguments and returns a uint, the value of the state variable data. The initialization of state variables can be done at declaration.
Layout of Storage
Statically sized variables (everything except mapping and dynamically sized array types) are laid out contiguously in storage starting from position 0. Multiple items that need less than 32 bytes are packed into a single storage slot if possible, according to the following rules:
• The first item in a storage slot is stored lower-order aligned.
• Elementary types use only as many bytes as are necessary to store them.
• If an elementary type does not fit the remaining part of a storage slot, it is moved to the next storage slot.
• Structs and array data always start a new slot and occupy whole slots, but items inside a struct or array are packed tightly according to these rules.
The elements of structs and arrays are stored after each other, just as if they were given explicitly.
Due to their unpredictable size, mapping and dynamically sized array types use a sha3 computation to find the starting position of the value or the array data. These starting positions are always full stack slots.
The mapping or the dynamic array itself occupies an (unfilled) slot in storage at some position according to the above rule (or by recursively applying this rule for mappings to mappings or arrays of arrays). For a dynamic array, this slot stores the number of elements in the array. For a mapping, the slot is unused, but it is needed so that two equal mappings after each other will use a different hash distribution. Array data is located at sha3(p) and the value corresponding to a mapping key is located at sha3(k . p) where . is concatenation. If the value is again a non-elementary type, the positions are found by adding an offset of sha3(k . p).
So for the following contract snippet:
Run Ethereum Dapps in Your Browser
Prior to blockchain, the application development life cycle, which facilitated large “Web2” applications, was built using tools like HTML, CSS, JavaScript, REST web services, Java, SQL, and NOSQL data stores. Now it is being amended to integrate the blockchain onto that stack. Ethereum enables the decentralized web, referred to as “Web3.” What makes it different from Web2 is that on Ethereum the web servers are gone except where used to access some verifiable condition needed to support smart contract execution. So the new dapp (“decentralized application”) is just like most applications. It consists of two parts: classic front-end and back-end architecture. As you would expect the frontend is written to either handle web services like REST or provide an HTML/CSS user experience to handle user requests and provide a response. The other part of the application is the backend, which interacts with the blockchain, the new “database.” So how does a web browser application converse with the blockchain?
MetaMask solves that key blockchain usability point of friction by providing a way for normal browsers to access the blockchain and propose transactions, to help anyone accomplish any action on the blockchain, easily and securely, enabling a new kind of web browsing experience.
MetaMask is a browser extension that injects the web3 API into every website you visit. Using MetaMask, you can use the browser you are comfortable with to browse the emerging decentralized web. The key advantage of using MetaMask is simplified key management. It encrypts your private key locally and asks users to confirm and sign transactions and messages as requested before relaying them to the Ethereum blockchain.
In order to interact with the blockchain, a client needs access to the entire chain. This implies that for MetaMask to interact with the blockchain, it would need to download the entire blockchain locally for use. To circumvent this, a “zero-client” gateway can be used for instant access via RPC to and from the blockchain. The JSON-RPC API was discussed in the previous chapter. MetaMask uses INFURA as its gateway, which allows for instant setup simply by installing an extension.
Installing MetaMask
MetaMask is currently available as a Chrome extension, with other browser support under active development. The technology is advancing rapidly that could ultimately allow for MetaMask to function within a browser without requiring an extension. To install MetaMask, simply visit the Chrome Web Store, search for and install MetaMask.
Developing a Contract Using MetaMask
After installing, you will see the MetaMask fox logo in the browser toolbar. The first time using the application you will need to generate your wallet public and private keys. The private key will be encrypted locally using a password you set. You will also be given a recovery seed phrase which you should save and store securely if you plan to use MetaMask to store real value. If you forget your wallet password, lose your computer, or otherwise can’t get access to your MetaMask wallet, you will be able to restore to a fresh browser using this seed phrase.
The Ethereum wallet is a gateway to decentralized applications on the Ethereum blockchain. It allows you to hold and secure ether and other crypto-assets built on Ethereum, as well as write, deploy, and use smart contracts. MetaMask provides an Ethereum wallet inside your browser. Metamask hosts a wallet with your private key—an Ethereum wallet—and allows you to access sites directly in your Chrome browser and trade as if you had your wallet right there with you on the site. The MetaMask user interface is quite simple, as seen in Figure 6-1. Your Ethereum account address is available, with links to a more detailed view of the account activity on a popular blockchain explorer. When on the Ethereum Main Net, you have the option to buy the ether token via integrations with popular exchanges such as Coinbase, where you can buy ether for fiat currency such as USD, or ShapeShift, where you can convert existing cryptocurrencies such as bitcoin to ether. You can send transactions as well, including sending the ether token to another account or smart contract.
FIGURE 6-1 MetaMask user interface
In order to interact with the Ethereum blockchain, it is necessary to pay “gas” costs for each computational step a smart contract takes. Since this could become quite costly during development, test networks exist where the ether has no real-world value. In this way, development and testing can occur without risk of lost value. One such test network is called Ropsten. MetaMask supports Ropsten natively with INFURA on the backend communicating with the Ropsten chain. For now, you can switch MetaMask to use the Ropsten network on the top navigation bar of the MetaMask interface.
In the next step, we will start to write our first smart contract. To deploy that to the Ropsten test network we will need some Ropsten test ether. You can click the Buy button in MetaMask to get a link to the Ropsten faucet. At the faucet, you can request 1 ether. As soon as that transaction is included on the Ropsten blockchain, your ether balance in MetaMask will be 1. We will come back to this later when we deploy a smart contract.
MetaMask is the gateway that allows your web-based decentralized application to interact with the blockchain. Deployed smart contracts on the blockchain are the backbone of the decentralized web. Now that we have a gateway to interact with these smart contracts, we can look more closely at how to write and deploy them.
Remix/Browser Solidity
Smart contracts for the Ethereum blockchain are written in high-level languages and compiled to bytecode interpreted by the Ethereum Virtual Machine (EVM). Compilers exist for the following languages, developed specifically for Ethereum: LLL, Serpent, and Solidity. There are active efforts to further the development of LLL and Serpent, but for now Solidity is the most popular language used by Ethereum developers. The easiest way to get your feet wet with Solidity is through the Remix Solidity IDE and compiler.
Remix is an online Solidity editor that enables compilation of Solidity code and even deployment to the blockchain using MetaMask. To access Remix, visit https://remix.ethereum.org.
When you first visit the Remix interface, you will see sample Solidity code in the editor window. For this exercise, we will be starting with a much more basic smart contract.
Develop a Simple Smart Contract
Let’s write our first smart contract! Open Remix in a browser and create an empty new file by clicking the + at the top left. Enter the following Solidity code into the editor:
This is a very simple smart contract that when executed writes “Hello World!” to the transaction log for that contract address. By default, Remix is set to autocompile as you are typing. When you have completely entered the code with no syntax errors, the Contract tab on the right side of the Remix interface will show the compiled bytecode and the application binary interface (ABI) needed to interact with the contract. The ABI is a JSON-formatted text string you will use in your code that interacts with a smart contract.
Remix provides a whole set of other features, including a debugger, formal verification, and of course links to complete documentation of the Solidity language. Remix has integrated deployment capabilities, which coupled with MetaMask make deployment painless.
Deploy the Smart Contract
As previously mentioned, the Remix compiler auto-compiles as you type into the editor window. When the smart contract is syntactically correct, the right panel Contract tab will provide the compiled bytecode; the ABI and web3 deploy JavaScript code on the Contract Details tab. You should see something similar to Figure 6-2. The bytecode is what is actually sent to the blockchain. This transaction must first be signed by your private key. MetaMask makes this easy.
FIGURE 6-2 Remix compiler with smart contract Solidity code
First, in Remix, select Injected Web3 in the option to select execution environment. This tells Remix that you want to rely on MetaMask in your browser to intercept and handle any interactions with the web3 APIs. Now you are ready to deploy Hello World to the Ropsten network. Assuming you have pointed MetaMask at Ropsten and your Hello World contract has compiled successfully, you can click the Create button.
When you click Create, Remix will create a transaction to send to the Ropsten test network. That transaction must first be signed, so a MetaMask window will pop up asking you to accept the transaction (see Figure 6-3). By accepting, you are effectively signing the transaction with your private key in your MetaMask wallet and sending the signed transaction to the Ethereum blockchain.
FIGURE 6-3 MetaMask transaction signing
After accepting, you will see Remix telling you that the transaction is waiting to be mined. As soon as this pending transaction is mined, or included in a block, you will see the contract address where this newly deployed smart contract can be found on the blockchain. In this case, the contract address is 0x2f8eb76Db701a36f8F44C1cEf0402bD329F6C03B. Once this contract has been deployed to the blockchain, it cannot be changed, deleted, or tampered with. It is now an immutable piece of software that when executed will do exactly what it should. Namely, log Hello World.
Validate the Smart Contract
To validate that our Hello World smart contract has been deployed, we can look it up in a block explorer. Recall that a property of most blockchains is complete transparency to the blocks and the data in each transaction. A block explorer is like a search engine that allows you to look into all of the data contained on the chain. The leading explorer in the Ethereum ecosystem is Etherscan (etherscan.io).
Etherscan supports multiple test networks, in addition to the main Ethereum network. To search for your newly deployed contract, first select the Ropsten network in Etherscan. On the MISC menu, you will be able to choose Ropsten. Then you can search for the contract address you received from Remix when you deployed the contract. Etherscan should identify the address as a contract, as opposed to a user account. The contract is holding 0 ether and has had one transaction, which was the contract creation we just did. You’ll be able to see what block this contract was created on as well, which can be useful in proving a timeline of activity. Furthermore, you’ll see who created the contract—this is your MetaMask wallet address as MetaMask was the wallet that signed the transaction and sent it to the test network.
Now that we know the contract exists, let’s execute it so we can validate that it behaves as we expect. To execute the contract, we need to send a transaction to the contract itself. There is no need to send any ether to the contract—in fact, if you do, that ether will be lost forever because the contract isn’t written to do anything with any ether sent to it. Therefore, we can send an empty transaction to the contract address to execute it. How will we send a transaction? The answer again is MetaMask.
Back in MetaMask, ensure you are on the Ropsten network. You should still have plenty of ether left since the last transaction used just a tiny bit. To create a transaction, click Send in MetaMask. For the Recipient Address, enter the address of your smart contract. For Amount, leave that at 0 and click Send. Again, you will be prompted to accept the transaction. After acceptance, the transaction will be sent to Ropsten and eventually included in a block and written to the blockchain.
Back at Etherscan, you will notice now there are two transactions for this smart contract. The first is the contract creation, and the most recent is our transaction we just sent causing the code to execute. If we drill into the details for that most recent transaction, we see a handful of metadata about the transaction itself. In Etherscan, they also provide the event logs. In the event log for our contract, the data payload is stored in hexadecimal format. Etherscan conveniently provides a conversion to text, and we see what we are expecting to see: Hello World! Congratulations on successfully deploying your first smart contract!
Next Step: Try Truffle
If you’re interested in some interesting tutorials or you want to start building web-based applications with the Ethereum blockchain, you will find the Truffle web framework to be a nice fit for your needs. For many types of dapps, Truffle does everything you could want: it compiles your blockchain contracts, injects them into your web app, and can even run a test suite against them! See http://truffleframework.com/ for documentation and tutorials.
Summary
In this chapter, we introduced the Solidity smart contract programming language and tools that make it simple and easy to fast-track deploy a smart contract to the Ethereum blockchain. In the next chapter, we will introduce tools that are a little more complex and support a development workflow to handle more complex development.