Forem: Emanuele Ricci

Ethernaut Challenge #4 Solution — Telephone

Emanuele Ricci — Sun, 07 Aug 2022 05:57:46 +0000

This is Part 4 of the "Let's play OpenZeppelin Ethernaut CTF" series, where I will explain how to solve each challenge.

The Ethernaut is a Web3/Solidity based wargame created by OpenZeppelin.
Each level is a smart contract that needs to be 'hacked'. The game acts both as a tool for those interested in learning ethereum, and as a way to catalogue historical hacks in levels. Levels can be infinite and the game does not require to be played in any particular order.

Challenge #4: Telephone

Claim ownership of the contract below to complete this level.

Level author: Kyle Riley

For this challenge, our end goal is to be able to claim the ownership of the contract.

Study the contracts

The Telephone contract is pretty small, so it will be fast to read and understand how to solve the challenge.

The owner state variable is initialized in the constructor. The only function that will update the owner is changeOwner :

function changeOwner(address _owner) public

It is a public function that take only one parameter address _owner.
If the tx.origin value is different from msg.sender it will update the owner with the function input parameter _owner.

To solve this challenge, we need to understand what are msg.sender and tx.origin.

If we look at the Block and Transaction Properties documentation page from the Solidity official doc, we find this definition:

tx.origin (address): sender of the transaction (full call chain)
msg.sender (address): sender of the message (current call)

Both tx.origin and msg.sender are "special variables" which always exist in the global namespace and are mainly used to provide information about the blockchain or are general-use utility functions.

But we need to pay attention to this:

The values of all members of msg, including msg.sender and msg.value can change for every external function call. This includes calls to library functions.
tx.origin will return the address that have sent (in origin) the transaction, while msg.sender will return the value that have originated the external call.

What does this mean?

Let's make an example and see the different values for both of them

Scenario A: Alice (EOA) call directly Telephone.changeOwner(Bob)

tx.origin: Alice address
msg.sender: Alice address

Scenario B: Alice (EOA) call a smart contract Forwarder.forwardChangeOwnerRequest(Bob) that will call Telephone.changeOwner(Bob)

Inside Forwarder.forwardChangeOwnerRequest

tx.origin: Alice address
msg.sender: Alice address

Inside Telephone.changeOwner(Bob)

tx.origin: Alice address
msg.sender: Forwarder (contract) address

This happens because while tx.origin will always return the address that have created the transaction, msg.sender will return the address who made the last external call.

Solution code

We just need to create a contract that will be in the middle of the call to the Telephone contract.

contract Exploiter {
    function exploit(Telephone level) public {
        level.changeOwner(msg.sender);
    }
}

And in our solution code, just deploy it and call it

function exploitLevel() internal override {
    vm.startPrank(player, player);

    Exploiter exploiter = new Exploiter();

    vm.stopPrank();
}

If you have paid attention to our previous blog post, you already saw the startPrank cheat code. startPrank has another overloaded version

// Sets all subsequent calls' msg.sender to be the input address until `stopPrank` is called
function startPrank(address) external;

// Sets all subsequent calls' msg.sender to be the input address until `stopPrank` is called, and the tx.origin to be the second input
function startPrank(address, address) external;

In this case, we are using the second one because we need to also override the initial tx.orgin that otherwise would be address(this): the address of the test contract itself!

You can read the full solution of the challenge opening Telephone.t.sol

Disclaimer

All Solidity code, practices and patterns in this repository are DAMN VULNERABLE and for educational purposes only.

I do not give any warranties and will not be liable for any loss incurred through any use of this codebase.

DO NOT USE IN PRODUCTION.

Ethernaut Challenge #3 Solution — Coin Flip

Emanuele Ricci — Fri, 05 Aug 2022 05:24:39 +0000

Challenge #3: Coin Flip

This is a coin flipping game where you need to build up your winning streak by guessing the outcome of a coin flip. To complete this level you'll need to use your psychic abilities to guess the correct outcome 10 times in a row.

Things that might help

See the Help page above, section "Beyond the console"

Level author(s): Kyle Riley

For this challenge, our end goal is to be able to consecutively guess the coin flip result by calling the flip() function passing the correct guess.

Study the contracts

First thing that we notice, the Solidity compiler version used is < 0.8.x. This mean that the contract would be prone to math underflow and overflow bugs.

This contract is importing and using OpenZeppelin SafeMath library, so they should be safe about overflow/underflow problems.

There are three state variables:

consecutiveWins initialized by zero from the constructor. This variable will count how many consecutive correct guess we have made
FACTOR that is declared as 57896044618658097711785492504343953926634992332820282019728792003956564819968. Gas optimization tip: it can be declared as constant to save gas (see further reading)
lastHash that will be updated each time by the flip() function

The only function inside the contract is flip(), let's see what it does

function flip(bool _guess) public returns (bool) {
    uint256 blockValue = uint256(blockhash(block.number.sub(1)));

    if (lastHash == blockValue) {
        revert();
    }

    lastHash = blockValue;
    uint256 coinFlip = blockValue.div(FACTOR);
    bool side = coinFlip == 1 ? true : false;

    if (side == _guess) {
        consecutiveWins++;
        return true;
    } else {
        consecutiveWins = 0;
        return false;
    }
}

This challenge allows you to learn two important aspects about the blockchain:

Everything on the blockchain is public, even private variables like lastHash and FACTOR
There is no real "native" randomness in the blockchain, but only "pseudo randomness"

Note: I have added some useful links in the "Further reading" section of the article if you want to learn more about these two topics.

Looking at the code of the function, we know that:

We know how to calculate the correct _guess function parameter. _guess = uint256(blockhash(block.number.sub(1))).div(FACTOR) == 1 ? true : false
We know that we cannot call multiple time flip() in the same block; otherwise the function will revert. This mean that to pass the challenge, we need to at least guess correctly for 11 blocks. If you look at the Factory contract, you will see that the challenge is solved when instance.consecutiveWins() >= 10

Knowing that, let's see the solution.

Solution code

function exploitLevel() internal override {

    vm.startPrank(player);

    uint256 factor = 57896044618658097711785492504343953926634992332820282019728792003956564819968;
    uint8 consecutiveWinsToReach = 10;

    while (level.consecutiveWins() < consecutiveWinsToReach) {
        uint256 blockValue = uint256(blockhash(block.number.sub(1)));
        uint256 coinFlip = blockValue.div(factor);

        level.flip(coinFlip == 1 ? true : false);

        // simulate a transaction
        utilities.mineBlocks(1);
    }
    vm.stopPrank();
}

As you see, the solution is pretty straightforward. Loop until the consecutiveWins() getter tell us we have reached 10.

Inside the loop we calculate the value to pass to flip replicating the same logic of the CoinFlip.flip function.

After calling it, we call utilities.mineBlock(1);. This is a utility function that I have created that call Foundry cheat code vm.roll(targetBlock); that allow you to set the current block number. Basically, we are just increasing the block number in each loop section to simulate that a new block has been minted.

You can read the full solution of the challenge opening CoinFlip.t.sol

Disclaimer

All Solidity code, practices and patterns in this repository are DAMN VULNERABLE and for educational purposes only.

I do not give any warranties and will not be liable for any loss incurred through any use of this codebase.

DO NOT USE IN PRODUCTION.

Ethernaut Challenge #2 Solution — Fallout

Emanuele Ricci — Thu, 04 Aug 2022 11:59:30 +0000

This is Part 2 of the "Let's play OpenZeppelin Ethernaut CTF" series, where I will explain how to solve each challenge.

The Ethernaut is a Web3/Solidity based wargame created by OpenZeppelin.
Each level is a smart contract that needs to be 'hacked'. The game acts both as a tool for those interested in learning ethereum, and as a way to catalogue historical hacks in levels. Levels can be infinite and the game does not require to be played in any particular order.

Challenge #2: Fallout

Claim ownership of the contract below to complete this level.

Things that might help

Solidity Remix IDE

Level author(s): Alejandro Santander

Study the contracts

First thing that we notice, the Solidity compiler version used is < 0.8.x. This mean that the contract would be prone to math underflow and overflow bugs.

This contract is importing and using OpenZeppelin SafeMath library, so they should be safe about overflow/underflow problems.

The challenge is pretty unique and if you are new to the Solidity security topic probably you will have a hard time to understand how to solve this challenge but only for one reason: this problem only existed before Solidity 0.4.22.

Before Solidity 0.4.22 the only way to define a constructor for a contract was to define a function with the same name as the contract itself.
You can imagine what could go wrong... you think to have defined the constructor function that should have the name of the contract, but you make a typo while writing it... the function is never called automatically because it's not recognized as a constructor anymore and so the contract is not initialized at creation time.

After that Solidity version, they introduced a new constructor keyword to avoid this kind of mistake.

If you look at the code, the contract's name is Fallout but the constructor function is called Fal1out. Can you see the typo? They used a 1 instead of an l.
Because of that typo, when the contract is deployed, the constructor function is never executed at creation time and the owner variable is never updated. This is because Fal1out now is seen as a "normal" function.

Solution code

The solution of this challenge is pretty easy. We just need to call the Fal1out function that has never been called.

function exploitLevel() internal override {
    vm.startPrank(player);

    // Before Solidity 0.4.22 the only way to define a constructor for a contract was to define a function with the same name of the contract itself
    // After that version they introduced a new `constructor` keyword to avoid this kind of mistake
    // In this case the developer made the mistake to misstype the name of the constructor
    // Contract name -> Fallout
    // Constructor name -> Fal1out
    // The result of this is that the contract was never initialized, the owner was the address(0)
    // and we were able to call the `Fal1out` function that at this point is not a constructor (callable only once)
    // but a "normal" function. This also mean that anyone can call multiple time this function switching the owner of the contract.
    level.Fal1out();

    vm.stopPrank();
}

You can read the full solution of the challenge opening Fallout.t.sol

Disclaimer

All Solidity code, practices and patterns in this repository are DAMN VULNERABLE and for educational purposes only.

I do not give any warranties and will not be liable for any loss incurred through any use of this codebase.

DO NOT USE IN PRODUCTION.

Ethernaut Challenge #1 Solution — Fallback

Emanuele Ricci — Wed, 03 Aug 2022 08:15:14 +0000

This is Part 1 of the "Let's play OpenZeppelin Ethernaut CTF" series, where I will explain how to solve each challenge.

The Ethernaut is a Web3/Solidity based wargame created by OpenZeppelin.
Each level is a smart contract that needs to be 'hacked'. The game acts both as a tool for those interested in learning ethereum, and as a way to catalogue historical hacks in levels. Levels can be infinite and the game does not require to be played in any particular order.

Challenge #1: Fallback

Look carefully at the contract's code below.

You will beat this level if

you claim ownership of the contract

you reduce its balance to 0 Things that might help

How to send ether when interacting with an ABI

How to send ether outside of the ABI

Converting to and from wei/ether units (see help() command)

Fallback methods

Level author(s): Alejandro Santander

The goal of this challenge is to claim ownership of the Fallback contract and reduce its balance to 0.

Study the contracts

First thing that we notice, the Solidity compiler version used is < 0.8.x. This mean that the contract would be prone to math underflow and overflow bugs.

This contract is importing and using OpenZeppelin SafeMath library, but they are not using it. There is still no way to exploit it by overflow, at least in this specific case.

The only way to drain the contract is via the withdraw function that can be called only if the msg.sender equal to the value of the variable owner (see the onlyOwner function modifier). This function will transfer to the owner address, all the funds in the contract.

