Context

At the core of the Self-Sovereign Identity movement are the new W3 specs for Decentralized Identifiers (DIDs) and Verifiable Credentials (VCs).
From working on InterRep I was already familiar with using an NFT as a way to represent credentials on-chain, but VCs appeared as an interesting alternative with different characteristics. Here are some similarities and differences:

• VCs are not tied to any single blockchain, whereas NFTs live in smart contracts on a specific blockchain.
• If DeFi has shown something, it's how powerful composability can become when building on top of an open, permissionless platform. As soon as an NFT is generated by one protocol it becomes usable by all other smart contracts out of the box! (NFT ownership can be verified in one line of code)
  VCs, however, can't be used natively in blockchain applications as they don't live on chain.
  It's still possible to use a VC with smart contracts by relying on an oracle or passing a proof as part of the transaction data but the process is much more cumbersome.
• Everything stored on a blockchain, like Ethereum, is public. As a result, NFTs and any data related to them stored in their smart contract also is. That has massive implications in terms of privacy. As a rule of thumb, no personally identifiable information (PII) should be stored on-chain. VCs are like fancy JSON documents so they don't suffer from the same characteristic, they can be stored securely and privately. What's more with zero-knowledge proof and selective disclosure, a VC holder can choose to reveal only a part of the information attested by a VC or a true statement derived from it.
• Both rely on cryptographic signatures and are tamper-resistant, although in the case of NFTs you are also relying on the security of the underlying blockchain for a few things; chief among them is preserving ownership of the tokens according to the rules written in the NFT smart contract.
  

But why not combine both?

Since NFTs often have a reference to some metadata, that reference could actually point to a VC!

Only the VC's URI would be stored in the NFT smart contract. Note that this URI could actually point to a "location" in an encrypted user data vault such that permissions could be put in place: then this URI would only resolve to the VC document only if you have been granted read access. With this approach, you get the best of both worlds, personal, private information can stay off-chain and stored in the VC, while the token, free of personally identifiable or private information, can be used on-chain.
This is what I would call hybrid crypto-credentials.

Right when I wanted to test this idea, a friend of mine suggested that we participate in the HackFS21 hackathon. It seemed like the perfect opportunity. We fleshed out the idea a bit more and chose to create an online learning platform that would issue these hybrid crypto-credentials. As an additional requirement, the whole system we set ourselves to create should be as much decentralized as possible: in other words no traditional backend servers (!).

The lessons for this online learning platform could be crowdsourced as the code is public on Github. Anyone would be able to create a new lesson and submit a Pull Request to add it to the catalog. This gives added meaning to the word "open" in Massive Open Online Courses: access and contributions are open to everyone. A DAO could be formed and tokens awarded to contributors whose lessons are added, but I digress... This blog post focuses on describing this "Proof Of Concept" that Iustin and I built.

Although it's clear that some improvements can be made (again, it's just a hack!), I'm pretty happy with the end result: it proves that hybrid crypto-credentials work and the whole system has very few centralized parts. Only one server is needed to sign VCs while keeping the signing key private (but even that could potentially be upgraded to a threshold signature scheme to avoid full centralization).

Overview

Here's an overview of how this decentralized learning platform works and issues hybrid crypto-credentials:

Lessons are accessible via a front-end. They are interactive in the sense that they require users to write some code and submit transactions to a smart contract (not a backend API).
To pass a lesson, the user has to submit a final transaction with the right data. If it's successful, a chain of actions are triggered: a Chainlink oracle asks for the issuance of a Verifiable Credential which gets stored on the decentralized storage network Ceramic, then, a non-transferrable NFT is minted on-chain and the location on the Ceramic Network of its VC counterpart is associated to it. Everything is pseudonymous as users are identified by a DID or their Ethereum address.

How it works

Curious to know more details? Here are the different step that go into getting the hybrid credentials.

The system is composed of two distinct parts: Open_Cred which can be re-used to create hybrid crypto-credential for any kind of use case and Open_Classes (which uses Open_Cred) containing everything related to this decentralized learning example.

Open_Classes

