We will cover topics such as the syntax for defining and using modifiers, the _; symbol, using multiple modifiers on a single function, modifiers with arguments, enum-based modifiers, inherited and overridden modifiers, and examples of how to use modifiers in real-world contracts.

By the end of this article, you will have a deep understanding of how modifiers work and how to use them effectively in your Solidity code.

What are Solidity Modifiers?

A modifier is a special type of function that you use to modify the behavior of other functions. Modifiers allow you to add extra conditions or functionality to a function without having to rewrite the entire function.

To define a modifier, you use the modifier keyword followed by the name of the modifier and any parameters it may have.

Here is an example for a modifier:

modifier onlyOwner {
    require(msg.sender == owner);
    _;
}

In this example, the onlyOwner modifier has no parameters and includes a require statement that checks that the message sender is the contract owner.

If the message sender is the contract owner, the function will be executed. If the message sender is not the contract owner, the function will not execute.

To use a modifier, attach it to a function by placing it in the function definition. For example:

function changeOwner(address newOwner) onlyOwner public {
    // function body
}

In this example, the changeOwner function has the onlyOwner modifier attached to it. This means that in order to execute the changeOwner function, the caller must be the contract owner.

If the message sender is not the contract owner, the require statement in the onlyOwner modifier will fail and the function will not execute.

How Does the _; Symbol Work?

The _; symbol is a special symbol that is used in Solidity modifiers to indicate the end of the modifier and the beginning of the function that the modifier is modifying.

The body of a modifier is made up of one or more statements that are used to modify the behavior of the function, and the _; symbol.

Here is the onlyOwner modifier with the _; symbol:

modifier onlyOwner {
    require(msg.sender == owner);
    _;
}

Without the _; symbol, the compiler would not know where to insert the code from the modifier into the function.

How to Use Multiple Modifiers on a Function

You may want to use multiple modifiers on a single function. Solidity lets you use more than one modifier on a function as in the example below:

contract MyContract{
   address owner;

   modifier ownerChanges {
       _;
       require(msg.sender == owner);
   }

   modifier onlyOwner {
       require(msg.sender == owner);
       _;
   }

   function changeOwner(address newOwner) onlyOwner ownerChanges public {
       owner = newOwner;
   }
}

The order you place your modifiers in doesn’t matter. When you call the changeOwner function, the virtual machine executes both onlyOwner and ownerChanges.

How to Use Modifiers with Arguments

Modifiers in Solidity can have arguments of any data type supported by Solidity. Modifiers with arguments are defined in the same way as regular modifiers, with the addition of one or more parameters in the function definition.

Here is an example syntax for a modifier with regular arguments:

modifier onlyAllowedUser(address user) {
    require(msg.sender == user);
    _;
}

In this example, the onlyAllowedUser modifier has one parameter, user, which is of type address. The modifier includes a require statement that checks the value of the user parameter and only allows the function to execute if the message sender is equal to user.

To use a modifier with regular arguments, you can attach it to a function and pass the appropriate values as arguments. For example:

function updateData(uint id, bytes32 newData, address user) onlyAllowedUser(user) public {
    // function body
}

In this example, the updateData function has the onlyAllowedUser modifier attached to it and takes an address parameter called user. When the updateData function is called, the value of the user parameter is passed to the onlyAllowedUser modifier.

How to Create an Enum-based Modifier

Another way to use modifiers is to create an enum-based modifier. Enum-based modifiers allow you to specify a set of predefined values that can be used to determine whether or not a function should execute.

To create an enum-based modifier, you first need to define an enum type. An enum type is a special data type that consists of a set of named values called "members". Here is an example enum type:

enum ActionType {
    CREATE,
    UPDATE,
    DELETE
}

Once you have defined the enum type, you can create an enum-based modifier by adding a parameter of the enum type to your modifier function.

The modifier function should include a required statement that checks the value of the enum parameter and determines whether or not the function should execute. Here is an example of an enum-based modifier:

modifier onlyAllowedAction(ActionType action) {
    require(action == ActionType.CREATE || action == ActionType.UPDATE);
    _;
}

The modifier, called onlyAllowedAction, will only allow the function to which it is attached to execute if the value of the action parameter is either ActionType.CREATE or ActionType.UPDATE. If the value of action is anything else, the require statement will fail and the function will not execute.

To use the enum-based modifier, you would attach it to a function and pass the appropriate enum value as an argument. For example:

function updateData(uint id, bytes32 newData, ActionType action) onlyAllowedAction(action) public {
    // function body
}

In this example, the updateData function can only be executed if the action parameter is set to either ActionType.CREATE or ActionType.UPDATE.

How to Inherit and Override Modifiers

In Solidity, it is possible to inherit and override modifiers in order to reuse code and customize the behavior of functions.

To inherit a modifier, use the is keyword in the contract that you want to inherit the modifier from. For example:

contract BaseContract {
    modifier onlyOwner {
        require(msg.sender == owner);
        _;
    }
}

contract MyContract is BaseContract {
    // functions in MyContract can use the onlyOwner modifier
}

In this example, the MyContract contract inherits the onlyOwner modifier from the BaseContract. This means that any function in MyContract can use the onlyOwner modifier. The onlyOwner modifier ensures that only the contract owner can execute the function that it is attached to.

You can also override a modifier by defining a new version of the modifier in a contract that inherits from another contract. To do this, you can use the same name for the modifier and define a new implementation for it. For example:

contract BaseContract {
    modifier onlyOwner {
        require(msg.sender == owner);
        _;
    }
}

contract MyContract is BaseContract {
    // override the onlyOwner modifier
    modifier onlyOwner {
        require(msg.sender == newOwner);
        _;
    }
}

In this example, the MyContract contract overrides the onlyOwner modifier from the BaseContract. This means that any function in MyContract that uses the onlyOwner modifier will now check that the message sender is equal to the newOwner variable, rather than the owner variable.

Inheriting and overriding modifiers can be a useful way to reuse code and customize the behavior of functions in your Solidity contracts.

Conclusion

Modifiers in Solidity are special functions that modify the behavior of other functions. They allow developers to add extra conditions or functionality without having to rewrite the entire function.

Modifiers can have arguments and can be inherited and overridden to customize their behavior, and they can be used in combination with other modifiers to further customize the behavior of functions.

Enum-based modifiers allow developers to specify a set of predefined values to determine whether or not a function should execute. State-based modifiers use the contract's current state to determine whether or not a function should execute.

Modifiers can help developers write cleaner, more modular code and make it easier to maintain and update their contracts.

Thanks for reading!

After 15 years in law and other roles, I’d experienced a number of jobs, countries, companies, and career paths. None of them compared to the joy and thrill I get from coding.

The downside? Picking up new coding skills can be confusing, frustrating, and time consuming. And it’s easy to forget some of the minute but important details.

So I wrote this handbook. It's intended to get you started on coding Solidity ASAP. It follows the Pareto Principle (aka the 80/20 rule) by focusing on the 20% of the info that will cover 80% of your needs.

I started assembling these concepts when I was learning Solidity, as part of my role at Chainlink Labs. I applied many of the self-learning techniques that I learned when transitioning to coder at the age of 38.

This is the resource I wish I had. It is designed to give beginner and intermediate developers solid mental models to stack as you get deeper into the language (mental models massively accelerate effective learning).

I will keep this handbook updated, but I could really use your help! Just tweet me @ZubinPratap to let me know if I need to update this handbook.

I’d like to acknowledge my amazing colleagues Kevin Ryu, Andrej Rakic, Patrick Collins, and Richard Gottleber for the invaluable guidance and input on this handbook.

Table of Contents

1. Who is this handbook for?

2. Essential prior knowledge

3. What is Solidity?

4. What is a smart contract?

5. How to declare variables and functions in Solidity?

6. Variable scope in Smart Contracts

7. How visibility specifiers work

8. What are constructors?

9. Interfaces and abstract contracts

10. Smart contract example #2

11. What is contract state?

12. State mutability keywords (modifiers)

13. Data locations – storage, memory, and stack

14. How typing works

15. Solidity data types

16. How to declare and initialize arrays in Solidity

17. What are function modifiers?

18. Error handling in Solidity - require, assert, revert

19. Inheritance in Solidity

20. Inheritance with constructor parameters

21. Type conversion and type casting in Solidity

22. How to work with floating point numbers in Solidity

23. Hashing, ABI encoding and decoding

24. How to call contracts and use the fallback function

25. How to send and receive Ether

26. Solidity libraries

27. Events and logs in Solidity

28. Time logic in Solidity

29. Conclusion and further resources

Who Is This Handbook For?

This handbook is for people who are interested in exploring the vision behind “Web3”, and who wish to acquire in-demand skills that are essential to realizing that vision.

Do not memorize it! Read it and then use it as a “desktop reference” companion. As you learn any new language, you will find that concepts, idioms, and usage can get a bit confusing or your memory fades with time. That’s ok! That’s what this handbook is designed to help you with.

Over time I may add some more advanced topics to this, or create a separate tutorial. But for now this handbook will get you most of the outcomes you require to build your first several Solidity dApps.

This handbook assumes you have at least a few months of experience with programming. By programming I mean at the very least you’ve written in JavaScript or Python or some compiled language (since HTML and CSS aren't actually "programming" languages, it won't be enough to know only them).

The only other requirements are that you are curious, committed, and not putting arbitrary deadlines on yourself.

As long as you have a laptop, and a browser with an internet connection, you’ll be able to run the Solidity code. You can use Remix in your browser to write the code in this handbook. No other IDE required!

Essential Prior Knowledge

I have also assumed that you know the basics of blockchain technology, and in particular you understand the basics of Ethereum and what smart contracts are (hint: they’re programs that run on blockchains and hence provide special trust-minimized benefits!).

You are unlikely to need them to understand this handbook. But practically speaking, having a browser wallet like Metamask and understanding the difference between Ethereum contract accounts and externally owned accounts will help you get the most out of this handbook.

What is Solidity?

Now, let’s start with understanding what Solidity is. Solidity is an object-oriented programming language influenced by C++, JavaScript and Python.

Solidity is designed to be compiled (converted from human readable to machine readable code) into bytecode that runs on the Ethereum Virtual Machine (EVM). This is the runtime environment for Solidity code, just like your browser is a runtime environment for JavaScript code.

So, you write Smart Contract code in Solidity, and the compiler converts it into bytecode. Then that bytecode gets deployed and stored on Ethereum (and other EVM-compatible blockchains).

You can get a basic introduction to the EVM and bytecode in this video I made.

What is a Smart Contract?

Here is a simple smart contract that works out of the box. It may not look useful, but you’re going to understand a lot of Solidity from just this!

Read it along with each comment to get a sense of what’s going on, and then move on to some key learnings.

We will get to some of the details like what public and view mean shortly.

For now, take seven key learnings from the above example:

1. The first comment is a machine readable line ( // SPDX-License-Identifier: MIT) that specifies the licensing that covers the code.

SPDX license identifiers are strongly recommended, though your code will compile without it. Read more here. Also, you can add a comment or “comment out” (suppress) any line by prefixing it with two forward slashes "// ".

2. The pragma directive must be the first line of code in any Solidity file. Pragma is a directive that tells the compiler which compiler version it should use to convert the human-readable Solidity code to machine readable bytecode.

Solidity is a new language and is frequently updated, so different versions of the compiler produce different results when compiling code. Some older solidity files will throw errors or warnings when compiled with a newer compiler version.

In larger projects, when you use tools like Hardhat, you may need to specify multiple compiler versions because imported solidity files or libraries that you depend on were written for older versions of solidity. Read more on Solidity’s pragma directive here.

3. The pragma directive follows Semantic Versioning (SemVer) - a system where each of the numbers signifies the type and extent of changes contained in that version. If you want a hands-on explanation of SemVer is check out this tutorial - it is very useful to understand and it’s used widely in development (especially web dev) these days.

4. Semicolons are essential in Solidity. The compiler will fail if even a single one is missing. Remix will alert you!

5. The keyword contract tells the compiler that you’re declaring a Smart Contract. If you’re familiar with Object Oriented Programming, then you can think of Contracts as being like Classes.

If you’re not familiar with OOP then think of contracts as being objects that hold data - both variables and functions. You can combine smart contracts to give your blockchain app the functionality it needs.

6. Functions are executable units of code that encapsulate single ideas, specific functionality, tasks, and so on. In general we want functions to do one thing at a time.

Functions are most often seen inside smart contracts, though they can be declared in the file outside the smart contract’s block of code. Functions may take 0 or more arguments and they may return 0 or more values. Inputs and outputs are statically typed, which is a concept you will learn about later in this handbook.

7. In the above example the variable qtyCups is called a “state variable”. It holds the contract’s state - which is the technical term for data that the program needs to keep track of to operate.

Unlike other programs, smart contract applications keep their state even when the program is not running. The data is stored in the blockchain, along with the application, which means that each node in the blockchain network maintains and synchronizes a local copy of the data and smart contracts on the blockchain.

State variables are like database “storage” in a traditional application, but since blockchains need to synchronize state across all nodes in the network, using storage can be quite expensive! More on that later.

How to Declare Variables and Functions in Solidity

Let’s break down that HotFudgeSauce Smart Contract so we understand more about each little piece.

The basic structure/syntax to defining things in Solidity is similar to other statically typed languages. We give functions and variables a name.

But in typed languages we also need to specify the type of the data that is created, passed as input or returned as output. You can jump down to the Typing Data section in this handbook if you need to understand what typed data is.

Below, we see what declaring a “State Variable” looks like. We also see what declaring a function looks like.

The first snippet declares a State Variable (I’ll explain what this is soon, I promise) called qtyCups. This can only store values that are of type uint which means unsigned integers. “Integer” refers to all whole numbers below zero (negative) and above zero (positive).

Since these numbers have a + or - sign attached, they’re called signed integers. An unsigned integer is therefore always a positive integer (including zero).

In the second snippet, we see a familiar structure when we declare functions too. Most importantly, we see that the functions have to specify a data type for the value that the function returns.

In this example, since get() returns the value of the storage variable we just created, we can see that the returned value must be a uint.

public is a visibility specifier. More on that later. view is a State-Mutability modifier. More on that below too!

It’s worth noting here that state variables can also be of other types - constant and immutable. They look like this:

Constants and immutable variables have their values assigned once, and only once. They cannot be given another value after their first value is assigned.

So if we made the qtyCups state variable either constant or immutable, we would not be able to call the increment() or decrement() functions on it anymore (in fact, the code wouldn’t compile!).

Constants must have their values hardcoded in the code itself, whereas immutable variables can have their values set once, generally by assignment in the constructor function (we’ll talk about constructor functions very soon, I promise). You can read more in the docs here.

Variable Scope in Smart Contracts

There are three scopes of variables that Smart Contracts have access to:

1. State Variables: store permanent data in the smart contract (referred to as persistent state) by recording the values on the blockchain.

2. Local Variables: these are “transient” pieces of data that hold information for short periods of time while running computations. These values are not stored permanently on the blockchain.

3. Global variables: these variables and functions are “injected” into your code by Solidity, and made available without the need to specifically create or import them from anywhere. These provide information about the blockchain environment the code is running on and also include utility functions for general use in the program.

You can tell the difference between the scopes as follows:

1. state variables are generally found inside the smart contract but outside of a function.

2. local variables are found inside functions and cannot be accessed from outside that function’s scope.

3. Global variables aren’t declared by you - they are “magically” available for you to use.

Here is our HotFudgeSauce example, slightly modified to show the different types of variables. We give qtyCups a starting value and we dispense cups of fudge sauce to everyone except me (because I’m on a diet).

How Visibility Specifiers Work

The use of the word “visibility” is a bit confusing because on a public blockchain, pretty much everything is “visible” because transparency is a key feature. But visibility, in this context, means the ability for one piece of code to be seen and accessed by another piece of code.

Visibility specifies the extent to which a variable, function, or contract can be accessed from outside the region of code where it was defined. The scope of visibility can be adjusted depending on which portions of the software system need to access it.

If you’re a JavaScript or NodeJS developer, you’re already familiar with visibility – any time you export an object you’re making it visible outside the file where it is declared.

Types of Visibility

In Solidity there are 4 different types of visibility: public, external, internal and private.

Public functions and variables can be accessed inside the contract, outside it, from other smart contracts, and from external accounts (the kind that sit in your Metamask wallet) - pretty much from anywhere. It’s the broadest, most permissive visibility level.

When a storage variable is given public visibility, Solidity automatically creates an implicit getter function for that variable’s value.

So in our HotFudgeSauce smart contract, we don’t really need to have the get() method, because Solidity will implicitly provide us identical functionality, just by giving qtyCups a public visibility modifier.

Private functions and variables are only accessible within the smart contract that declares them. But they cannot be accessed outside of the Smart Contract that encloses them. private is the most restrictive of the four visibility specifiers.

Internal visibility is similar to private visibility, in that internal functions and variables can only be accessed from within the contract that declares them. But functions and variables marked internal can also be accessed from derived contracts (that is, child contracts that inherit from the declaring contract) but not from outside the contract. We will talk about inheritance (and derived/child contracts) later on.

internal is the default visibility for storage variables.

The 4 Solidity Visibility specifiers and where they can be accessed from

The external visibility specifier does not apply to variables - only functions can be specified as external.

External functions cannot be called from inside the declaring contract or contracts that inherit from the declaring contract. Thus, they can only be called from outside the enclosing contract.

And that’s how they’re different from public functions – public functions can also be called from inside the contract that declare them, whereas an external function cannot.

What are Constructors?

A constructor is a special type of function. In Solidity, it is optional and is executed once only on contract creation.

In the following example we have an explicit constructor and it accepts some data as a parameter. This constructor parameter must be injected by you into your smart contract at the time you create it.

Solidity constructor function with input parameter

To understand when the constructor function gets called, it’s helpful to remember that a Smart Contract is created over a few phases:

• it is compiled down to bytecode (you can read more about bytecode here). This phase is called “compile time”.

• it gets created (constructed) - this is when the constructor kicks into action. This can be referred to as “construction time”.

• Bytecode then gets deployed to the blockchain. This is “deployment”.

• The deployed smart contract bytecode gets run (executed) on the blockchain. This can be considered “runtime”.

In Solidity, unlike other languages, the program (smart contract) is deployed only after the constructor has done its work of creating the smart contract.

Interestingly, in Solidity, the finally deployed bytecode does not include the constructor code. This is because in Solidity, the constructor code is part of the creation code (construction time) and not part of the runtime code. It is used up when creating the smart contract, and since it’s only ever called once it is not needed past this phase, and is excluded in the finally deployed bytecode.

So in our example, the constructor creates (constructs) one instance of the Person smart contract. Our constructor expects us to pass a string value which is called _name to it.

When the smart contract is being constructed, that value of _name will get stored in the state variable called name (this is often how we pass configuration and other data into the smart contract). Then when the contract is actually deployed, the state variable name will hold whatever string value we passed into our constructor.

Understanding the Why

You might wonder why we bother with injecting values into the constructor. Why not just write them into the contract?

This is because we want contracts to be configurable or “parameterized”. Rather than hard code values, we want the flexibility and reusability that comes with injecting data as and when we need.

In our example, let’s say that _name referred to the name of a given Ethereum network on which the contract is going to be deployed (like Rinkeby, Goerli, Kovan, Mainnet, and so on).

How could we give that information to our smart contract? Putting all those values in it would be wasteful. It would also mean we need to add extra code to work out which blockchain the contract is running on. Then we'd have to pick the right network name from a hard-coded list which we store in the contract, which takes up gas on deployment.

Instead, we can just inject it into the constructor, at the time we are deploying the smart contract to the relevant blockchain network. This is how we write one contract that can work with any number of parameter values.

Another common use case is when your smart contract inherits from another smart contract and you need to pass values to the parent smart contract when your contract is being created. But inheritance is something we will discuss later.

I mentioned that constructors are optional. In HotFudgeSauce, we didn’t write an explicit constructor function. But Solidity supports implicit constructor functions. So if we don’t include a constructor function in our smart contract, Solidity will assume a default constructor which looks like constructor() {}.

If you evaluate this in your head you’ll see it does nothing and that’s why it can be excluded (made implicit) and the compiler will use the default constructor.

Interfaces and Abstract Contracts

An interface in solidity is an essential concept to understand. Smart Contracts on Ethereum are publicly viewable and therefore you can interact with them via their functions (to the extent the Visibility Specifiers allow you to do so!).

This is what makes smart contracts “composable” and why so many Defi protocols are referred to as “money Legos” - you can write smart contracts that interact with other smart contracts that interact with other smart contracts and so on…you get the idea.

So when you want your smart contract A to interact with another smart contract B, you need B’s interface. An interface gives you an index or menu of the various functions available for you to call on a given Smart Contract.

An important feature of Interfaces is that they must not have any implementation (code logic) for any of the functions defined. Interfaces are just a collection of function names and their expected arguments and return types. They’re not unique to Solidity.

So an interface for our HotFudgeSauce Smart Contract would look like this (note that by convention, solidity interfaces are named by prefixing the smart contract’s name with an “I”:

That’s it! Since HotFudgeSauce had only three functions, the interface shows only those.

But there is an important and subtle point here: an interface does not need to include all the functions available to call in a smart contract. An interface can be shortened to include the function definitions for the functions that you intend to call!

So if you only wanted to use the decrement() method on HotFudgeSauce then you could absolutely remove get() and increment() from your interface - but you would not be able to call those two functions from your contract.

So what’s actually going on? Well, interfaces just give your smart contract a way of knowing what functions can be called in your target smart contract, what parameters those functions accept (and their data type), and what type of return data you can expect. In Solidity, that’s all you need to interact with another smart contract.

In some situations, you can have an abstract contract which is similar to but different from an interface.

An abstract contract is declared using the abstract keyword and is one where one or more of its functions are declared but not implemented. This is another way of saying that at least one function is declared but not implemented.

Flipping that around, an abstract contract can have implementations of its functions (unlike interfaces which can have zero implemented functions), but as long as at least one function is unimplemented, the contract must be marked as abstract:

You may (legitimately) wonder what the point of this is. Well, abstract contracts cannot be instantiated (created) directly. They can only be used by other contracts that inherit from them.

So abstract contracts are often used as a template or a “base contract” from which other smart contracts can “inherit” so that the inheriting smart contracts are forced to implement certain functions declared by the abstract (parent) contract. This enforces a defined structure across related contracts which is often a useful design pattern.

This inheritance stuff will become a little clearer when we discuss Inheritance later. For now, just remember that you can declare an abstract smart contract that does not implement all its functions - but if you do, you cannot instantiate it, and future smart contracts that inherit it must do the work of implementing those unimplemented functions.

Some of the important differences between interfaces and abstract contracts are that:

• Interfaces can have zero implementations, whereas abstract contracts can have any number of implementations as long as at least one function is “abstract” (that is, not implemented).

• All functions in an interface must be marked as “external” because they can only be called by other contracts that implement that interface.

• Interfaces cannot have constructors, whereas abstract contracts may.

• Interfaces cannot have state variables where abstract contracts may.

Smart Contract Example #2

For the next few Solidity concepts we’ll use the below smart contract. This is partly because this example contains a smart contract that is actually used in the real world. I've also chosen it because I have a clear bias to Chainlink Labs since I work there (😆) and it’s awesome. But it’s also where I learned a lot of Solidity, and it’s always better to learn with real-world examples.

So start by reading the code and the comments below. You’ve already learned 99% of what you need to understand the contract below, provided you read it carefully. Then move on to key learnings from this contract.

This smart contract gets the latest USD price of 1 Eth, from a live Chainlink price feed oracle (see the oracle on etherscan). The example uses the Goerli network so you don’t end up spending real money on the Ethereum mainnet.

Now to the 6 essential Solidity concepts you need to absorb:

1. Right after the pragma statement we have an import statement. This imports existing code into our smart contract.

This is super cool because this is how we reuse and benefit from code that others have written. You can check out the code that is imported on this GitHub link.

In effect, when we compile our smart contract, this imported code gets pulled in and compiled into bytecode along with it. We will see why we need it in a second…

2. Previously you saw that single-line comments were marked with //. Now you're learning about multiline comments. They may span one or more lines and use /* and */ to start and end the comments.

3. We declare a variable called priceFeed and it has a type AggregatorV3Interface. But where does this strange type come from? From our imported code in the import statement - we get to use the AggregatorV3Interface type because Chainlink defined it.

If you looked at that Github link, you’d see that the type defines an interface (we just finished talking about interfaces). So priceFeed is a reference to some object that is of type AggregatorV3Interface.

4. Take a look at the constructor function. This one doesn’t accept parameters, but we could have just as easily passed the ETH/USD Price Feed’s oracle smart contract’s address 0xD4a33860578De61DBAbDc8BFdb98FD742fA7028e to it as a parameter of type address. Instead, we are hard-coding the address inside the constructor.

But we are also creating a reference to the Price Feed Aggregator smart contract (using the interface called AggregatorV3Interface).

Now we can call all the methods available on the AggregatorV3Interface because the priceFeed variable refers to that Smart Contract. In fact, we do that next… 5. Let's jump to the function getLatestPrice(). You’ll recognize its structure from our discussion in HotFudgeSauce, but it’s doing some interesting things.

Inside this getLatestPrice() function we call the latestRoundData() function which exists on the AggregatorV3Interface type. If you look at the source code of this method you’ll notice that this latestRoundData() function returns 5 different types of integers!

Calling methods on another smart contract from our smart contract

In our smart contract, we are commenting out all 4 values that we don’t need. So this means that Solidity functions can return multiple values (in this example we are returned 5 values), and we can pick and choose which ones we want.

Another way of consuming the results of calling latestRoundData() would be:( ,int price, , ,) = priceFeed.latestRoundData() where we ignore 4 out of 5 returned values by not giving them a variable name.

When we assign variable names to one or more values returned by a function, we call it “destructuring assignment” because we destructure the returned values (separate each one out) and assign them at the time of destructuring, like we do with price above.

Since you’ve learned about interfaces, I recommend you take a look at Chainlink Labs’ GitHub repo to examine the implemented latestRoundData() function in the Aggregator contract and how the AggregatorV3Interface provides the interface to interact with the Aggregator contract.

What is Contract State?

Before we proceed any further, it’s important to make sure that the terminology that we’re going to see a lot is comprehensible to you.

“State” in computer science has a well-defined meaning. While it can get very confusing, the crux of state is that it refers to all the information that is “remembered” by a program as it runs. This information can change, update, be removed, created and so on. And if you were to take a snapshot of it at various times, the information will be in different “states”.

So the state is just the current snapshot of the program, at a point in time during its execution - what values do its variables hold, what are they doing, what objects have been created or removed, and so on.

We have previously examined the three types of variables - State Variables, Local Variables, and Global variables. State variables, along with Global variables give us the state of the smart contract at any given point in time. Thus, the state of a smart contract is a description of:

1. what values its state variables hold,

2. what values the blockchain-related global variables have at that moment in time, and

3. the balance (if any) lying in the smart contract account.

State Mutability Keywords (Modifiers)

Now that we have discussed state, state variables, and functions, let’s understand the Solidity keywords that specify what we are allowed to do with state.

These keywords are referred to as modifiers. But not all of them permit you to modify state. In fact many of them expressly disallow modifications.

Here are Solidity modifiers you will see any real-world smart contract:

Note that in Solidity version 0.8.17, there were breaking changes that enabled the use of payable as a data type. Specifically we now allowed to convert the address data type to a payable address type by doing a type conversion that looks like payable(0xdCad3a6d3569DF655070DEd06cb7A1b2Ccd1D3AF).
What this does is makes a given ethereum address payable, after which we can send Eth to that address.

Note that this use of payable is a type conversion, and not the same as the function modifier, though the same keyword is used. We will cover the address type later, but you can read about this here. | | virtual | functions | This is a slightly more advanced topic and is covered in detail in the section on Inheritance. This modifier allows the function to be “overridden” in a child contract that inherits from it. In other words, a function with the keyword virtual can be “rewritten” with different internal logic in another contract that inherits from this one. | | override | functions | This is the flip side to the virtual modifier. When a child contract “rewrites” a function that was declared in a base contract (parent contract) from which it inherits, it marks that rewritten function with override to signal that its implementation overrides the one given in the parent contract. If a parent’s virtual function is not overridden by the child, the parent's implementation will apply to the child. | | indexed | events | We will cover events later in this handbook. They are small bundles of data “emitted” by a smart contract typically in response to noteworthy events happening. The indexed keyword indicates that one of the pieces of data contained in an event should be stored in the blockchain for retrieval and filtering later. This will make more sense once we cover Events and Logging later in this handbook. | | anonymous | events | The docs say “Does not store event signature as topic” which probably doesn’t mean a lot to you just yet. But the keyword does indicate that it’s making some part of the event “anonymous”. So this will make sense once we understand events and topics later in this handbook. |

Note that variables that are not storage variables ( i.e. local variables declared and used inside the scope of a given function) do not need state modifiers. This is because they’re not actually part of the smart contract’s state. They’re just part of the local state inside that function. By definition then, they’re modifiable and don’t need controls on their modifiability.

Data Locations – Storage, Memory, and Stack

On Ethereum and EVM-based chains, data inside the system can be placed and accessed in more than one “data location”.

Data locations are part of the fundamental design and architecture of the EVM. When you see the words “memory”, “storage” and “stack”, you should start thinking “data locations” - that is, where can data be stored (written) to and retrieved (read) from.

Data location has an impact on how the code executes at run time. But it also has very important impacts on how much gas gets used during deployment and running of the smart contract.

The use of gas requires a deeper understanding of the EVM and something called opcodes - we can park that discussion for now. While useful, it is not strictly necessary for you to understand data locations.

Though I’ve mentioned 3 data locations so far, there are 2 other ways in which data can be stored and accessed in Smart Contracts: “calldata”, and “code”. But these are not data locations in the EVM’s design. They’re just subsets of the 3 data locations.

Let’s start with storage. In the EVM’s design, data that needs to be stored permanently on the blockchain is placed in the relevant smart contract’s “storage” area. This includes any contract “state variables”.

Once a contract is deployed and has its specific address, it also gets its own storage area, which you can think of as a key-value store (like a hash table) where both the keys and the values are 256 bit (32 byte) data “words”. And “words” has a specific meaning in computer architecture.

Because storage persists data on the blockchain permanently, all data needs to be synchronized across all the nodes in the network, which is why nodes have to achieve consensus on data state. This consensus makes storage expensive to use.

You’ve already seen examples of storage variables (aka contract state variables) but here is an example taken from the Chainlink Verifiable Random Number Consumer smart contract

Storage data location. Putting data in the contract's storage layout.

When the above contract is created and deployed, whatever address that is passed into the contract’s constructor becomes permanently stored in the smart contract’s storage, and is accessible using the variable vrfCoodinator. Since this state variable is marked as immutable, it cannot be changed after this.

To refresh your memory from the previous section on keywords, where we last discussed immutable and constant variables, these values are not put in storage. They become part of the code itself when the contract is constructed, so these values don’t consume as much gas as storage variables.

Now let’s move to memory. This is temporary storage where you can read and write data needed during the running of the smart contract. This data is erased once the functions that use the data are done executing.

The memory location space is like a temporary notepad, and a new one is made available in the smart contract each time a function is triggered. That notepad is thrown away after the execution completes.

When understanding the difference between storage and memory, you can think of storage as a kind of hard disk in the traditional computing world, in the sense that it has “persistent” storage of data. But memory is closer to RAM in traditional computing.

The stack is the data area where most of the EVM’s computations are performed. The EVM follows a stack based computation model and not a register based computation model, which means each operation to be carried out needs to be stored and accessed using a stack data structure.

The stack’s depth - that is the total number of items it can hold - is 1024, and each item in the stack can be 256 bits (32 bytes) long. This is the same as the size of each key and value in the storage data location.

You can read more about how the EVM controls access to the stack data storage area here.

Next, let's talk about calldata. I have assumed that you have a basic understanding about Ethereum smart contract messages and transactions. If you don’t, you should first read those links.

Messages and transactions are how smart contract functions are invoked, and they contain a variety of data necessary for the execution of those functions. This message data is stored in a read-only section of the memory called calldata, which holds things like the function name and parameters.

This is relevant for externally callable functions, as internal and private functions don’t use calldata. Only “incoming” function execution data and function parameters are stored in this location.

Remember, calldata is memory except that calldata is read-only. You cannot write data to it.

And finally, code is not a data location but instead refers to the smart contract's compiled bytecode that is deployed and stored permanently on the blockchain. This bytecode is stored in an immutable ROM (Read Only Memory), that is loaded with the bytecode of the smart contract to be executed.

Remember how we discussed the difference between immutable and constant variables in Solidity? Immutable values get assigned their value once (usually in the constructor) and constant variables have their values hard-coded into the smart contract code. Because they’re hardcoded, constant values are compiled literally and embedded directly into the smart contract’s bytecode, and stored in this code / ROM data location.

Like calldata, code is also read-only - if you understood the previous paragraph you’ll understand why!

How Typing Works

Typing is a very important concept in programming because it is how we give structure to data. From that structure we can run operations on the data in a safe, consistent and predictable way.

When a language has strict typing, it means that the language strictly defines what each piece of data’s type is, and a variable that has a type cannot be given another type.

In other words, in strictly typed languages:

But in JavaScript, which is not typed, b=a would totally work - this makes JavaScript “dynamically typed”.

Similarly, in statically typed languages you cannot pass an integer into a function that expects a string. But in JavaScript we can pass anything to a function and the program will still compile but it may throw an error when you execute the program.

For example take this function:

As you can imagine, this can produce some pretty hard-to-find bugs. The code compiles and can even execute without failing, though it produces unexpected results.

But a strongly typed language would never let you pass the string “2” because the function would insist on the types that it accepts.

Let’s take a look at how this function would be written in a strongly typed language like Go.

How typing works in syntax, using Golang for illustration purposes

Trying to pass a string (even if it represents a number) will prevent the program from even compiling (building). You will see an error like this:

./prog.go:13:19: cannot use "2" (untyped string constant) as int value in argument to add

Go build failed.

Try it out for yourself!

So types are important because data that seems the same to a human can be perceived very differently by a computer. This can cause some pretty weird bugs, errors, program crashes and even big security vulnerabilities.

Types also give developers the ability to create their own custom types, which can then be programmed with custom properties (attributes) and operations (behaviors).

Type systems exist so that humans can reason about the data by asking the question “what is this data’s type, and what should it be able to do?” and the machines can do exactly what is intended.

Here is another example of how data that looks the same to you and me may be interpreted in hugely different ways by a processor. Take the sequence of binary digits (that is the digits can only have a value of 0 or 1, which is the binary system that processors work with) 1100001010100011.

To a human, using the decimal system that looks like a very large number - perhaps 11 gazillion or something.

But to a computer that is binary, so it’s not 11 anything. The computer sees this as a sequence 16 bits (short for binary digits) and in binary this could mean the positive number (unsigned integer) 49,827 or the signed integer -15,709 or the UTF-8 representation of the British Pound symbol £ or something different!

A sequence of bits can be interpreted by a computer to have very different meanings (source)

So all this explanation is to say that types are important, and that types can be “inbuilt” into a language even if the language does not strictly enforce types, like JavaScript.

JavaScript already has inbuilt types like numbers, strings, booleans, objects, and arrays. But as we saw, JavaScript does not insist on types being stuck to the way a statically typed language like Go does.

Now back to Solidity. Solidity is very much a statically typed language. When you declare a variable you must also declare its type. Going further, Solidity will simply refuse to compile if you try to pass a string into a function that expects an integer.

In fact Solidity is very strict with types. For example, different types of integers may also fail compilation like the following example where the function add() expects an unsigned integer (positive) and will only add to that number thus always returning a positive integer. But the return type is specified as an int which means it could be positive or negative!

So even though the input and output are 256-bit integers, the fact that the function only receives unsigned integers makes the compiler complain that the unsigned integer type is not implicitly convertible to the signed integer type.

That’s pretty strict! The developer can force the conversion (called type casting) by rewriting the return statement as return int256(a + 10). But there are issues to consider with that sort of action, and that’s out of scope for what we’re talking about here.

For now, just remember that Solidity is statically typed, which means that the type of each variable must be expressly specified when declaring them in the code. You can combine types to form more complex, composite types. Next, we can discuss some of these inbuilt types.

Solidity Data Types

Types that are built into the language and come with it “out of the box” are often referred to as “primitives”. They’re intrinsic to the language. You can combine primitive types to form more complex data structures that become “custom” data types.

In JavaScript, for example, primitives are data that is not a JS object and has no methods or properties. There are 7 primitive data types in JavaScript: string, number, bigint, boolean, undefined, symbol, and null.

Solidity also has its own primitive data types. Interestingly, Solidity does not have “undefined” or “null”. Instead, when you declare a variable and its type, but do not assign a value to it, Solidity will assign a Default Value to that type. What exactly that default value is depends on the data type .

Many of Solidity’s primitive data types are variations of the same ‘base’ type. For example the int type itself has subtypes based on the number of binary digits that the integer type can hold.

If that confuses you a bit, don’t worry - it isn’t easy if you’re not familiar with bits and bytes, and I’ll cover integers a bit more shortly.

Before we explore Solidity types, there is another very important concept that you must understand - it is the source of many bugs, and “unexpected gotchas” in programming languages.

This is the difference between a value type and reference type, and the resulting distinction between data in programs being “passed by value” vs “passed by reference”. I’ll go into a quick summary below but you may also find it useful to watch this short video to strengthen your mental model before proceeding.

Pass by reference vs pass by value

At an operating system level, when a program is running, all data used by the program during its execution is stored in locations in the computer’s RAM (memory). When you declare a variable, some memory space is allocated to hold data about that variable and the value that is, or eventually will be, assigned to that variable.

There is also a piece of data that is often called a “pointer”. This pointer points to the memory location (an “address” in the computer’s RAM) where that variable and its value can be found. So the pointer effectively contains a reference to where the data can be found in the computer’s memory.

So when you pass data around in a program (for example when you assign a value to a new variable name, or when you pass inputs (parameters) into a function or method, the language’s compiler can achieve this in two ways. It can pass a pointer to the data’s location in the computer’s memory, or it can make a copy of the data itself, and pass the actual value.

The first approach is “pass by reference”. The second approach is “pass by value”.

Solidity’s data type primitives fall into two buckets - they’re either value types, or they’re reference types.

In other words, in Solidity, when you pass data around, the type of the data will decide whether you’re passing copies of the value or a reference to the value’s location in the computer’s memory.

Value Types and Reference Types in Solidity

In Solidity’s “value types”, integers are of two categories - uint is unsigned (positive integers only, so they have no plus or minus signs) and int is signed (could be positive or negative, and if you wrote them down, they’d have a plus or minus sign).

Integer types can also specify how many bits long they are - or how many bits are used to represent the integer.

An uint8 is an integer represented by 8 binary digits (bits) and can store up to 256 different values (2^8=256). Since uint is for unsigned (positive) integers, this means it can store values from 0 to 255 (not including 1 to 256).

However when you have signed integers, like an int8, then one of the bits is used up to represent whether it's a positive or negative number. That means we have only 7 bits left, and so we can only represent up to 2^7 (128) different values, including 0. So an int8 can represent anything from -127 to +127.

By extension, an int256 is 256 bits long and can store +/- (2^255) values.

The bit lengths are multiples of 8 (because 8 bits makes a byte) so you can have int8, int16, int24 etc all the way to 256 (32 bytes).

Addresses refer to the Ethereum account types - either a smart contract account or an externally owned account (aka “EOA”. Your Metamask wallet represents an EOA). So an address is also a type in Solidity.

The default value of an address (that is the value it will have if you declare a variable of type address but don’t assign it any value) is 0x0000000000000000000000000000000000000000 which is also the result of this expression: address(0).

Booleans represent either true or false values. Finally, we have fixed size byte arrays like bytes1, bytes2 … bytes32. These are arrays of fixed length that contain bytes. All these types of values are copied when they’re passed around in the code.

For “reference types”, we have arrays, which can have a fixed size specified when they’re declared, or dynamically sized arrays, which start off with a fixed size, but can be “resized” as the number of data elements in the array grows.

Bytes are a low-level data type that refer to the data that is encoded into binary format. All data is eventually reduced to binary form by the compiler so that the EVM (or, in traditional computing, the processor) can work with it.

Storing and working with bytes is often faster and more efficient compared to other data types that are more human readable.

You may be wondering why I’ve not referred to strings in either types of data in the picture above. That’s because in Solidity, strings are actually dynamically-sized arrays, and the arrays store a sequence of bytes (just binary numbers) that are encoded in the UTF-8 encoding format.

They’re not a primitive in Solidity. In JavaScript they’re referred to as primitives, but even in JavaScript strings are similar (but not the same as) to arrays and are a sequence of integer values, encoded in UTF-16.

It is often more efficient to store a string as a bytes type in a smart contract, as converting between strings and bytes is quite easy. It is therefore useful to store strings as bytes but return them in functions as strings. You can see an example below:

Other than Solidity strings, the bytes data type is a dynamically sized byte array. Also, unlike its fixed-size byte array cousin, it's a reference type. The bytes type in Solidity is a shorthand for “array of bytes” and can be written in the program as bytes or byte[].

If you’re confused by bytes and byte arrays…I sympathise.

The underlying gory details of strings and byte arrays are not too relevant for this handbook. The important point for now is that some data types are passed by reference and others are passed by copying their values.

Suffice it to say that Solidity strings and bytes without a size specified are reference types because they’re both dynamically sized arrays.

Finally, among Solidity’s primitives, we have structs and mappings. Sometimes these are referred to as “composite” data types because they’re composed from other primitives.

A struct will define a piece of data as having one or more properties or attributes, and specifying each property’s data type and name. Structs give you the ability to define your own custom type so that you can organize and collect pieces of data into one larger data type.

For example you could have struct that defines a Person as follows:

You can instantiate or initialize a Person struct in the following ways:

Mappings are similar to hashtables, dictionaries or JavaScript objects and maps, but with a little less functionality.

A mapping is also a key-value pair, and there are restrictions on the kinds of data types you can have as keys, which you can read about here. The data types associated with a mapping’s keys can be any of primitives, structs, and even other mappings.

Here is how mappings are declared, initialized, written to and read from - the below example is from the Chainlink Link Token Smart Contract source code.

Declaring and using the Mappings type in Solidity

If you try to access a value using a key that doesn’t exist in the mapping, it will return the default value of the type that is stored in the mapping.

In the above example, the type of all values in the balances mapping is uint256, which has a default value of 0. So if we called balanceOf() and passed in an address that does not have any LINK tokens issued to it, we’d get a value of 0 back.

This is reasonable in this example, but it can be a bit tricky when we want to find out whether or not a key exists in a mapping.

Currently there is no way to enumerate what keys exist in a mapping (that is, there is nothing equivalent to JavaScript’s Object.keys() method). Retrieving using a key will only return the default value associated with the data type, which does not clearly tell us whether or not the key actually exists.

There is an interesting “gotcha” with mappings. Unlike other languages where you can pass key-value data structures as an argument to function, Solidity does not support passing mappings as arguments to functions except where the functions visibility is marked as internal. So you could not write an externally or publicly callable function that would accept key-value pairs as an argument.

How to Declare and Initialize Arrays in Solidity

Solidity comes with two flavors of arrays, so it is useful to understand the different ways in which they can be declared and initialized.

The two main types of arrays in Solidity are the fixed-size array and the dynamic-sized array.

To refresh your memory, fixed-size arrays are passed by value (copied when passed around in the code) and dynamic-sized arrays are passed by reference (a pointer to the memory address is passed around in the code).

They’re also different in their syntax and their capacity (size), which then dictates when we would use one versus the other.

Here’s what a fixed-size array looks like when declared and initialized. It has a fixed capacity of 6 elements, and this cannot be changed once declared. The memory space for an array of 6 elements is allocated and cannot change.

A fixed-size array can also be declared by just declaring a variable and the size of the array and the type of its elements with the following syntax:

Contrast that with a dynamically-sized array that is declared and initialized as follows. Its capacity is unspecific and you can add elements using the push() method:

You can also declare and initialize the value of an array in the same line of code.

These arrays are available in storage. But what if you needed only temporary in-memory arrays inside a function? In that case there are two rules: only fixed size arrays are allowed, and you must use the new keyword.

Clearly, there are several ways to declare and initialize arrays. When you’re wanting to optimize for gas and computations you want to carefully consider which type of arrays are required, what their capacity is, and if they’re likely to grow without an upper bound.

This also influences and is influenced by the design of your code - whether you need arrays in storage or whether you need them only in memory.

What are Function Modifiers?

When writing functions, we often receive inputs that need some sort of validation, checking, or other logic run on those inputs before we go ahead with the rest of the “business” logic.

For example, if you’re writing in pure JavaScript, you may want to check that your function receives integers and not strings. If it’s on the backend you may want to check that the POST request contained the right authentication headers and secrets.

In Solidity, we can perform these sort of validation steps by declaring a function-like block of code called a modifier.

A modifier is a snippet of code that can run automatically before or after you run the main function (that is, the function that has the modifier applied to it).

Modifiers can be inherited from parent contracts too. It is generally used as a way to avoid repeating your code, by extracting common functionality and putting it in a modifier that can be reused throughout the codebase.

A modifier looks a lot like a function. The key thing to observe about a modifier is where the _ (underscore) shows up. That underscore is like a “placeholder” to indicate when the main function will run. It reads as if we inserted the main function where the underscore is currently.

So in the modifier snippet below, we run the conditional check to make sure that the message sender is the owner of the contract, and then we run the rest of the function that called this modifier. Note that a single modifier can be used by any number of functions.

How function modifiers are written, and the role of the underscore symbol

In this example, the require() statement runs before the underscore (changeOwner()) and that’s the correct way to ensure that only the current owner can change who owns the contract.

If you switched the modifier’s lines and the require() statement came second, then the code in changeOwner() would run first. Only after that would the require() statement run, and that would be a pretty unfortunate bug!

Modifiers can take inputs too - you’d just pass the type and name of the input into a modifier.

Modifiers are a great way to package up snippets of logic that can be reused in various smart contracts that together power your dApp. Reusing logic makes your code easier to read, maintain and reason about – hence the principle DRY (Don’t Repeat Yourself).

Error Handling in Solidity - Require, Assert, Revert

Error handling in Solidity can be achieved through a few different keywords and operations.

The EVM will revert all changes to the blockchain’s state when there is an error In other words, when an exception is thrown, and it’s not caught in a try-catch block, the exception will “bubble up” the stack of methods that were called, and be returned to the user. All changes made to the blockchain state in the current call (and its sub-calls) get reversed.

There are some exceptions, in low-level functions like delegatecall, send, call, and so on, where an error will return the boolean false back to the caller, rather than bubble up an error.

As a developer there are three approaches you can take to handle and throw errors. You can use require(), assert() or revert().

A require statement evaluates a boolean condition you specify, and if false, it will throw an error with no data, or with a string that you provide:

We use require() to validate inputs, validate return values, and check other conditions before we proceed with our code logic.

In this example, if the function’s caller does not send at least 1 ether, the function will revert and throw an error with a string message: “you must pay me at least 1 ether!”.

The error string that you want returned is the second argument to the require() function, but it is optional. Without it, your code will throw an error with no data - which is not terribly helpful.

The good thing about a require() is that it will return gas that has not been used, but gas that was used before the require() statement will be lost. That’s why we use require() as early as possible.

An assert() function is quite similar to require() except that it throws an error with type Panic(uint256) rather than Error(string).

An assert is also used in slightly different situations– where a different type of guarding is required.

Most often you use an assert to check an “invariant” piece of data. In software development, an invariant is one or more pieces of data whose value never changes while the program is executing.

In the above code example, the contract is a tiny contract, and is not designed to receive or store any ether. Its design is meant to ensure that it always has a contract balance of zero, which is the invariant we test for with an assert.

Assert() calls are also used in internal functions. They test that local state does not hold unexpected or impossible values, but which may have changed due to the contract state becoming “dirty”.

Just as require() does, an assert() will also revert all changes. Prior to Solidity’s v0.8, assert() used to use up all remaining gas, which was different from require().

In general, you’d likely use require() more than assert().

A third approach is to use a revert() call. This is generally used in the same situation as a require() but where your conditional logic is much more complex.

In addition, you can throw custom-defined errors when using revert(). Using custom errors can often be cheaper in terms of gas used, and are generally more informative from a code and error readability point of view.

Note how I improve the readability and traceability of my error by prefixing my custom error’s name with the Contract name, so we know which contract threw the error.

In the above example, we use revert once with a custom error that takes two specific arguments, and then we use revert another time with only a string error data. In either case, the blockchain state is reverted and unused gas will be returned to the caller.

Inheritance in Solidity

Inheritance is a powerful concept in Object Oriented Programming (OOP). We won't go into the details of what OOP is here. But the best way to reason about inheritance in programming is to think of it as a way by which pieces of code “inherit” data and functions from other pieces of code by importing and embedding them.

Inheritance in Solidity also allows a developer to access, use and modify the properties (data) and functions (behaviour) of contracts that are inherited from.

The contract that receives this inherited material is called the derived contract, child contract or the subclass. The contract whose material is made available to one or more derived contracts is called a parent contract.

Inheritance facilitates convenient and extensive code reuse – imagine a chain of application code that inherits from other code, and those in turn inherit from others and so on. Rather than typing out the entire hierarchy of inheritance, we can just use a a few key words to “extend” the functions and data captured by all the application code in the inheritance chain. That way child contract gets the benefit of all parent contracts in its hierarchy, like genes that get inherited down each generation.

Unlike some programming languages like Java, Solidity allows for multiple inheritance. Multiple inheritance refers to the ability of a derived contract to inherit data and methods from more than one parent contract. In other words, one child contract can have multiple parents.

You can spot a child contract and identify its parent contract by looking for the is keyword.

If you were to deploy only Contract B using the in-browser Remix IDE you’d note that Contract B has access to the getName() method even though it was not ever written as part of Contract B. When you call that function, it returns “A” , which is data that is implemented in Contract A, not contract B. Contract B has access to both storage variables A_NAME and B_NAME, and all functions in Contract A.

This is how inheritance works. This is how Contract B reuses code already written in Contract A, which could have been written by someone else.

Solidity lets developers change how a function in the parent contract is implemented in the derived contract. Modifying or replacing the functionality of inherited code is referred to as “overriding”. To understand it, let’s explore what happens when Contract B tries to implement its own getName() function.

Modify the code by adding a getName() to Contract B. Make sure the function name and signature is identical to what is in Contract A. A child contract’s implementation of logic in the getName() function can be totally different from how it’s done in the parent contract, as long as the function name and its signature are identical.

The compiler will give you two errors:

1. In Contract A, it will indicate that you are “trying to override non-virtual function” and prompt you by asking if you forgot to add the virtual keyword.

2. In Contract B, it will complain that the getName() function is missing the override specifier.

This means that your new getName in Contract B is attempting to override a function by the same name in the parent contract, but the parent’s function is not marked as virtual – which means that it cannot be overridden.

You could change Contract A’s function and add virtual as follows:

Adding the keyword virtual does not change how the function operates in Contract A. And it does not require that inheriting contracts must re-implement or override it. It simply means that this function may be overridden by any derived contracts if the developer chooses.

Adding virtual fixes the compiler’s complaint for Contract A, but not for Contract B. This is because getName in Contract B needs to also add the override keyword as follows:

We also add the pure keyword for Contract B’s getName() as this function does not change the state of the blockchain, and reads from a constant (constants, you’ll remember, are hardcoded into the bytecode at compile time and are not in the storage data location).

Keep in mind that you only need to override a function if the name and the signature are identical.

But what happens with functions that have identical names but different arguments? When this happens it’s not an override, but an overload. And there is no conflict because the methods have different arguments, and so there is enough information in their signatures to show the compiler that they're different.

For example, in contract B we could have another getName() function that takes an argument, which effectively gives the function a different “signature” compared to the parent Contract A’s getName() implementation. Overloaded functions do not need any special keywords:

Don’t worry about the abi.encodepacked() method call. I’ll explain that later when we talk about encoding and decoding. For now just understand that encodepacked() encodes the strings into bytes and then concatenates them, and returns a bytes array.

We discussed the relationship between Solidity strings and bytes in a previous section of this handbook (under Typing).

Also, since you’ve already learned about function modifiers, this is a good place to add that modifiers are also inheritable. Here’s how you’d do it:

You might wonder which version of a function will be called if a function by the same name and signature exists in a chain of inheritance.

For example, let's say there is a chain of inherited contracts like A → B → C → D → E and all of them have a getName() that overrides a getName() in the previous parent contract.

Which getName() gets called? The answer is the last one – the “most derived” implementation in the contract hierarchy.

State variables in child contracts cannot have the same name and type as their parent contracts.

For example, Contract B below will not compile because its state variable “shadows” that of the parent Contract A. But note how Contract C correctly handles this:

It’s important to note that by passing a new value to the variable author in Contract C’s constructor, we are effectively overriding the value in Contract A. And then calling the inherited method C.getAuthor() will return ‘Hemingway’ and not ‘Zubin’!

It is also worth noting that when a contract inherits from one or more parent contract, only one single (combined) contract is created on the blockchain. The compiler effectively compiles all the other contracts and their parent contracts and so on up the entire hierarchy all into a single compiled contract (which is referred to as a “flattened” contract).

Inheritance with Constructor Parameters

Some constructors specify input parameters and so they need you to pass arguments to them when instantiating the smart contract.

If that smart contract is a parent contract, then its derived contracts must also pass arguments to instantiate the parent contracts.

There are two ways to pass arguments to parent contracts - either in the statement that lists the parent contracts, or directly in the constructor functions for each parent contract. You can see both approaches below:

In Method 2 in the ChildTwo contract, you’ll note that the arguments passed to the parent contracts are first supplied to the child contract and then just passed up the inheritance chain.

This is not necessary, but is a very common pattern. The key point is that where parent contract constructor functions expect data to be passed to them, we need to provide them when we instantiate the child contract.

Type Conversion and Type Casting in Solidity

Sometimes we need to convert one data type to another. When we do so we need to be very careful when converting data and how the converted data is understood by the computer.

As we saw in our discussion on typed data, JavaScript can sometimes do strange things to data because it is dynamically typed. But that’s also why it’s useful to introduce the concept of type casting and type conversions generally.

Take the following JavaScript code:

There are two ways of converting the variable a into an integer. The first, called type casting, is done explicitly by the programmer and usually involves a constructor-like operator that uses ().

Now let's reset a to a string and do an implicit conversion, also known as a type conversion. This is implicitly done by the compiler when the program is executed.

In Solidity, type casting (explicit conversion) is permissible between some types, and would look like this:

In this example we converted an integer with a size of 256 bits (since 8 bits makes 1 byte, this is 32 bytes) into a bytes array of size 32.

Since both the integer value of 2022 and the bytes value are of length 32 bytes, there was no “loss” of information in the conversion.

But what would happen if you tried to convert 256 bits into 8 bits (1 byte)? Try running the following in your browser-based Remix IDE:

Why does the integer 2022 get converted to 230? That’s clearly an undesirable and unexpected change in the value. A bug, right?

The reason is that an unsigned integer of size 256 bits will hold 256 binary digits (either 0 or 1). So a holds the integer value ‘2022’ and that value, in bits, will have 256 digits, of which most will be 0, except for the last 11 digits which will be... (see for yourself by converting 2022 from decimal system to binary here).

The value of b on the other hand will have only 8 bits or digits, being 11100110. This binary number, when converted to decimal (you can use the same converter - just fill in the other box!) is 230. Not 2022.

Oopsie.

So what happened? When we dropped the integer’s size from 256 bits to 8 bits we ended up shaving the first three digits of data (11111100110) which totally changed the value in binary!

This, folks, is information loss.

So when you’re explicitly casting, the compiler will let you do it in some cases. But you could lose data, and the compiler will assume you know what you’re doing because you’re explicitly asking to do it. This can be the source of many bugs, so make sure you test your code properly for expected results and be careful when explicitly casting data to smaller sizes.

Casting up to larger sizes does not result in data lost. Since 2022 needs only 11 bits to be represented, you could declare the variable a as type uint16 and then up-cast it to a variable b of type uint256 without data loss.

The other kind of casting that is problematic is when you’re casting from unsigned integers to signed integers. Play around with the following example:

Note that a , being a signed integer of size 16 bits holds -2022 as a (negative integer) value. If we explicitly type cast it to an unsigned integer (only positive) values, the compiler will let us do it.

But if you run the code, you’ll see that b is not -2022 but 63,514! Because uint cannot hold information regarding the minus sign, it has lost that data, and the resulting binary gets converted to a massive decimal (base 10) number - clearly undesirable, and a bug.

If you go further, and un-comment the line that assigns the value of c, you’ll see the compiler complain with 'Explicit type conversion not allowed from "int16" to "uint256"'. Even though we are up-casting to a larger number of bits in uint256, because c is an unsigned integer, it cannot hold minus sign information.

So when explicitly casting, be sure to think through what the value will evaluate to after you’ve forced the compiler to change the type of the data. It is the source of many bugs and code errors.

There is more to Solidity type conversions and type casting and you can go deep into some of the nitty gritty in this article.

How to Work with Floating Point Numbers in Solidity

Solidity doesn’t handle decimal points. That may change in the future, but currently you cannot really work with fixed (floating) point numbers like 93.6. In fact typing int256 floating = 93.6; in your Remix IDE will throw an error like : Error: Type rational_const 468 / 5 is not implicitly convertible to expected type int256.

What’s going on here? 468 divided by 5 is 93.6, which seems a weird error, but that’s basically the compiler saying it cannot handle floating point numbers.

Follow the suggestions of the error, and declare the variable’s type to be fixed or ufixed16x1.

You’ll get an “UnimplementedFeatureError: Not yet implemented - FixedPointType” error.

So in Solidity, we get around this by converting the floating point number to a whole number (no decimal points) by multiplying by 10 raised to the exponent of the number of decimal places to the right of the decimal point.

In this case we multiply 93.6 by 10 to get 936 and we have to keep track of our factor (10) in a variable somewhere. If the number was 93.2355 we would multiply it by 10 to the power 4 as we need to shift the decimal 4 places to the right to make the number whole.

When working with ERC tokens we will note that the decimal places are often 10, 12, or 18.

For example, 1 Ether is 1*(10^18) wei, which is 1 followed by 18 zeros. If we wanted that expressed with a floating point, we would need to divide 1000000000000000000 by 10^18 (which will give us 1), but if it was 1500000000000000000 wei, then dividing by 10^18 will throw a compiler error in Solidity, because it cannot handle the return value of 1.5.

In scientific notation, 10^18 is also expressed as 1e18, where 1e represents 10 and the number after that represents the exponent that 1e is raised to.

So the following code will produce a compiler error: “Return argument type rational_const 3 / 2 is not implicitly convertible to expected type…int256”:

The result of the above division operation is 1.5, but that has a decimal point which Solidity does not currently support. Thus Solidity smart contracts return very big numbers, often up to 18 decimal places, which is more than JavaScript can handle. So you'll need to handle that appropriately in your front end using JavaScript libraries like Ethersjs that implement helper functions for the BigNumber type.

Hashing, ABI Encoding and Decoding

As you work more with Solidity, you’ll see some strange-sounding terms like hashing, ABI encoding, and ABI decoding.

While these can take some effort to wrap your head around, they’re quite fundamental to working with cryptographic technology, and Ethereum in particular. They’re not complex in principle, but can be a bit hard to grasp at first.

Let’s start with hashing. Using cryptographic math, you can convert any data into a (very large) unique integer. This operation is called hashing. There are some key properties to hashing algorithms:

1. They’re deterministic - identical inputs will always produce an identical output, each time and every time. But the chance of producing the same output using different inputs is extremely unlikely.

2. It is not possible (or computationally infeasible) to reverse engineer the input if you only have the output. It is a one-way process.

3. The output’s size (length) is fixed - the algorithm will produce fixed-size outputs for all inputs, regardless of the input size. In other words the outputs of a hashing algorithm will always have a fixed number of bits, depending on the algorithm.

There are many algorithms that are industry-standard for hashing but you’ll likely see SHA256 and Keccak256 most commonly. These are very similar. And the 256 refers to the size - the number of bits in the hash that is produced.

For example, go to this site and copy and paste “FreeCodeCamp” into the text input. Using the Keccak256 algorithm, the output will (always) be 796457686bfec5f60e84447d256aba53edb09fb2015bea86eb27f76e9102b67a.

This is a 64 character hexadecimal string, and since each character in a hex string represents 4 bits, this hexadecimal string is 256 bits (32 bytes long).

Now, delete everything in the text input box except the “F”. The result is a totally different hex string, but it still has 64 characters. This is the “fixed-size” nature of the Keccak265 hashing algorithm.

Now paste back the “FreeCodeCamp” and change any character at all. You could make the “F” lowercase. Or add a space. For each individual change you make, the hash hex string output changes a lot, but the size is constant.

This is an important benefit from hashing algorithms. The slightest change changes the hash substantially. Which means you can always test whether two things are identical (or have not been tampered with at all) by comparing their hashes.

In Solidity, comparing hashes is much more efficient than comparing the primitive data types.

For example, comparing two strings is often done by comparing the hashes of their ABI-encoded (bytes) form. A common helper function to compare two strings in Solidity would look like this:

We’ll address what ABI encoding is in a moment, but note how the result of encodePacked() is a bytes array which is then hashed using the keccak256 algorithm (this is the native hashing algorithm used by Solidity). The hashed outputs (256 bit integers) are compared for equality.

Now let's turn to ABI encoding. First, we recall that ABI (Application Binary Interface) is the interface that specifies how to interact with a deployed smart contract. ABI-encoding is the process of converting a given element from the ABI into bytes so that the EVM can process it.

The EVM runs computation on bits and bytes. So encoding is the process of converting structured input data into bytes so that a computer can operate on it. Decoding is the reverse process of converting bytes back into structured data. Sometimes, encoding is also referred to as “serializing”.

You can read more about the solidity built-in methods provided with the global variable abi that do different types of encoding and decoding here. Methods that encode data convert them to byte arrays (bytes data type). In reverse, methods that decode their inputs expect the bytes data type as input and then convert that into the data types that were encoded.

You can observe this in the following snippet:

I ran the above in Remix, and used the following inputs for encode(): 1981, 0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC, [1,2,3,4].

And the bytes I got returned were represented in hexadecimal form as the following:

0x00000000000000000000000000000000000000000000000000000000000007bd0000000000000000000000003c44cdddb6a900fa2b585dd299e03d12fa4293bc000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000030000000000000000000000000000000000000000000000000000000000000004

I fed this as my input into the decode() function and got my original three arguments back.

Thus, the purpose of encoding is to convert data into the bytes data type that the EVM needs to process data. And decoding brings it back into the human readable structured data that we developers can work with.

How to Call Contracts and Use the Fallback Function

Depending on the design of the smart contract and the visibility specifiers present in it, the contract can be interacted with by other smart contracts or by externally owned accounts.

Calling from your wallet via Remix is an example of the latter, as is using Metamask. You can also interact with smart contracts programmatically via libraries like EthersJS and Web3JS, the Hardhat and Truffle toolchains, and so on.

For the purposes of this Solidity handbook, we will use Solidity to interact with another contract.

There are two ways for a smart contract to call other smart contracts. The first way calls the target contract directly, by using interfaces (which we discussed previously). Or, if the Target contract is imported into the scope of the calling contract, it directly calls it.

This approach is illustrated below:

In Remix you can deploy Target first, and call count() to see that the default value for the count variable is 0, as expected. This value will be decremented by 1 if you call the decrement() method.

Then you can deploy TargetCaller and there are two methods you can call, both of which will decrement the value of count in Target.

Note that each of these two methods access the Target contract using a slightly different syntax. When interacting by using the ITarget interface, the first method takes in Target’s address whereas the second method treats Target as a custom type.

This second approach is only possible when the Target contract is declared in, or imported into, the same file as the TargetCaller. Most often, you will interact with smart contracts deployed by third parties, for which they publish ABI interfaces.

Each time you call these methods, the value of count in Target will decrease by 1. This is a very common way to interact with other smart contracts.

The second way to do it is by using the “low level” call syntax that Solidity provides. You use this when you also want to send some ether (value) to the target contract. Will talk about sending value in the next section, but for now just replace the code in Remix with the following:

You’ll note that decrement() now takes an argument, and the interface and the Target contract are updated with this new input data.

Next note that TargetCaller implements a new function that calls decrement() with a new syntax, explained below.

In the next section we will see examples of these low level ways of calling a target smart contract to send Ether to it.

But what happens when you call a contract and it doesn’t actually have the function you tried to call?

This can happen maliciously to exploit how Solidity works on the EVM. Or, more commonly, it can happen accidentally. This occurs when, for example, there is an error in the Interface and the compiler cannot match the function and parameters you sent with any that are actually contained in the contract. What happens then?

For these situations, many contracts employ a special function called the fallback function. The function looks like a normal function but it doesn’t need the function keyword. If you want it to also handle situations where your contract is sent some ether, you must also mark it payable. But this is not the recommended way to enable your contract to receive payments.

Let’s take a look by repurposing our previous Target, ITarget and TargetCaller and adding a fallback function as follows:

Once we deploy a fresh instance of Target, we can call count() and see that it is set to the default value of zero.

Next we can deploy TargetCaller and call the callFallback() method which internally calls nonExistentFunction().

It’s worth noting that the interface says that nonExistentFunction() is available but the actual Target contract does not have any such function. This is why the Target fallback function gets triggered and the value of count is now incremented by 1.

The purpose of the fallback function is to handle calls to the contract where no other function is available to handle it. And if the fallback is marked payable, the fallback function will also enable the smart contract to receive Ether (though that is not the recommended use for fallback). We will cover this in the next section.

How to Send and Receive Ether

To send Ether to a target contract from your smart contract, you need to call the target contract using one of the following three in-built Solidity methods: transfer, send or call.

transfer will throw an exception when it fails, and send and call will return a boolean that you must check before proceeding. Of these three, transfer and send are no longer recommended for security reasons, though you can still use them and they'll work.

Smart Contracts cannot receive Ether except in the following scenarios:

• They implement a payable fallback or payable receive special function, or

• Forcibly when the calling contract calls selfdestruct and forces a target contract to accept all its remaining ether. The calling contract is then deleted from the blockchain. This is a separate topic and is often used maliciously by exploiters.

It is generally recommended that you use a receive() function if you want your smart contract to receive Ether. You can get away by just making your fallback function payable, but recommended practice is to use a receive() function instead.

If you rely only on the fallback function, your compiler will grumble at you with the following message: “Warning: This contract has a payable fallback function, but no receive ether function. Consider adding a receive ether function.”

If you have both receive and fallback, you may legitimately wonder how Solidity decides which function to receive Ether with. This design decision also tells you what these functions are designed to do.

Receive is meant to receive ether. And fallback is meant to handle situations where the contract has been called but, as we discussed in the previous section, there is no matching method in the contract that can handle the call.

Solidity matches the method that was intended to be called by checking the msg.data field in the transaction sent by the caller. If that field is a non-empty value, and that value does not match any other function declared in the called contract, then the fallback method is triggered.

If msg.data is empty, then it will check if there is a receive function that has been implemented. If so, it will use that to accept the Ether. If no receive exists, it will default to the fallback function. The fallback is therefore the...fallback (default) method when nothing else makes sense.

The receive function is the better way to enable your contract to receive Ether. You can use the fallback function for any scenario where your smart contract is called but there is nothing to “handle” that call.

Here is a super handy logic tree that shows what receive and fallback are intended to handle.

(credit: Solidity By Example)

Going back to our example where we explored the fallback function, we can add a receive function to Target as follows:

We already saw how callFallback will change the count value in Target. But if we deploy a fresh instance of Target, we can now send it 10 wei, as shown below, because it now has a payable receive function. Prior to sending 10 wei (or any other amount) Target has a balance of zero, as shown below.

Hitting the Transact button with empty calldata (msg.data) will change the balance as shown in the image below. We can check count to see that it is incremented by 5, which is the logic in the receive function.

Sending Wei to the Target Contract and observing the updated balance

If we call callFallback and give it the address of the new Target instance, we will note that it increments only by 1. If we include some wei, that will increase the balance of Target as well.

So any transfer of Ether to a smart contract would require the receiving smart contract to have payable functions that can receive it. At the very minimum, the receiving smart contract would need a payable fallback function, though a payable receive function is the better approach for receiving Ether payments.

Solidity Libraries

In any programming language, a library refers to a collection of helper and utility functions that are designed to be reusable across multiple code bases. These functions solve specific, recurring programming problems.

In Solidity, libraries serve the same purpose, but have some special attributes.

First, they are stateless - that is, they don't store data (other than constants because these do not change the blockchain’s state). They also can't receive value (which means they cannot have payable receive or fallback functions).

They also cannot inherit from other contracts or libraries, nor can libraries have child (derived) contracts.

All functions declared in a library must not be abstract - that is, they must all have concrete implementations.

Since Solidity libraries are stateless, none of the methods in them can modify the blockchain’s state. This means all methods inside libraries are pure or view functions.

Another interesting attribute of Solidity libraries is that they don't need to be imported into your smart contract. They can be deployed as standalone contracts and then called via their interface in all consuming smart contracts - just as you would an API service in the traditional engineering world.

However, this is true only where the library contains public or external methods. Then that library can be deployed as a standalone contract with its own Ethereum address, and becomes callable to all consuming smart contracts.

If the libraries contain only internal methods, then the EVM simply “embeds” the library code into the smart contract that uses the library (because internal functions cannot be accessed from other smart contracts).

Libraries in Solidity have advantages that go beyond code reuse. Deploying a library one time on the blockchain can save on future gas costs by avoiding repeated deployment or importing of the library's code.

Let's look at a simple library and then dissect the code to understand how to use the library’s code.

This library has two methods that operate on the int data type. The first argument is called self for reasons that will become clear shortly. One method takes a number and then multiplies it by a constant value that is stored in the library’s code. The second method takes in two numbers and adds them.

Now let’s see how we can use this in a consuming smart contract.

The first thing to note is that there are two ways of using the WeirdMath library.

You can use it by either:

1. Invoking the library’s name followed by the function you want to call, or

2. calling the function directly on the data type you want the function to operate on. This data type must be identical to the type of the self parameter in the library’s function.

The first approach is demonstrated by method 1 in the code snippet where we invoke the library with WeirdMath.add(num1, num2);.

The second approach uses the Solidity using keyword. The expression return num1.add(num2); applies the WeirdMath library’s add function to the num1 variable. This is the same as passing it in as self, which is the first argument to the add function.

Events and Logs in Solidity

Smart Contracts can emit events. The events contain pieces of data that you the developer specify.

Events cannot be consumed by other smart contracts. Instead, they are stored on the blockchain as logs, and can be retrieved via the APIs that read from the blockchain.

This means that your application (most commonly your front end application) can “read” logs that contain the event’s data from the blockchain. In this way your user interface can respond to events on the blockchain.

This is how application user interfaces are updated to respond to on-chain events. Since these logs on the blockchain can be queried, logs are a cheap form of storage, as discussed previously in the discussion on storage areas.

Events emitted by a Smart Contract can be inspected using the relevant blockchain explorer, because everything on a public blockchain is publicly viewable. But if the smart contract’s bytecode has not been verified, the event data may not be human readable (it will be encoded). The events of verified smart contracts will be human readable.

Nodes and other blockchain clients can listen for (subscribe to) specific events. At the heart of it, this is how Chainlink Oracles work - decentralized oracle nodes listen to events from smart contracts, and then respond accordingly. They can even pull data off from events, run complex and resource-intensive computations off-chain, and then submit cryptographically verifiable computation results back onto the blockchain.

Other network APIs and indexing services like subgraphs are made possible because of the ability to query blockchain data via the events emitted by smart contracts.

Here is what an Event looks like in Solidity:

An event is first declared, and its arguments and their data types are specified. Any piece of data that has the indexed keyword is indexed by the EVM so that queries on blockchain logs can use the indexed param as a filter. This makes retrieving logs faster.

An event can store up to 4 indexed parameters - depending on whether it is anonymous or non-anonymous. Indexed event parameters are also referred to as “Topics” in the Solidity world.

Most events are non-anonymous, meaning that they include data on the name and arguments of the Event.

Non-anonymous events allow the developer to specify only 3 topics because the first topic is reserved to specify the Event signature in ABI-encoded hexadecimal form. You can read more about anonymous and non-anonymous topics here.

You can also explore Events on the relevant blockchain explorer (like etherscan.io).

You can approach this from one of two entry points. You can look at the contract’s address directly and then go to the Events Tab (which will show you events emitted by that contract only). Or you can go to a transaction hash and examine all the events emitted by all contracts that were touched by that transaction.

For example, below is a screenshot of the Chainlink VRF Coordinator smart contract’s events on Ethereum mainnet.

Inspecting the Chainlink VRF Coordinator Contract's events on etherscan

The contract tab has a green tick mark which means the contract is verified, and so the Event name and arguments are human readable. Take a moment to study this image as it contains a lot of information! If you’d like to study it directly on etherscan, click here.

This Chainlink VRF Coordinator contract responds to requests for cryptographically verifiable random numbers, and supplies the asking smart contract with random numbers (referred to as “random words”).

If you want to learn what the computer science meaning of “word” is, check out my colleague and I addressing this question in this Chainlink 2022 Hackathon video).

When the VRF Coordinator contract fulfills the request for random numbers, it emits a RandomWordsFulfilled event. That event contains 4 pieces of data, of which the first one, requestID, is indexed.

Solidity events contain three categories of data:

1. The address of the contract that emitted the event.

2. The topics (indexed event parameters used for filtering queries of the logs).

3. Non-indexed parameters, referred to as “data”, and they are ABI-encoded and represented in hexadecimal. This data needs to be ABI-decoded, in the way described in the section on ABI encoding and decoding.

When working in Remix you can also inspect the Events in the console as shown below:

Inspecting Event data in the Remix Browser IDE

You can also programmatically access the events using the contract receipts object in EthersJS. Using the code snippet we used above in the SimpleStorage contract, we can access the events using EthersJS and Hardhat using the following JavaScript:

You can also use libraries such as the EtherJs library in your front end application to listen to events and filter historical events. Both of these are useful when your application needs to respond to events on the blockchain.

Time Logic in Solidity

Time in Solidity is specified in relation to each block that gets added to the blockchain.

The global variable block.timestamp refers to the time, in milliseconds, when the block was generated and added to the blockchain. The milliseconds count refers to the number of milliseconds that have passed since the beginning of the Unix Epoch (in computing, this is 1 January 1970).

Unlike Web2 references to timestamps in milliseconds, the value may not increment with every millisecond.

A block often contains several transactions, and since block.timestamp refers to the time at which the block was mined, all transactions in a mined block will have the same timestamp value. So the timestamp really refers to the block’s time, and not so much as to when the caller may have initiated the transaction.

Solidity supports directly referring to the following units of time: seconds, minutes, hours, days, and weeks.

So we could do something like uint lastWeek = block.timestamp - 1 weeks; to calculate the timestamp of exactly 1 week before this current block was mined, down to milliseconds. That value would be the same as block.timestamp - 7 days;.

You can also use this to calculate future expiry dates, where, for example, you may want an operation to be possible between now and next week. You could do this with uint registrationDeadline = block.timestamp + 1 weeks; and then we could use the registrationDeadline as a validation or guard in a function as follows:

In this function we register the voter only if the current block’s timestamp is not past the registration deadline.

This logic is used extensively when we want to make sure certain operations are performed at the right time, or within an interval.

This is also one of the ways in which Chainlink Automation, a decentralized way to automate the execution of your smart contract, can be configured. The Chainlink decentralized oracle network can be configured to automatically trigger your smart contracts, and you can run a wide variety of automations by checking conditions, including time related conditions. These are used extensively for airdrops, promotions, special rewards, earn-outs and so on.

Conclusion and Further Resources

Congrats! You made it through this epic journey. If you’ve invested the time digesting this handbook, and run some of the code in the Remix IDE, you are now trained in Solidity.

From here on, it’s a question of practice, repetition and experience. As you go about building your next awesome decentralized application, remember to revisit the basics and focus on security. Security is especially important in the Web3 space.

You can get good information on best practices from OpenZeppelin’s blogs and the Trail of Bits resources, amongst others.

You can also get more practical hands on experience by doing the full end-to-end full-stack blockchain developer course that my colleague Patrick Collins published on freeCodeCamp (it’s free!).

There are other resources like blockchain.education and freeCodeCamp’s own upcoming Web3 curriculum that can consolidate your learnings.

In any event, this handbook can be your “desktop companion” for that quick refresh on basic concepts, regardless of what level of experience you’re at.

The important thing to remember is that Web3 technology is always evolving. There is a crying need for developers willing to tackle complex challenges, learn new skills, and solve important problems that come with decentralized architecture.

That could (and should) be you! So just follow your curiosity and don’t be afraid to struggle along the way.

And once again, I intend to keep this handbook updated. So if you see anything that’s not quite right, is outdated, or unclear, just mention it in a tweet and tag me and freeCodeCamp - a big shout out to you all for being part of keeping this handbook fresh.

Now…go be awesome!

Post Script

If you are serious about a career change to code, you can learn more about my journey from lawyer to software engineer. Check out episode 53 of the freeCodeCamp podcast and also Episode 207 of "Lessons from a Quitter". These provide the blueprint for my career change.

If you are interested in changing your career and becoming a professional coder, please reach out here. You can also check out my free webinar on Career Change to Code if that is what you're dreaming of.

The first time I tried to learn blockchain development, I felt overwhelmed.

This tutorial you're reading is what I wish I could send back in time to myself.

This will give you a strong foundation in blockchain development, and set you up for success in coding your own smart contracts.

In in addition to my explanation and code examples, I've included lots of videos you can use to supplement your learning.

Prerequisites

This tutorial assumes that you understand some foundational coding concepts. One of these that will be particularly helpful is the concept of object-oriented programming (OOP).

What is Blockchain?

The Blockchain is a network of transactions or assets called blocks where every block is connected to the others. Everyone here has equal access to the data circulating within the network.

You can see blockchain as a document that holds the details of transactions made by a group of people where everyone has a copy. Everyone must agree upon any updates before they are accepted.

Anyone who tries to mutilate their document without the others' consent is seen as fraudulent and will suffer predefined consequences.

For example, imagine that a group of friends (Njoku, Samson, and Ebere) decides to start a peer-to-peer savings account that must run for a certain period before a withdrawal is possible. The three agree that no one will be the boss, and each person will have equal access to the account to ensure trust. So they open an account.

Each time one of them deposits money, everyone gets a new account history document emailed to them. Whenever they decide to add a new member, the person becomes part of the signatories and gets a copy of the account history.

Everyone must consent before a withdrawal happens outside the proposed date. Not following these terms will incur consequences such as losing all of a person’s savings or leaving the association after paying a fine.

Blockchain is known as a decentralized technology since data and authority are shared equally among everybody in the network. It differs from centralized applications where the company owns the data, and the consumers just hope their data isn’t misused.

Examples of decentralized applications include Bitcoin and Ethereum, while centralized applications include Facebook and Google.

Blockchain technology falls under the category of Web 3 simply because it is the third phase of the internet in which users can read, write, and own data. Web 1 was the stage where users could only read data. Web 2 emerged sometime around the early 2000s and is the phase in which users can read and write data.

How Blockchain Works

In this section, I will explain what happens in a blockchain application behind the scenes.

We will begin by looking at how it works in theory and then how we can replicate it using a programming language that many devs already know – JavaScript.

Theory Behind the Blockchain

A blockchain is a connection of many blocks. So it begins with one block called the genesis block. Among other things, a block contains a hash, the previous block hash, and at least one transaction.

Every block in the blockchain keeps a record of its hash and the previous block’s hash to keep the network safe from hackers.

This implies that for a hacker to gain access and break the network, they need to generate the hashes and match them to the right block without breaking other blocks. Now that sounds really stressful and almost impossible. That is how secure blockchains are.

Next, any user on the network can perform at least one transaction. If the user has completed a set of transactions they need at a time, they can use those transactions to create a block. The block may now be added to the others.

The whole process of adding a new block is known as mining. The process secures and verifies the transactions contained in a block.

The hash of a block gets generated when mining. The process of calculating the hash is known as proof of work.

Blockchain in Practice

Let's use some JavaScript object-oriented programming to demonstrate how blockchain works. We are using the OOP method because blockchain programming uses the same pattern.

But before we start building, let's learn how to generate the hash for every block in a blockchain.

How to generate a block's hash

There are a lot of libraries for generating a block's hash. But we will use the SHA256 library for this tutorial. SHA256 is the most popular and is used by many renowned companies.

The SHA256 library takes any data given to it and returns a 64-character long string. Every string passed to the SHA256 library will always return the same 64-character long string every time.

You can check out https://emn178.github.io/online-tools/sha256.html and play around with the UI to see how it works.

Blockchains do not use just any hash generated because of security reasons. It specifies what the first few characters must look like for the hash to be accepted. This means that the hash will have to be generated several times, and a record of what changes on each iteration will be kept for reference purposes.

For example, a blockchain may specify that the only acceptable hash must contain three zeros at the beginning.

To calculate the hash, we need to add a number known as a nonce to the string being hashed. The nonce usually starts from zero and is incremented every time the hash is generated until a hash beginning with three zeros is found. Then the hash and the nonce will be stored for reference purposes.

The code below will calculate the hash for "man":

SHA256("man").toString()

However, we may run the function several times to get a string with three zeros at the beginning. Since the function will always return the same result, we need to add a number to the string and increment it until we get the hash we want.

The code we'd use for that will look like this:

let hash = "";
let nonce = 0;

while (hash.substring(0, 3) !== "000") {
  nonce++;
  hash = SHA256("man" + nonce).toString();
}

console.log(nonce);
console.log(hash);

This code will produce 000d6575d4670dae39df9944e54c27dc4837beab1db23e2de264a7c1a3f38b1a after 5707 times instead of 48b676e2b107da679512b793d5fd4cc4329f0c7c17a97cf6e0e3d1005b600b03.

This level of security measures taken to build blockchain applications makes them very reliable and acceptable.

Now that we understand how a hash is generated in blockchain, let's get back to demonstrating how blockchain works.

How Blockchain Works Using JavaScript

First, create a directory called intro_to_blockchain. Then open the directory in a terminal.

Run the following command and hit enter for all the prompts to initialize the project:

npm init

Create 2 files: blockchain.js and test.js:

touch blockchain.js test.js

We will use the blockchain.js file to write the code that emulates how blockchain works and use test.js to test the code and see the result.

In the blockchain.js, enter the following code:

class Blockchain {
    constructor () {
        this.chain = [this.createGenesisBlock()];
        this.pendingTransactions = [];    
    }
}

The code above declares a class named Blockchain. The constructor function is used to initialize the chain and pendingTransactions array.

The chain array will contain every block or group of transactions added to the network. The pendingTransactions array will hold all transactions that have not been added to a block.

Remember that a blockchain starts with a genesis block. That is why the chain array is initialized with an array containing a function that creates the genesis block. You may hardcode the genesis block into the chain array, too.

We now need to build the createGenesisBlock function. Use the code below:

  createGenesisBlock() {
    return {
      index: 1,
      timestamp: Date.now(),
      transactions: [],
      nonce: 0,
      hash: "hash",
      previousBlockHash: "previousBlockHash",
    };
  }

The function will only execute once because the constructor function runs only once – at the beginning of the program.

It is also the only time a random uncalculated hash or previousBlockHash is used because it is the first block in the chain and does not carry any transactions.

The next thing to do is to make a function to get the last block. Use the code below:

  getLastBlock() {
    return this.chain[this.chain.length - 1];
  };

This code will enable us to access the details of the most recent block added. Remember that we need to keep track of the previous block's hash.

Let's now add the code to calculate the hash of a block.

generateHash(previousBlockHash, timestamp, pendingTransactions) {
    let hash = "";
    let nonce = 0;

    while (hash.substring(0, 3) !== "000") {
      nonce++;
      hash = SHA256(
        previousBlockHash +
          timestamp +
          JSON.stringify(pendingTransactions) +
          nonce
      ).toString();
    }

    return { hash, nonce };
  }

To ensure that this works, install the SHA256 library using the following command:

npm i sha256

Import it at the top of your blockchain.js file like this:

const SHA256 = require("sha256");

We will now add a function that creates our transactions and adds them to the list of pending transactions. Enter the following code:

  createNewTransaction(amount, sender, recipient) {
    const newTransaction = {
      amount,
      sender,
      recipient,
    };

    this.pendingTransactions.push(newTransaction);
  }

The time has now arrived for us to build the last function – createNewBlock. It will enable us to add the pending transactions to a block, calculate the hash, and add the block to the chain. Type the code below:

  createNewBlock() {
    const timestamp = Date.now();
    const transactions = this.pendingTransactions;
    const previousBlockHash = this.getLastBlock().hash;
    const generateHash = this.generateHash(
      previousBlockHash,
      timestamp,
      transactions
    );

    const newBlock = {
      index: this.chain.length + 1,
      timestamp,
      transactions,
      nonce: generateHash.nonce,
      hash: generateHash.hash,
      previousBlockHash,
    };

    this.pendingTransactions = [];
    this.chain.push(newBlock);

    return newBlock;
  }

The code above uses the getLastBlock function to access the previous block's hash. It calculates the hash of the current block, adds all the detail of the new block in an object, clears the pendingTransactions array, and pushes the new block into the chain.

Let's export the Blockchain class to be able to access it outside the file:

module.exports = Blockchain;

How to Test the Code

We want to test the code we have written so far and see if it works as expected. We will navigate to the test.js file and begin by importing the Blockchain class that we exported a moment ago like this:

const Blockchain = require("./blockchain");

Now that we have the class here, we can make an instance of it and name it bitcoin:

let bitcoin = new Blockchain();

You may call it whatever you see fit, but I will use bitcoin because it is popular.

Let's now see what we have in bitcoin by default. To do that, we will log it to the console like this:

console.log(bitcoin);

We will now open the project in a terminal and run the following command:

node test

It should output the following:

Default Output

In the output above, we have the chain array containing the genesis block and the pendingTransactions array containing nothing.

You will recall that the constructor function contains all those data and it runs once at the beginning of the program.

To add a new transaction, use the code below:

bitcoin.createNewTransaction(
  "100",
  "0xBcd4042DE499D14e55001CcbB24a551F3b954096",
  "0xa0Ee7A142d267C1f36714E4a8F75612F20a79720"
);

The first parameter is the amount, the second is the sender, and the third is the recipient just as we specified while creating the function.

If you run node test again, you should have one item in the pendingTransactions array like this:

One pending transaction added

To create or mine a block, enter the following code:

bitcoin.createNewBlock();

You should get the output below this time:

You will notice that there are now two (2) blocks in the chain and no more transactions in the pendingTransactions array.

Some things to note in the second block are the nonce and the hash. The nonce is 1404. That means it took 1404 iterations to get the correct hash for this block.

To see the transactions in the second block, we use the following code:

console.log("\n");
console.log("Second Block Transactions", bitcoin.chain[1].transactions);

Now we have the result below:

That looks good! It shows that all our functions work as intended. And that is what goes on behind the scenes of many blockchain applications.

You've just learned how blockchain works. But you shouldn’t build a blockchain application solely on this program idea. There is much more to learn to enable you to build real-world DApp. Still, what we have done so far will help you dive more into learning web3.

One of the things you need to learn is a blockchain programming language such as Solidity and other blockchain frontend libraries such as Web3js and Etherjs.

I'll now introduce you to smart contracts using Solidity.

How to Write a Smart Contract

In this section, we will cover all you need to know about smart contracts and the Solidity programming language.

What is a Smart Contract?

A smart contract is a program stored on the blockchain. It holds certain conditions that must be met before it executes.

Smart contracts take after traditional contracts. But they're different because they are run by a computer automatically when the predefined terms are met.

What is Solidity?

Solidity is the main programming language used to build most smart contracts because it is specifically designed for that purpose. It follows the OOP pattern that we demonstrated using JavaScript and borrows the typed nature of TypeScript. So while some syntax might differ from what you already know, it is not too far-fetched to grasp.

We will be learning the basics of Solidity by using it to build a smart contract that enables users to send funds to each other.

Don't worry, you will not have to set up another project. We will use the remix playground to do everything – write the code, compile, debug, and test.

Let's now head over to https://remix.ethereum.org/. You should have the following screen stare at you for a while:

Remix welcome page

Remix is getting everything ready for you. Just be patient 😊

When it's done, you should have the following screen:

This playground provides us with all we need to write our first smart contract.

Let's start by deleting the file created for us by default. To do that, click on the first icon below the remix logo.

Right-click on the file name in the explorer section and select delete:

Click OK in the pop-up menu.

We will now create a new file named Blockchain.sol by clicking the document icon marked red in the image below and type the name of the file in the space provided:

.sol is the extension used for solidity files. The blank space is where we will type our code.

Solidity code always begins with the line below:

// SPDX-License-Identifier: UNLICENSED

Without this code, you will get an error. It is just like saying that you accept the terms and conditions of writing Solidity.

The next thing to do is to state the Solidity version you want to use. I will use the following code:

pragma solidity ^0.8.7;

The caret (^) sign indicates that the program will be compatible with higher versions of solidity. We can now start the program.

The first thing to do is to define a Class named Blockchain. However, the keyword for Class in solidity is contract. So we have:

contract Blockchain {

}

Inside the contract above, we will create a data-type called BlockStruck with the code below:

struct BlockStruck {
    uint256 index;
    uint256 timestamp;
    uint256 amount;
    address sender;
    address recipient;
}

Solidity allows us to create any data-type that we see fit using the struct keyword, which is short for structure.

We define all the keys we expect a value for in the struct. Since solidity is a strongly typed language, we specified a data-type before each key. The struct is similar to Object in JavaScript.

uint indicates that a variable is an integer. Adding a number after it (such as uint256 or uint18) specifies the maximum size it should take, but uint assumes uint256 by default.

address, on the other hand, indicates that a variable is a wallet address. There is also the string data-type.

The next thing that we want to define is an event. An event is usually triggered at the end of a function's execution to send data to the frontend. You can see it like console.log. Some people also use it as a cheap way of storage.

We want to define a BlockEvent that we will trigger after adding a block to the chain. Enter the following code below the BlockStruct:

event BlockEvent(uint256 amount, address sender, address recipient);

Unlike struct, circular braces are used for an event, and their keys are separated by commas (,). Also, notice that struct does not end with a semicolon, but event does.

Now that we have defined the structure of blocks, let's use it to setup an array of blocks called chain like this:

BlockStruck[] chain;

The code above defines the chain to be an array of BlockStruct. As always, we specify the data-type before the variable name.

Next, define a variable to keep track of how many blocks are in the chain:

uint256 chainCount;

You may choose to assign it a value on the same line (uint256 chainCount = 0;) or do it in the constructor function like this:

constructor() {
    chainCount = 0;
}

We will now define three (3) functions: addBlockToChain (to add blocks to the chain), getChain (to return all the blocks added to the chain), and getChainCount (to get the number of blocks added to the chain).

addBlockToChain function

The code below begins the function:

function addBlockToChain(uint256 amount, address payable recipient) public {

}

Like the functions you already know, it begins with the function keyword followed by the name of the function, and the argument it expects in braces.

One of the arguments (recipient) has a flag called payable, indicating that the wallet address is eligible to receive funds. Next to it is the function's visibility flag (public).

Visibility defines who can call a function or variable. It can be public, private, internal, or external.

1. A public function can be called by any contract.
2. private functions can only be called inside the contract where they are defined.
3. Only contracts that inherit internal functions can call them.
4. external functions are only accessible by other contracts.

In the addBlockToChain, we start by incrementing the chainCount by one like this:

chainCount += 1;

Next, add the block of a transaction to the chain like this:

        chain.push(
            BlockStruck(
                chainCount,
                block.timestamp,
                amount,
                msg.sender,
                recipient
            )
        );

The BlockStruct takes values corresponding to the keys set when defining the struct. It is then added to the chain array using the .push method. Now we have a new block in the chain.

Finally, we trigger the BlockEvent we created a while ago:

emit BlockEvent(amount, msg.sender, recipient);

emit is the keyword used to call an event. As with the BlockStruct, the BlockEvent takes the values as they correspond to the keys set when defining the it.

The addBlockToChain function now looks like this:

    function addBlockToChain(uint256 amount, address payable recipient) public {
        chainCount += 1;

        chain.push(
            BlockStruck(
                chainCount,
                block.timestamp,
                amount,
                msg.sender,
                recipient
            )
        );

        emit BlockEvent(amount, msg.sender, recipient);
    }

getChain function

This function takes no argument but returns a BlockStruct. We will use the following code:

    function getChain() public view returns (BlockStruck[] memory) {
        return chain;
    }

The program returns the chain, an array of all blocks.

Something to note in the function above is that we used view to show that this function returns a value. We also indicated the kind of data type we expect to be returned (returns (BlockStruck[] memory)) and the storage type to be used (memory).

There are two main storage types in solidity: Storage and Memory. Storage is the default type of storage used to hold data permanently for a program while Memory is temporary and is less expensive in terms of gas.

Gas is a fee paid to execute smart contracts. Don't worry about that. We have some dummy gas that will enable us to test our program.

getChainCount function

Like the getChain, this function also takes no argument. It returns the number of blocks added to the chain so far. See the code below:

    function getChainCount() public view returns (uint256) {
        return chainCount;
    }

That completes the smart contract that we intended to create. Now the code looks like this:

// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.7;

contract Blockchain {
    struct BlockStruck {
        uint256 index;
        uint256 timestamp;
        uint256 amount;
        address sender;
        address recipient;
    }

    event BlockEvent(uint256 amount, address sender, address recipient);

    BlockStruck[] chain;
    uint256 chainCount;

    constructor() {
        chainCount = 0;
    }

    function addBlockToChain(uint256 amount, address payable recipient) public {
        chainCount += 1;

        chain.push(
            BlockStruck(
                chainCount,
                block.timestamp,
                amount,
                msg.sender,
                recipient
            )
        );

        emit BlockEvent(amount, msg.sender, recipient);
    }

    function getChain() public view returns (BlockStruck[] memory) {
        return chain;
    }

    function getChainCount() public view returns (uint256) {
        return chainCount;
    }
}

How to Compile the Smart Contract

We need to compile the code to check if there are errors that we need to fix. The steps below will help us do just that.

Click on the third icon on the left side menu of the remix IDE:

Ensure that the solidity version selected matches the one you specified at the beginning of the smart contract. Then click the Compile button:

The compilation was successful since we have no errors. Beautiful 🥰.

How to Deploy the Smart Contract

Now that compilation is successful, let's deploy the contract.

Click on the fourth icon in the side menu:

Select Remix VM (London) for the ENVIRONMENT. It has ten (10) accounts with 100 dummy ethers each that you may use for test purposes. Then click the Deploy button:

Now when you scroll to the bottom, you will find the Blockchain contract under Deployed Contracts. Click the arrow by the deployed contract name to see the functions of the contract that you can interact with.

There are three (3) functions in the image above that match the three (3) functions we defined in our smart contract. Remix automatically creates a UI for you to test your contracts as soon as you deploy them

How to Test the Smart Contract

We will now test the functions we created to see how they respond.

How to test the addBlockToChain function

To test the addBlockToChain function, click the caret (^) icon by the side of the function button and input box. That drops down a form. Fill in 10 for the amount, and fill in one of the ten 10 account addresses for the recipient:

Click the transact button.

Note that you cannot send funds to the same address you used to deploy the contract. You must choose a different account.

How to test the getChain function

Click the getChain button to reveal the blocks in the chain so far:

It returns a tuple, which is a kind of array. Recall that chain is supposed to be an array containing a list of blocks.

How to test the getChainCount function

To get the number of blocks added, click the getChainCount button:

And just as we defined it, it returns a uint. There is just one item in the chain for now, but as you keep adding more blocks, the number will increase.

Walah! Did we come this far? 😳 How Awesome 😍.

Congratulations on sticking to the end of this tutorial!

You are now ready to explore all that you can do with blockchain.

Conclusion

Blockchain is redefining the internet and has come to stay. The difficulty I encountered trying to learn the ropes of this new technology moved me to document this beginner-friendly guide. I hope that it helps everyone still struggling out there.

In this tutorial, you learned what blockchain is, how it works and what goes on behind the scenes. We demonstrated how it works using the OOP pattern of JavaScript and then concluded with a brief introduction to how to build smart contracts using the solidity programming language and remix IDE.

I recommend that you keep learning and getting better at building blockchain applications by creating the following projects in the order they are listed (by increasing difficulty):

Hello World
Simple Storage
Voting Smart Contract
Ether Wallets
Multi Send
Time Lock Smart Contract
ERC20 Token
Token Wallet
Air Drop
ICO

These projects will challenge you to do research and sharpen your blockchain skill.

Happy Chaining!

In this article I will show you three ways you can create a whitelist in a smart contract.

Here's what we'll discuss:

• On-chain whitelists
• Digital signatures
• Merkle trees

All methods are available in the repo here.

A whitelist is useful if you want to restrict access to a certain function or want to grant privileges to a certain group of users.

To compare these methods, I'm going to use very minimalistic smart contracts to reduce the unnecessary spending of gas.

Let's dive into it.

How to Create an On-Chain Whitelist

The main idea is to store all whitelist addresses in the smart contract.

Take a look at this schema:

On-chain whitelist

When user calls the smart contract function, it checks if the address is in the whitelist. If it is, the function executes.

If you want to add or remove addresses from the whitelist, you can do it in the smart contract with additional external functions.

Pros:

• easy to implement
• all addresses are stored in the smart contract and only the owner can edit them

Cons:

• it's the most expensive method
• you have to spend gas to add and remove the addresses

Here's what the smart contract looks like:

contract OnChainWhitelistContract is Ownable {

    mapping(address => bool) public whitelist;

    /**
     * @notice Add to whitelist
     */
    function addToWhitelist(address[] calldata toAddAddresses) 
    external onlyOwner
    {
        for (uint i = 0; i < toAddAddresses.length; i++) {
            whitelist[toAddAddresses[i]] = true;
        }
    }

    /**
     * @notice Remove from whitelist
     */
    function removeFromWhitelist(address[] calldata toRemoveAddresses)
    external onlyOwner
    {
        for (uint i = 0; i < toRemoveAddresses.length; i++) {
            delete whitelist[toRemoveAddresses[i]];
        }
    }

    /**
     * @notice Function with whitelist
     */
    function whitelistFunc() external
    {
        require(whitelist[msg.sender], "NOT_IN_WHITELIST");

        // Do some useful stuff
    }
}

All addresses will be stored in the whitelist variable.

The function addToWhitelist allows the owner to add an array of addresses. Keep in mind that each address in the list will spend about 22904 gas units. To call that function costs 23994 gas units.

The function removeFromWhitelist allows you to remove addresses from the whitelist.

And the function whitelistFunc checks if the address belongs to the whitelist.

Gas spending:

Gas spending for on-chain whitelist

How to Create a Digital Signature Whitelist

The main idea is to create signatures for addresses and check them inside the smart contract.

Digital signature whitelist

You store the whitelist on your server. Before making a call to the smart contract, you should check if the address is in the whitelist or not. If yes, create a signature for the address and pass that signature to the smart contract. Inside the smart contract you have to validate that signature.

Pros:

• No gas for adding or removing addresses from the whitelist.
• No need to interact with the smart contract about the whitelist

Cons:

• Whitelist is located in a database that can be compromised. If the audience trusts the owner of the project, then this is not a problem
• The most expensive price for contract deployment and whitelist validating

Here's the smart contract:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.14;

import "@openzeppelin/contracts/access/Ownable.sol";
import "@openzeppelin/contracts/utils/cryptography/ECDSA.sol";

contract DigitalSignatureWhitelistContract is Ownable {

    using ECDSA for bytes32;

    /**
     * @notice Used to validate whitelist addresses
               Replace this wallet address to your own!
     */
    address private signerAddress = 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266;

    /**
     * @notice Verify signature
     */
    function verifyAddressSigner(bytes memory signature) private 
    view returns (bool) {
        bytes32 messageHash = keccak256(abi.encodePacked(msg.sender));
        return signerAddress == messageHash.toEthSignedMessageHash().recover(signature);
    }

     /**
     * @notice Function with whitelist
     */
    function whitelistFunc(bytes memory signature) external
    {
        require(verifyAddressSigner(signature), "SIGNATURE_VALIDATION_FAILED");

        // Do some useful stuff
    }
}

How to implement a digital signature

First, you'll need to create a new wallet address. It will be signer address.

ATTENTION: Do not send any funds to that wallet. It will be used only for making signatures.

Let's assume, that the signer wallet address is 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266

Specify it in the smart contract here:

address private signerAddress = 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266;

In the root of your web project, create a .env file with private key of that wallet:

SIGNER_PRIVATE_KEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80

Specify only your own public and private keys, because these are publicly known.

Next, create the whitelist database. It can be PostgreSQL, MySQL, MongoDB – any one you want. You can easily add or remove addresses.

Then when it's time to interact with the smart contract, the user clicks a button on your website. You send the request to your server with the user's address.

If the user is in the whitelist, create the signature for the address on your server:

import { ethers } from 'ethers'

export default async function handler() {

  // Whitelist array from you database
  const whitelist = [
    '0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC',
    '0x90F79bf6EB2c4f870365E785982E1f101E93b906',
    '0x15d34AAf54267DB7D7c367839AAf71A00a2C6A65',
    '0x9965507D1a55bcC2695C58ba16FB37d819B0A4dc',
    '0x976EA74026E726554dB657fA54763abd0C3a0aa9',
  ]

  // This variable will contain the signature we need
  let signature = ''

  // Parse params passed to server and get user wallet address
  const userWalletAddress = ''

  if (whitelist.includes(userWalletAddress)) {
    const signer = new ethers.Wallet(process.env.SIGNER_PRIVATE_KEY!)
    const addressHash = ethers.utils.solidityKeccak256(['address'], [userWalletAddress.toLowerCase()])
    const messageBytes = ethers.utils.arrayify(addressHash)
    signature = await signer.signMessage(messageBytes)
  }

  // Return signature to web
}

Then pass the signature to the smart contract function, where verifyAddressSigner will validate it according to the sender's address.

Gas spending:

Gas spending for digital signature whitelist

How to Create a Merkle Tree Whitelist

What is the Merkle tree?

Merkle tree is a tree in which every "leaf" (node) is labelled with the cryptographic hash of a data block, and every node that is not a leaf (called a branch, inner node, or inode) is labelled with the cryptographic hash of the labels of its child nodes. – Source

How does it connect to the whitelist problem?

We will use it to hash all addresses into one root hash.

Merkle tree

This is the schema of work:

Merkle tree whitelist

Like in the digital signature method, you need a database for the whitelisted addresses. When you are ready to start the sale or something else, you need to create the Merkle root hash and save it in the smart contract. This hash will validate all the addresses.

When the user wants to make a request to the smart contract, you need to create a Merkle proof for him, based on the Merkle tree of all addresses. Then you need to send proof to the smart contract. You can store the tree locally.

After editing the whitelist you should update the Merkle root hash and rewrite it to the smart contract. You should also update the local Merkle tree.

Pros:

• Deployment of the smart contract is much cheaper than the digital signature method
• Validating addresses in the smart contract is also cheaper
• No gas for adding or removing addresses from whitelist, until you start a sale

Cons:

• After the sale has started, it will be complicated to change the whitelist. You will need to update the smart contract and Merkle tree each time. Therefore, gas will be spent.
• You need to know how to create a Merkle root and update the smart contact. It's impossible to change the whitelist without interacting with the smart contract.

Here's the smart contract:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.14;

import "@openzeppelin/contracts/access/Ownable.sol";
import "@openzeppelin/contracts/utils/cryptography/MerkleProof.sol";

contract MerkleTreeWhitelistContract is Ownable {

    /**
     * @notice Merkle root hash for whitelist addresses
     */
    bytes32 public merkleRoot = 0x09485889b804a49c9e383c7966a2c480ab28a13a8345c4ebe0886a7478c0b73d;

    /**
     * @notice Change merkle root hash
     */
    function setMerkleRoot(bytes32 merkleRootHash) external onlyOwner
    {
        merkleRoot = merkleRootHash;
    }

    /**
     * @notice Verify merkle proof of the address
     */
    function verifyAddress(bytes32[] calldata _merkleProof) private 
    view returns (bool) {
        bytes32 leaf = keccak256(abi.encodePacked(msg.sender));
        return MerkleProof.verify(_merkleProof, merkleRoot, leaf);
    }

    /**
     * @notice Function with whitelist
     */
    function whitelistFunc(bytes32[] calldata _merkleProof) external
    {
        require(verifyAddress(_merkleProof), "INVALID_PROOF");

        // Do some useful stuff
    }
}

How to implement a Merkle tree on the web

First, create the whitelist database. It can be PostgreSQL, MySQL, MongoDB or any other you want. You can easily add or remove addresses.

When it's time to interact with the smart contract, create a Merkle root hash:

import { ethers } from 'ethers'
import { MerkleTree } from 'merkletreejs'

// Your whitelist from database
const whitelist = [
  '0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC',
  '0x90F79bf6EB2c4f870365E785982E1f101E93b906',
  '0x15d34AAf54267DB7D7c367839AAf71A00a2C6A65',
  '0x9965507D1a55bcC2695C58ba16FB37d819B0A4dc',
  '0x976EA74026E726554dB657fA54763abd0C3a0aa9',
]

const { keccak256 } = ethers.utils
let leaves = whitelist.map((addr) => keccak256(addr))
const merkleTree = new MerkleTree(leaves, keccak256, { sortPairs: true })

// Save this value to smartcontract
const merkleRootHash = merkleTree.getHexRoot()
// 0x09485889b804a49c9e383c7966a2c480ab28a13a8345c4ebe0886a7478c0b73d

Then save the Merkle root hash in the smart contract.

Specify it before the deployment:

bytes32 public merkleRoot = 0x09485889b804a49c9e383c7966a2c480ab28a13a8345c4ebe0886a7478c0b73d;

Or use a function setMerkleRoot for it:

function setMerkleRoot(bytes32 merkleRootHash) external onlyOwner
{
    merkleRoot = merkleRootHash;
}

When the user clicks a button on your website, you send the request to your server with the user's address. If the user is in the whitelist, create the Merkle proof on your server:

import { ethers } from 'ethers'
import { MerkleTree } from 'merkletreejs'

export default async function handler() {

  // Whitelist array from you database
  const whitelist = [
    '0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC',
    '0x90F79bf6EB2c4f870365E785982E1f101E93b906',
    '0x15d34AAf54267DB7D7c367839AAf71A00a2C6A65',
    '0x9965507D1a55bcC2695C58ba16FB37d819B0A4dc',
    '0x976EA74026E726554dB657fA54763abd0C3a0aa9',
  ]

  // This variable will contain the signature we need
  let proof = []

  // Parse params passed to server and get user wallet address
  const userWalletAddress = ''

  if (whitelist.includes(userWalletAddress)) {
    const { keccak256 } = ethers.utils
    let leaves = whitelist.map((addr) => keccak256(addr))
    const merkleTree = new MerkleTree(leaves, keccak256, { sortPairs: true })
    let hashedAddress = keccak256(userWalletAddress)
    proof = merkleTree.getHexProof(hashedAddress)
  }

  // Return proof to web
}

Then pass proof to the smart contract function, where verifyAddress will validate it according to the sender's address.

Gas spending:

Gas spending for Merkle tree whitelist

Summary

Below you will find a comparison table of the gas units these different methods spend:

Long story short:

• An on-chain whitelist easy to implement, but expensive to use. I would not recommend using it.
• A digital signature whitelist is a universal tool that does not require additional interactions with the smart contract. You can easily edit the whitelist at any time. But you have to pay for versatility. Deployment and function with the whitelist are the most expensive. If your addresses change frequently, then use digital signature.

• Merkle tree is the best option if your whitelist addresses will not change after you start presale or whatever you want. For example, it costs nothing to collect addresses and edit them in your database. When the sale starts, you stop editing the whitelist, create the root hash, save it to the smart contract and that's it. In that case the Merkle tree is better than digital signature.

  What exactly to use is up to you!

Finally, I want to show you how to calculate gas price.

How to calculate gas price

Use the following formula:

(gas units) * (gas price per unit) = gas fee in gwei

Use https://ethgasstation.info/ or any other website to find gas price per unit. At the moment of writing this article, gas price is 22.

Gas price per unit

The value can change depending on the time of day.

Let's calculate how much it will cost to deploy a digital signature smart contract.

Deployment = 486 182 * 22 = 10 696 004 gwei = 0,010696004 ETH

Now since the ETH/USD price is $1,324, it means that deployment to the Mainnet will cost about $14.

Maybe you want to convert the comparison table to USD?
Gas price per unit = 22, ETH = $1,324

Thank you for reading! ❤

Learning a new technology often means learning a new framework, programming language, IDE, or deployment method. And the blockchain is no different.

In this tutorial, I am going to show you how to get started with Truffle, a Node.js blockchain framework, in Visual Studio Code.

How to Install Truffle

To install Truffle you need to have Node and NPM along with Python setup on your machine.

If you do not have them already, you can install them from their official websites (Node and Python). Once you're done with that, you are all set to install Truffle.

We will use npm to install Truffle. Enter the following command in your command prompt:

npm install -g truffle

While the installation runs, if you come across the following error, I have got you covered:

gyp ERR! stack Error: Could not find any Visual Studio installation to use

Google shows a bunch of solutions for the above error. What actually worked for me was installing Visual Studio along with 'Desktop Development with C++'.

After you download Visual Studio and run the installer you will see the following screen:

Under the 'Desktop and mobile' section, check 'Desktop Developement with C++' and continue with the installation process.

Once this is done you can run the Truffle installation command again.

To verify if Truffle is installed successfully, run:

truffle version

in your command prompt. You should see an output like the image below:

Congratulations! You have installed Truffle.

How to Use Truffle in Visual Studio Code

Visual Studio Code comes with it's own extension for Truffle. We will install it to make our work easier.

In the marketplace search bar, type "Truffle for VS Code" and click on install (similar to the image below).

VS Code requires you to have other extensions for it to work, so just check the ones you don't have installed and continue the setup:

If you do not see the Truffle logo in the left bar you might have to restart VS Code.

How to Set Up Ganache in VS Code

Ganache comes with the Truffle suite to deploy DApps.

Click on the 'Networks' > 'Create a new network' in Truffle explorer.

From the dropdown box select 'Ganache service'.

Select type 'local' or 'fork'. Since this a local setup I will select 'local'.

Next, you will be asked to enter your 'local project's name'. Enter any name of your choice and hit enter.

Your network setup is complete.

To start the network, right click on the network name and click on 'Start Ganache'.

When you start the Ganache service, you will see a command line output as follows:

The output displays a set of things to speed up. We do not need to worry about them just yet.

How to Start a Tuffle Project

To start a project in Truffle, go into a directory and type the init command.

truffle init

This will create a new Truffle project.

How to Create a Contract in Truffle

The following commands creates a contract in Truffle:

truffle create contract <contract name>

Here we created a contract named 'SimpleStorage'.

How to Run Tests in Truffle

To run test in Truffle, just enter this command:

truffle test

All the tests will be run one by one.

How to Deploy in Truffle

We will use Ganache to deploy in Truffle.

truffle develop

You use the above command to start the deployment process.

Ganache has some accounts and private key ready for this purpose.

In the above image at the bottom you will see truffle (develop)> console.

Type migrate --reset in the console.

You will see that the initial migrations are made and the deployment process starts. In the end you will get a summary (the cost and number of deployments) of the deployment.

Conclusion

We progress more quickly when we can learn from each other's mistake. I have just started learning Blockchain, and it took me a while to get the setup running. So here I am sharing my findings. Happy learning!

About four months ago, I switched to Hardhat from Truffle. This cool new kid on the block drastically improved my coding experience. So today I want to share it with my fellow Solidity developers.

In this post, I will walk you through the initial set-up, compilation, testing, debugging, and finally deployment.

At the end of this post, you will be able understand how to deploy an NFT contract to the local network with Hardhat.

The goal of this post is to make you familiar with Hardhat. I won’t talk about how to write a test or Solidity syntax. However, you should be able to follow along without any Solidity knowledge if you know how to write JavaScript.

See this repo for the code.

How to Set Up the Project

Let’s start an npm project first:

npm init --yes

Then install the Hardhat package:

npm install --save-dev hardhat

Cool! Now you are ready to create a new Hardhat project:

npx hardhat

Choose Create an empty hardhat.config.js:

This will create hardhat.config.js in your root directory with the solidity compiler version specified:

/**
 * @type import('Hardhat/config').HardhatUserConfig
 */
module.exports = {
  solidity: "0.7.3",
};

How to Write and Compile the Contract

All right, we will start writing a simple contract and then we'll compile it.

Make a new Solidity file within a new contracts directory:

 mkdir contracts && cd contracts && touch MyCryptoLions.sol

We'll use the open-zeppelin package to write our NFT contract. So first, install the open-zeppelin package:

npm install --save-dev @openzeppelin/contracts

Here is the contract code we will be compiling:

pragma solidity ^0.7.3;

import "@openzeppelin/contracts/token/ERC721/ERC721.sol";

contract MyCryptoLions is ERC721 {
    constructor(string memory name, string memory symbol)
        ERC721(name, symbol)
    {}
}

The first thing you need to do in any solidity file is to declare the compiler version. Then we can import the ERC721 contract (NFT contract) from open-zeppelin just like you do in JavaScript.

Solidity is a contract-oriented language. Just like an object-oriented language, contracts can have members such as functions and variables. In our code, we have only the constructor, which will be called when we deploy our contract.

Our contract inherits the ERC721 and then passes the name and symbol arguments which are going to be passed to the ERC721 contract. They literally decide the name and symbol of your NFT token.

We will pass whatever values we want to name and symbol at the point of deployment.

To compile it, run:

npx hardhat compile

You might get some warnings but we'll ignore them to keep things simple. You should see Compilation finished successfully at the bottom.

You should also notice that the /arfifacts and /cache directories were generated. You don’t have to worry about them for this post, but it’s good to keep in mind that you can use abi in the artifacts if you want to interact with the contract when you build the frontend.

How to Test the Contract

Since smart contracts are mostly financial applications – and they're also hard to change – testing is critical.

We will use some packages for testing. Install with the command below:

npm install --save-dev @nomiclabs/hardhat-waffle ethereum-waffle chai @nomiclabs/hardhat-ethers ethers

ethereum-waffle is a testing framework for smart contracts. chai is an assertion library. We'll write tests in waffle using Mocha alongside Chai. ethers.js is a JavaScript SDK for interacting with the Ethereum blockchain. The other two packages are plugins for Hardhat.

Now, let’s make a new directory test in the root directory and make a new file called test.js in it:

mkdir test && cd test && touch test.js

Make sure you require @nomiclabs/hardhat-ethers in the hardhat.config.js to make it available everywhere:

require("@nomiclabs/hardhat-ethers");

Here is a simple test:

const { expect } = require("chai");

describe("MyCryptoLions", function () {
  it("Should return the right name and symbol", async function () {
    const MyCryptoLions = await hre.ethers.getContractFactory("MyCryptoLions");
    const myCryptoLions = await MyCryptoLions.deploy("MyCryptoLions", "MCL");

    await myCryptoLions.deployed();
    expect(await myCryptoLions.name()).to.equal("MyCryptoLions");
    expect(await myCryptoLions.symbol()).to.equal("MCL");
  });
});

This code deploys our contract to the local Hardhat network and then checks if the name and symbol values are what we expect.

Run the test:

Awesome, it passed the test!

How to Use console.log() in Hardhat

Now here is the coolest thing you can do with Hardhat. You can use console.log() just like you do in JavaScript, which was not possible before. console.log() alone is more than enough reason to switch to Hardhat.

Let’s go back to your solidity file and use console.log().

pragma solidity ^0.7.3;

import "@openzeppelin/contracts/token/ERC721/ERC721.sol";
import "hardhat/console.sol";

contract MyCryptoLions is ERC721 {
    constructor(string memory name, string memory symbol) ERC721(name, symbol) {
        console.log("name", name);
        console.log("symbol", symbol);
        console.log("msg.sender", msg.sender); //msg.sender is the address that initially deploys a contract
    }
}

And run the test again with npx hardhat test. Then the command will compile the contract again, and then run the test. You should be able to see some values logged from the contract.

This makes debugging a lot easier for you.

One caveat is that it supports only these data types:

• uint
• string
• bool
• address

But other than that, you can use it as if you are writing JavaScript.

How to Deploy the Contract

All right! Now let’s deploy our contract. We can deploy our contract to one of the testing networks, the Mainnet, or even a mirrored version of the Mainnet in local.

But in this post, we will deploy to the local in-memory instance of the Hardhat Network to keep things simple. This network is run on startup by default.

Make a new directory called scripts in the root directory and deploy.js in it.

mkdir scripts && cd scripts && touch deploy.js

Here is the deploy script. You deploy along with constructor values:

async function main() {
  const MyCryptoLions = await hre.ethers.getContractFactory("MyCryptoLions");
  const myCryptoLions = await MyCryptoLions.deploy("MyCryptoLions", "MCL");

  await myCryptoLions.deployed();

  console.log("MyCryptoLions deployed to:", myCryptoLions.address);
}

main()
  .then(() => process.exit(0))
  .catch((error) => {
    console.error(error);
    process.exit(1);
  });

You might want to remove console.log() before you deploy. And then run this deploy script with:

npx hardhat run scripts/deploy.js
MyCryptoLions deployed to: 0x5FbDB2315678afecb367f032d93F642f64180aa3

Boom! Now your NFT contract is deployed to the local network.

You can target any network configured in the hardhat.config.js depending on your needs. You can find more about configuration here.

Wrapping Up

Hardhat has some other cool features like helpful stack trace, support for multiple Solidity compiler versions, a robust Mainnet forking, great TypeScript support and contract verification in Etherescan. But that’s for another time!

In the cryptoverse, a lot of attention is laid on Bitcoin. But don't let that overshadow the growing interest in Ethereum, which is revolutionizing the way we think of applications.

So, what is a Dapp? A Dapp, or decentralized application, is a software application that runs on a distributed network. It's not hosted on a centralized server, but instead on a peer-to-peer decentralized network.

Alright, that's the short version, but there's a lot more to unpack. Let's dive into the world of Dapps, more specifically those built on the Ethereum protocol.

What is Ethereum?

To understand what a Dapp is, you first need to understand what Ethereum is. Now, there are other protocols that are used to build Dapps, like EOS, NEO, Stellar, Tron, and Cardano, but the big dog is Ethereum.

Ethereum is a network protocol that allows users to create and run smart contracts over a decentralized network. A smart contract contains code that runs specific operations and interacts with other smart contracts, which has to be written by a developer. Unlike Bitcoin which stores a number, Ethereum stores executable code.

So, why should you care?

Because Ethereum removes the need for a third party to handle transactions between peers. Since the middle man is replaced by code, all kinds of costs are reduced, including time and money.

Just like Bitcoin removes the need for someone to hold your money, Ethereum removes the need for someone to broker a deal.

Now you might be wondering, where are all these smart contracts? Well, they're essentially hosted on multiple computer nodes all across the world.

These nodes contain all of the information of all the world's smart contracts, including code, transactions, etc. They're constantly working to keep this information up-to-date so they all have the exact same copy. This what makes smart contracts, and cryptocurrencies in general, decentralized.

And since all of the nodes have the same information and are spread across the world, the removal of a node won't interrupt the execution of any smart contract. Redundancy ensures uptime.

What is a Dapp?

Now that we have a good idea of what Ethereum and smart contracts are, we can start diving into the details of what a Dapp is.

Just to be clear, a Dapp is just like any other software application you use. It could be a website or an app on your phone. What makes a Dapp different than a traditional app is that it's built on a decentralized network, like Ethereum.

When you're creating your own Ethereum smart contracts, you're actually writing a piece of the backend code for your Dapp. And while your Dapp will have a user interface like a traditional app, either all or part of the backend is built on top of Ethereum.

Dapp = frontend + smart contract backend

This backend code is written in an Ethereum-specific language, including Solidity (the most popular), Serpent, and Vyper. Below is an example of a simple "Hello World" contract written in Solidity.

pragma solidity ^0.4.22;

contract helloWorld {
 function printHelloWorld () public pure returns (string) {
   return 'Hello World!';
 }
}

If the smart contract is deployed onto Ethereum's mainnet (i.e., production) or even a local testnet, your Dapp can execute the code in the smart contract by calling the function printHelloWorld().

But what about the frontend? Is there any specific language you need to use for your Dapp?

Nope! You can use whatever frontend language/framework you want. But it is possible to host your frontend code on decentralized storage nodes to make both your frontend and backend decentralized.

Take a look at technologies like Swarm and IPFS to learn more about decentralized storage.

OK, so Dapps are just applications that have some or all of their backend decentralized and possibly even have a decentralized frontend. Why should you care?

The development of Dapps is another step toward a future of the Internet that's commonly referred to as Web 3.0.

Ethereum Dapps: The Backbone of Web 3.0

Since the creation of the Internet, the amount of information and human interaction has exploded. We're able to produce and consume information at near infinite levels.

Unfortunately, the ability to control this information has become heavily centralized over time. This includes information about your social life, health, finances, and much more. Those who control this information are the ultimate owners of it and can use it as they see fit.

These are essentially middle men that hold your information on their centralized servers so they can provide you with services, like holding your money, hosting you website, connecting with family and friends, etc. And at the push of a button, they can completely remove you from accessing this (your?) information and all related services.

This is a monopoly on the information you produce and consume as well as the services you use. Thankfully, Web 3.0 changes all of that and Ethereum Dapps are playing a central role.

Web 3.0 is a lot of things, but at its core is a technology based on decentralization. By decentralizing information and services, large corporations and governments won't be able to control users of the Internet through monopolistic, authoritarian tactics.

Ethereum Dapps, with their ability to decentralize information and services, gives Web 3.0 a platform to deliver a completely free (as in freedom) and accessible Internet for everyone. No longer will there be a central point of control because there won't be middle men to facilitate the flow of information and services.

Some of the most promising Ethereum tokens and Dapps are laying the foundation for the future of the Internet, including:

• Basic Attention Token (BAT): used to improve privacy and value transfer between users, publishers, and advertisers. Used in the Brave browser.
• Golem (GNT): used to run code on one or many distributed compute nodes.
• Minds: a social media platform that improves value transfer between content creators and consumers.
• TokenSets: used to manage cryptocurrency assets via tokenized automated asset management strategies.
• Aave: used to earn interest on cryptocurrency deposits and borrow cryptocurrency assets.
• IDEX: a decentralized cryptocurrency exchange.

Closing Thoughts

Since the creation of Bitcoin, the first cryptocurrency, there's been a massive growth in the cryptoverse.

Being able to store data in a decentralized way was a necessary stepping stone to the decentralization of code execution. With Ethereum, it's now possible to deploy smart contracts across the world to power the backend for existing and future Dapps.

And as more and more Dapps are launched, we'll get closer and closer to a more free, fair, and accessible Internet.

I’m Grant and I’m a freelance SEO and content professional. If you’re looking to grow your brand's organic search traffic, I can help with your fintech SEO. Cheers!

Ever since Ethereum graced the crypto space with its presence in mid-2015, the revolutionary invention by Canadian-Russian Programmer Vitalik Buterin has given birth to many new decentralised applications (dApps). Along with the myriad of dApps being built, Ethereum’s success is mainly attributed to its implementation of smart contracts.

Interestingly enough, the invention of smart contracts dates back to 1996. Computer scientist Nick Szabo drew up the term “smart contracts,” and explains them as follows:

“I call these new contracts “smart”, because they are far more functional than their inanimate paper-based ancestors. No use of artificial intelligence is implied. A smart contract is a set of promises, specified in digital form, including protocols within which the parties perform on these promises”

— Nick Szabo, 1996

His work later went on to inspire many other researchers and scientists, including Vitalik, who created Ethereum.

Basic info

Before we delve further into the guide, it is important to understand two important concepts.

The first thing that we need to understand is what the Ethereum Virtual Machine (EVM) is. Its sole purpose is to act as a runtime environment for smart contracts based on Ethereum. Think of it as a global super computer that runs all the smart contracts. As the name suggests, the EVM is virtual and not a physical machine. You can read more about the EVM here.

The second concept we need to understand is what is gas. In the EVM, gas is a unit of measurement used to assign a fee to each transaction with a smart contract. Each computation that happens in the EVM requires gas. The more complex and tedious it is, the more gas is needed to execute the smart contract.

Every transaction specifies the gas price it is willing to pay in ether for each unit of gas, allowing the market to decide the relationship between the price of ether and the cost of computing operations (as measured in gas). It’s the combination of the two, total gas used multiplied by gas price paid, that results in the total fee paid by a transaction.

Fee for transaction = Total gas used * gas price;

Read more about gas here.

Now that you have basic knowledge about what a smart contract is and how the smart contract runs, we can go straight into how we are going to make our very own smart contract!

Setting up

We’re going to use a tool for this: Pragma. It’s an easy-to-use platform for creating and deploying smart contracts. Sign up here and go the editor:

Log in to Metamask. If you haven’t installed MetaMask yet, you can start here.

Switch to the Kovan test network both in Pragma and MetaMask.
Just to give you a brief overview about testnets, check out this article.

The Ethereum mainnet is the official Ethereum network. It is more secure, and uses Ether, which has real monetary value.

Testnets are playground Ethereum networks in which the Ether is agreed to have no monetary value. Developers use these playgrounds to test applications before deploying them to the mainnet for their users.

To switch between these networks, click on the network name next to the MetaMask icon and select the network. For this tutorial, please choose Kovan.

Writing the smart contract

The following contract will implement the simplest form of a cryptocurrency. It is possible to generate coins out of thin air, but only the person that created the contract is able to do that (it is trivial to implement a different issuance scheme). Furthermore, anyone can send coins to each other without needing to register with a username and password. All you need is an Ethereum keypair.

pragma solidity ^0.4.21; //tells that the source code is written for Solidity version 0.4.21 or anything newer that does not break functionality


contract yourToken {
    // The keyword "public" makes those variables readable from outside.

    address public minter;

    // Events allow light clients to react on changes efficiently.
    mapping (address => uint) public balances;

    // This is the constructor whose code is run only when the contract is created
    event Sent(address from, address to, uint amount);

    function yourToken() public {

        minter = msg.sender;

    }

    function mint(address receiver, uint amount) public {

        if(msg.sender != minter) return;
        balances[receiver]+=amount;

    }

    function send(address receiver, uint amount) public {
        if(balances[msg.sender] < amount) return;
        balances[msg.sender]-=amount;
        balances[receiver]+=amount;
        emit Sent(msg.sender, receiver, amount);

    }


}

This code basically lets you mint and send tokens to other accounts.

Let’s go through it line by line:

pragma solidity ^0.4.21;

This indicates that the source code is written for Solidity version 0.4.21 or anything newer that does not break functionality. This is to ensure that the code doesn’t behave differently with the new compiler versions.

contract yourToken

Everything related to yourToken goes inside this contract. Essentially, a contract in solidity is the collection of functions and state (code and data) sitting at an address on the Ethereum blockchain.

address public minter;

This is the address of the minter. The keyword “public” makes those variables readable from outside.

event Sent(address from, address to, uint amount);

Events allow light clients (UI) to react to the changes efficiently.

function yourToken() public {
  minter = msg.sender;
}

Let’s set your Ethereum address as minter of the contract. You’ll need to access the contract through your MetaMask to be able to mint. We’ll go through this again after deploying the contract.

function mint(address receiver, uint amount) public {
  if(msg.sender != minter) return;
  balances[receiver]+=amount;
}

This function lets you mint the amount of coins you want to. You can mint as many tokens as you want to. The if condition tells the system to stop executing if you’re not the minter, which is set in yourToken function.

If you are in fact the minter, it lets you mint the tokens.

function send(address receiver, uint amount) public {
  if(balances[msg.sender] < amount) return;
  balances[msg.sender]-=amount;
  balances[receiver]+=amount;
  emit Sent(msg.sender, receiver, amount);
}

This is a function that lets one address send the tokens to another address. It takes two parameters: receiver and amount. It reduces the amount from the sender’s address and adds the same amount to receiver’s address. Event Sent, which we declared earlier, is now used to do the transfer. Currently, we have kept the sender as msg.sender, which is the minter, as we do not want to complicate the contract.

That’s it. Your contract is now ready, so let’s compile it.

Compiling and deploying the smart contract

Once the contract is compiled, let’s deploy it on the blockchain. As mentioned earlier, we’ll use Kovan testnet to deploy the contract.

Check if the smart contract is deployed.

For the contract I deployed for this tutorial, this is the transaction. You can also see it in Pragma under your contracts.

Interact with the smart contract in Pragma

Let’s mint 1000000 tokens!

Signing the transaction

Yay!

There you have it. Your first smart contract, deployed on blockchain. :)

A lot of new concepts were introduced along with a couple of amazingly helpful tools. It might be a little overwhelming, and that’s okay! Just try to get your head around the concepts and then run with it.

Have you created any simple but interesting smart contracts? Post them in the comments and I’ll add them in the post for reference.

Have questions? Add them in the comments or join our telegram group and talk to us directly.

Ethereum doesn’t have the concept of smart contract ownership built into it.
Even though the creation and deployment of a smart contract is done by an account — be it an External Owned Account (EOA) or another contract — being the creator of the smart contract doesn’t give the account any special privileges over the contract they deployed.

Most use cases for smart contracts require someone to own the contracts. This “owner” is given privileges — and responsibilities — over the smart contract.

In a crowdsale contract they might be tasked with managing the whole process and pausing the crowdsale if something goes wrong.

In a Lottery/Ruffle Dapp they might be tasked with executing the number draw.

In any contract that holds funds, they might be set as the beneficiary upon construct destruction.

_Photo by [Unsplash](https://unsplash.com/photos/OvitgXQeN0Q?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText" rel="noopener" target="_blank" title="">Ricardo Resende on <a href="https://unsplash.com/?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText" rel="noopener" target="blank" title=")

A common pattern used by many smart contracts is to set the owner to the account deploying the contract like so:

pragma solidity 0.4.19;

contract MyContract {  address owner;

  function MyContract(){    owner = msg.sender;  }}

Then, adding a modifier:

modifier onlyOwner {  require(msg.sender == owner);  _;    }

And finally, using that modifier to enforce that critical operations can only be performed by the owner of the contract:

// Suicide the contract and transfer funds to the owner// Only available to the owner, for obvious reasons.

function destroyContract() public onlyOwner {  selfdestruct(owner);}

The Problem with Changing Contract Ownership

There are some situations that would require ownership of a contract to be given to someone else. To name a few:

• The person that deployed the contract did it on behalf of someone else
  A developer or consultant doing a contracting job for a company
• A company wants to liquidate / sell its assets, which include smart contracts
  Which might or not have ether balance
• The owner of the smart contract wants to give it away, donate it, or just flip it for profit

_Photo by [Unsplash](https://unsplash.com/photos/5x8kipLwVug?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText" rel="noopener" target="_blank" title="">rawpixel.com on <a href="https://unsplash.com/?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText" rel="noopener" target="blank" title=")

Some contracts, but unfortunately not many, include a function to give ownership of the contract to some other account. And some of them also include another function for that person to accept the ownership that has been bestowed upon him.

function changeOwner(address _newOwner)public onlyOwner {  ownerCandidate = _newOwner;}

function acceptOwnership()public {  require(msg.sender == ownerCandidate);    owner = ownerCandidate;}

Now, the situations mentioned above share a few common issues that these not-so-widely-used changeOwner() and acceptOwnership() functions don’t address:

• How can the buyer of the contract be certain that once they pay for the ownership of the contract, the seller will actually execute the corresponding changeOwner() function?
• This can happen the other way around. How can the seller of the contract be certain that they will get paid if they cede ownership first?
• How can the buyer of the contract be certain that the current owner of the contract will not modify it (well, it’s data) before giving away its ownership?

The Sellable Contract Protocol

The solution I propose is implementing a series of functions that would allow the owner of a smart contract to sell it in exchange of ether to someone of his choosing or just put it up for sale for anyone to buy at the asking price on a first-come first-save basis. This could be extended to allow different sale methods using different auction styles.

The details of the protocol can be read — and discussed — on the corresponding EIP.

In the following paragraphs I’ll go through an implementation example, which is available on my Github Repository.

Handling Ownership

Handling ownership of the contract is pretty basic. As typically done, we set the owner of the deployed contract to msg.sender upon initialization:

function Sellable() public {        owner = msg.sender;        Transfer(now,address(0),owner,0);    }

Then, we add the onlyOwner modifier, which will be used on every function that we want to make only executable by the person currently owning the contract:

modifier onlyOwner {        require(msg.sender == owner);        _;    }

What we’ll want our contract to do is to allow the owner to be changed under certain conditions.

Putting the Contract for Sale

The owner of the contract can put it up for sale by calling the following function:

function initiateSale(uint _price, address _to) onlyOwner public {        require(_to != address(this) && _to != owner);        require(!selling);                selling = true;                // Set the target buyer, if specified.        sellingTo = _to;                askingPrice = _price;    }

initiateSale() takes two parameters:

• uint _price: which is the price the owner wants to sell the contract for.
• address _to: which is optional, and corresponds to who the owner wants to sell the contract to.

When putting the contract up for sale, the owner has two options: They can choose the buyer, in that case the sale has been prearrange. Or they can simply “announce” the contract is for sale and the first person to claim it (and paying its price) gets it.

Additionally, the asking price can be set to 0. This means that the owner of the contract is allowed to gift, donate or give the contract away.

There’s one more important thing to notice: There’s a ifNotLocked modifier that can be added to the contract’s functions to prevent them from being executed if the contract is in a sale process. If used properly, this prevents the contract’s data from being modified just before it is purchased.

Finally, there’s the cancelPurchase() function which allows the owner to cancel the sale before someone completes it.

function cancelSale() onlyOwner public {        require(selling);                // Reset sale variables        resetSale();    }

Buying the Contract

Once the contract is up for sale, all it takes to complete the sale is for the buyer (if it was specified) or anyone (if no particular buyer was specified) to call the following function:

function completeSale() public payable {        require(selling);        require(msg.sender != owner);        require(msg.sender == sellingTo || sellingTo == address(0));        require(msg.value == askingPrice);                // Swap ownership        address prevOwner = owner;        address newOwner = msg.sender;        uint salePrice = askingPrice;                owner = newOwner;                // Transaction cleanup        resetSale();                prevOwner.transfer(salePrice);                Transfer(now,prevOwner,newOwner,salePrice);    }

The completeSale() function is a payable function which requires the ether to be sent. The amount to be sent must be the exactly the same the owner set as the asking price.

When completeSale() is executed, the ether will be transferred to the owner and then the ownership will be transferred to the buyer. This finishes the transaction and cleans up the contract for the new owner, who can now use it normally, or even put it up for sale again.

An Example Use Case

Here’s a very simple example of how this base contract could be used:

contract Kitty is Sellable {        string public name;    uint public kittyValue = 0;        function Kitty(string _name) public {        name = _name;    }        function findNewOwner() public onlyOwner {        kittyValue = kittyValue + 1 ether;           super.initiateSale(kittyValue,address(0));    }        function renameKitty(string newName) ifNotLocked public onlyOwner {        name = newName;    }        function buyKitty() public payable {        require(msg.value == kittyValue);        super.completeSale();    }}

We have a contract which represents a CryptoKitty ?. The owner can findNewOwner() to put it up for sale. Each time the kitty is bought his value increases by 1 ether. The owner of the kitty can change its name, as long as it is not being sold at the moment by implementing the ifNotLocked modifier in renameKitty .

That’s it!

If you have further suggestions to improve this Sellable protocol, please add your comments, bugs or suggestions in the EIP I created.

_Photo by [Unsplash](https://unsplash.com/photos/xulIYVIbYIc?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText" rel="noopener" target="_blank" title="">Jonas Vincent on <a href="https://unsplash.com/?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText" rel="noopener" target="blank" title=")