Let's look at the code:

function withdraw() public onlyOwner {
    owner.transfer(address(this).balance);
}

So if we find a way to change the owner value to our address, we will be able to drain all the ether from the contract.

There are actually two places in the contract where the owner variable is updated with msg.sender

The contribute function
The receive function

The `contribute` function

function contribute() public payable {
    require(msg.value < 0.001 ether);
    contributions[msg.sender] += msg.value;
    if (contributions[msg.sender] > contributions[owner]) {
        owner = msg.sender;
    }
}

This function allows the msg.sender to send wei to the contract. Those wei will be added to the user's balance, tracked by the contributions mapping variable.

If the total contribution made by the user is greater than the one made by the actual owner (contributions[msg.sender] > contributions[owner]) the msg.sender will become the new owner.

The problem is that the contribution made by the owner is equal to 1000 ETH. It's not written anywhere in the description of the challenge, but we can think that our user will start with a limited amount of ETH, an amount that does not allow us to contribute more than the owner. So, we need to find another way.

The `receive` function

This is a "special" function that is called "automatically" when someone sends some ether to a contract without specifying anything in the "data" field of the transaction.

Quoting from the official Solidity blog post when the function has been introduced:

A contract can now have only one receive function, declared with the syntax: receive() external payable {…} (without the function keyword).
It executes on calls to the contract with no data (calldata), e.g. calls made via send() or transfer().
The function cannot have arguments, cannot return anything and must have external visibility and payable state mutability.

Here's the code:

receive() external payable {
    require(msg.value > 0 && contributions[msg.sender] > 0);
    owner = msg.sender;
}

In the receive function, the owner is updated with msg.sender only if the amount of wei sent with the transaction is > 0 and our contribution in contributions[msg.sender] is > 0

At this point, we have all the pieces to build the puzzle and win the challenge. Let's see the solution!

Solution code

Here's what we need to do:

Contribute to the contract with at max 0.001 ether (to pass the require check) calling the contribute function so the contributions[msg.sender] will be greater than zero
Send 1 wei directly to the contract to trigger the receive function and become the new owner
Call withdraw and bring home all the ETH stored in the contract!

And here's the Solidity code:

function exploitLevel() internal override {
    vm.startPrank(player);

    // send the minimum amount to become a contributor
    level.contribute{value: 0.0001 ether}();

    // send directly to the contract 1 wei, this will allow us to become the new owner
    (bool sent, ) = address(level).call{value: 1}("");
    require(sent, "Failed to send Ether to the level");

    // now that we are the owner of the contract withdraw all the funds
    level.withdraw();

    vm.stopPrank();
}

You can read the full solution of the challenge opening Fallback.t.sol

Disclaimer

All Solidity code, practices and patterns in this repository are DAMN VULNERABLE and for educational purposes only.

I do not give any warranties and will not be liable for any loss incurred through any use of this codebase.

DO NOT USE IN PRODUCTION.

Let’s play OpenZeppelin Ethernaut CTF — learning Solidity security while playing!

Emanuele Ricci — Wed, 03 Aug 2022 08:10:27 +0000

The Ethernaut is a Web3/Solidity based war game created by OpenZeppelin.

Each level is a smart contract that needs to be ‘hacked’. The game acts both as a tool for those interested in learning Ethereum, and as a way to catalog historical hacks in levels. Levels can be infinite, and the game does not require to be played in any particular order.

How to play

If you want to play it by your own, just go to the Ethernaut website and start solving the challenges.

Otherwise, you could clone my own personal repository, remove the solutions in the test folder and build your own! I have explained in the README file how to do it, and it should be pretty easy.

Solutions to each puzzle

Each day I will publish the solution to a new challenge, so stay tuned.

An unofficial audit of a Solidity Game smart contract: Wizards & Dragons Game

Emanuele Ricci — Wed, 01 Dec 2021 18:26:08 +0000

Two days ago Wizards & Dragons Game, an ethereum game has released their smart contract to be reviewed publicly.

After following the Secureum Bootcamp about Smart Contract security I decided to take this opportunity and put into practice everything I've learned during this Bootcamp period.

Premise

I'm not a professional auditor, I'm just a full-stack web2 developer that is learning everything in web3 step by step. So take this as a developer that is making his homework :D

This audit is an unordered list of what I've found while I reviewed the smart contract. They are not well-formatted and mostly rushed because I have done this review in ~5 hours during a single day. I have full-time web2 work so I've done this audit before and after my day job.

Not having a specification document nor documentation available, only a few code comments, and only a couple of hours of time I spent most of the time reading the code of the contracts and trying to create a mental map of how those contracts were working and interacting each other.

No tests were provided with the code so I would need to create all of them from scratch, something impossible to do in a short period of time.

Contracts on which the audit was based

Audit Finding

Slither Finding

If you want to know more about this tool you should check it on GitHub: Slither.

Slither is a Solidity static analysis framework written in Python 3. It runs a suite of vulnerability detectors, prints visual information about contract details, and provides an API to easily write custom analyses. Slither enables developers to find vulnerabilities, enhance their code comprehension, and quickly prototype custom analyses.

I have started these findings from number 100 because I've done the Slither run after all the manual review (as you should).

WD-100: check `gpToken.transferFrom` return value

I see in the code that there are 2 parts in the code where you execute gpToken.transferFrom without checking the result of the operation.

WD-101: check all divisons

In solidity, numbers get automatically rounded when divided and the result is a floating-point number. Check all the code for cases where the division is done before the multiplication.

Always do the multiplication first and division after.

Example: uint256 encodedLen = 4 * ((data.length + 2) / 3); in Traits.sol
Check Documentation to know more.

WD-102: WNDGame stuck money?

It seems that the mint function in WNDGame.sol receives ether to mint tokens but there's not a withdraw method to withdraw them. The only withdraw function I see is in the WnD.sol contract that does not seem to have a way to receive/get redirected eth from WNDGame.sol

General

WD-001: Floating pragma

In all the contracts the pragma version of the compiler is not locked pragma solidity ^0.8.0;.
See SWC-103 for more information.

WD-002: Hardhat console imported in deployed contract

In both Tower.sol and WNDGame.sol I see that the import "hardhat/console.sol"; is still in the code. It should be only on the dev version of the project and never shipped with the production version. It just increases the contract size and the gas cost of deployment.

As far as I can see console.log() is not used inside contract code.

WD-003: import not used in interfaces

IWnDGame.sol is importing importing OpenZeppelin IERC721Enumerable.sol but not using to extend the IWnDGame from it.

WD-004: missing explanation about `lastWrite` mechanism

I see in a lot of the contract's code the usage of lastWrite to check lastWrite[tx.origin] < block.number. The developer should add more documentation on the reason behind those checks.

WD-005: Emission of events missing for critical actions

I see that many critical actions are missing event emission. For example GP.sol is missing events for actions like addAdmin, removeAdmin, updateOriginAccess.

GP.sol: missing events for functions addAdmin, removeAdmin, updateOriginAccess
SacrificialAlter.sol: missing events for functions addAdmin, removeAdmin, updateOriginAccess, setContracts, setType, setExchangeAmt, updateOriginAccess
Tower.sol: missing events for functions setRescueEnabled, _payDragonTax
Traits.sol: missing events for functions setWnD, uploadTraits
WnD.sol: missing events for functions addAdmin, removeAdmin, updateOriginAccess, withdraw, setPaidTokens, setContracts
WNDGame.sol: missing events for functions setContracts, setTreasureChestId, addToWhitelist, setPublicSaleStart, setMaxGpCost, payTribute, makeTreasureChests, sellTreasureChests, sacrifice

Some events are for security and transparency reasons, some events are to allow web3/external applications to use contract data to display information.

WD-006: Event does not have indexed parameters

In Tower.sol all three events TokenStaked, WizardClaimed, DragonClaimed does not have indexed parameters. Each event in solidity can have at max 3 indexed parameters.

Indexed parameters allow web3 applications to filter events by those parameters. It's super important to build a successful smart contract to allow external resources to filter by those.

WD-007: create an external contract for the `lastWrite` mechanism

The lastWrite mechanism is used in GP.sol, SacrificialAlter.sol and WnD.sol but in all three are implemented from scratch using the same code.

For both security, gas consumption, and code readability it would be better if a new utility contract is created and all the code is added to that contract. Other contracts that need that mechanism can simply inherit from it.

WD-009: replace admins mechanism with AccessControl

The admin mechanism could be replaced with OpenZeppelin AccessControl. In this case, you would automatically also get the implementation of important events when a role is granted or removed.

Another benefit is that the OZ implementation automatically do all the input checks

The GP.sol contract could inherit directly from the OpenZeppelin ERC20PresetMinterPauser contract.

You should also think to add a Pause mechanism in order to block the minting/burning in case of a critical situation.

WD-010: add admin mechanism should validate the address

All the addAdmin and removeAdmin functions should check to not give to the 0 address the admin role

SacrificialAlter.sol

WD-011: `setContracts` should revert if `_gp` address is `0 address`

Doing so you could remove the requireContractsSet and use the pause function when you need to block the

WD-012: `maxSupply` in `setType` can be == 0?

Without a full specification or documentation doc and without any comments in code is difficult to understand if the check is needed

WD-013: `exchangeAmt` in `setExchangeAmt` can be == 0?

Setting it to 0 means that people are able to mint without paying GP.
Without a full specification or documentation doc and without any comments in code is difficult to understand if the check is needed.

WD-014: possible reentrancy issue

Please always follow the Checks-Effects-Interactions Pattern from Solidity docs to prevent reentrancy issues.

Every time you do an external call always remember to update your state and emit events before it. For example in the burn and mint methods. It's true that both methods check if the sender is the admin but even an admin could exploit the contract.

WD-015: `updateOriginAccess` is updating incorrectly `lastWrite[tx.origin].time`

In the function you are doing lastWrite[tx.origin].time = uint64(block.number); when instead you should use block.timestamp

Be aware that block.timestamp is a uint256 (same for block.number) as noted by the Solidity Documentation.

Traits.sol

WD-016: unbound array

looping over uploadTraits that is an unbound array could raise an auto-of-gas denial of service. it seems that traitData at max can contain 2^8 items so check that traits.length is less than 2^8.

WD-017: `setWnD` wndNFT could be set 0x address

Check that the _wndNFT parameter of setWnD function is != 0x address

WD-018: BASE 64 code could be replaced by an external library

You could replace the code of the base64 function by installing the original library and including it (like an external library as OpenZeppelin): https://github.com/Brechtpd/base64

WnD.sol

WD-019: check that _maxTokens respect what's written in the comments

In comments you say

// max number of tokens that can be minted: 60000 in production
uint256  public maxTokens;

but in the contract's constructor, you set maxTokens directly from the parameter. If the correct number of max tokens to be minted is 60000 just remove it from the constructor and declare it as a constant. If you want to still be parametrized think about setting it as immutable to reduce gas cost.

If maxTokens is set to 0 no one would be able to mint tokens.

WD-020: add checks on `setContracts` parameters

Check that those contracts address are != 0 address. If so you could remove the requireContractsSet and just use the paused flag/modifier reducing the logic complexity and having always a correct state.

WD-021: `generate` is an internal method that returns a `WizardDragon` but its return value is never used

In the mint function generate is called but the return value is never used. Think about using it instead of accessing to tokenTraits[minted] or just remove the returns statement.

WD-022: `updateOriginAccess` assign the incorrect value to `lastWrite[tx.origin].time`