First a user / student connects their wallet and log in with 3ID (step #0) on the Open_Classes website. 3ID is a DID method created by Ceramic. This is so we can issue an NFT to their address but also a VC to their DID.

💡 We could have simply used the ethr did method as we already know the user's address, but 3ID offers more flexiblity. It gives users the ability to control a DID via multiple blockchain accounts.

Lesson 1

The first lesson teaches you how to query events using ethers.js. The user first calls the smart contract for this lesson (#1) which triggers the generation of a unique random number using Chainlink VRF (#2, #3). This random number is stored and associated with the student's address. In addition, an event is emitted containing both this random number and the student's address.
The goal for this lesson is to find this random number, using Javascript and ethers.js, filtering the events by your address.

As a shortcut we added a CodeSandbox to have an IDE embedded right in our lesson's page. By following the instructions on the left side and adding some code on the right side, the random number can be printed to its console! 💪

Once the random number is found, it can be submitted on this same page which crafts a transaction to the lesson smart contract containing the number and the user's DID (#5). The smart contract in turn verifies it corresponds to the number expected for the sender's address (#6). If that's the case, the student passed the lesson and the credential issuance flow is initiated: the DID is passed as credential subject and the name of the lesson as credential title to the OpenCredentials smart contract (#7).

Open_Cred

Once the OpenCredentials smart contract receives a request to generate a hybrid credential with all the properties needed, it forwards this request to a Chainlink node via an on-chain Oracle (#8). It also stores the requestId along with the recipient's address and the credential id (each "lesson smart contract" submitting a request is mapped to a credential id), these will be needed later.

Then, the Chainlink node calls a Lambda function on AWS via an external adapter (#9). You can view this lambda as the "VC issuer module" deployed by our Open Classes University to generate Verifiable Credentials and sign them (#10).
How are they signed? Inside the Lambda, a seed is used to create a DID which is authenticated with Ceramic, this time simply using the Key DID method, and able to create JSON Web Signatures (JWS).

Next, the signed VC is stored on the Ceramic (Clay test) Network in a Stream and the issuer's DID is passed as controller (#11). This returns a streamId which enables anyone to retrieve the VC from Ceramic (#12).

💡 For simplicity, a lot of thing were done from inside the Lambda, however I think only the signature could be performed there and the rest, handled by the Chainlink node including generating and storing the VC.

With the VC created and stored, now it's a matter of taking the same route in the opposite direction: the streamId is passed back from the lambda to the Chainlink node (#13) and back to the OpenCredentials smart contract with the right requestId (Chainlink handles that automatically).
Here's one of such transactions: https://rinkeby.etherscan.io/tx/0xa7c13f10ec64f9ba7607fe09f74b987c8984d35c1d82c191b9950942ad31e07a

😬 Fun fact showing how early this tech is: For a while Chainlink only permitted 32 bytes to be returned to a smart contract. As a result, any string you'd want to return from a Chainlink node was getting truncated, only keeping the first 32 characters. So I was actually stuck for a bit for that last step because a Ceramic streamId is more than 32 characters long... Fortunately Chainlink recently released a new version supporting "large responses" and unblocked me after I upgraded my node and Oracle smart contract.

From there, the OpenCredentials contract is able to retrieve the token recipient's address and the credential / lesson id from the requestId, it then calls the NFT contract to mint a token with recipient, lessonId and streamId.

The NFT contract is a ERC721 contract with some modifications:

• The NFTs are non-transferrable. They can be minted by authorized addresses and burnt by their owner or authorized parties, but they cannot be transferred. If they were transferrable, someone would be able to acquire these tokens just by buying them and they would lose their significance as proof of completion of a lesson for all token recipients.
  Because it's a ERC721 contract the non-transferrability restriction of this contract is not straighforward at all at first glance. Plus, a lot of unused code for transfers and approvals ends up being deployed. For these reasons, I've been working on ERC1238 towards making a streamline token standard for non-transferable tokens a.k.a Badges.
• Each token is uniquely identified by a unique tokenId - they're Non-Fungible Tokens after all - but they also belong to a group under a lessonId. From a tokenId you can retrieve the lessonId it is associated with.
• Balances for a lesson are tracked. This lets someone see if an address received a credential for a specific lesson (querying by lessonId) and how many of them they own. This comes from the assumption that an address may own several tokens for the same lesson. For example if lessons were graded, someone might decide to obtain the crypto-credential of a lesson again but with a higher grade.
  

I created a demo video going through the whole flow and getting credentials as an end user:

All the code is available here:

• Open_Cred
• Open_Classes

Deployments on Rinkeby:
OpenClasses: 0xb25873E1fd210EF76D4528F04d1142434efbA8bc
VCNFT: 0x0D7f626141Ab3866533f98b4D4406b23e8bE7608
OpenCredentials: 0x27187729F39de1bEB68e9Aa4E3D52240DD409730

Usual disclaimer: it's been developed for demonstration purposes only, has not been tested nor audited and must contain bugs, do not use in production!

If you're interested in the topic of decentralized identity and crypto-credentials, don't hesitate to reach out to me on Twitter!

The code for this tutorial was written by JulienKode and I.
Disclaimer: The code obviously hasn't been audited so it may contain vulnerabilities.

If you want to jump straight into it, the repository is accessible here (spoiler alert!).

What we will be building

For this tutorial, we are going to build a decentralized application that is a bit more suited for a blockchain than, say, a to-do app. Using smart contracts, the goal will be to replace, or rather complement, a rental agreement. In brief, it should be able to manage rent payments and security deposits for landlords and tenants without any third-party or guarantors AND generate interests on the deposit.

For the full context and motivation of what we will develop in this tutorial, please refer to this post. However, beyond the "why", here's the "what", i.e the requirements.

Requirements

First, let's define a security deposit as money protecting against damage to the property and rent guarantee as protecting against unpaid rent. There's usually no distinction between the two. Here we're making one because the latter is verifiable on-chain, the former is not, so the way to reach a settlement differs.

1. Moving in

After agreeing upon an amount for rent and security deposit, landlord and tenants should be able to enter into an agreement.

As a tenant:

• I should be able to lock up a certain amount as security deposit and rent guarantee, and pay the first month rent to start the lease.
• I should earn interest on the money locked up.

2. Renting

As a tenant:

• I should be able to pay my rent on time

As a landlord:

• I should be able to withdraw from the protocol the rent from the moment it's due
• If rent payment is late, I should be able to withdraw from the rent guarantee an amount equivalent to the unpaid rent

3. Moving out

As a tenant:

• If I always paid my rent in time, I should be able to get the rent guarantee back in full
• I should get all earned interests on the security deposit and rent guarantee

As a landlord:

• I should have control over how much of the security deposit is given back to the tenant (in case there were damages)

Let's dive in!

Prerequisites

• Some familiarity with Solidity, in particular types, visibility specifiers, functions definitions... My previous post has got you covered.
• Node and Yarn installed

And that's it! This is a tutorial for beginners. :)

Boilerplate

Instead of spending too much time, setting things up we are going to re-use an excellent template created by Paul Razvan Berg: Solidity-template.

It comes with many plugins and super useful tools already installed for us:

• Hardhat: My favorite framework to develop, compile and run smart contracts locally
• Ethers: An essential library to interact with smart contracts from client-side apps and tests
• TypeChain: Generates TypeScript types for smart contracts
• Waffle: Tooling for writing comprehensive smart contract tests
• Solhint: Linter
• Solcover: Generates code coverage for smart contracts
• Prettier Plugin Solidity: Code formatter for Solidity

If you want to follow along, click on "Use this template" on Github, follow these steps and then clone your repo locally. Inside of it, we install the dependencies by running:

yarn install

Lending Service

Interface

We are going to create a Lending Service which will be responsible for interacting with a DeFi protocol as we want the deposit and rent guarantee to earn interests.

Because we could potentially have a lending service for each yield-earning DeFi protocol (Aave, Compound, Yearn etc...), we first define an interface that any Lending Service will have to implement.

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

interface ILendingService {
    /// @notice Deposits funds from current smart contract to a lending
    /// protocol
    /// @dev Will revert if the amount exceeds the contract balance or
    /// caller is not the owner.
    /// @param amount The amount to deposit
    function deposit(uint256 amount) external;

    /// @notice Withdraws `amount` from a lending protocol
    /// @dev Will revert if the amount exceeds the balance of capital
    /// deposited or caller is not the owner.
    /// @param amount The amount to withdraw
    function withdraw(uint256 amount) external;

    /// @notice Withdraws all capital and interests earned from a 
    /// lending protocol
    /// @dev Will revert if the caller is not the owner.
    function withdrawCapitalAndInterests() external;

    /// @notice Returns the amount deposited on a lending protocol
    function depositedBalance() external view returns (uint256);
}

The first line specifies the license for this file.

The second line indicates to the Solidity compiler the Solidity version this file was written for, in this case ^0.8.0. If the compiler's version does not match, an error will be thrown.  The syntax to specify a valid version is the same as npm.

Then, in the interface itself, we have function declarations for depositing, withdrawing and checking the balance of deposited tokens on a lending protocol. They are declared without their implementation, because they're in an interface.

Aave Lending Service

Now that we have a generic interface we can define a smart contract that inherits it. It will be responsible for interacting with AAVE v2, a DeFi protocol that we can use to lend tokens.

import "./ILendingService.sol";

contract AAVELendingService is ILendingService { }

ERC20 🤑

We need to declare the token that will be used as currency. This token must follow the widely-used ERC20 standard and adhere to its interface (IERC20) which we import from OpenZeppelin.

With Aave, whenever you deposit tokens, you get aTokens in return. Deposit 100 DAI, you get 100 aDAI; 300 USDC, you get 300 aUSDC etc... We declare both token types as ERC20 tokens.

 import "@openzeppelin/contracts/token/ERC20/IERC20.sol";

 contract AAVELendingService is ILendingService {
   IERC20 public aToken;
   IERC20 public tokenUsedForPayments;
 }

We're also indicating that our contract uses the SafeERC20 library from OpenZeppelin by 1. importing it and 2. including using SafeERC20 for IERC20;.

The SafeERC20 library makes interacting with an ERC20 token a bit safer by reverting if an operation fails and sends back a return value equals to false.

import "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";

contract AAVELendingService is ILendingService {
    using SafeERC20 for IERC20;

    // this shouldn't be harcoded normally
    address public aDaiTokenAddress = 0xdCf0aF9e59C002FA3AA091a46196b37530FD48a8;

    IERC20 public aToken;
    IERC20 public tokenUsedForPayments;

    constructor(address _tokenUsedToPay) {
        tokenUsedForPayments = IERC20(_tokenUsedToPay);
        aToken = IERC20(aDaiTokenAddress);
    }
}

The address of the token used as currency is passed in the constructor which offers some flexibility, but normally the aToken's address should be retrieved based on that token address (only kovan DAI will work here). I leave that to you to implement ;) (Hint: this method).

Ownership

Granted their visibility is public or external, functions defined in a smart contract can be called by anyone. We don't want anyone to withdraw the funds here so we'll need some access control.

address payable public owner;

modifier onlyOwner() {
  require(msg.sender == owner, "Restricted to the owner only");
  _;
}

constructor(address _tokenUsedToPay) {
   ...
   owner = payable(msg.sender);
}

We first declare a variable for the owner of the smart contract.
We then add a modifier, onlyOwner. It contains a require statement which reverts the transaction if the caller is not the owner that we defined. When applied to a function, that check will be performed before executing the function itself (_ represents the function body).

In the constructor, the address that deployed the current smart contract gets assigned to that variable.

It's great to have an owner defined, but we should also enable transferring ownership. Here's how to do it and a first example of applying our onlyOwner modifier:

function transferOwnership(address newOwner) public onlyOwner {
  require(newOwner != address(0), "new owner is the zero address");
  owner = payable(newOwner);
}

Deposit & Withdraw

Let's move on to the core features now.

First, we define a variable which will be helpful to keep track of the balance of token that were deposited in AAVE.

uint256 public depositedAmountBalance;

Next, we define a function used to deposit some amount of tokens in AAVE.

function deposit(uint256 amount) external override(ILendingService) onlyOwner {
  require(amount <= tokenUsedForPayments.balanceOf(address(this)), "amount exceeds contract balance");
  // Approve the LendingPool contract to pull the amount to deposit
  tokenUsedForPayments.approve(address(aaveLendingPool), amount);
  // Deposit the amount in the LendingPool
  aaveLendingPool.deposit(address(tokenUsedForPayments), amount, address(this), 0);

  depositedAmountBalance += amount;
}

It first does a preventive check, verifying that the smart contract holds the amount to deposit.

The AAVE lending pool will pull these tokens from our contract. So if you're not familiar with how ERC20 tokens work, we first need to allow Aave's smart contract to transfer the tokens the Lending Service holds on its behalf (tokenUsedForPayments.approve).

We then call aaveLendingPool.deposit  passing in 1. the underlying asset, 2. amount to be deposited, 3. the address that will receive the aTokens in exchange which is the current contract's address and 0 as we're not using any referral code.

depositedAmountBalance  gets logically incremented by amount.

To withdraw, it's almost the same process but in reverse. After checking that the contract holds a balance superior to the amount to withdraw (of aTokens this time!), we need to approve the lending pool to transfer aTokens from our smart contract in order to get our underlying tokens back in exchange.

function withdraw(uint256 amount) external override(ILendingService) onlyOwner {
    uint256 aTokenBalance = aToken.balanceOf(address(this));
    // Check that the amount to withdraw is less than what the contract holds
    require(aTokenBalance >= amount, "Amount exceeds balance");

    // Approve the aToken contract to pull the amount to withdraw
    aToken.approve(address(aaveLendingPool), amount);
    // Withdraw from the LendingPool
    aaveLendingPool.withdraw(address(tokenUsedForPayments), amount, address(this));
}

At that point if all goes well, our lending service should hold the amount in underlying tokens so we can transfer it and then decrease the depositedAmountBalance.

function withdraw(uint256 amount) external override(ILendingService) onlyOwner {
    uint256 aTokenBalance = aToken.balanceOf(address(this));
    // Check that the amount to withdraw is less than what the contract holds
    require(aTokenBalance >= amount, "Amount exceeds balance");

    // Approve the aToken contract to pull the amount to withdraw
    aToken.approve(address(aaveLendingPool), amount);
    // Withdraw from the LendingPool
    aaveLendingPool.withdraw(address(tokenUsedForPayments), amount, address(this));
    // Transfer withdrawn amount
    tokenUsedForPayments.safeTransfer(msg.sender, amount);

    depositedAmountBalance -= amount;
}

View Function

Finally, let's define a function that will return the depositedAmountBalance. It will be needed later.

 function depositedBalance() external override(ILendingService) view returns (uint256) {
  return depositedAmountBalance;
}

It is a simple view  function as it simply reads data from the blockchain.

Developing the rental agreement

With our lending service created, we can now develop a smart contract called RentalAgreement. It will make use of the Lending Service and contain the "rules" of the agreement between a landlord and a tenant, embedded programmatically (🔥🔥🔥).

Inside our contract,  let's declare some state variables. They get assigned their values in the constructor which will be provided when deploying a RentalAgreement.

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

import "./ILendingService.sol";

contract RentalAgreement {
    address public landlord;
    address public tenant;
    uint256 public rent;
    uint256 public deposit;
    uint256 public rentGuarantee;

    ILendingService public lendingService;

    constructor(
        address _landlord,
        address _tenantAddress,
        uint256 _rent,
        uint256 _deposit,
        uint256 _rentGuarantee,
        address _tokenUsedToPay,
        address _lendingService
    ) {
        require(_landlord != address(0), "Landlord address cannot be the zero address");
        require(_tenantAddress != address(0), "Tenant address cannot be the zero address");
        require(_tokenUsedToPay != address(0), "Token address cannot be the zero address");
        require(_lendingService != address(0), "Lending Service address cannot be the zero address");
        require(_rent > 0, "rent cannot be 0");

        landlord = _landlord;
        tenant = _tenantAddress;
        rent = _rent;
        deposit = _deposit;
        rentGuarantee = _rentGuarantee;
        lendingService = ILendingService(_lendingService);
    }
}

The different variables declared are:

• addresses for landlord and tenant
• unsigned integer for the rent
• unsigned integer for deposit and rent guarantee (these two are different! See specs above)

They all have a public visibility.

The require statements are used for input validation. If the condition provided, such as _rent > 0, is true, execution will proceed; otherwise, the transaction will revert and since it's in the constructor, contract deployment will fail. Boohoo.

This smart contract also expects the address of a lendingService to be passed to its constructor. We keep it simple for now and assume the landlord deploys a lending service, and then has to transfer ownership to the rental agreement once deployed.

Modifiers

Let's add two modifiers to restrict permissions:

modifier onlyTenant() {
        require(msg.sender == tenant, "Restricted to the tenant only");
        _;
 }

modifier onlyLandlord() {
        require(msg.sender == landlord, "Restricted to the landlord only");
        _;
}

Once added to a function, the onlyTenant modifier will revert the transaction if the caller is not the tenant (that we defined previously as state variable).

Same thing for the second modifier, onlyLandlord but only allowing the landlord.

ERC20 (again!)

The RentalAgreement will be transferring the tokens used as currency so we need to add the following lines, just like we did in the Lending Service.

import "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";

contract RentalAgreement {
    using SafeERC20 for IERC20;

    IERC20 public tokenUsedForPayments;

    constructor(
        ...
        address _tokenUsedToPay,
    ) {
        ...
        tokenUsedForPayments = IERC20(_tokenUsedToPay);
    }

 }

Entering the agreement 🤝

Assuming the landlord has to deploy the RentalAgreement, we are now going to add a function which will make the tenant acknowledge the terms by providing them as arguments and start the lease. (A cool improvement would be to have the tenant sign these terms with Metamask for example, and verify the signature in our RentalAgreement smart contract).

Here's what we add, explained with comments:

// Timestamp (e.g. 1622131469) used to keep track of when the rent will be due next
uint256 public nextRentDueTimestamp;

// Event emitted at the start of the lease
event TenantEnteredAgreement(uint256 depositLocked, uint256 rentGuaranteeLocked, uint256 firstMonthRentPaid);

// ...

function enterAgreementAsTenant(
    address _landlordAddress,
    uint256 _deposit,
    uint256 _rentGuarantee,
    uint256 _rent
) public onlyTenant {
    // Makes sure the tenant "agrees" with the terms first registered by the landlord
    require(_landlordAddress == landlord, "Incorrect landlord address");
    require(_deposit == deposit, "Incorrect deposit amount");
    require(_rentGuarantee == rentGuarantee, "Incorrect rent guarantee amount");
    require(_rent == rent, "Incorrect rent amount");

    uint256 deposits = deposit + rentGuarantee;
    // Transfers the deposits to this smart contract
    tokenUsedForPayments.safeTransferFrom(tenant, address(this), deposits);
    // Approve the transfer of the deposits to the lending service
    tokenUsedForPayments.approve(address(lendingService), deposits);
    // Deposit the `deposits` amount in the lending service
    lendingService.deposit(deposits);

    // Transfer the first month of rent to the landlord
    tokenUsedForPayments.safeTransferFrom(tenant, landlord, rent);
    // First rent payment was made, we set the next time it's due as 4 weeks from now
    nextRentDueTimestamp = block.timestamp + 4 weeks;

    emit TenantEnteredAgreement(deposit, rentGuarantee, rent);
}

Note that we're using lendingService  which was declared and coded previously.

Tests

This tutorial wouldn't be complete without explaining how to test the Solidity code we write.

You can dive in the repository for the full test suite but let's focus on a test for the previous function. And before we can test it, we actually need to initialize several things:

Init

import hre from "hardhat";
import { Artifact } from "hardhat/types";
import { SignerWithAddress } from "@nomiclabs/hardhat-ethers/dist/src/signer-with-address";

import { RentalAgreement } from "../typechain/RentalAgreement";
import { MockLendingService } from "../typechain/MockLendingService";
import { expect } from "chai";
import { deployMockLendingService } from "./utils/mockLendingService";
import { parseUnits18 } from "../utils/parseUnits";

const { deployContract } = hre.waffle;
const { ethers } = hre;

describe("Rental Agreement", function () {
  let landlord: SignerWithAddress;
  let tenant1: SignerWithAddress;
  let rental: RentalAgreement;
  let lendingService: MockLendingService;

  let rent: BigNumber;
  let deposit: BigNumber;
  let rentGuarantee: BigNumber;
  let dai: Contract;

  before(async function () {
    [landlord, tenant1] = await ethers.getSigners();

    // deploy an ERC20 token to mock dai
    const daiFactory = await ethers.getContractFactory("ERC20PresetMinterPauser");
    dai = await daiFactory.deploy("dai", "DAI");
    console.log("dai deployed at:", dai.address);

    // Give 1 000 000 mock dai to tenant1
    const initialTenant1Balance = parseUnits18("1000000");
    const mintingTx = await dai.mint(tenant1.address, initialTenant1Balance);
    await mintingTx.wait();

    expect(await dai.balanceOf(tenant1.address)).to.eq(initialTenant1Balance);
  });

Here we assign 2 signers: the first one playing the role of landlord and the other tenant (tenant1). Then a simple ERC20 contract is deployed to serve as a mock token used for payments. We use it to grant 1M of them to tenant1. That should be enough to pay rent for a little while. 😄

beforeEach(async function () {
  rent = parseUnits18("500");
  deposit = parseUnits18("500");
  rentGuarantee = parseUnits18("1500");

  lendingService = await deployMockLendingService(landlord, dai);

  const rentalArtifact: Artifact = await hre.artifacts.readArtifact("RentalAgreement");
  rental = <RentalAgreement>(
    await deployContract(landlord, rentalArtifact, [
      landlord.address,
      tenant1.address,
      rent,
      deposit,
      rentGuarantee,
      dai.address,
      lendingService.address,
    ])
  );

  const transferOwnershipTx = await lendingService.connect(landlord).transferOwnership(rental.address);
  await transferOwnershipTx.wait();
});

Next, beforeEach is used to re-deploy our smart contracts before each test in order to isolate them. Deployment is done in 2 steps:

1. Getting the contract's artifact with await hre.artifacts.readArtifact(<CONTRACT NAME>);
2. Calling deployContract  passing in a signer, the contract's artifact and then an array of parameters expected by the constructor.

As mentioned before, after deploying, a landlord needs to give up ownership of the lending service.

Testing enterAgreementAsTenant

First we compute the sum of everything a tenant needs to transfer upfront when entering the agreeement: deposit, rentGuarantee and first month's rent. That sum is used to call approve first so that our smart contract is allowed to pull that amount from the tenant.

  it("should let the tenant enter the agreement", async () => {
      const deposits = deposit.add(rentGuarantee);
      const totalUpfront = deposits.add(rent);

      const approveTx = await dai.connect(tenant1).approve(rental.address, totalUpfront);
      await approveTx.wait();
    });

We can then call the function to enter the agreement, wait for the transaction to be mined and get the block that included it.

 const tx = await rental.connect(tenant1).enterAgreementAsTenant(landlord.address, deposit, rentGuarantee, rent);
 const txReceipt = await tx.wait();
 const blockHash = txReceipt.blockHash;
 const block = await ethers.provider.getBlock(blockHash);

Calling nextRentDueTimestamp,  we can check that it's set 4 weeks from the block's timestamp.

const nextRentDueTimestamp = await rental.nextRentDueTimestamp();
expect(nextRentDueTimestamp).to.eq(block.timestamp + FOUR_WEEKS_IN_SECS);

Finally we check that the deposits were indeed deposited in the lending service, the rentalAgreement's balance is 0 and the landlord received the first month's rent!

expect(await dai.balanceOf(lendingService.address)).to.eq(deposits);
expect(await dai.balanceOf(rental.address)).to.eq(parseUnits18("0"));
expect(await dai.balanceOf(landlord.address)).to.eq(rent);

Everything should pass ✅

Paying Rent

Back to Solidity, we define a function to allow the tenant to pay rent, fittingly called payRent.

 event RentPaid(address tenant, uint256 amount, uint256 timestamp);
 // ...
function payRent() public onlyTenant {
    require(tokenUsedForPayments.allowance(tenant, address(this)) >= rent, "Not enough allowance");

    tokenUsedForPayments.safeTransferFrom(tenant, landlord, rent);

    nextRentDueTimestamp += 4 weeks;

    emit RentPaid(tenant, rent, block.timestamp);
}

Let's unpack the 4 lines in the function body.

The first one checks on the token's smart contract that the allowance given to our current smart contract by the tenant is at least the amount of rent. If it wasn't the case, the transfer would fail but we catch that possibility earlier here.

The second line executes the transfer from tenant to landlord of the rent  amount.

Once done, we consider that the tenant just "bought 4 more weeks" in the property so we add 4 weeks to the current value of nextRentDueTimestamp.

The last line emits a RentPaid event, notifying that rent was paid.

What if the tenant stops paying rent?! 😨

We are going to add a function that handles this situation and lets the landlord withdraw from the money locked up by the tenant.

function withdrawUnpaidRent() public onlyLandlord {
    // Checks that rent payment is late
    require(block.timestamp > nextRentDueTimestamp, "There are no unpaid rent");
    // Pushes back next time rent is due by 4 weeks
    nextRentDueTimestamp += 4 weeks;
    // Registers that the amount for rent was taken out of `rentGuarantee`
    rentGuarantee -= rent;
    // Withdraws from the Lending Service
    lendingService.withdraw(rent);
    // Transfers "rent" to the landlord
    tokenUsedForPayments.safeTransfer(landlord, rent);
}

As you can see the landlord is still getting rent but from the rent guarantee, not the tenant directly.

Ending the tenancy

Let's recap what needs to happen at the end of a tenancy:

The tenant should get:

• her deposit back minus any amount retained by the landlord for damages
• her rent guarantee back (or whatever is left of it)
• any interest earned on both of these deposits

Let's code this up!

We add a public function but with the onlyLandlord  modifier so only the landlord can call it passing as parameter how much should be given back to the tenant from the deposit amount (_amountOfDepositBack).

We're also checking that this amount is inferior or equal to the deposit.

function endRental(uint256 _amountOfDepositBack) public onlyLandlord {
  require(_amountOfDepositBack <= deposit, "Invalid deposit amount");
}

Next, we need to send to the tenant the right amount which includes the amount of deposit back, the rent guarantee (or whatever is left of it) and the interests earned.

function endRental(uint256 _amountOfDepositBack) public onlyLandlord {
    require(_amountOfDepositBack <= deposit, "Invalid deposit amount");

    uint256 depositedOnLendingService = lendingService.depositedBalance();
    uint256 beforeWithdrawBalance = tokenUsedForPayments.balanceOf(address(this));
    lendingService.withdrawCapitalAndInterests();
    uint256 afterWithdrawBalance = tokenUsedForPayments.balanceOf(address(this));
    uint256 interestEarned = (afterWithdrawBalance - depositedOnLendingService) - beforeWithdrawBalance;

    // compute and transfer funds to tenant
    uint256 fundsToReturnToTenant = _amountOfDepositBack + rentGuarantee + interestEarned;
    tokenUsedForPayments.safeTransfer(tenant, fundsToReturnToTenant);
}

There's a bit going on here because we are computing how much interest was earned. With this amount known, that means we could easily split it between tenant and landlord.

This computation is done by comparing the capital deposited in the lending service with how much was transferred to the smart contract after withdrawing everything from it.

If the landlord is keeping some of the deposit we need to figure this out and transfer it to  them!

 uint256 landlordWithdraw = deposit - _amountOfDepositBack;
// landlord is keeping some of the deposit
if (landlordWithdraw > 0) {
    tokenUsedForPayments.safeTransfer(landlord, landlordWithdraw);
}

Finally, we set both deposit and rentGuarantee  to 0 and emit an event to signal the end of the tenancy:

deposit = 0;
rentGuarantee = 0;
emit EndRental(fundsToReturnToTenant, landlordWithdraw);

And that's it for the Rental Agreement!

Factory

Let's now create a smart contract that will make it easy for landlords to deploy rental agreements.

import "./RentalAgreement.sol";

contract RentalFactory {

    function createNewRental(
        address _tenantAddress,
        uint256 _rent,
        uint256 _deposit,
        uint256 _rentGuarantee,
        address _tokenUsedToPay,
        address _lendingService
    ) public {
        RentalAgreement newRental =
            new RentalAgreement(msg.sender, _tenantAddress, _rent, _deposit, _rentGuarantee, _tokenUsedToPay, _lendingService);
    }
}

We import the contract we created and add a public function that forwards all the parameters needed to create a new RentalAgreement.

Next, let's add an event for whenever a new agreement is deployed.

  event NewRentalDeployed(address contractAddress, address landlord, address tenant);

    function createNewRental(
        address _tenantAddress,
        uint256 _rent,
        uint256 _deposit,
        uint256 _rentGuarantee,
        address _tokenUsedToPay,
        address _lendingService
    ) public {
        RentalAgreement newRental =
            new RentalAgreement(msg.sender, _tenantAddress, _rent, _deposit, _rentGuarantee, _tokenUsedToPay, _lendingService);

        emit NewRentalDeployed(address(newRental), msg.sender, _tenantAddress);
    }

Note that we are getting the address of the freshly deployed contract as the first event argument.

Finally, we use a mapping that keeps track of the RentalAgreements  deployed by address. Any new rental deployed gets pushed to it.

mapping(address => RentalAgreement[]) public rentalsByOwner;

...
function createNewRental( ...
  RentalAgreement newRental = new RentalAgreement(msg.sender, _tenantAddress, _rent, _deposit, _rentGuarantee, _tokenUsedToPay, _lendingService);

  emit NewRentalDeployed(address(newRental), msg.sender, _tenantAddress);
  
 rentalsByOwner[msg.sender].push(newRental);
}

🏁🏁 And we're done! 🏁🏁
If you have any comment or feedback about this tutorial, we'd love to hear it, so please don't hesitate to reach out!

Here's how to get the current price of any cryptocurrency directly in Google Sheets.
After following the steps below, you'll be able to use a function GETCRYPTOPRICE which takes 2 parameters: 1. the ticker / symbol of a cryptocurrency and 2. the fiat currency.

It doesn't take long to set up, I promise!

STEP 1: Add the script to Google Sheets

In Google Sheets, go to "Extensions" and then "Apps Script". Once the script editor is open, replace all the existing code with the following code:

const CMC_PRO_API_KEY = "YOUR_API_KEY";

function GETCRYPTOPRICE(ticker, currency) {
  try {
    // fetch data from url
    const res = UrlFetchApp.fetch(`https://pro-api.coinmarketcap.com/v1/cryptocurrency/quotes/latest?symbol=${ticker}&convert=${currency}&CMC_PRO_API_KEY=${CMC_PRO_API_KEY}`);
    
    const content = res.getContentText();
    
    // parse content
    const json = JSON.parse(content);

    // return the price
    return json.data[ticker.toString()].quote[currency.toString()].price;
  }
  catch (err) {
    return JSON.stringify(err);
  }
}

Save the code and rename it as “GETCRYPTOPRICE”.

STEP 2: Get your CoinMarketCap key

Go to https://coinmarketcap.com/api/ and click on "Get your API key now". Create an account, which takes less than 2 minutes.
Then on your dashboard, click on "COPY KEY".

STEP 3: Add your API key

Back to the script editor, replace "YOUR_API_KEY" with your actual API key that you just copied. The line should look like this:

const CMC_PRO_API_KEY = "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxx";

Hit "Save project" or Ctrl/Cmd + S.

STEP 4: Use GETCRYPTOPRICE function in your Google Sheet

You can now use the following formula in a cell:

=GETCRYPTOPRICE(ticker, fiatCurrency)

So for example to get the price of ETH in USD: =GETCRYPTOPRICE("ETH","USD")

STEP 5: Sit back and enjoy monitoring your portfolio

Disclaimer: I am not a real estate expert, the following just comes from personal experience and I realize it might potentially gloss over some regulatory constraints.

Have you ever had difficulties renting a place? Or maybe you know someone who has. Landlords usually ask prospective tenants to provide proof of recurring income, which is easy if you're an employee with a solid contract. However, it can get more difficult for someone who's self-employed, on a temp contract, or even just moved from abroad.

Some companies offer to automate the screening process with a neat web interface and API connections to banks and databases, only to fall short if an applicant who's just moved from abroad is not yet registered in any of them. The complexities, don't end there. Countries that rely on a credit score system consider you inexistant in their system's eyes until you start building up your score, regardless of you physically being on their soil.

In cities like Paris, the market for apartment rentals has been incredibly favorable to landlords - although the COVID pandemic might have helped relieve some of that pressure.
As a result of this imbalance between supply and demand, which in this case we call a seller's market, landlords might receive hundreds of applicants within hours of posting a listing. They can afford to be picky. You may have provided all the proofs and guarantees that you would be a model tenant, your application is just one among many, as good as yours, if not better, in the pile. And if you're a freelancer, without stable earnings then good luck! Companies have increasingly been embracing contractors over the years; landlords seem to be lagging behind. This is a real problem for people without a full-time, long-term work contract and results in weeks-long hassle, fraught with rejections.

Apart from damages, landlords' biggest fear is a tenant that doesn't pay rent. As a cover, it's not uncommon to get an insurance policy against it. So prospective tenants sometimes get a rejection that actually and indirectly comes from the insurance company.

Using something like Airbnb is one solution, but it's often more expensive. And it might feel homey, but not like your home. That's why it works well but only as a temporary solution.
Another solution is to use a guarantor, who's liable for the rent in case you can't pay, and pray you make it out of the pile of applicants this way.
But what if you can't provide worthy guarantors?
What's mind boggling, by the way, is that guarantors might not be able to actually pay themselves if need be. They might have their own debts or mortgage to pay first, but we don't check that, do we?!

So another solution, which I recognize only few could afford, would be to lock up a number of months worth of rent which would essentially replace the insurance company. That's already common practice in several countries and is known as a security deposit. Though it usually protects the landlord against damages, the amount here would be large enough to protect against default by the tenant as well.
Wouldn't it be reassuring to know that a sum is locked up and would be automatically transferred to a landlord in case of a missed rent payment?
That money has to be locked up and can't be trusted in hands of either the landlord or the tenant: the other would object. So one way to solve this trust issue is to put that money in escrow. Doing so, however, can incur some fees.
That's where a blockchain like Ethereum can shine, acting as an escrow account without a third-party.  The security deposit would be managed by a smart contract with rules agreed upon between landlord and tenant. With rent being paid through this smart contract, it becomes not only very easy to verify if it was paid on time, it also becomes automatically actionable, i.e the money locked is released to the landlord if rent is due and wasn't paid. In case that undesirable event happens, it can be considered that rent was paid from the security deposit. Another - harsher - variant would be to consider that rent is still due for that "missed month" although the tenant lost some of that deposit.

Thanks to the composable nature of DeFi that "rent guarantee" could even earn interest while being locked up! Because it can represent quite a large sum, it might as well be put to work.
The earned interest on it can also be programmatically split between landlord and tenant. This would bear some similarities to Jeonse, a type of lease common in South Korea which was born out of an environment with high interest rates, just like in DeFi today!
Many designs in terms of micro-economics are possible. For example, it could be programmed that tenants lose the earned interest if they don't pay on time, as an additional incentive to do so.

If we want to take things even further, it might make sense to use money streams, introduced by protocols such as Sablier or Superfluid, which allow money to be streamed from an account to another just like a video stream!
If you think about it, isn't paying rent once a month kind of arbitrary? Why not every 2 weeks? Or once a week? Renting a space is agreed for a period of time, which is continuous; why not pay continuously then?! I haven't explored the pros and cons of doing just that but it is just as arbitrary, if not a more natural way of paying rent.
Whereas with traditional banking it would be absurd to wire a small fraction of your monthly rent every minute, now it's at least technically feasible on a blockchain.

With a friend a mine we even started a basic implementation of what I just described. I've been wanting to write a technical tutorial about smart contract development, so it will be published here, taking that application as an example. Subscribe to my newsletter if you want to get notified when it comes out!

A friend of mine told me he was interested to learn how to make decentralized applications. After having been through part of this journey myself, I can recommend some resources that I personally used. Hopefully it will help answer the question: Where do I start?

So here we go, here's a list of free resources that I found the most helpful for learning how to build decentralized applications on Ethereum:

1 - Mastering Ethereum

This is a book written by crypto OG Andreas Antonopoulos and Gavin Wood, co-creator of Ethereum. It's meant to serve both "as a reference manual and as a cover-to-cover exploration of Ethereum".
It's ideal for developers wanting to learn how Ethereum works from a technical perspective. It starts with the fundamentals (addresses, transaction, gas etc...) up to the inner workings (EVM) and teaches how to build a complete decentralized application with examples.
Originally published at the end of 2018, it is getting outdated though (the Ethereum space has been evolving quite a lot since!). The good news is that a 2nd edition is in the works.

You can either buy the paperback version here or find it as open-source here.

2 - CryptoZombies

#1 Solidity Tutorial & Ethereum Blockchain Programming Course | CryptoZombies

CryptoZombies is The Most Popular, Interactive Solidity Tutorial That Will Help You Learn Blockchain Programming on Ethereum by Building Your Own Fun Game with Zombies — Master Blockchain Development with Web3, Infura, Metamask & Ethereum Smart Contractsand Become a Blockchain Developer in Record Ti…

CryptoZombies

This an interactive tutorial that has become a reference recommended by many. It is well-polished and provides a fun introduction to Solidity (and more!).
Plus, you'll get to develop a simplified version of the famous CryptoKitties game. 🐱✨

3 - ETH.Build

ETH.Build - Educational Sandbox For Web3

Educational sandbox for prototyping Web3. Learn Ethereum visually with drag-and-drop programming.

Educational Sandbox For Web3

Austin Griffith has put out fantastic videos that help understanding how a blockchain works, starting from the ground up. You can learn by watching him, literally manipulating the building blocks of Ethereum thanks to a really awesome sandbox he has developed. Try it out yourself at https://sandbox.eth.build/

4 - EatTheBlocks

EatTheBlocks

Do you want to learn how to build Solidity smart contracts and Ethereum decentralized applications (Dapps)? On this channel, you will find a ton of high-quality tutorials on Solidity and Ethereum Dapps development:- How to learn Solidity programming?- How to develop Ethereum smart contracts?- H…

YouTube

EatTheBlocks is a Youtube channel covering a broad range of topics related to Ethereum and DeFi. Although its videos have veered more and more towards news coverage with time, broadening its target audience to not only include developers, the channel still contains very helpful tutorials. Its host, Julian, offers some courses as well.

5 - Tutorials for smart contract development frameworks

As part of the web 3 stack, you should master a framework for developing on Ethereum that will help with compiling your smart contracts, running tests, deploying them, etc...

The one that seems to be winning the community over at the moment is Hardhat 👷. Their tutorial is here.

You might also come across Truffle which was the main framework for a while. It has this tutorial in particular (though it might have become a bit old).

6 - Scaffold-Eth

austintgriffith/scaffold-eth

🏗 forkable Ethereum dev stack focused on fast product iterations - austintgriffith/scaffold-eth

GitHubaustintgriffith

Scaffold-eth, also made by Austin Griffith, comes with a lot of handy things out of the box, just as its name suggests. Beyond just smart contracts, it uses React and Hardhat so it's a good playground to practice your skills across the whole web 3 stack thanks to tutorials such as this one.
Then, at some point, it's wise to avoid "the Tutorial trap" and starts developing on your own, without following a tutorial. Scaffold-eth can help there too, as a launchpad to quickly take your idea and build a prototype from it.

7 - ChainShot

ChainShot

Fast-track your Ethereum Developer career in an instructor-led and challenging bootcamp focused on discussion and application!

Chainshot provides a great interactive tutorial to learn how to build on top of Aave. Though I really liked it and felt like a game, it's the only one that I've completed from them, so I cannot vouch for the rest.

8 - Solidity Docs

Adding to the list, the Solidity docs are obviously the reference when it comes to getting a good grasp on Solidity and its subtleties.
However, they are rightfully exhaustive so they might be a bit intimidating as a place to start.

Alternatives 🐍

As an alternative to Solidity, you might want to learn Vyper with Vyper.fun. Especially if you're more into Python than JavaScript, then check out Brownie!

If you want to get notified of a new post, subscribe here.

💡 This is a living document. It will probably get updated with time.

Here are some of my favorite quotes, in no particular order:

"Learn who you are to become who you are."
Pindar

“Take care to get what you like or you will be forced to like what you get.”
Bernard Shaw

"Men press towards the light, not so as to see better, but so as to shine better."
Friedrich Nietzsche

"The difference between a successful person and others is not a lack of strength, not a lack of knowledge, but rather in a lack of will."
Vince Lombardi

“Happiness is not a finish line, and if we can’t feel content amid the mess and the striving, we might never feel it.”
Ben Saunders

"I have not failed. I've just found 1000 ways that don't work."
Thomas A. Edison

“Only passions, great passions can elevate the soul to great things.”
Denis Diderot

"The most exciting phrase to hear in science, the one that heralds new discoveries, is not 'Eureka!' but 'That's funny...’ "
Isaac Asimov

“The reasonable man adapts himself to the world; the unreasonable one persists in trying to adapt the world to himself. Therefore all progress depends on the unreasonable man.”
George Bernard Shaw

“Strong minds discuss ideas, average minds discuss events, weak minds discuss people.”
Socrates

“There is surely nothing quite so useless as doing with great efficiency what should not be done at all.”
Peter Drucker

"We suffer more often in imagination than in reality."
Seneca

"An investment in knowledge always pays the best interest."
Benjamin Franklin

“The two most important days in your life are the day you are born and the day you find out why.”
Mark Twain.