Solidity in Easy Steps: How to Build an Escrow Smart Contract (Part 1)

Introduction

Learning a new programming language comes with some challenges which may include: deciding whether the programming language is worth learning in the first place; time allocation; and hardest of all, persistence in the face of other responsibilities. It's a fact that learning by building a project of interest can be the best motivation to keep the learning going, even when other things need to be attended to.

Hi! This is the first article in a series where we shall be learning Solidity in Easy Steps. We will create a contract for two business partners that don't trust each other 🤣🤣. The first doesn't trust the second to deliver his task or goods after payment, while the second doesn't trust the first to pay after fulfilling his part of the deal... 😳😳Sounds familiar?

Thus, we suggest an Escrow contract.

Expectations

In this article, we will build an escrow smart contract using Solidity with dummy explanation for each line of code. Readers are advised to manually type in the codes provided. Before we get the ball rolling, lets take a look at what is expected of you so that we can be on the same page.

Assumption: You have a basic understanding of Solidity and programming in general.

Difficulty: 1/10 (Beginner)

Programming Time: 5 min.

By the end of this article, readers should understand:

• How to come up with a simple class diagram for contracts
• The different types of comments in Solidity programming language
• The basics of Remix IDE
• How to create simple smart contracts
• How to create functions in Solidity
• Solidity keywords public, payable, view and this
• Solidity global msg variable

Features to be Implemented

We will have to climb the ladder of features in a stepwise fashion, in this version:

• The funder should be able to fund the contract
• The funder should specify the sole beneficiary address
• The beneficiary or anyone should be able to verify that the contract has been funded with the agreed amount
• The beneficiary should be able to see who was designated as the beneficiary
• The payer should be able to release funds only to the beneficiary

Class Diagram

When analyzing or coding an application, professionals start off with a design (such as class diagram). Though not necessary at this stage, it's good to be accustomed to good practices, hence we are going to come up with a minimalistic class diagram just for conceptualization.

What the hell is a class diagram??? Simply put, a class diagram is a graphical representation of a system. An up-to-date class diagram allows anyone including your future self to gain insight into the entire contract. Typically, a contract class diagram lists the variables, functions, and events in a contract.

The variables

In this version we will need two variables, which are:

• funder: The payer. Everyone should be able to check who deposited the fund. Since blockchain users can be anonymous, how do we find out the funder? Have them create a username? No!!! We can track the wallet address that was used to fund the contract instead.
• beneficiary: The proposed recipient. Again, everyone should be able to verify this. At least, the beneficiary will rest assured that the fund has been locked up for him/her.

The Functions

We will need the following functions for this version:

• fund: This function will be called by the funder with the amount to lockup and the proposed beneficiary it's meant for.
• release: This function is to be called by the funder, when ready to release the fund to the beneficiary. Note that we don't want a scenario whereby the beneficiary will be able to release funds for themselves.
• getBalance: This function should be accessible to anyone to verify the actual amount that has been locked up in the contract. A function that does nothing other than to get the current value of a variable, like this one, is called a getter function. Thus, our contract can be depicted as shown below:

Development Setup

You don’t need to download anything... What???? That’s strange for a programming session...

In this session, we will be making use of a web-based Solidity development platform called Remix. It can be used freely by accessing https://remix.ethereum.org/. You can learn more about this amazing platform by reading its documentation.

Now, to set up our development environment:

• Visit Remix Website https://remix.ethereum.org/
• Once Remix has been loaded, create a new file named “Escrow.sol” as shown below.

Coding and Explanation

Next the full code for this version is given followed by a detailed line based explanation. While explaining the code lines we will touch on different aspects of Solidity so read on!!! Type the lines below into the Escrow.sol file created above , explanation follows.

// SPDX-License-Identifier: MIT

pragma solidity >=0.7.0 <0.9.0;

/**
 * @title EscrowSol
 * @dev Manages fund transfers between two parties
 */
contract EscrowSol {
    // Wallet address of the payer
    address public funder;
    // Wallet address of the intended beneficiary
    address public beneficiary;

    /// Lockup a certain crypto value.
    /// @param counterpart the address of the intended beneficiary
    /// @dev lockup crypto for the counterpart
    function fund(address counterpart) public payable {
        beneficiary = counterpart;
        funder = msg.sender;
    }

    /// Release all locked funds.
    /// @dev The deal is done, let only the payer release fund.
    function release() public payable {
        if (msg.sender==funder){
            // Transfer all the funds to the beneficiary
            payable(beneficiary).transfer(address(this).balance);
        }
    }

    /// Return the locked value.
    /// @dev anyone should be able to see the actually locked crpto value .
    /// @return the crypto value
    function getBalance() public view returns (uint) {
        return address(this).balance;
    }
}

Line 1

// SPDX-License-Identifier: MIT

An informative line to signify the license type of the entire code contained within the specific file.

Line 3

pragma solidity >=0.7.0 <0.9.0;

Hey solidity, run this file using any of your versions ranging from 0.7.0 up till 0.9.0. Note that, unlike line 1, this line ends with a semicolon.

Line 5-8

/**
 * @title EscrowSol
 * @dev Manages fund transfers between two parties
 */

Bunch of special type of comments called NatSpec (Natural Specifications). They are useful for automatically generating user documentation. How are NatSpecs different from ordinary multiline comments??? Jargons aside, its sufficient to know that generally, comments can serve three purposes:

• Communicate the code license (When present, its usually the first line?)
• Explain lines of codes within the program only to who has access to the souce code.
• Document sections of codes, these are multiline comments with some supported tags (such as @title) called NatSpecs. They can be automatically compiled to serve as documentation for the program.

Back to code explanation, here we declare the title with @title and a one-line contract description with @dev