As far as I get it should be lastWrite[tx.origin].time = uint64(block.timestamp)
Be aware that block.timestamp is a uint256 (same for block.number) as noted by the Solidity Documentation.

It's important to set the correct value because lastWrite[tx.origin].time is used as an input of the random function in generate

WD-023: `_paidTokens` parameter of `setPaidTokens` should have the same int type of `PAID_TOKENS`

WD-024: check `setPaidTokens` parameter value

PAID_TOKENS is used in WNDGame.sol. It could happen that the owner of the contract set a number equal to 0 and all the minted tokens in WNDGame would be minted for free.

WD-025: be aware of modifier orders in `setPaused`

If the requireContractsSet revert you will not be able to pause/unpause the contract. Orders of function modifiers matter!

WNDGame.sol

WD-026: define `presalePrice` as a `constant` if it never change

WD-027: add param checks in `setContracts`

Like other contracts, you could add checks on those addresses to be sure to be different from 0x address and different one between the other (gptoken cannot be equal to traits address!). In that case, you can remove the requireContractsSet and just use the pause modifier if needed.

WD-028: `startedTime` can be resetted multiple time.

If the owner calls setPublicSaleStart multiple time during the contract life he can reset the value of startTime that is used in currentPriceToMint

WD-029: `addToWhitelist` can reset an account whitelisting allowing it to mint more than 2 tokens in whitelist period

Scenario:

addToWhitelist is called whitelisting Alice address addr1.
Alice mint 2 items in whitelist period
Admin call again addToWhitelist with Alice's address as a parameter. Alice whitelisting metadata gets reset and can mint again.

Given that the contract is not tracking all these methods with events it's impossible to know that the admin has reset the whitelist of some addresses.

WD-030: add nonReentrancy on both `makeTreasureChests` and `sellTreasureChests`?

Kinda tired right now but I think that you should add a reentrancy guard in there because they are internally calling the altar mint/burn that makes an external call. Double-check it.

Update 1: an official GitHub repository

The team behind the game has provided an updated version of the contracts on their GitHub repository. Still, no specification, documentation, or tests are added.

How to create tests for your Solidity Smart Contract

Emanuele Ricci — Sat, 16 Oct 2021 16:54:05 +0000

If you have followed all my previous blog posts and you had a peek at the code of all the contracts I have created you should already have seen that I always write tests for every smart contract I create.

Have you missed those projects? Well, don’t worry, here’s a list to refresh your memory:

In each of those blog posts you have a GitHub repository where you can see the contract and test code, so don’t wait and give it a read before continuing!

Why should you bother to write tests?

I know, you have written your Solidity smart contract, you have already started the React dev server and you just want to interact with your smart contract deploying it to the main net yoloing everything.

I know that feeling, I know that excitement you get. And you could ask me “Tests are BORING!, why should I bother to write them? Let’s deploy things and see what happen”

Nope, tests are not boring and they are not difficult to write if you know what you need to test and what your contract should and shouldn’t do!

Your smart contract when deployed is immutable, remember that always. You need to be sure that things work as you expect when you deploy them. You can’t predict how others (users or contracts) will interact with it.

But tests come to the rescue you, and while you will write them (and I can assure you that you will write them fast) you will notice all the bugs, errors, and not implemented things you have missed while writing your code.

It’s like reviewing something from a different point of view.

With tests you can:

Automate how accounts (wallets) and external smart contracts interact with your contract. Do you really want to do everything manually?
Check that calling a function with specific input gives the expected output: correct returned value and correct and correct contract’s state
Check that all the require statements work as expected
Check that events are correctly emitted
Check that user, contract and token balances correctly change after a transaction
Check that your last-minute change or a new function that interacts with other parts of the code does not break other tests.

🛠 Tools you should use when developing

Many common errors can be easily covered using specific tools that you should always have:

If you want to know more about those tools and how to use them in your Solidity Hardhat project follow my previous post “How to deploy your first smart contract on Ethereum with Solidity and Hardhat”.

Another great suggestion is to not reinvent the wheel. If your contract is about creating a Token (ERC20) or an NFT (ER721) just use an OpenZeppelin contract. They provide secure and optimized implementations of those standards and you can be sure that they are more than battle-tested!

What should you cover in tests?

Before starting writing test coverage I try to think about which tests I need to develop. This is my personal test checklist so it can differ between developers and developers but I think that it can be taken as a good start.

When you write tests you need to cover two main aspects:

Known bugs / exploits / common errors
Check that for each of your functions that are externally or publicly accessible given a specific input you get the output you expect. When I say output it can be both a state change of your contract or values returned by your function. If some of these functions break people could burn all the transaction gas, lose money or get the NFT stuck forever.

Cover Known bugs/exploits/common errors

This part is both easy and hard at the same time. It’s easy because these errors that your smart contract code needs to cover are already known. The hard part is to know all of them and remember where in your code they could happen.

I have collected some really good content about ethereum and smart contract security and best practice. I strongly suggest you to

Secureum on Twitter and its founder 0xRajeev and their newsletter archive
Solidity by Example has a list of Hacks
OpenZeppelin Smart Contract Security Guidelines
Ethereum smart contracts security recommendations and best practices by Guy Lando
Known Attacks and Secure Development Recommendations by Consensys
Ethereum Smart Contract Security Best Practices by Consensys

Cover the implementation of your own functions

When you start writing tests you need to have in mind very clear which are the actors, which is the context, which is the state of the world before the transaction and after a transaction.

For example:

You have implemented an NFT contract and at mint time you want to limit people to mint only 2 NFT per transaction with a total of 10 NFT per account.

In this case:

Actors: User’s wallet and Contract’s wallet
Context: NFT sale
State before: user has X1 ETH and Y1 NFT, the contract has Z1 ETH and W1 NFT
State after (if everything goes well): user has X2 ETH and Y2 NFT, the contract has Z2 ETH and W2 NFT

When you write a test for the implementation of your own functions you need to start answering these questions:

Have I covered all the edge cases?
Is the function reverting when expected?
Is the function emitting the needed events?
With a specific input, will the function produce the expected output? Will the new state of the Contract be shaped as we expect?
Will the function returns (if it returns something) what we are expecting?
Has the user’s wallet and contract’s wallet changed their value as expected after the transaction

Some useful tips

I’ll list some useful concepts and functions that I created while I was writing tests for different smart contracts.

How to simulate blockchain mining in your test

When you create unit testing you are using Hardhat local blockchain and not a “real” one where people mint blocks every X seconds. Locally you are the only one interacting with the blockchain and it means that you are the only one creating transactions and minting blocks. It could happen that you need to simulate “time passing” because you need to make some checks on the block.timestamp . The timestamp of the block is updated only if a transaction happens.

To solve this issue on our test I have implemented a little utility:

When you callincreaseWorldTimeInSeconds(10, true) it will increase the EVM internal timestamp 10 seconds ahead of the current time. After that, if you specify it, it will also mine a block to create a transaction.

The next time that your contract will be called the block.timestamp should be updated.

How to impersonate an account or a contract

In the latest contract, I needed to test an interaction from ContractA that was calling ContractB. In order to do that I needed to impersonate ContractA

It can be easily be done like this

Waffle

Waffle is a library for writing and testing smart contracts that work with ethers-js like a charm.

Waffle is packed with tools that help with that. Tests in waffle are written using Mocha alongside with Chai. You can use a different test environment, but Waffle matchers only work with _chai_.

To test our contract we will use Chai matchers that will verify that the conditions we are expecting have been met.

After you have written all your test you just need to type yarn test and all your tests will be automatically run against your contract.

Chai matchers

Matchers are utilities that make your test easy to write and read. When you write tests usually you can think about them like this

expect(SOMETHING_TO_EXPECT_TO_HAPPEN).aMatcher(HAPPENED);

So you are expecting that something matches something else that has happened.

For example:

When you call contractA.emitEvent() it will emit a specific event NFTMinted with specific parameters
When you call contractA.mint(10) the transaction has been reverted because users are allowed to mint at max 2 NFT per transaction
and so on

I’ll list all the available matchers, go to the documentation to know how to use them:

Bignumber: testing equality of two big numbers (equal, eq, above, gt, gte, below, lt, lte, least, most, within, closeTo)
Emitting events: testing what events were emitted with what arguments. Only indexed event parameters can be matched
Called on contract: test if a specific function has been called on the provided contract. It can be useful to check that an external contract function has been correctly called. You can also check if that function has been called passing specific arguments.
Revert: test if a transaction has been reverted or has been reverted with a specific message.
Change ether balance: test that after a transaction the balance of a wallet (or multiple one) has changed of X amount of ETH. Note that changeEtherBalance won’t work if there is more than one tx mined in the block and that the expected value ignores fee (gas) by default (you can change it via options)
Change token balance: same thing as the changeEtherBalance but this matcher tests that a specific token balance has changed of an X delta (instead of ETH).

Advanced Waffle

Waffle offers much more than only matchers and you could build tests even without using hardhat as a local chain.

Creating a Mocked Provider for your tests
Getting wallets from a Mocked Provider
Deploying a contract
Using fixtures to speed up tests when you need to automate some tasks like deploying contracts and adding funds to them. Waffle execute once and then remember those scenarios by taking snapshots of the blockchain

WorldPurpose Contract

I have created a basic smart contract in order to be able to write test coverage for it. The smart contract is called WorldPurpose and the scope for this contract is to allow people to set a World Purpose paying investment to be the one to decide which is the purpose for the whole of humanity. Everyone can override the world's purpose, you just need to invest more money. The previous owners of the purposes can withdraw their funds only when their purposes are overridden.

The most important method in this smart contract are:

function setPurpose(string memory __purpose_) public payable onlyNewUser returns (Purpose memory _newPurpose_)
function withdraw() public

Let’s see the entire code of the contract, we are going to discuss how to create a test later on

Test Coverage

Let’s assume that you already have a working hardhat project, fully set up with all the libraries installed. If you don’t already have one just clone my solidity-template project.

So first of let’s set up the test file. Usually, I create a test file for each contract. If the contract is big, it has a lot of functions and so a lot of tests maybe it could be a good thing to split each function’s test into different files, but this is just up to you and how you usually manage your project’s structure.

Let’s create a worldpurpose.js file inside our /test folder at the root of our project. If you want to use TypeScript (as I usually do, head over to the template project to see how to create tests with TypeChain and Typescript)

Inside of it, we are going to write this code that I’ll explain

describe is a function that describes what the test is about, what we are going to be testing in this file. It’s useful to structure and read the code and organize the output of our shell when we will run the test.

beforeEach is a function that is executed before every single test. In this case for each test that we add to our test coverage file, a new worldPurpose contract will be deployed. We want to do that because in this case we always want to start a test from a clean checkpoint (everything is reset).

Now, for every function, we are going to set up a new describe function. And inside of them, we will create a test to cover a specific scenario thanks to the function it that will run the test itself.

For example

describe('Test withdraw', () => {  
  it('You cant withdraw when your balance is empty', async () => {  
    const tx = worldPurpose.connect(addr1).withdraw();await expect(tx).to.be.revertedWith("You don't have enough withdrawable balance");  
  });  
});

Ok now that we know how to structure a test let’s review them.

Create tests for the setPurpose function

If we review the solidity code of the function we see that:

it has a function modifier onlyNewUser that check that the msg.sender is different from the current purpose owner. We don’t want that the owner can override his/her purpose
it requires that ether be sent (the method declared as payable) is greater than the current purpose investment value
it requires that the string memory _purpose input parameter (the purpose value) is not empty

If everything passes these checks the function will

update the current purpose
track the investment of new purpose’s owner in a balances variables
emit a PurposeChange event
return the new purpose struct

For each of these requirements, state changes, event emitted, and returned value we need to create a test. Keep in mind that this is a “simple contract” without contract-to-contract interactions or complex logic.

These are the test we need to implement:

❌ user can’t override his/her own purpose
❌ user can set a purpose if the investment is 0
❌ purpose message must be not empty
❌ if there’s already a purpose and the user wants to override it, he/she must invest more than the current purpose’s investment
✅ user set a purpose successfully when there’s no current purpose
✅ user overrides the previous purpose
✅ setting a purpose correctly emit the PuposeChange event

Let’s review some of those. This is the code that covers the first scenario in the previous list:

it("You can't override your own purpose", async () => {  
  await worldPurpose.connect(addr1).setPurpose("I'm the new world purpose!", {  
    value: ethers.utils.parseEther('0.10'),  
  });const tx = worldPurpose.connect(addr1).setPurpose('I want to override the my own purpose!', {  
    value: ethers.utils.parseEther('0.11'),  
  });await expect(tx).to.be.revertedWith('You cannot override your own purpose');  
});

In this case, we want to test that if the current owner of the purpose tries to override his/her own purpose the transaction will be reverted.

Let’s review the code

worldPurpose is the variable that contains the deployed contract (deployed by the beforeEach method before every test)

worldPurpose.connect(addr1) allow you to connect to the contract with the wallet’s address of the account addr1

await worldPurpose.connect(addr1).setPurpose("I'm the new world purpose!", {

value: ethers.utils.parseEther('0.10'),

});

addr1 invoke the setPurpose function of the worldPurpose contract passing I’m the new world purpose! as _purpose input parameter. The value parameter is how much ether will be sent with the transaction. In this case 0.10 ETH

The second part of the test tries to repeat the same operation but we already know that it will fail because the same address cannot override the purpose.

We are going to use the Waffle matcher to check that the transaction has been reverted with a specific error message.

await expect(tx).to.be.revertedWith('You cannot override your own purpose');

});

Easy right?

Now it’s your turn to write all the other reverting tests that need to be covered.

Let’s see the code of a “success” scenario (the fifth one on the previous list) where we want to cover the case where the user successfully overrides a purpose.

it("set purpose success when there's no purpose", async () => {  
  const purposeTitle = 'Reduce the ETH fee cost in the next 3 months';  
  const purposeInvestment = ethers.utils.parseEther('0.1');  
  await worldPurpose.connect(addr1).setPurpose(purposeTitle, {  
    value: purposeInvestment,  
  });// Check that the purpose has been set  
  const currentPurpose = await worldPurpose.getCurrentPurpose();  
  expect(currentPurpose.purpose).to.equal(purposeTitle);  
  expect(currentPurpose.owner).to.equal(addr1.address);  
  expect(currentPurpose.investment).to.equal(purposeInvestment);// Check that the balance has been updated  
  const balance = await worldPurpose.connect(addr1).getBalance();  
  expect(balance).to.equal(purposeInvestment);  
});

We have already explained the first part where the addr1 call the setPurpose function.

Now we want to be sure that the purpose has been written into the contract’s state and that the user’s investment has been tracked correctly into the balances variable.

We call the getCurrentPurpose getter function to get the current purpose of the contract and for each member of the struct Purpose we check that the value is equal (.to.be) to the one we expect

After that, we check that the balance of addr1 (worldPurpose.connect(addr1).getBalance()) is equal to the amount of ether we have sent with the transaction.

We could also check that the event PurposeChange has been emitted by the function (in the code we are doing it in another test). To do that we can write

await expect(tx).to.emit(worldPurpose, 'PurposeChange').withArgs(addr1.address, purposeTitle, purposeInvestment);

Create tests for the withdraw function

We calculate the withdrawable amount by the msg.sender. If the sender is also the owner of the current world’s purpose we subtract the purpose.investment from the balances[msg.sender].

With that in mind we need to do some checks:

withdrawable the amount must be greater than zero
msg.sender.call{value: withdrawable}("") must return success (user has withdrawn successfully the amount)

If everything passes these checks the function will

update the user’s balance to balances[msg.sender] -= withdrawable

These are the test we are going to implement

❌ user can’t withdraw because he has an empty balance (never set a purpose)
❌ user can’t withdraw because he’s the current owner of the purpose. his/her withdrawable amount is 0
✅ user1 has set a purpose, someone else has overridden the purpose so user1 can withdraw the whole amount
✅ user1 has set a purpose, someone else has overridden it but user1 set a new purpose for the second time. In this case, he can withdraw only the first purpose investment

Let’s review the code of the success scenario (the third one in the previous list) and you will be in charge to implement the other tests.

it('Withdraw your previous investment', async () => {  
  const firstInvestment = ethers.utils.parseEther('0.10');  
  await worldPurpose.connect(addr1).setPurpose('First purpose', {  
    value: ethers.utils.parseEther('0.10'),  
  });await worldPurpose.connect(addr2).setPurpose('Second purpose', {  
    value: ethers.utils.parseEther('0.11'),  
  });const tx = await worldPurpose.connect(addr1).withdraw();// Check that my current balance on contract is 0  
  const balance = await worldPurpose.connect(addr1).getBalance();  
  expect(balance).to.equal(0);// Check that I got back in my wallet the whole import  
  await expect(tx).to.changeEtherBalance(addr1, firstInvestment);  
});

We have already seen the setPurpose function so the first part should be pretty straightforward.

addr1 set a purpose with 0.10 ETH investment, addr2 override the purpose of investing 0.11 ETH

addr1 call the withdraw() function. The contract checks how much he can withdraw and send the amount back to his/her wallet.

In this test scenario, we check that after the transaction has been minted:

the getBalance the function of the contract must return 0 (he/she has withdrawn all the balance)
the transaction should have changed the ether balance of the addr1 wallet of the same amount he has invested when he/she has invoked the setPurpose, in this case 0.10 ETH

Now it’s your turn to implement the remaining tests!

Run all tests together

When you have finished writing down all your tests just run this command to run them npx hardhat test. You should see a result similar to this:

Well done! You have just created your first test file for your solidity project!

Did you like this content? Follow me for more!

Rarity Achievement System: update and release date

Emanuele Ricci — Sat, 02 Oct 2021 06:36:44 +0000

I have already introduced the project some days ago with the previous blog post “Proof of Concept of an Achievement System for Rarity”.

In the last couple of days, I’ve dedicated my spare time to refactor the whole project changing some strong requirements I had hardcoded with it.

So let’s view what has changed, how other smart contract developers or web3 developers can integrate with it, and when I’ll release the contract.

But first, just a TL;DR on what’s this project about!

TL;DR: What’s the project about?

Rarity Achievement is a smart contract to create a decentralized achievement system for Rarity by Andre Cronje. The concept of the project can be adapted and adopted by other crypto games in the ecosystem.

For the summoner

Track the total amount of achievement points earned by the summoner while playing the game
Track the list of achievements earned

For the other contracts/web developers

Enable a way to unlock achievements when the user interacts with a contract
Enable to unlock content if the user has reached a certain amount of achievements points or has unlocked a specific achievement

What does this enable for the ecosystem?

Players are more engaged to play the game to earn achievements
Contract with achievements will be used more
The overall longevity of the Rarity game is extended
Other contracts / dApp could enable some content only if the user has reached a minimum level of achievements points
Achievements points (that’s just an idea) could be “burned” to purchase specific items payable with achievements points instead of golds
More concepts to come

What has changed since the last time?

First of all, I would like to thanks all the people that have given me feedback from Twitter and Discord. A special mention to @Newti from the Rarity Discord, he has helped me a lot giving me feedback and suggestions on some specific mechanics I should adopt.

Remove all the source and achievement whitelisting process

In the first version of the smart contract, I implement a whitelisting process to only accept legit smart contracts to be able to register achievements.

It was the perfect green garden but the process was too complex and the adoption of the project was doomed by the start. It could have been fine for a PoC but not for a real-world use case or at least not for the current state of the blockchain ecosystem.

So now every smart contract (even if it’s not from the Rarity ecosystem) can register achievement metadata and can award achievements to a summoner.

So you will be asking me

Aren’t you afraid that malicious users could create achievements and spam/send junk achievements to summoners?

Yup. That was the reason why I originally structured the logic to force smart contract developers to be whitelisted in order to register achievement metadata.

But as Newti suggested to me, that’s not the correct solution. The correct solution is to allow anyone to do whatever they want but allow frontend dev or other smart contract developers to be able to filter the list of achievements owned by the summoner.

Filter awarded achievements and achievement points

The second big part of the refactor was on the getters for both achievements and achievement points.

I needed to allow other developers to only get achievements from the whitelisted or recommended list of smart contracts.

So now you can specify a list of contract addresses on the getAchievements and getPoints.

How to interact with the contract?

For smart contract developers that want to register and award achievements

If you want to see an example of a contract that integrate with RarityAchievement you can look at RarityBlockSandbox.sol

What your contract needs to do is

First of all, you need to import both the RarityAchievement interface and Model

import “../interfaces/AchievementInterface.sol”;  
import “../data/AchievementModel.sol”;

Save a reference to the RarityAchievement contract like this

AchievementContractInterface _ac;

Declare the Achievement Metadata ID used by your contract

uint256 private mobAchievement;  
uint256 private miniBossAchievement;  
uint256 private bossAchievement;

Register your achievement metadata calling _ac.registerAchievement(achievementMetadata); for each of your contract’s achievements.

registerAchievement takes a metadata as input and return the metadataID you need to send the contract when you want to award an achievement to a summoner.

The model of the metadata is like this:

AchievementModel.AchievementMetadata metadata = AchievementModel.AchievementMetadata({  
    id: 0, // ID here is not important, will be replaced by the AchievementContract  
    source: address(this), // source is not important, will be replaced by the AchievementContract  
    source_name: "The nightmare dungeon!",  
    difficulty: AchievementModel.Difficulty.Uncommon,  
    title: "Defeated first miniboss",  
    description: "You have been brave enough to defeat the Eruptus, the mini boss of 'The Fantom Dungeon'",  
    points: 10  
})

I’ll explain each of those

idis the ID of the metadata. You can pass 0 because it will be replaced by the RarityAchievement contract when you call the registration process
source is your contract’s address
source_name is the name of your contract. For example The Fantom Dungeon, it will be used by web apps to know from which contract the achievement comes.
difficulty is how difficult is to get this achievement. It goes from Common to Legendary
titleis the title of the achievement
description is the description of the achievement
points are the number of achievement points that the summoner will receive when awarded the achievement. Try to be fair otherwise, your contract will not be used by other web apps/contracts!

id and source are optional, they will be replaced by the RarityAchievement contract, other properties are required, otherwise, the transaction will revert!

When you have registered all your achievement you just need to award those achievements when the summoner has done some specific action like for example

Beaten a difficult boss
Crafted 100 swords
Collected 100.000 gold
Reached level 10
Defeated 10 times a dungeon
…

To award an achievement to a summoner you need to call _ac.awardAchievement(summonerId, achievementMetadataId);.

Please be aware that:

You can award only achievement that your contract owns
You cannot award multiple time the same achievement to the same summoner

If you want to be sure that a summoner already owns an achievement you can call _ac.hasAchievement(summonerId, achievementMetadataId);

For web3 developers / other integration