Line 9

contract EscrowSol { //} Closed on line 38 

We signify the beginning of our contract named EscrowSol and everything within the parentheses on this line and its closing counterpart will be regarded by Solidity as part of this contract. Why signify the beginning of a contract, after all, solidity is for writing contracts? Well, more than one contract can be placed within a file, hence all elements that belong to a contract, if not imported, must be encapsulated within the parentheses of the contract.

Line 11

    // Wallet address of the payer
    address public funder;

We need to know the funder and since we want anyone to access the funder's address, thus we added a public Solidity keyword to achieve that.

Line 13

    // Wallet address of the intended beneficiary
    address public beneficiary;

Same explanation as Line11 but now for the beneficiary.

Line 15-17

    /// Lockup a certain crypto value.
    /// @param counterpart the address of the intended beneficiary
    /// @dev lockup crypto for the counterpart

NatSpecs for the fund function we are about to write. Note that the previous NatSpec was enclosed within "/"and "/" while this time around we used "///" on every line.

Well, that’s a way of letting you know another way it can be achieved in Solidity. Recall that we want the funder to specify the intended beneficiary at the time of funding, thus the only parameter we need to pass on to this function. This is now explicitly stated in the NatSpec with the use of the @param which is the only new tag here.

Line 18

    function fund(address counterpart) public payable { //Closed on line 21

Generally in Solidity, a function is defined by using the function keyword, give it a name, enclose arguments (if any) and their types in a bracket, followed by decorators/modifiers (if any), and lastly followed by parentheses that encapsulate the codes to be executed when called.

Therefore on line 18, we defined a function named fund that accepts the beneficiary address as an argument named counterpart decorated with public Solidity keyword for it to be executable from anywhere and also decorated with payable for payment into the contract to be processed.

What the heck is payable??? Without going into too much details, whenever cryptos are to be transferred, the address or function (as in this case) must be made payable else actual coin transfer will never take place.

Line 19

        beneficiary = counterpart;

We set the beneficiary address to the counterpart address provided by the funder.

Line 20

        funder = msg.sender;
) // End of fund function

We set the address of the funder with msg.sender Hope you are not asking what is msg?

Line 25

    function release() public payable {

We put in place a payable function named release.

Line 26-29

        if (msg.sender==funder){
            // Transfer all the funds to the beneficiary
           payable(beneficiary).transfer(address(this).balance);
        }
    } // End of release function

We ensure that the person calling this function is the funder after which we transfer all the funds locked-up in the smart contract to the beneficiary

Line 35-37

    function getBalance() public view returns (uint) {
        return address(this).balance;
    }
} // End of the contract

We now create a function named getBalance to enable us to retrieve the value of funds in our contract. In the process we introduce two new keywords (view and this).

Here, we accessed the balance of the contract through the this keyword.

Yey!!!! Its time to set our contract into action. Save it if you haven’t already.

Running our Escrow Contract

Remix is equipped with JavaScript VM that simulates blockchain which makes it easy to test smartcontracts on the go within a browser. See the gif below, we first have to compile (this is mostly done automatically unless an error has been encountered) and then deploy our smart contract.

Note that after deploying, we click on contract name below to reveal the eternally accessible variables and functions of the contract. Also notice that some buttons are colored blue while some are colored red.

By default, Remix JavaScript VM gives some addresses and fake ethers to run our contract. In this case, we will assume the second account to be the funder, while the third account to be the beneficiary.

That said, let’s perform some operations after which you can play around with the contract as you deem fit. A gif illustration is displayed below followed by the list of the steps that were taken to run the contract.

• Click on the beneficiary, funder and getAmount buttons to verify that they are currently empty.

• Select the third account, which we intend to use as the beneficiary, and copy the address.

• Select the second account, which we want to use as the funder.

• Input the amount to fund the contract in the value box. Let's assume we want to fund the contract with 1Ether.

• Go to the fund button, paste the beneficiary address copied in step2, and click fund. Notice that the value has been deducted from our ether balance.

• Click on the beneficiary, funder and getAmount buttons to verify that the values have been updated.

  Change to any of the remaining accounts (stranger) and try to release the fund by clicking on the release button. Check the balance again to see if it was successfully withdrawn. Notice that the amount still rremainsin the contract, this is as a result of line 26 of our code which ensures that only the funder has the right to release.

• Now change the account back to the funders account.

• Click on release.

• Click on getBalance to verify that the fund has been moved out of the contract to the beneficiary. You can confirm that it went to the beneficiary address by checking the amount of ether on the third account.

Well done!!!! You've developed the first version of a blockchain smart contract in Solidity.

Areas for Further Improvement

Let's now take a look at some room for further development which we will explore in the next article of this series.

• Problem 1: The funder is made to provide the beneficiary at the time of funding the contract or the funder can add more funds to the contract. This is a good feature especially when the parties have some other agreements, say the funder has to fund the escrow on a milestone basis or the parties agree to increase the amount in question. The problem with the current implementation is that if the funder wants to be fraudulent, after the completion of the task, they can call the fund function again and pass their fiancé's address as the beneficiary. This will ultimately release the fund to their fiancé 🥺. Thus, in the next post, we will still retain multiple funding options but prevent updating the beneficiary account.

• Problem 2: This current implementation involves no middleman. What if a dispute arises? Well, if we've fixed the security issue above, the funds will remain in the contract forever until released by the funder. Thus, We shall introduce a trusted party (such as is the case, a peer-to-peer trading platform) who runs the contract (instead of any of the parties) and will have the right, only in case of a dispute, to release or refund funds.

These amongst other issues will be tackled in the next post of this series.

Let me go cook it up!!!

Also read here.