If you want to build a frontend to list the summoner’s achievement you are in the right place. These functions could also be used by other smart contract developers to create derivative contracts.

For example, you could allow a summoner to craft the ultimate sword only if he owns the achievement unlocked after crafting 100 swords. Or you can allow accessing the final dungeon only if the summoner owns all the achievements from previous dungeons and so on. Just use your imagination!

Back to web3 devs. You have 3 utility functions you can call:

hasAchievement(uint256 summonerId, uint256 metadataId) will return a bool. It will be true if the summoner owns a specific achievement.

getPoints(uint256 summonerId, address[] memory sources) it will return the total amount of achievement points owned by the summoner.

The sources is an array of whitelisted contracts from which you want to filter the achievements from. For example, you want to get only points gained by ContractA and ContractB contracts, you just need to pass those addresses as an array.

If you don’t want to filter at all, just pass an empty array like this []

function getAchievements(uint256 summonerId, address[] memory sources, uint256 offset, uint256 limit) will return the list of Achievements owned by the summoner. The sources parameter is used for the same reason: get only the achievement awarded from those contract addresses. The offset and limit parameters are used to paginate the results (because of RPC limitations). Use them only if you get some errors while querying the contract otherwise just pass 0 as the offset and 9999999999 (or any big number) as the limit.

When will it be released?

I’m planning to take the weekend to apply some final touch to the code, release it on testnet and as soon as I’m satisfied with the result I’ll release it on the main net. So at max a couple of days more!

Feedback, help, new ideas?

I’m open to discussion and feedback, if you have any please DM me on Twitter @StErMi or open a GitHub issue/PR!

Proof of Concept of an Achievement System for Rarity

Emanuele Ricci — Fri, 24 Sep 2021 06:29:03 +0000

I think that everyone here knows already what Rarity is right?

TLDR; Rarity is a project created by Andre Cronje. You can think about it as D&D on the blockchain. Rarity is deployed on Fantom Opera (FTM) because of its speed and low-cost fees.

What I really liked about Rarity is the idea of a framework of Smart Contracts. Each smart contract is like a building block (Contract) that interacts with other building blocks. For example, the core block is the Summoner. Each summoner can have skills, grind golds, level up, craft equipment, or adventure into a Dungeon.

Every building block can be created by anyone, not just the creator of the game, it just needs that the community recognize it and start using it. This is a fully decentralized game.

And the cool thing is that everything and I mean everything is owned by the Summoner that is an NFT itself. You don’t own golds, the summoner does. You will not find items inside your wallet as NFTs, your summoner will be the owner.

Why create an Achievement System?

I wanted to be part of this. I wanted to be part of a stepping stone that is creating a new kind of game development mechanics. I wanted to be able to contribute to it and learn from this experience. That’s why I’ve come with the idea to create an Achievement System for the Summoner that other contracts need to call like a decentralized API.

What does it do?

For the summoner

Track the total amount of achievement points earned by the summoner while playing the game
Track the list of achievements earned

For the other contracts

Enable a way to unlock achievements when the user interacts with a contract
Enable to unlock content if the user has reached a certain amount of achievements points

How does it work?

To make it works and not allow random contracts to spam achievements I needed to make some ground rules. This is just a PoC and I hope to get some feedback that will allow me to find a more elegant and scalable solution.

The ground rules are these:

Achievements are bonded to the Summoner and not the Player
Summoner’s achievements are unique. You can’t unlock the same Achievement more than one time (at least for the moment).
Only whitelisted (approved by the Achievement System owner) contracts can add Achievements Metadata
Each contract can add a maximum of 10 achievements (this number needs to be defined better)
A contract can unlock a summoner’s achievement only if it’s the owner. For example, ContractA can unlock AchievementZ to summoner only if that specific achievement has been added by the ContractA itself. ContractA cannot ask the system to unlock an achievement owned by ContractB.

Whitelisting contracts and achievements at the moment is the only way I had in mind to solve the spam/garbage issue that could come.

What does this enable for the ecosystem?

Players are more engaged to play the game to earn achievements
Contract with achievements will be used more
The overall longevity of the Rarity game is extended
Other contracts / dApp could enable some content only if the user has reached a minimum level of achievements points
Achievements points (that’s just an idea) could be “burned” to purchase specific item payable with achievements points instead of golds
More concepts to come

What needs to be done? How could you help?

If you want to follow the development of the project just head over these links:

Rarity Achievement System on GitHub: https://github.com/StErMi/rarity-achievements
Achievement System proposal on Rarity’s GitHub: https://github.com/andrecronje/rarity/issues/65

This is still a Proof of Concept so it needs to be polished and things can change.

What I don’t like of the current implementation

“centralized” way to whitelist contracts that can add and unlock summoner’s achievements
contracts needs to hold FTM in order to whitelist and unlock achievements because it costs gas
the current “flow” it’s not superfluid, each contract must be whitelisted by hand and they need to implement a method that calls the whitelistAchievements

Every feedback, suggestion, and PR is very appreciated so don’t hesitate to create a GitHub issue or DM me on twitter!

How to deploy your first smart contract on Ethereum with Solidity and Hardhat

Emanuele Ricci — Sat, 18 Sep 2021 06:37:57 +0000

I was planning to release a tutorial on how to deploy your first NFT smart contract but while I was writing it I understood that more than half of the content was about how to set up Hardhat to have the perfect development environment ready to go for your next project.

So let’s start from here and when I’ll release the NFT tutorial you can leverage the work we have done today to be ready instantly to start developing your next smart contract. Shall we proceed?

What are you going to learn today?

Configure Hardhat to compile, deploy, test, and debug your Solidity code
Write a smart contract
Test your smart contract
Deploy your smart contract on Rinkeby
Get your smart contract verified by Etherscan

Hardhat

Hardhat is the core tool we will be using today and a must-have if you need to develop and debug your smart contract locally before deploying it on the test net and then on the main net.

What is Hardhat?

Hardhat is a development environment to compile, deploy, test, and debug your Ethereum software. It helps developers manage and automate the recurring tasks that are inherent to the process of building smart contracts and dApps, as well as easily introducing more functionality around this workflow. This means compiling, running, and testing smart contracts at the very core.

Why use hardhat?

You can run Solidity locally to deploy, run, test, and debug your contracts without dealing with live environments.
You get Solidity stack traces, console.log, and explicit error messages when transactions fail. Yeah, you heard it right, console.log in your Solidity contract!
Tons of plugins to add cool functionalities and allows you to integrate your existing tools. We will use a couple of them to feel that magic!
Full native support for TypeScript.

Useful links to learn more

Create your first Hardhat project

It’s time to open your Terminal, your Visual Studio code IDE, and start building!

What project are we going to build?

In this tutorial, we are going to build an “easy” smart contract. It will be pretty stupid but our main goal here is to configure hardhat and deploy the contract, not for the contract purpose.

What will the contract do?

Track the “purpose” of the contract in a string that will be publicly visible
You can change the purpose only if you pay more than the previous owner
You cannot change the purpose if you are already the owner
You can withdraw your ETH only if you are not the current purpose’s owner
Emit a PurposeChange event when the purpose has changed

Create the project, init it and configure Hardhat

Open your terminal and let’s go. We will call our project world-purpose!

mkdir world-purpose  
cd world-purpose  
npm init -y  
yarn add --dev hardhat  
npx hardhat

With npx hardhat the hardhat wizard will kickstart helping you configure your project.

Choose Create a basic sample project
Choose the default Hardhat project root because in this tutorial we are only configuring hardhat.
Confirm to add the .gitignore
Confirm to install the sample project's dependecies with yarn this will install some required dependencies for your project that we will use along the way

Now your project structure should have these files/folder

contracts where all your contracts will be stored
scripts where all your scripts/tasks will be stored
test where your smart contract tests will be stored
hardhat.config.js where you will configure your hardhat project

Important hardhat commands and concepts you should master

Hardhat Configuration file
Hardhat Tasks
npx hardhat node — Run the node task to start a JSON-RPC server on top of Hardhat Network (your local ethereum blockchain)
npx hardhat test — To run tests stored in the test folder
npx hardhat compile — To compile the entire project, building your smart contracts
npx hardhat clean — To clean the cache and delete compiled smart contracts
npx hardhat run —-network <network> script/path — To run a specific script in a specific network

Add TypeScript Support

As we said Hardhat supports typescript natively and we will be using it. Using javascript or typescript doesn’t change much but this is my personal preference because I think that it allows you to make fewer errors and understand better how to use external libraries.

Let’s install some needed dependencies

yarn add --dev ts-node typescriptyarn add --dev chai @types/node @types/mocha @types/chaiddd

Change the hardhat configuration file extension to .ts and update the content with this

Now create a default tsconfig.json in the root of your project with this content

{
  "compilerOptions": {
    "target": "es2018",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "outDir": "dist"
  },
  "include": [
    "./scripts",
    "./test"
  ],
  "files": [
    "./hardhat.config.ts"
  ]
}

Now update also the test file and script file to the typescript file type .ts and change their code.

Let’s test that everything is working correctly

npx hardhat test  
npx hardhat node  
npx hardhat run --network localhost scripts/sample-script.ts

Let’s add some Hardhat plugins and some code utilities

add solhint, solhint-plugin-prettier, and hardhat-solhint plugin

Now we want to add support to solhint a linting utility for Solidity code that will help us to follow strict rules while we develop our smart contract. These rules a useful for both follow the code style standard best practice and adhering to the best security approaches.

solhint+solhint prettier

yarn add --dev solhint solhint-plugin-prettier prettier prettier-plugin-solidity

Add a .solhint.json configuration file in your root folder

{  
  "plugins": ["prettier"],  
  "rules": {  
    "prettier/prettier": "error"  
  }  
}

Add a .prettierrc config file and add styles as you prefer. This is my personal choice

{  
  "arrowParens": "always",  
  "singleQuote": true,  
  "bracketSpacing": false,  
  "trailingComma": "all",  
  "printWidth": 120,  
  "overrides": [  
    {  
      "files": "*.sol",  
      "options": {  
        "printWidth": 120,  
        "tabWidth": 4,  
        "useTabs": false,  
        "singleQuote": false,  
        "bracketSpacing": false,  
        "explicitTypes": "always"  
      }  
    }  
  ]  
}

If you want to know more about solhint and its prettier plugin checkout their documentation site

hardhat-solhint

If you want to know more follow the Hardhat solhint plugin documentation.

yarn add --dev @nomiclabs/hardhat-solhint

and update the hardhat config adding this line to the import

import “[@nomiclabs/hardhat-solhint](http://twitter.com/nomiclabs/hardhat-solhint "Twitter profile for @nomiclabs/hardhat-solhint")”;

typechain for typed contract support

This part is totally optional. As I said I love typescript and I like to use it everywhere whenever it’s possible. Adding support to contract types allow me to know perfectly which functions are available, which parameters are needed of which type, and what are they returning.

You could totally go without it but I highly suggest you follow this step.

Why typechain?

Zero Config Usage — Run the compile task as normal, and Typechain artifacts will automatically be generated in a root directory called typechain.
Incremental generation — Only recompiled files will have their types regenerated
Frictionless — return type of ethers.getContractFactory will be typed properly - no need for casts

If you want to dig deeper into these projects and know all the possible configuration options you can follow these links:

Let’s do it

yarn add --dev typechain @typechain/hardhat @typechain/ethers-v5

Add these imports to your Hardhat config file

import '@typechain/hardhat'import '@nomiclabs/hardhat-ethers'import '@nomiclabs/hardhat-waffle'

Add "resolveJsonModule": true to your tsconfig.json

Now when you compile your contract typechain will generate the corresponding types into the typechain folder and you will be able to use it in your tests and web app!

Updated the tests file to use Typechain generated types

Update scripts in `package.json`

This part is totally optional but it allow you to run command faster and preconfigure them. Open your package.json and override the scripts section with these commands:

"scripts": {
  "clean": "npx hardhat clean",
  "chain": "npx hardhat node",
  "deploy": "npx hardhat run --network localhost scripts/deploy.ts",
  "deploy:rinkeby": "npx hardhat run --network rinkeby scripts/deploy.ts",
  "test": "npx hardhat test"
}

Now if you want to simply run the Hardhat node you can write in your console yarn chain and boom! We are ready to go!

If you have skipped the TypeScript part and you want to use only Javascript just change those .ts back to .js and everything will work as expected.

Developing the smart contract

Ok, now we are really ready to go. Rename Greeter.sol in your contracts folder to WorldPurpose.sol and we will start building from here.

Our contract needs to do these things:

Track the “purpose” of the contract in a struct
You can change the purpose only if you pay more than the previous owner
You cannot change the purpose if you are already the owner
You can withdraw your ETH only if you are not the current purpose’s owner
Emit a PurposeChange event when the purpose has changed

Concepts you should master

Smart Contract Code

Let’s start by creating a Struct to store the Purpose information

/// [@notice](http://twitter.com/notice "Twitter profile for @notice") Purpose struct  
struct Purpose {  
    address owner;  
    string purpose;  
    uint256 investment;  
}

Let’s now define some state variables to track both the current Purpose and user’s investment

/// @notice Track user investments
mapping(address => uint256) private balances;

/// @notice Track the current world purpose
Purpose private purpose;

Last but not least define an Event that will be emitted when a new World Purpose has been set

/// @notice Event to track new Purpose
event PurposeChange(address indexed owner, string purpose, uint256 investment);

Let’s create some utility functions to get the current purpose and the user’s balance that is still in the contract. We need to do that because balances and purpose variables are private so they cannot be accessed directly from external contract/web3 apps. We need to expose them via these functions

/**
 @notice Getter for the current purpose
 @return currentPurpose The current active World purpose
*/
function getCurrentPurpose() public view returns (Purpose memory currentPurpose) {
    return purpose;
}

/**
 @notice Get the total amount of investment you have made. It returns both the locked and unloacked investment.
 @return balance The balance you still have in the contract
*/
function getBalance() public view returns (uint256 balance) {
    return balances[msg.sender];
}

Now let’s create the setPurpose function. It takes one parameter as input: _purpose . The function must be payable because we want to accept some Ether in order to set the purpose (those ethers will be withdrawable by the owner the purpose has been overridden by someone else).

The transaction will revert if some conditions are not met:

_purpose input parameter is empty
the msg.value (amount of ether sent with the transaction) is empty (0 ethers)
the msg.value is less than the current purpose
the current world purpose owner tries to override his purpose (msg.sender must be different from the current owner)

If everything works we set the new purpose, update the balance and emit the event.

Now we want to allow users to withdraw their investment from previous purposes. Please note that only the current purpose’s investment is “locked”. It will be unlocked only when a new person will set the new purpose.

Deploy it locally just to test that everything works as expected. You should see something like this:

Contract deployment on local blockchain successful

Add local Test

Now I will not go into detail about the code inside the testing file but I’ll explain the concept behind it. You should always create test cases for your contract. It’s a fast way to understand if the contact’s logic is working as expected and allows you to prevent deploying something that it’s not working.

My current workflow is like this: I take every function and I test that they do what I expect them to do in both success cases and revert cases. Nothing more, nothing less.

When you write tests for Solidity contracts you are going to use Waffle. Head over to their website to have an overview of the library, it’s really well made and offers a lot of utilities.

Now, delete the file you have in your test folder, create a new one called worldpurpose.ts and replace the content with this

Execute your tests with yarn test and see if everything pass as expected

Tests execution

Deploy your contract on test net

===== HUGE DISCLAIMER START =====
DO NOT USE YOUR MAIN WALLET PRIVATE FOR TESTING PURPOSES
USE A BURNER WALLET OR CREATE A NEW WALLET
===== HUGE DISCLAIMER END =====

We have already seen how to deploy the contract in our local hardhat chain but now we want to do it for the Rinkeby test net (the procedure is the same one for the main net but it’s not the scope of the tutorial).

To deploy on the local chain we just need to type on console this command

npx hardhat run --network localhost scripts/deploy.ts

To deploy your contracts on another network we just need to change the parameter value of --network but before doing that need to do some preparation step.

Get some ETH from testnet Faucet

Deploying a contact cost gas so we need some from a Faucet. Choose one test network and head over to the faucet to get funds.

In our case, we decided to use Rinkeby so go and get some funds over there.

Choose an Ethereum Provider

In order to deploy our contract, we need a way to interact directly with the Ethereum network. Nowadays we have two possible options:

In our case, we are going to use Alchemy, so go over there, create an account, create a new app and grab the Rinkeby API Key.

Update the Hardhat Config file

Install the dotenv dependencies, this nodejs library allow us to create a .env environment file to store our variables without exposing them to the source code.

yarn add --dev dotenv

Now create in the root of your project a .env file and paste all the information you have collected

RENKEBY_URL=https://eth-rinkeby.alchemyapi.io/v2/<YOUR_ALCHEMY_APP_ID>
PRIVATE_KEY=<YOUR_BURNER_WALLET_PRIVATE_KEY>

I can’t stress enough. Don’t use your main wallet private case for testing purposes. Create a separate wallet or use a burning wallet to do this type of testing!

The last step is to update the hardhat.config.ts file to add dotenv and update the rinkeby information.

At the top of the file add require("dotenv").config(); and now update the config like this

const config: HardhatUserConfig = {
  solidity: '0.8.4',
  networks: {
    rinkeby: {
      url: process.env.RENKEBY_URL || '',
      accounts: process.env.PRIVATE_KEY !== undefined ? [process.env.PRIVATE_KEY] : [],
    },
  },
};

Are we ready? Let’s deploy it!

npx hardhat run --network rinkeby scripts/deploy.ts

If everything goes well you should see something like this in your console

If you copy that contract address and past it on Etherscan Rinkeby you should be able to see it live! Mine is located here: 0xAf688A3405531e0FC274F6453cD8d3f3dB07D706

Get your contract verified by Etherscan

Source code verification provides transparency for users interacting with smart contracts. By uploading the source code, Etherscan will match the compiled code with that on the blockchain. Just like contracts, a “smart contract” should provide end users with more information on what they are “digitally signing” for and give users an opportunity to audit the code to independently verify that it actually does what it is supposed to do.

So let’s do it. It’s really an easy step because Hardhat provide a specific Plugin to do that: hardhat-etherscan.

Let’s install yarn add --dev @nomiclabs/hardhat-etherscan

and include it in your hardhat.config.ts adding import "@nomiclabs/hardhat-etherscan"; at the end of your imports.

The next step is to register an account on Etherscan and generate an API Key.

Once you have it we need to update our .env file adding this line of code

ETHERSCAN_API_KEY=<PAST_YOU_API_KEY>

and update the hardhat.config.ts adding the Etherscan config needed by the plugin.

The last thing to do is to run the verify task that has been added by the plugin:

npx hardhat verify --network rinkeby <YOUR_CONTRACT_ADDRESS>

The plugin have a lot of configurations and different options so check out their documentation if you want to know more.

If everything goes well you should see something like this in your console

Contract verified by Etherscsan

If you go over the Etherscan contract page again you should see a green checkmark on top of the Contract section. Well done!

Conclusion and next steps

If you want to use this solidity-template to kickstart you next smart contract project just head over to the GitHub repo https://github.com/StErMi/solidity-template and it the “Use this template” green button and boom, you are ready to go!

This is just the start, I’m planning to add more features in time like for example:

Support to eslint for the typescript testing lib
Support for hardhat-deploy, an Hardhat Plugin to better manage deployment
Add support to solidity-coverage plugin
Add support to hardhat-gas-reporter plugin
TBD

Do you have any feedback or do you want to contribute to the Solidity Template? Just create a Pull Request on the GitHub page and let’s discuss it!

Did you like this content? Follow me for more!

Unloot the Loot Project: my very first Solidity smart contract deployed on Ethereum

Emanuele Ricci — Tue, 14 Sep 2021 16:12:02 +0000

Before digging into why I’ve created Unloot I need to explain a little bit the Loot Project. So bear with me.

The Inspiration: The Loot Project

I think that at this moment everyone knows what the Loot Project is, right? If you still don’t know I will quote directly from their site for a TLDR;

Loot is randomized adventurer gear generated and stored on-chain. It’s a project created by Dom Hofmann. The initial total supply is 8,000 unique bags of adventurer gear. In each bag, you will find 8 items: chest, foot, hand, head, neck, ring, waist, and weapon.

Why is loot so unique?

Loot is unique — the first project of its kind. With no company, art, team, or attributes, Loot makes it impossible to gate-keep any creative decisions (h/t @john_c_palmer).

Loot is the unfiltered, uncensorable building block for stories, experiences, games, and more, in the hands of the community, at no cost. Loot pursues complete decentralization from day one.

At this specific moment, on OpenSea the Loot Project floor price is almost 6 ETH. What does it mean? That if you want to buy the lowest-priced bag it will cost you (with the current ETH-USD conversion) almost $20k.

It’s not a cheap start, right?

The Idea

I’m fairly new to the web3 world but I’m the kind of person that enjoys learning new things, experiment, build and release.

On Sunday, during a walk, I was thinking about this interesting project and how the current floor price on Open Sea was ruining what could have been an amazing concept to kickstart a whole new kind of project inside the blockchain.

I wanted to allow everyone to play with the Loot Project items but in order to do that people (poor like me :D) should be able to afford to buy at least a basic set of items or at least have the choice to pick whatever items they need to create their adventurer’s equipment.

That’s why while walking I started thinking about a solution and what I could build. The cool thing is that everything is new in web3/solidity and you need a different mental approach to solve issues compared to the “old” mental scheme of web2.

I wanted to create a PoC (proof of concept) in a couple of hours and release an MVP (minimum viable product) without bugs and issues in a couple more.

I got too excited, the idea to create something from scratch, on top of an existing project, on the most bleeding-edge technology at this very moment was too much. I rushed home and started developing…

The Unloot Project

The Unloot project is based on a very simple idea (as I explained before): allow people to afford items to build their equipment set with a low investment.

The smart contract is an ERC721 contract that implements two main functions

Unpack function

You pass the tokenId of your current Loot bag and it will unpack the items contained into your Loot NFT creating eight different Unloot items. Each Unloot NFT is bound to both the original bag and the type of item it represents from the bag.

So for example you own the Loot Bag #3 and you want to unpack it.

The result of the operation would be that you will own eight different Unloot NFT

Katana
Ornate Chestplate
Great Helm
Ornate Belt of detection
Ornate Greaves of Anger
Dragonskin Gloves
Necklace
Gold Ring of Titans

In order to call the unpack function on the contract, you need to approve the Unloot Contract to be able to transfer the Loot Bag to its contract itself. I will not go too deep in technical explanation in this blog post, I will release a specific one where I will explain how to create an identical contract, test it and deploy it on Rinkeby.

But bear with me, I tried a couple of solution to achieve a better user experience but you always arrive at the same point: you need to accept some security or complexity compromise to offer a better experience and sometimes it’s not worth, mostly when you need to deal with the current floor price of a Loot NFT.

Anyway, now you own those items. You can sell them separately on Open Sea, you can transfer a couple to one of your friends that still need a Katana or maybe you can trade one ring with a more powerful chest that you miss to enter that damn dungeon that you cannot defeat with your current inventory!

Repack function

The repack function (or we can call it un-do? :D) allows you to re-pack eight Unloot NFT into the original Loot bag only if those items you are trying to repack were coming from the same bag.

When the bag is transferred back to your wallet, those Unloot items will be burned.

The cool thing is that you don’t need to be the original owner of the Loot bag to repack it, those items could have been in the hands of many people, used for months, and at some point, you have just luckily found them on OpenSea, available to be bought and repacked in the holy grail of the original one.

Conclusion

Where can I test it?

Unloot Contract on Rinkeby: 0xd4c4900b0006B39482888d3712c9dBf45a98A2c3
Loot Contract on Rinkeby (clone of Loot Project just for testing purpose): 0x256AfE6504C04249D74fe7f7EA40575ec6a30bf8
UI on Rinkeby: https://loot-unloot.surge.sh/

So what can you do at the moment (I know the UI/UX is not great but this is just an MVP to test the idea):

Go on the Loot Contract tab and claim a Loot Bag (try some not claimed ID)
You should now see your Bag in the Loot list tab
Now what you need to do is to go on the Loot Contract and approve the Unloot address to transfer your Loot Bag the Unloot Contract
Now you can go to the Unloot Contract tab and execute the unpack function. Use your Loot tokenId as input
If you go to Unloot list you should see your bag exploded into 8 different Unloot NFT item.
Now you can do whatever you want with those items! Sell them on OpenSea, transfer them to a friend, exchange them with another adventure’s item.
If you own all the items from a Loot bag you can go to the Unloot Contract tab and repack those items to get back a Loot Bag. The UI is not super easy so you need to remember the ID of Unloot tokenId and input them from the smaller to the bigger one (smaller = sword, bigger = ring).

Why have you developed it?

Mostly because of four reasons

I want to grow in my web3/solidity path and learn fast
I like to build things
I wanted to create something on my own from scratch
This project allowed me to create content to share with the community that will learn from my experience

Is this project useful?

Yes and no, it could be if other contracts in the Loot Project ecosystem start to recognize and use items from the Unloot contract, otherwise, you would have at worst wasted some gas to just unpack and repack those items.

Are there other projects like this?

Yup, while I was talking with Austin Thomas Griffith on Telegram a couple of days ago showcasing this project he told me that another couple of devs have already released something similar. I’m talking about Loot Loose by Georgios Konstantopoulos

Where can I follow you?

How to create an ERC20 Token and a Solidity Vendor Contract to sell/buy your own token

Emanuele Ricci — Fri, 10 Sep 2021 18:15:19 +0000

In the previous scaffold-eth challenge, we have created a Staker dApp. In this challenge, we are going to create a Token Vendor contract.

The goal of the dApp

The goal of this challenge is to create your own ERC20 Token and a Token Vendor Contract that will handle the sell/buy process of your token exchanging it with ETH sent by the user.

What are you going to learn?

What is an ERC20 Token
How to mint an ERC20 Token
OpenZeppelin ERC20 implementation
Ownership of a Contract
How to create a Token Vendor contract to sell/buy your token

In addition to the content above we are going to learn a lot of new Solidity and web3 concepts and how to write well-made tests for your Solidity code. I’m going to skip some basic parts so if you feel lost just go back to the first challenge blog post and read all the explanations.

Some always useful links that you should always have in mind:

What is an ERC20 Token?

Before we start I will just give you an overview of what an ERC20 Token is quoting directly the Ethereum Documentation.

Tokens can represent virtually anything in Ethereum:

reputation points in an online platform
skills of a character in a game
lottery tickets
financial assets like a share in a company
a fiat currency like USD
an ounce of gold
and more…

Such a powerful feature of Ethereum must be handled by a robust standard, right? That’s exactly where the ERC-20 plays its role! This standard allows developers to build token applications that are interoperable with other products and services.

The ERC-20 introduces a standard for Fungible Tokens, in other words, they have a property that makes each Token be exactly the same (in type and value) of another Token. For example, an ERC-20 Token acts just like the ETH, meaning that 1 Token is and will always be equal to all the other Tokens.

If you want to know more about the ERC-20 token you can look at these links:

Setup the project

First of all, we need to set up it. Clone the scaffold-eth repository, switch to the challenge 1 branch and install all the needed dependencies.

git clone [https://github.com/austintgriffith/scaffold-eth.git](https://github.com/austintgriffith/scaffold-eth.git) challenge-2-token-vendor  
cd challenge-2-token-vendor  
git checkout challenge-2-token-vendor  
yarn install

To locally test your application

yarn chain to start your local hardhat chain
yarn start to start your local React app
yarn deploy to deploy/redeploy your contract and update the React app

OpenZeppelin and ERC20 Implementation

OpenZeppelin provides security products to build, automate, and operate decentralized applications.

We are going to use the OpenZeppelin Contract framework to build our own ERC20 Token.

The framework is a library for secure smart contract development. Build on a solid foundation of community-vetted code.

Implementations of standards like ERC20 and ERC721.
Flexible role-based permissions scheme.
Reusable Solidity components to build custom contracts and complex decentralized systems.

If you want to learn more about the OpenZeppelin implementation you can follow these links:

Exercise Part 1: Create your own ERC20 Token and deploy it!

In the first part of the exercise, you need to create a Token Contract inhering from OpenZepllein’s ERC20 Contract.

In the constructor, you have to mint 1000 token (remember that in Solidity an ERC20 token has 18 decimals) and send them to the msg.sender (the one that deployed the contract).

Remember to update the deploy.js file to send those tokens to the correct address. You can find your current address on the top right of your web application, just hit the copy icon!

To transfer tokens to your account, add this line to your deploy.js:

const result = await yourToken.transfer("**YOUR FRONTEND ADDRESS**", utils.parseEther("1000"));

Don’t be scared, I’ll explain later after reviewing the code.

Can you see on the frontend that the balanceOf your Wallet has those 1000 tokens?
Can you transfer() some of those tokens to another wallet address? Simply open a new incognito window on Chrome, type your localhost address and you should have a brand new burner account to send those tokens to!

Important Concepts to master

OpenZeppelin ERC20 Contract
Ethereum ERC-20 Standard
Inheritance — Contracts can inherit from other contracts by using the is keyword.
Shadowing Inherited State Variables — As explained by SolidityByCode unlike functions, state variables cannot be overridden by re-declaring them in the child contract

YourToken.sol

As you can see we are importing the ERC20.sol Contract from the OpenZeppelin library. That Contract is the OpenZeppelin implementation of the ERC20 Standard and they made an amazing job on both security and optimization!

When in your code you is ERC20 that code make your YourContract contract inherits all the function/state variables implemented in the ERC20 Contract from OpenZeppelin.

The amazing thing is that everything is open source. Try to CMD+click on the ERC20 keyword or on the _mint function.

As you can see when the constructor of our contract is called, we are also calling the ERC20 constructor passing two arguments. The first one is the name of our Token and the second one is the symbol.

The second important part is the _mint function, let’s take a look at it.

The first require you see is just checking that the minter (the one that will receive all the token minted) is not the null address.

_beforeTokenTransfer and _afterTokenTransfer are function hooks that are called after any transfer of tokens. This includes minting and burning.

In the rest of the code, we are updating the _totalSupply of the token (in our case it would be 1000 tokens with 18 decimals), updating the minter balance with the amount and we are emitting a Transfer event.

How cool is that? And in our TokenContract we have only called one function.

Remember that I said to updated the deploy.js file to transfer all those tokens to our wallet in the web app? The code was this:

await yourToken.transfer(‘0xafDD110869ee36b7F2Af508ff4cEB2663f068c6A’, utils.parseEther(‘1000’));

transfer is another function offered by the ERC20 Contract implementation.

I will not go much into detail but after checking that both the sender and recipient are not the null address the function will check if the sender has enough balance to transfer the requested amount, will transfer it and will also emit a Transfer event.

Exercise Part 2: Create a Vendor Contract

In this part of the exercise, we are going to create our Vendor Contract.

The Vendor will be responsible to allow users to exchange ETH for our Token. In order to do that we need to

Set a price for our token (1 ETH = 100 Token)
Implement a payable buyToken() function. To transfer tokens look at the transfer() function exposed by the OpenZeppelin ERC20 implementation.
Emit a BuyTokens event that will log who’s the buyer, the amount of ETH sent and the amount of Token bought
Transfer all the Tokens to the Vendor contract at deployment time
Transfer the ownership of the Vendor contract (at deploy time) to our frontend address (you can see it on the top right of your web app) to withdraw the ETH in the balance

Important Concepts to master

Events
Payable functions
Open Zeppelin Ownable & ownership — OpenZeppelin module used through inheritance. It will make available the modifier onlyOwner, which can be applied to your functions to restrict their use to the owner.
OpenZeppelin Address utility (not required but useful to known) — Collection of functions related to the address type. You could use it to safely transfer ETH funds from the Vendor to the owner
Transfer function from OpenZeppelin ERC20 contract — transfer(address recipient, uint256 amount) moves amount tokens from the caller’s account to recipient and returns a boolean value indicating whether the operation succeeded.
Sending ether — As we saw in the previous challenge always use the call function to do that!

Vendor.sol

Let’s review the important part of the code.

In the buyTokens() we are checking that the user has sent us at least some ETH otherwise we will revert the transaction (don’t be cheap!). Remember that in order to receive ETH our function must have the keyword payable.

After that, we calculate, based on the token price how many tokens he will receive with the amount of ETH sent.

We are also checking that the Vendor contract has enough balance of Tokens to fill the user buy request, otherwise we revert the transaction.

If every check goes well we trigger the transfer function of our Token Contract implemented inside the ERC20 contract that is inherited by the Token Contract (see the image above to view the code). That function is returning a boolean that will notify us if the operation was successful.

The last thing to do is to emit the BuyTokens event to notify to the blockchain that we made the deal!

The withdraw() function is pretty simple. As you can see it rely on the onlyOwner function modifier that we inherited by the Owner contract. That modifier is checking that the msg.sender is the owner of the contract. We don’t want another user to withdraw the ETH we collected. Inside the function, we are transferring the ETH to the owner and checking if the operation was successful. Another way to do that, as I said previously is to use the sendValue of the Address utility of OpenZeppelin.

Exercise Part 3: Allow the Vendor to buy back!

This is the last part of the exercise and it’s the most difficult one, not from a technology point of view but more from a concept and UX.

We want to allow the user to sell their token to our Vendor contract. As you know, Contract can accept ETH when their function is declared as payable, but they are only allowed to receive ETH.

So what we need to implement is to allow our Vendor to take Tokens directly from our Token’s balance and trust him to give us back the equal value amount of ETH back. This is called the “Approve approach”.

This is the flow that will happen:

The user requests to “approve” the Vendor contract to transfer tokens from the user’s balance to Vendor’s wallet (this will happen on the Token’s contract). When you invoke the approve function you will specify the number of tokens that you want to decide to let the other contract be able to transfer at max.
The user will invoke a sellTokens function on Vendor’s contract that will transfer user’s balance to Vendor’s balance
The vendor’s contract will transfer to the user’s wallet an equal amount of ETH

Important Concepts to master

approve ERC20 function — Sets amount as the allowance of spender over the caller’s tokens. Returns a boolean value indicating whether the operation succeeded. Emits an [Approval](https://docs.openzeppelin.com/contracts/4.x/api/token/erc20#IERC20-Approval-address-address-uint256-) event.
transferFrom ERC20 function — Moves amount tokens from sender to recipient using the allowance mechanism. amount is then deducted from the caller’s allowance. Returns a boolean value indicating whether the operation succeeded. Emits a [Transfer](https://docs.openzeppelin.com/contracts/4.x/api/token/erc20#IERC20-Transfer-address-address-uint256-) event.

An important note that I would like to explain: UX over security
This approve mechanism is not something new. If you ever used a DEX like Uniswap you already have done this.

The approve function allows other wallet/contract to transfer at max the number of tokens you specify within the function arguments. What does it mean? What if I want to trade 200 tokens I should approve the Vendor contract to only transfer to itself 200 tokens. If I want to sell another 100, I should approve it again. Is it a good UX? Maybe not but it’s the most secure one.

DEX uses another approach. To avoid to ask every time to the user to approve each time you want to swap TokenA for TokenB they simply ask to approve the MAX possible number of tokens directly. What does it mean? That every DEX contract could potentially steal all your tokens without you knowing it. You always should be aware of what’s happening behind the scene!

Vendor.sol

Let’s review sellTokens.

First of all, we check that the tokenAmountToSell is greater than 0 otherwise, we revert the transaction. You need to sell at least one of your tokens!

Then we check that the user’s token balance is at least greater than the amount of token he’s trying to sell. You cannot oversell what you don’t own!

After that, we calculate the amountOfETHToTransfer to the user after the sell operation. We need to be sure that the Vendor can pay that amount so we’re checking that Vendor’s balance (in ETH) is greater than the amount to transfer to the user.

If everything is OK we proceed with the (bool sent) = yourToken.transferFrom(msg.sender, address(this), tokenAmountToSell); operation. We are telling the YourToken contract to transfer tokenAmountToSell from the user’s balance msg.sender to the Vendor’s balance address(this) . This operation can succeed only if the user has already approved at least that specific amount with the approve function we already reviewed.

The last thing we do is to transfer the ETH amount for the sell operation back to the user’s address. And we’re done!

Update your App.jsx

In order to test this in your React app, you can update your App.jsx adding two Card to Approve and Sell tokens (see the GitHub code repo at the end of the post) or you can just do everything from the Debug Contract tab that offers all the needed features.

Exercise Part 4: Create a test suite

You know already from the previous post that Tests are a great foundation for the security and optimization of your app. You should never skip them and they are a way to understand the flow of the operations that are involved in the logic of the overall application.

Tests on Solidity environment leverage on four libraries:

Hardhat
Ethers-js
Waffle
Chai (part of Waffle)

Let’s review one test and then I’ll dump the whole code

Testing the sellTokens() function

This is the test that will verify that our sellTokens functions work as expected.

Let’s review the logic:

First of all addr1 buys some tokens from the Vendor contract
Before selling as we said before we need to approve the Vendor contract to be able to transfer to itself the amount of token that we want to sell.
After the approval, we double-check that Vendor’s token allowance from addr1 is at least the amount of the token addr1 needs to sell (and transfer to the Vendor). This check could be skipped because we know that OpenZeppeling has already battle-tested their code but I just wanted to add it for learning purposes.
We are ready to sell the amount of token we just bought using the sellTokens function of Vendor contract

At this point we need to check three things:

The user’s token balance is 0 (we sold all our tokens)
User’s wallet has increased by 1 ETH with that transaction
The vendor’s token balance is 1000 (we bought 100 tokens)

Waffle offers some cool utilities to check changes in ether balance and changes in token balances but unfortunately, it seems that there’s an issue on the latter one (check out the GitHub issue I just created).

Test coverage complete code

Final step: deploy your Contract to the moon (testnet)

Ok, now it’s time. We have implemented our Smart Contract, we have tested the frontend UI, we have covered every edge case with our tests. We are ready to deploy it on the testnet.

Following the scaffold-eth documentation, these are the steps we need to follow:

Change the defaultNetwork in packages/hardhat/hardhat.config.js to the testnet you would like to use (in my case rinkeby)
Updated the infuriaProjectId with one created on Infura
Generate a deployer account with yarn generate . This command should generate two .txt file. One that will represent the account address and one with the seed phrase of the generated account.
Run yarn account to see details of the account like eth balances across different networks.
Make sure that the mnemonic.txt and relative account files are not pushed with your git repository, otherwise, anyone could get ownership of your Contract!
Fund your deployer account with some funds. You can use an instant wallet to send funds to the QR code you just saw on your console.
Deploy your contract with yarn deploy!

If everything goes well you should see something like this on your console

Deployment metadata is stored in the _/deployments_ folder, and automatically copied to _/packages/react-app/src/contracts/hardhat_contracts.json_ via the _--export-all_ flag in the _yarn deploy_ command (see _/packages/hardhat/packagen.json_).

If you want to check the deployed contract you can search for them on the Etherscan Rinkeby site:

Update your frontend app and deploy it on Surge!

We are going to use the Surge method but you could also deploy your app on AWS S3 or on IPFS, that’s up to you!

The scaffold-eth documentations always come in hand but I will summarize what you should do:

If you are deploying on mainnet you should verify your contract on Etherscan. This procedure will add credibility and trust to your application. If you are interested in doing so just follow this guide for scaffold-eth.
Turn off Debug Mode (it prints an awful lot of console.log, something that you don’t want to see in Chrome Developer Console, trust me!). Open App.jsx , find const DEBUG = true; and turn it to false.
Take a look at App.jsx and remove all unused code, just be sure to ship only what you really need!
Make sure that your React app is pointing to the correct network (the one you just used to deploy your Contract). Look for const targetNetwork = NETWORKS[“localhost”]; and replace localhost with the network of your contract. In our case, it will be rinkeby
Make sure you are using your own nodes and not the ones in Scaffold-eth as they are public and there’s no guarantee they will be taken down or rate limited. Review lines 58 and 59 of App.jsx
Update constants.js and swap Infura, Etherscan, and Blocknative API Keys if you want to use their services.

Are we ready? Let’s go!

Now build your React App withyarn build and when the build script has finished deploy it to Surge with yarn surge.

If everything goes well you should see something like this. Your dApp is now live on Surge!

You can check out our deployed dApp here: https://woozy-cable.surge.sh/

Recap and Conclusions

That’s what we have learned and done so far

Clone scaffold-eth challenge repo
Learned a lot of web3/solidity concepts (deep dive into the ERC20 contract, approve pattern, and so on)
Create an ERC20 Token contract
Create a Vendor contract to allow users to buy and sell them
Tested our Contract locally on hardhat network
Deployed our contract on Rinkeby
Deployed our dApp on Surge

If everything works as expected, you are ready to make the big jump and deploy everything on Ethereum main net!

GitHub Repo for this project: scaffold-eth-challenge-2-token-vendor

Forem: Emanuele Ricci

Ethernaut Challenge #4 Solution — Telephone

Challenge #4: Telephone

Study the contracts

Solution code

Further reading

Disclaimer

Ethernaut Challenge #3 Solution — Coin Flip

Challenge #3: Coin Flip

Study the contracts

Solution code

Further reading

Disclaimer

Ethernaut Challenge #2 Solution — Fallout

Challenge #2: Fallout

Study the contracts

Solution code

Further reading

Disclaimer

Ethernaut Challenge #1 Solution — Fallback

Challenge #1: Fallback

Study the contracts

The contribute function

The receive function

Solution code

Further reading

Disclaimer

Let’s play OpenZeppelin Ethernaut CTF — learning Solidity security while playing!

How to play

Solutions to each puzzle

An unofficial audit of a Solidity Game smart contract: Wizards & Dragons Game

Premise

Contracts on which the audit was based

Audit Finding

Slither Finding

WD-100: check gpToken.transferFrom return value

WD-101: check all divisons

WD-102: WNDGame stuck money?

General

WD-001: Floating pragma

WD-002: Hardhat console imported in deployed contract

WD-003: import not used in interfaces

WD-004: missing explanation about lastWrite mechanism

WD-005: Emission of events missing for critical actions

WD-006: Event does not have indexed parameters

WD-007: create an external contract for the lastWrite mechanism

WD-009: replace admins mechanism with AccessControl

WD-010: add admin mechanism should validate the address

SacrificialAlter.sol

WD-011: setContracts should revert if _gp address is 0 address

WD-012: maxSupply in setType can be == 0?

WD-013: exchangeAmt in setExchangeAmt can be == 0?

WD-014: possible reentrancy issue

WD-015: updateOriginAccess is updating incorrectly lastWrite[tx.origin].time

Traits.sol

WD-016: unbound array

WD-017: setWnD wndNFT could be set 0x address

WD-018: BASE 64 code could be replaced by an external library

WnD.sol

WD-019: check that _maxTokens respect what's written in the comments

WD-020: add checks on setContracts parameters

WD-021: generate is an internal method that returns a WizardDragon but its return value is never used

WD-022: updateOriginAccess assign the incorrect value to lastWrite[tx.origin].time

WD-023: _paidTokens parameter of setPaidTokens should have the same int type of PAID_TOKENS

WD-024: check setPaidTokens parameter value

WD-025: be aware of modifier orders in setPaused

WNDGame.sol

WD-026: define presalePrice as a constant if it never change

WD-027: add param checks in setContracts

WD-028: startedTime can be resetted multiple time.

WD-029: addToWhitelist can reset an account whitelisting allowing it to mint more than 2 tokens in whitelist period

WD-030: add nonReentrancy on both makeTreasureChests and sellTreasureChests?

Update 1: an official GitHub repository

How to create tests for your Solidity Smart Contract

Why should you bother to write tests?

🛠 Tools you should use when developing

What should you cover in tests?

Cover Known bugs/exploits/common errors

Cover the implementation of your own functions

Some useful tips

The `contribute` function

The `receive` function

WD-100: check `gpToken.transferFrom` return value

WD-004: missing explanation about `lastWrite` mechanism

WD-007: create an external contract for the `lastWrite` mechanism

WD-011: `setContracts` should revert if `_gp` address is `0 address`

WD-012: `maxSupply` in `setType` can be == 0?

WD-013: `exchangeAmt` in `setExchangeAmt` can be == 0?

WD-015: `updateOriginAccess` is updating incorrectly `lastWrite[tx.origin].time`

WD-017: `setWnD` wndNFT could be set 0x address

WD-020: add checks on `setContracts` parameters

WD-021: `generate` is an internal method that returns a `WizardDragon` but its return value is never used

WD-022: `updateOriginAccess` assign the incorrect value to `lastWrite[tx.origin].time`

WD-023: `_paidTokens` parameter of `setPaidTokens` should have the same int type of `PAID_TOKENS`

WD-024: check `setPaidTokens` parameter value

WD-025: be aware of modifier orders in `setPaused`

WD-026: define `presalePrice` as a `constant` if it never change

WD-027: add param checks in `setContracts`

WD-028: `startedTime` can be resetted multiple time.

WD-029: `addToWhitelist` can reset an account whitelisting allowing it to mint more than 2 tokens in whitelist period

WD-030: add nonReentrancy on both `makeTreasureChests` and `sellTreasureChests`?

Update scripts in `package.json`